Administrar sus configuraciones de NGINX con GitHub

Las configuraciones, opciones y configuraciones del software existen en muchas formas diferentes. En un extremo del espectro se encuentran las GUI elegantes y responsivas diseñadas para ser intuitivas y al mismo tiempo brindar protección contra estados no válidos. En el otro extremo: archivos de texto. Si bien los archivos de texto son elogiados tanto por los ingenieros como por los equipos de DevOps por su claridad, potencial de automatización y requisitos mínimos de uso (es probable que tenga algunas ventanas de terminal abiertas, ¿verdad?), configurar software con ellos implica claras desventajas. Por ejemplo, intente encontrar un usuario de Linux que no haya logrado bloquear un paquete de software al configurar incorrectamente un archivo de texto.

Como el único proxy de software, equilibrador de carga, servidor web y puerta de enlace API todo en uno, NGINX es un componente clave de la infraestructura de Internet moderna. Una infraestructura que, en la mayoría de los casos, se basa en sistemas operativos respaldados por el kernel Linux. Para adaptarse a este ecosistema y a los profesionales que lo respaldan, NGINX depende en gran medida de configuraciones basadas en texto.

El módulo F5 NGINX Instance Manager ha sido durante mucho tiempo la opción preferida para la orquestación de configuraciones relacionadas con NGINX. Proporciona capacidades avanzadas para la gestión remota de configuración por lotes a través de su interfaz de usuario intuitiva y API, con documentación de apoyo y protecciones adicionales. Sin embargo, los archivos de configuración individuales de NGINX se parecen mucho al código y los equipos de software ya cuentan con una herramienta increíble para administrar el código: Git. Git ofrece a los desarrolladores y equipos de operaciones una gran cantidad de funciones orientadas a la gestión de flujos de trabajo de archivos de texto.

La nueva integración de Instance Manager con Git y otros sistemas externos habilita funciones como control de versiones, contribución descentralizada, flujos de trabajo de aprobación y coordinación de equipos. Plataformas como GitHub y GitLab amplían este conjunto de características a la integración continua/implementación continua (CI/CD), colaboración, seguimiento de problemas y otras funciones valiosas a través de una interfaz de usuario basada en la web.

En esta publicación de blog ilustramos cómo se puede usar GitHub para administrar configuraciones de NGINX, enviándolas automáticamente a las instancias cada vez que se realiza un cambio.

API del administrador de instancias

Instance Manager proporciona un amplio conjunto de API REST que complementan su interfaz de usuario web. Un beneficio clave de la API es su capacidad para actualizar los archivos de configuración de las instancias del plano de datos bajo administración. Recientemente, ampliamos esta funcionalidad al permitir la posibilidad de vincular las actualizaciones de configuración a una versión específica del archivo. Cuando se administran en un repositorio Git, las configuraciones se pueden etiquetar con un hash de confirmación de Git. Además, implementamos un nuevo estado dentro del Administrador de instancias para configuraciones administradas externamente que advierte a los posibles editores de archivos que las configuraciones están bajo administración externa.

Acciones de GitHub

GitHub permite a los desarrolladores crear canales de implementación personalizados en sus repositorios mediante una función llamada Acciones . Un usuario puede elegir definir sus propias acciones o invocar scripts existentes a través de una definición YAML . Estas canalizaciones se pueden activar de distintas maneras, como cuando se actualiza un repositorio con una confirmación o una fusión de solicitudes de extracción.

En el ejemplo de este blog, nos apoyamos en acciones de GitHub listas para usar y comandos de Linux. Aprenderá a usarlos para actualizar los archivos de configuración de NGINX administrados por GitHub en sus instancias de NGINX mediante la API del Administrador de Instancias. Para comenzar, siga estos pasos en la documentación de GitHub para crear un nuevo YAML y ejecutar acciones en su repositorio.

Configuración de secretos de acciones

El administrador de instancias admite varias formas de autenticación . En el ejemplo, utilizamos el método de autenticación básica , aunque recomendamos aprovisionar la autenticación OIDC en entornos de producción.

