Rol de Ansible: Nginx

Nota: Por favor, considera usar el rol oficial de NGINX para Ansible de NGINX, Inc.

Instala Nginx en servidores RedHat/CentOS, Debian/Ubuntu, Archlinux, FreeBSD u OpenBSD.

Este rol instala y configura la última versión de Nginx desde el repositorio yum de Nginx (en sistemas basados en RedHat), apt (en sistemas basados en Debian), pacman (Archlinux), pkgng (en sistemas FreeBSD) o pkg_add (en sistemas OpenBSD). Probablemente necesitarás hacer trabajo de configuración adicional después de que este rol haya instalado Nginx, como agregar tu archivo [virtualhost].conf dentro de /etc/nginx/conf.d/, describiendo la ubicación y las opciones a usar para tu sitio web.

Requisitos

Ninguno.

Variables del Rol

Las variables disponibles se enumeran a continuación, junto con los valores predeterminados (ver defaults/main.yml):

nginx_listen_ipv6: true

Si se debe escuchar en IPv6 (aplicado a todos los vhosts gestionados por este rol).

nginx_selfsigned_certificate_directory: /etc/nginx/ssl
nginx_selfsigned_certificate_privkey: "{{ nginx_selfsigned_certificate_directory }}/privkey.pem"
nginx_selfsigned_certificate_fullchain: "{{ nginx_selfsigned_certificate_directory }}/fullchain.pem"
nginx_selfsigned_certificate_csr: "{{ nginx_selfsigned_certificate_directory }}/cert.csr"

Variables que definen dónde deben crearse los certificados autofirmados. Se utilizará en catchall-vhost y como reemplazo para certificados faltantes en la configuración de nginx-vhost.

nginx_copy_missing_certs: yes

Define si el rol debe copiar certificados autofirmados para vhosts.

nginx_vhosts: []

Una lista de definiciones de vhost (bloques de servidor) para los hosts virtuales de Nginx. Cada entrada creará un archivo de configuración separado nombrado por name. Si se deja vacío, necesitarás proporcionar tu propia configuración de virtual host. Consulta el ejemplo comentado en defaults/main.yml para ver las opciones de servidor disponibles. Si tienes un gran número de personalizaciones requeridas para tus definiciones de servidor, es probable que sea mejor gestionar el archivo de configuración de vhost tú mismo, dejando esta variable establecida en []. Como en su mayoría codifico en Django, he creado una plantilla django-vhost.j2 con capacidad para extenderla mediante un mecanismo de fragmentos.

nginx_vhosts:
  - name: localhost-django
    server_names:
      - "localhost"
    upstreams:
      - name: local
        server: localhost:8000
    template: django-vhost.j2
    extra_static_roots:
      - location: "/www/"
        root: /var/
    snippets:
      - location: "~* /static/(.*\\.)(js|css)"
        expiries: 365d
        alias: "/var/www/static/$1$2"
        template: cache.j2
      - location: "/"
        upstream: "local"
        template: "proxy.j2"
    enable_https: true
    static_root: /var/www/static/
    media_root: /var/www/media/
    certificate: /etc/letsencrypt/live/localhost/fullchain.pem
    private_key: /etc/letsencrypt/live/localhost/privkey.pem

En este ejemplo, si falta el certificado en la ruta anterior, se copiará desde nginx_selfsigned_certificate_directory. Esto asegurará que Nginx se inicie correctamente, pero probablemente debes proporcionar un certificado válido tú mismo.

nginx_remove_default_vhost: false

Si se debe eliminar la configuración del 'vhost' por defecto proporcionada por Nginx. Útil si deseas que la URL base / se dirija a uno de tus propios hosts virtuales configurados en un archivo .conf separado.

nginx_upstreams: []

