BLOG | NGINX

Gerenciando suas configurações NGINX com o GitHub

NGINX-Parte-de-F5-horiz-preto-tipo-RGB
Michael Vernik Miniatura
Michael Vernik
Publicado em 04 de dezembro de 2023
Miniatura de Nina Forsyth
Nina Forsyth
Publicado em 04 de dezembro de 2023

As configurações, opções e configurações de software existem em muitas formas diferentes. Em uma extremidade do espectro estão as interfaces gráficas de usuário (GUIs) responsivas e elegantes, criadas para serem intuitivas e, ao mesmo tempo, fornecerem proteções contra estados inválidos. Na outra ponta: arquivos de texto. Embora os arquivos de texto sejam elogiados tanto por engenheiros quanto por equipes de DevOps por sua clareza, potencial de automação e requisitos mínimos de uso (você provavelmente tem algumas janelas de terminal abertas, certo?), há compensações claras na configuração de software com eles. Por exemplo, tente encontrar um usuário Linux que não tenha conseguido travar um pacote de software configurando incorretamente um arquivo de texto.

Como o único proxy de software completo, balanceador de carga, servidor web e gateway de API, o NGINX é um componente essencial da infraestrutura moderna da Internet. Uma infraestrutura que, na maioria dos casos, é baseada em sistemas operacionais sustentados pelo kernel Linux. Para se adequar a esse ecossistema e aos profissionais que o suportam, o NGINX depende muito de configurações baseadas em texto.

O módulo F5 NGINX Instance Manager tem sido o ideal para orquestração de configuração relacionada ao NGINX há muito tempo. Ele fornece recursos avançados para gerenciamento remoto de configuração em lote por meio de sua interface de usuário intuitiva e API, com documentação de suporte e proteções para inicializar. No entanto, os arquivos de configuração individuais do NGINX se assemelham muito ao código e as equipes de software já têm uma ferramenta incrível para gerenciar o código: Idiota. O Git fornece aos desenvolvedores e equipes de operações uma série de recursos voltados para o gerenciamento de fluxos de trabalho de arquivos de texto.

A nova integração do Instance Manager com o Git e outros sistemas externos permite recursos como controle de versão, contribuição descentralizada, fluxos de trabalho de aprovação e coordenação de equipe. Plataformas como GitHub e GitLab estendem esse conjunto de recursos para integração contínua/implantação contínua (CI/CD), colaboração, rastreamento de problemas e outras funções valiosas por meio de uma interface de usuário baseada na web.

Nesta postagem do blog, ilustramos como o GitHub pode ser usado para gerenciar configurações do NGINX, enviando-as automaticamente para instâncias sempre que uma alteração for feita.

API do Gerenciador de Instâncias

O Instance Manager fornece um rico conjunto de APIs REST que complementam sua interface de usuário web. Um benefício importante da API é sua capacidade de atualizar arquivos de configuração de instâncias do plano de dados sob gerenciamento. Recentemente, ampliamos essa funcionalidade habilitando a capacidade de vincular atualizações de configuração a uma versão específica do arquivo. Quando gerenciadas em um repositório Git, as configurações podem ser marcadas com um hash de confirmação do Git. Além disso, implementamos um novo estado no Instance Manager para configurações gerenciadas externamente que avisa os possíveis editores de arquivos que as configurações estão sob gerenciamento externo.

Ações do GitHub

O GitHub permite que os desenvolvedores criem pipelines de implantação personalizados em seus repositórios usando um recurso chamado Ações . Um usuário pode escolher definir suas próprias ações ou invocar scripts existentes por meio de uma definição YAML . Esses pipelines podem ser acionados de várias maneiras, como quando um repositório é atualizado com uma confirmação ou uma mesclagem de solicitação de pull.

No exemplo deste blog, nos baseamos em ações prontas do GitHub e comandos do Linux. Você aprenderá a usá-los para atualizar arquivos de configuração NGINX gerenciados pelo GitHub em suas instâncias NGINX por meio da API do Instance Manager. Para começar, siga estas etapas no GitHub Docs para criar um novo YAML para executar Ações em seu repositório.

