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.
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.
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.
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
.
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
).
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.
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}"
}'}'
/etc/nginx
.git
ou outro
. Em nosso exemplo, codificamos esse parâmetro para git
.%Y-%m-%dT%H:%M:%SZ
.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.
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
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
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.
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 }}"}'
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."