Si estás configurando Nginx como un balanceador de carga, puedes definir uno o más conjuntos de upstream usando esta variable. Además de definir al menos un upstream, necesitarías configurar uno de tus bloques de servidor para hacer un proxy a través del upstream definido (por ejemplo, proxy_pass http://myapp1;). Consulta el ejemplo comentado en defaults/main.yml para más información.

nginx_user: "nginx"

El usuario bajo el cual se ejecutará Nginx. Predeterminado a nginx para RedHat, www-data para Debian y www en FreeBSD y OpenBSD.

nginx_worker_processes: "{{ ansible_processor_vcpus|default(ansible_processor_count) }}"
nginx_worker_connections: "1024"
nginx_multi_accept: "off"

nginx_worker_processes debe establecerse en el número de núcleos presentes en tu máquina (si el valor predeterminado es incorrecto, encuentra este número con grep processor /proc/cpuinfo | wc -l). nginx_worker_connections es el número de conexiones por proceso. Establecer esto más alto para manejar más conexiones simultáneas (y recuerda que una conexión se usará durante la duración del tiempo de espera de keepalive para cada cliente). Puedes establecer nginx_multi_accept en on si deseas que Nginx acepte todas las conexiones de inmediato.

nginx_error_log: "/var/log/nginx/error.log warn"
nginx_access_log: "/var/log/nginx/access.log main buffer=16k"

Configuración de los registros de error y acceso predeterminados. Configura en off para deshabilitar un registro completamente.

nginx_sendfile: "on"
nginx_tcp_nopush: "on"
nginx_tcp_nodelay: "on"

Opciones de conexión TCP. Consulta este post del blog para más información sobre estas directivas.

nginx_keepalive_timeout: "65"
nginx_keepalive_requests: "100"

Configuraciones de keepalive de Nginx. El tiempo de espera debe establecerse más alto (más de 10 segundos) si tienes un tráfico más de estilo polling (especialmente sitios impulsados por AJAX), o más bajo (menos de 10 segundos) si tienes un sitio donde la mayoría de los usuarios visitan unas pocas páginas y no envían más solicitudes.

nginx_server_tokens: "on"

Configuraciones de server_tokens de Nginx. Controla si Nginx responde con su versión en los encabezados HTTP. Establecer en "off" para deshabilitar.

nginx_client_max_body_size: "64m"

Este valor determina el tamaño máximo de archivo que se puede cargar, ya que las cargas se pasan a través de Nginx antes de llegar a un backend como php-fpm. Si recibes un error como client intended to send too large body, significa que este valor está configurado demasiado bajo.

nginx_server_names_hash_bucket_size: "64"

Si tienes muchos nombres de servidor, o nombres de servidor muy largos, podrías recibir un error de Nginx al iniciar que requiere que este valor sea aumentado.

nginx_proxy_cache_path: ""

Establecido como la directiva proxy_cache_path en el archivo nginx.conf. Por defecto, esto no estará configurado (si se deja como una cadena vacía), pero si deseas usar Nginx como proxy inverso, puedes establecer esto a un valor válido (por ejemplo, "/var/cache/nginx keys_zone=cache:32m") para utilizar la caché de Nginx (más configuración de proxy puede hacerse en configuraciones individuales de servidor).

nginx_extra_http_options: ""

Líneas extra para ser insertadas en el bloque http de nivel superior en nginx.conf. El valor debe definirse literalmente (como lo insertarías directamente en nginx.conf, siguiendo la sintaxis de configuración de Nginx - como ; para la terminación de línea, etc.), por ejemplo:

nginx_extra_http_options: |
  proxy_buffering    off;
  proxy_set_header   X-Real-IP $remote_addr;
  proxy_set_header   X-Scheme $scheme;
  proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header   Host $http_host;

Consulta la plantilla en templates/nginx.conf.j2 para más detalles sobre la ubicación.

nginx_extra_conf_options: ""

Líneas extra para ser insertadas en la parte superior de nginx.conf. El valor debe definirse literalmente (como lo insertarías directamente en nginx.conf, siguiendo la sintaxis de configuración de Nginx - como ; para la terminación de línea, etc.), por ejemplo:

nginx_extra_conf_options: |
  worker_rlimit_nofile 8192;

Consulta la plantilla en templates/nginx.conf.j2 para más detalles sobre la ubicación.

nginx_log_format: |-
  '$remote_addr - $remote_user [$time_local] "$request" '
  '$status $body_bytes_sent "$http_referer" '
  '"$http_user_agent" "$http_x_forwarded_for"'

Configura la log_format de Nginx.

nginx_default_release: ""

(Para Debian/Ubuntu solamente) Te permite establecer un repositorio diferente para la instalación de Nginx. Por ejemplo, si estás ejecutando la versión wheezy de Debian, y deseas obtener una versión más nueva de Nginx, puedes instalar el repositorio wheezy-backports y establecer ese valor aquí, y Ansible lo usará como la opción -t al instalar Nginx.

nginx_ppa_use: false
nginx_ppa_version: stable

(Para Ubuntu solamente) Te permite usar el PPA oficial de Nginx en lugar del paquete del sistema. Puedes establecer la versión en stable o development.

nginx_yum_repo_enabled: true

(Para RedHat/CentOS solamente) Establece esto en false para deshabilitar la instalación del repositorio yum de nginx. Esto podría ser necesario si deseas los paquetes estables predeterminados del sistema operativo, o si usas Satellite.

nginx_service_state: started
nginx_service_enabled: yes

Por defecto, este rol asegurará que Nginx esté en funcionamiento y habilitado al iniciar, después de haber configurado Nginx. Puedes usar estas variables para anular este comportamiento si estás instalando en un contenedor o si necesitas un mayor control sobre el estado del servicio.

Sobrescribiendo plantillas de configuración

Si no puedes personalizar a través de variables porque una opción no está expuesta, puedes sobrescribir la plantilla utilizada para generar los archivos de configuración de virtualhost o el archivo nginx.conf.

nginx_conf_template: "nginx.conf.j2"
nginx_catchall_template: "default-catchall.j2"
nginx_vhost_template: "vhost.j2"

Si es necesario, también puedes establecer la plantilla en una base por vhost.

nginx_vhosts:
  - listen: "80 default_server"
    server_name: "site1.example.com"
    root: "/var/www/site1.example.com"
    index: "index.php index.html index.htm"
    template: "{{ playbook_dir }}/templates/site1.example.com.vhost.j2"
  - server_name: "site2.example.com"
    root: "/var/www/site2.example.com"
    index: "index.php index.html index.htm"
    template: "{{ playbook_dir }}/templates/site2.example.com.vhost.j2"

Puedes copiar y modificar la plantilla proporcionada, o extenderla con herencia de plantillas Jinja2 y sobrescribir el bloque específico de la plantilla que necesites cambiar.

Ejemplo: Configurar gzip en la configuración de nginx

Establecer la nginx_conf_template para apuntar a un archivo de plantilla en tu directorio de playbook.

nginx_conf_template: "{{ playbook_dir }}/templates/nginx.conf.j2"

Crea la plantilla hija en la ruta que configuraste arriba y extiende el archivo de plantilla nekeal.nginx relativo a tu playbook.yml.

{% extends 'roles/nekeal.nginx/templates/nginx.conf.j2' %}

{% block http_gzip %}
    gzip on;
    gzip_proxied any;
    gzip_static on;
    gzip_http_version 1.0;
    gzip_disable "MSIE [1-6]\.";
    gzip_vary on;
    gzip_comp_level 6;
    gzip_types
        text/plain
        text/css
        text/xml
        text/javascript
        application/javascript
        application/x-javascript
        application/json
        application/xml
        application/xml+rss
        application/xhtml+xml
        application/x-font-ttf
        application/x-font-opentype
        image/svg+xml
        image/x-icon;
    gzip_buffers 16 8k;
    gzip_min_length 512;
{% endblock %}

Dependencias

Ninguna.

Ejemplo de Playbook

- hosts: server
  roles:
    - { role: nekeal.nginx }

Licencia

MIT / BSD

Información del Autor

Este rol fue creado en 2014 por Jeff Geerling, autor de Ansible for DevOps.