En lugar de almacenar las credenciales del Administrador de instancias en el repositorio, GitHub le permite definir secretos como variables del repositorio. Estas variables son accesibles desde el entorno de Acciones, pero están ocultas en los registros. Siga estos pasos para almacenar las claves de nombre de usuario y contraseña de Instance Manager como secretos para poder usarlas para autenticar sus llamadas API.

Aquí, hemos establecido estas variables en NMS_USERNAME y NMS_PASSWORD .

Configuración de variables de acciones

De manera similar, en lugar de definir variables constantes en su YAML, puede ser útil factorizarlas para su administración en la interfaz de usuario de GitHub. En la página Variables , puede encontrar instrucciones sobre cómo definir variables que abarquen todas las acciones del repositorio. En el ejemplo, aprovechamos esta oportunidad para definir el FQDN o IP del administrador de instancias ( NMS_HOSTNAME ), el identificador del sistema en el que se ejecuta NGINX ( SYSTEM_ID ) y el identificador de la instancia NGINX específica que se actualizará ( INSTANCE_ID ).

Nota:  Hemos configurado estas variables para simplificar nuestro ejemplo, pero puede elegir administrar la información de identificación de Instance Manager, System y NGINX de otras maneras. Por ejemplo, puede optar por crear directorios en su repositorio que contengan configuraciones específicas para diferentes instancias y nombrar estos directorios con identificadores de sistema o de instancia. Luego, puede modificar su script YAML o Action para leer los nombres de directorio y actualizar los archivos de configuración en la instancia correspondiente.

Anatomía de la llamada a la API REST del Administrador de instancias para actualizar las configuraciones de NGINX

La llamada a la API REST de actualización de configuración del Administrador de instancias requiere varios componentes clave para funcionar. Su YAML deberá definir cada uno de estos parámetros y empaquetarlos en la llamada API en el formato adecuado.

En el ejemplo, utilizamos la llamada API para actualizar una sola instancia. Sin embargo, también es posible configurar un grupo de instancias dentro del Administrador de instancias. Al hacerlo, podrá actualizar todas las instancias de un grupo cada vez que se envíe una nueva configuración desde GitHub. Para obtener más información, consulte nuestra Guía práctica sobre configuraciones de publicación .

A continuación se muestra un desglose de la llamada API REST de actualización de configuración del Administrador de instancias:

<a href="https://{INSTANCE">https://{NOMBRE DE HOST DEL ADMINISTRADOR DE INSTANCIAS</a> }/api/platform/v1/systems/{ID DEL SISTEMA}/instances/{ID DE INSTANCIA}/config'
--header "aceptar: aplicação/json"
--header "Autorización: {CREDENCIALES DE INICIÓ DE SESIÓN}"
--header 'Tipo de contenido: aplicação/json'
--datos '{
"archivos de configuración": '{
"rootDir": "/etc/nginx",
"archivos": [{
"contenido": "{ARCHIVO DE CONFIGURACIÓN DE NGINX}",
"nombre": "{RUTA AL ARCHIVO DE CONFIGURACIÓN EN EL SISTEMA}"
}]
},
"externalIdType": "{FUENTE DE CONFIGURACIONES}",
"externalId": "{HASH DE CONFIRMACIÓN}",
"updateTime": "{TIMESTAMP}"
}'}'

Parámetros URI

• Identificador del sistema: una clave única que identifica el sistema en el que se ejecuta NGINX. En nuestro ejemplo, estos datos se definen en la interfaz de variables de acciones de GitHub.
• Identificador de instancia NGINX: una clave única que identifica una instancia NGINX específica en el sistema. En nuestro ejemplo, estos datos se definen en la interfaz de variables de acciones de GitHub.

Parámetros del encabezado

• Autorización: el método de autorización y las credenciales codificadas en Base64 que utiliza el Administrador de instancias para autenticar la llamada API. En el ejemplo, utilizará la autorización básica con datos de credenciales provenientes de los secretos establecidos en el repositorio.

Parámetros de datos JSON