Segredos de ações de configuração

O Instance Manager oferece suporte a várias formas de autenticação . No exemplo, usamos o método de autenticação básica , embora recomendemos provisionar a autenticação OIDC em ambientes de produção.

Em vez de armazenar credenciais do Instance Manager no repositório, o GitHub permite que você defina segredos como variáveis de repositório. Essas variáveis são acessíveis pelo ambiente Actions, mas ficam ocultas nos logs. Siga estas etapas para armazenar as chaves de nome de usuário e senha do Instance Manager como segredos para que você possa usá-las para autenticar suas chamadas de API.

Aqui, definimos essas variáveis como NMS_USERNAME e NMS_PASSWORD .

Captura de tela de uma plataforma de tecnologia exibindo opções de segredos de repositório

Definindo Variáveis de Ações

Da mesma forma, em vez de definir variáveis constantes no seu YAML, pode ser útil fatorá-las para gerenciamento na interface de usuário do GitHub. Na página Variáveis , você pode encontrar instruções sobre como definir variáveis que abrangem todas as Ações do repositório. No exemplo, usamos essa oportunidade para definir o FQDN ou IP do Instance Manager ( NMS_HOSTNAME ), o identificador do sistema no qual o NGINX está sendo executado ( SYSTEM_ID ) e o identificador da instância específica do NGINX a ser atualizada ( INSTANCE_ID ).

Captura de tela de uma plataforma de tecnologia exibindo opções de variáveis de repositório

Observação:  Definimos essas variáveis para simplificar nosso exemplo, mas você pode escolher gerenciar as informações de identificação do Instance Manager, do sistema e do NGINX de outras maneiras. Por exemplo, você pode optar por criar diretórios em seu repositório contendo configurações específicas para diferentes instâncias e nomear esses diretórios com IDs de sistema ou instância. Você pode então modificar seu YAML ou script de ação para ler nomes de diretório e atualizar arquivos de configuração na instância correspondente.

Anatomia da chamada da API REST do Instance Manager para atualização de configurações do NGINX

A chamada da API REST de atualização de configuração do Instance Manager requer vários componentes principais para funcionar. Seu YAML precisará definir cada um desses parâmetros e empacotá-los na chamada de API no formato adequado.

No exemplo, usamos a chamada de API para atualizar uma única instância. No entanto, também é possível configurar um grupo de instâncias no Instance Manager. Isso permite que você atualize todas as instâncias em um grupo sempre que uma nova configuração for enviada do GitHub. Para obter mais informações, consulte nosso Guia prático sobre configurações de publicação .

Abaixo está uma análise da chamada da API REST de atualização de configuração do Instance Manager:

https://{INSTANCE MANAGER HOSTNAME}/api/platform/v1/systems/{SYSTEM ID}/instances/{INSTANCE ID}/config' 
--header "accept: application/json" 
--header "Autorização: Básico {CREDENCIAIS DE LOGIN}" 
--header 'Content-Type: application/json'
--data '{
"configFiles": '{
"rootDir": "/etc/nginx",
"files": [{
"contents": "{ARQUIVO DE CONFIGURAÇÃO NGINX}",
"name": "{CAMINHO PARA O ARQUIVO DE CONFIGURAÇÃO NO SISTEMA}"
}]
},
"externalIdType": "{FONTE DAS CONFIGURAÇÕES}",
"externalId": "{HASH DE COMMIT}",
"updateTime": "{TIMESTAMP}"
}'}'

Parâmetros URI

  • Identificador do sistema – Uma chave exclusiva que identifica o sistema no qual o NGINX está sendo executado. Em nosso exemplo, esses dados são definidos na interface Variáveis de Ações do GitHub.
  • Identificador de instância NGINX – Uma chave exclusiva que identifica uma instância NGINX específica no sistema. Em nosso exemplo, esses dados são definidos na interface Variáveis de Ações do GitHub.

Parâmetros do Cabeçalho

  • Autorização – O método de autorização e as credenciais codificadas em Base64 que o Instance Manager usa para autenticar a chamada de API. No exemplo, você usará a Autorização Básica com dados de credenciais provenientes dos segredos definidos no repositório.