• configFiles: El contenido codificado en Base64 de los archivos de configuración que se están actualizando, junto con su ubicación en el sistema que ejecuta NGINX. También deberá proporcionar la ruta al directorio raíz de sus archivos de configuración de NGINX, que suele configurarse como: /etc/nginx .
• externalIdType: una etiqueta que identifica la fuente del archivo de configuración para el Administrador de instancias. Los valores posibles son git u otros . En nuestro ejemplo, codificamos este parámetro en git .
• externalId: el algoritmo hash seguro (SHA) de confirmación de Git que identifica el cambio en los archivos de configuración.
• updateTime – Una cadena que contiene la fecha y hora actuales en formato %Y-%m-%dT%H:%M:%SZ .

Codificación Base64

Para cumplir con la especificación de la API de Instance Manager, debe transformar ciertos datos codificándolos en formato Base64. Si bien no existe una forma nativa de lograr esto con las Acciones de GitHub existentes, podemos confiar en las herramientas de Linux, accesibles desde nuestro YAML.

Credenciales del administrador de instancias

Comience haciendo referencia a las credenciales de inició de sesión del Administrador de instancias que se definieron anteriormente como secretos y concatenelas. Luego, convierta la cadena a Base64, repítala como una variable de Linux ( NMS_LOGIN ) y agregue el resultado a una variable de entorno predefinida ( GITHUB_ENV ), accesible por el ejecutor de Acciones.

ejecutar: echo "NMS_LOGIN=`echo -n "${{ secretos.NMS_USERNAME }}:${{ secretos.NMS_PASSWORD }}" | base64`" >> $GITHUB_ENV

Marca de tiempo

La API del Administrador de instancias requiere que se envíe una marca de tiempo con un formato específico con determinadas cargas útiles de la API. Puede construir la marca de tiempo en ese formato utilizando el comando de fecha de Linux. De manera similar al ejemplo anterior, agregue la cadena construida como una variable al entorno Linux.

ejecutar: echo "NMS_TIMESTAMP=`date -u +"%Y-%m-%dT%H:%M:%SZ"`" >> $GITHUB_ENV

Configuraciones de NGINX

A continuación, agregue las configuraciones de NGINX que planea administrar en el repositorio. Hay muchas formas de agregar archivos a un repositorio de GitHub. Para obtener más información, siga esta guía en la documentación de GitHub. Para seguir nuestro ejemplo, puede crear una estructura de directorio en su repositorio de GitHub que refleje la de la instancia.

La entrada YAML a continuación lee el archivo de configuración de su repositorio, codifica su contenido en Base64 y agrega el resultado a una variable de entorno, como antes.

ejecutar: echo "NGINX_CONF_CONFIG_FILE=`cat nginx-server/etc/nginx/nginx.conf | base64 -w 0`" >> $GITHUB_ENV

En nuestro ejemplo, repetimos esto para cada archivo de configuración en nuestro repositorio de GitHub.

Todo en uno

Por último, puedes usar la implementación de referencia de muestra de GitHub para reunir lo que has aprendido en un archivo YAML funcional. Como se define en el archivo, todos los scripts de GitHub Actions asociados se ejecutarán siempre que un usuario actualice el repositorio a través de una confirmación o una solicitud de extracción. La entrada final en YAML ejecutará un comando curl que realizará la llamada API adecuada, que contiene los datos necesarios para que Instance Manager actualice todos los archivos de configuración relacionados.

Nota:  Utilice la entrada de ejecución de varias líneas ( run: | ) en su YAML para ejecutar el comando curl porque esto le indica al intérprete de YAML que trate los dos puntos ":" como texto en la parte de parámetros de la entrada.

nombre: Administración de configuraciones de NGINX con GitHub y GitHub Actions
# Controla cuándo se ejecutará el flujo de trabajo
on:
# Activa el flujo de trabajo en eventos de inserción o solicitud de extracción, pero solo para la rama "principal"
push:
branches: [ "main"]
pull_request:
branches: [ "main"]

# Permite ejecutar este flujo de trabajo manualmente desde la pestaña "Acciones"
workflow_dispatch:

# Una ejecución de flujo de trabajo se compone de uno o más trabajos que pueden ejecutarse secuencialmente o en paralelo
jobs:
# Este flujo de trabajo contiene un solo trabajo llamado "build"
build:
# El tipo de ejecutor en el que se ejecutará el trabajo
runs-on: ubuntu-latest

# Los pasos representan una secuencia de tareas que se ejecutarán como parte del trabajo
steps:
# Extrae el repositorio en $GITHUB_WORKSPACE para que tu trabajo pueda acceder a él
- uses: acciones/checkout@v4

- nombre: Establecer la variable de entorno para las credenciales de inició de sesión de la API de NMS
ejecutar: echo "NMS_LOGIN=`echo -n "${{ secretos.NMS_USERNAME }}:${{ secretos.NMS_PASSWORD }}" | base64`" >> $GITHUB_ENV

- nombre: Establecer la variable de entorno para la marca de tiempo de la API de NMS

Ejecutar: echo "NMS_TIMESTAMP=`date -u +"%Y-%m-%dT%H:%M:%SZ"`" >> $GITHUB_ENV

- nombre: Establecer la variable de entorno para el archivo de configuración codificado en base64.
Ejecutar: echo "NGINX_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/nginx.conf | base64 -w 0`" >> $GITHUB_ENV

- nombre: Establecer la variable de entorno para el archivo de configuración codificado en base64.
Ejecutar: echo "MIME_TYPES_CONFIG_FILE=`cat app-sfo-01/etc/nginx/mime.types | base64 -w 0`" >> $GITHUB_ENV

- nombre: Establecer la variable de entorno para el archivo de configuración codificado en base64.
Ejecutar: echo "DEFAULT_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/default.conf | base64 -w 0`" >> $GITHUB_ENV

- nombre: Establecer la variable de entorno para el archivo de configuración codificado en base64.
Ejecutar: echo "SSL_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/ssl.conf | base64 -w 0`" >> $GITHUB_ENV

- nombre: Llamada API al Administrador de instancias
correr: |
curl --location ' <a href="https://${{">https://${{</a> vars.NMS_HOSTNAME }}/api/platform/v1/systems/${{ vars.SYSTEM_ID }}/instances/${{ vars.INSTANCE_ID }}/config' --header "aceptar: aplicação/json" --header "Autorización: Básico ${{ env.NMS_LOGIN }}" --header 'Tipo de contenido: aplicação/json' --data '{"configFiles": {"rootDir": "/etc/nginx","files": [{"contenido": "${{ env.NGINX_CONF_CONFIG_FILE }}","nombre": "/etc/nginx/nginx.conf"},{"contenido": "${{ env.MIME_TYPES_CONFIG_FILE }}","nombre": "/etc/nginx/mime.types"},{"contenido": "${{ env.DEFAULT_CONF_CONFIG_FILE }}","nombre": "/etc/nginx/conf.d/default.conf"},{"contenido": "${{ env.SSL_CONF_CONFIG_FILE }}","nombre": "/etc/nginx/conf.d/ssl.conf"}]},"externalIdType": "git","externalId": "${{ github.sha }}","updateTime": "${{ env.NMS_TIMESTAMP }}"}' 

Implementación de referencia de NGINX

La ejecución de una llamada API de actualización de configuración después de que se haya modificado un archivo se puede lograr de diferentes maneras. Si bien GitHub Actions es el método más conveniente para quienes usan GitHub, no funcionará para GitLab o implementaciones de Git independientes. Para abordar estos casos de uso, hemos desarrollado una implementación de referencia de script de shell complementario que puede activarse desde la línea de comando o invocarse desde scripts personalizados.

En conclusión, nuestra nueva extensión de la API de Instance Manager proporciona una herramienta poderosa para administrar actualizaciones de configuración, reversiones e historiales de versiones de una manera moderna y descentralizada. Al combinar la extensión con una plataforma de gestión de código y archivos de texto de terceros como GitHub, se pueden disfrutar de funciones adicionales de flujo de trabajo, CI/CD, colaboración y seguimiento de problemas a través de una interfaz de usuario intuitiva basada en la web.

¡Nos encantaría conocer tu opinión! Pruébelo y cuéntenos lo que piensa en los comentarios o uniéndose a nuestro canal Slack de la comunidad NGINX .