Parâmetros de dados JSON

  • configFiles – O conteúdo codificado em Base64 dos arquivos de configuração que estão sendo atualizados, junto com suas localizações no sistema que executa o NGINX. Você também precisará fornecer um caminho para o diretório raiz dos seus arquivos de configuração do NGINX, mais comumente configurados como: /etc/nginx .
  • externalIdType – Um rótulo que identifica a origem do arquivo de configuração para o Instance Manager. Os valores possíveis são git ou outro . Em nosso exemplo, codificamos esse parâmetro para git .
  • externalId – O algoritmo de hash seguro (SHA) de commit do Git que identifica a alteração nos arquivos de configuração.
  • updateTime – Uma string contendo a data e hora atuais no formato %Y-%m-%dT%H:%M:%SZ .

Codificação Base64

Para acomodar a especificação da API do Instance Manager, você deve transformar determinados dados codificando-os no formato Base64. Embora não haja uma maneira nativa de fazer isso com as Ações do GitHub existentes, podemos contar com ferramentas do Linux, acessíveis a partir do nosso YAML.

Credenciais do Gerenciador de Instâncias

Comece referenciando as credenciais de login do Instance Manager que foram definidas anteriormente como segredos e concatene-as. Em seguida, converta a string para Base64, ecoe-a como uma variável Linux ( NMS_LOGIN ) e anexe o resultado a uma variável de ambiente predefinida ( GITHUB_ENV ), acessível pelo executor de ações.

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

Carimbo de data/hora

A API do Instance Manager exige que um registro de data e hora com formato específico seja enviado com determinadas cargas úteis da API. Você pode construir o registro de data e hora nesse formato usando o comando date do Linux. Semelhante ao exemplo anterior, anexe a string construída como uma variável ao ambiente Linux.

executar: eco "NMS_TIMESTAMP=`data -u +"%Y-%m-%dT%H:%M:%SZ"`" >> $GITHUB_ENV

Configurações NGINX

Em seguida, adicione as configurações do NGINX que você planeja gerenciar no repositório. Há muitas maneiras de adicionar arquivos a um repositório do GitHub. Para mais informações, siga este guia na documentação do GitHub. Para seguir nosso exemplo, você pode criar uma estrutura de diretório no seu repositório GitHub que espelhe a da instância.

A entrada YAML abaixo lê o arquivo de configuração do seu repositório, codifica seu conteúdo em Base64 e adiciona o resultado a uma variável de ambiente, como antes.

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

Em nosso exemplo, repetimos isso para cada arquivo de configuração em nosso repositório GitHub.

Juntando tudo

Por fim, você pode usar a implementação de referência de exemplo do GitHub para reunir o que aprendeu em um arquivo YAML funcional. Conforme definido no arquivo, todos os scripts associados do GitHub Actions serão executados sempre que um usuário atualizar o repositório por meio de uma confirmação ou solicitação de pull. A entrada final no YAML executará um comando curl que fará a chamada de API apropriada, contendo os dados necessários para que o Instance Manager atualize todos os arquivos de configuração relacionados.

Observação:  Use a entrada de execução de várias linhas ( run: | ) no seu YAML para executar o comando curl porque isso instrui o interpretador YAML a tratar dois pontos “:” como texto na parte do parâmetro da entrada.

nome: Gerenciando configurações do NGINX com GitHub e GitHub Actions
# Controla quando o fluxo de trabalho será executado
em:
# Aciona o fluxo de trabalho em eventos de solicitação push ou pull, mas apenas para o branch "main"
push:

branches: ["main"]

pull_request:

branches: ["main"]

# Permite que você execute este fluxo de trabalho manualmente na aba Actions

flow_dispatch:

# Uma execução de fluxo de trabalho é composta de um ou mais trabalhos que podem ser executados sequencialmente ou em paralelo
jobs:

# Este fluxo de trabalho contém um único trabalho chamado "build"

build:
# O tipo de executor no qual o trabalho será executado
runs-on: ubuntu-latest

# As etapas representam uma sequência de tarefas que serão executadas como parte do trabalho
steps:

# Faz check-out do seu repositório em $GITHUB_WORKSPACE, para que seu trabalho possa acessá-lo

- uses: actions/checkout@v4

- nome: Definir variável de ambiente para credenciais de login da API NMS
executar: echo "NMS_LOGIN=`echo -n "${{ secrets.NMS_USERNAME }}:${{ secrets.NMS_PASSWORD }}" | base64`" >> $GITHUB_ENV 

- nome: Definir variável de ambiente para o registro de data e hora da API NMS
executar: echo "NMS_TIMESTAMP=`date -u +"%Y-%m-%dT%H:%M:%SZ"`" >> $GITHUB_ENV 

- nome: Definir variável de ambiente para arquivo de configuração codificado em base64
executar: echo "NGINX_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/nginx.conf | base64 -w 0`" >> $GITHUB_ENV 

- nome: Definir variável de ambiente para arquivo de configuração codificado em base64
executar: echo "MIME_TYPES_CONFIG_FILE=`cat app-sfo-01/etc/nginx/mime.types | base64 -w 0`" >> $GITHUB_ENV 

- nome: Definir variável de ambiente para arquivo de configuração codificado em base64
executar: echo "DEFAULT_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/default.conf | base64 -w 0`" >> $GITHUB_ENV 

- nome: Definir variável de ambiente para arquivo de configuração codificado em base64
executar: echo "SSL_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/ssl.conf | base64 -w 0`" >> $GITHUB_ENV 

- nome: Chamada de API para o Instance Manager
run: | 
curl --location 'https://${{ vars.NMS_HOSTNAME }}/api/platform/v1/systems/${{ vars.SYSTEM_ID }}/instances/${{ vars.INSTANCE_ID }}/config' --header "accept: application/json" --header "Authorization: Básico ${{ env.NMS_LOGIN }}" --header 'Tipo de conteúdo: application/json' --data '{"configFiles": {"rootDir": "/etc/nginx","files": [{"contents": "${{ env.NGINX_CONF_CONFIG_FILE }}","name": "/etc/nginx/nginx.conf"},{"contents": "${{ env.MIME_TYPES_CONFIG_FILE }}","name": "/etc/nginx/mime.types"},{"contents": "${{ env.DEFAULT_CONF_CONFIG_FILE }}","name": "/etc/nginx/conf.d/default.conf"},{"contents": "${{ env.SSL_CONF_CONFIG_FILE }}","nome": "/etc/nginx/conf.d/ssl.conf"}]},"externalIdType": "git","externalId": "${{ github.sha }}","updateTime": "${{ env.NMS_TIMESTAMP }}"}' 

Implementação de referência do NGINX

A execução de uma chamada de API de atualização de configuração após a alteração de um arquivo pode ser feita de diferentes maneiras. Embora o GitHub Actions seja o método mais conveniente para quem usa o GitHub, ele não funcionará no GitLab ou em implementações autônomas do Git. Para abordar esses casos de uso, desenvolvemos uma implementação de referência de script de shell complementar que pode ser acionada a partir da linha de comando ou invocada a partir de scripts personalizados.

Concluindo, nossa nova extensão para a API do Instance Manager fornece uma ferramenta poderosa para gerenciar atualizações de configuração, reversões e históricos de versões de uma forma moderna e descentralizada. Acoplar a extensão a uma plataforma de gerenciamento de código e arquivo de texto de terceiros, como o GitHub, permite recursos adicionais de fluxo de trabalho, CI/CD, colaboração e rastreamento de problemas por meio de uma interface de usuário intuitiva baseada na web.

Gostaríamos de ouvir sua opinião! Experimente e diga-nos o que você acha nos comentários ou ingressando no nosso canal do Slack da Comunidade NGINX .


"Esta postagem do blog pode fazer referência a produtos que não estão mais disponíveis e/ou não têm mais suporte. Para obter as informações mais atualizadas sobre os produtos e soluções F5 NGINX disponíveis, explore nossa família de produtos NGINX . O NGINX agora faz parte do F5. Todos os links anteriores do NGINX.com redirecionarão para conteúdo semelhante do NGINX no F5.com."