Gerenciando suas configurações do NGINX com o GitHub

Michael Vernik

Nina Forsyth

Configurações, opções e ajustes de software existem de muitas formas diferentes. Em um extremo estão as interfaces gráficas elegantes e responsivas, projetadas para serem intuitivas e, ao mesmo tempo, oferecer proteções contra estados inválidos. No outro extremo: arquivos de texto. Embora sejam elogiados tanto por engenheiros quanto por equipes de DevOps por sua clareza, seu potencial de automação e seus requisitos mínimos de uso (você provavelmente tem algumas janelas de terminal abertas, não é?), há desvantagens evidentes em usá-los para configurar software. Por exemplo, tente encontrar um usuário de Linux que nunca tenha conseguido fazer um pacote de software travar ao configurar incorretamente um arquivo de texto.

Como a única solução de software completa que reúne proxy, 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, se baseia em sistemas operacionais sustentados pelo kernel Linux. Para se adequar a esse ecossistema e aos profissionais que lhe dão suporte, o NGINX depende fortemente de configurações baseadas em texto.

O módulo F5 NGINX Instance Manager há muito tempo é a principal opção para a orquestração de configurações relacionadas ao NGINX. Ele oferece recursos avançados para o gerenciamento remoto de configurações em lote por meio de sua interface de usuário intuitiva e API, além de documentação de apoio e mecanismos de proteção. No entanto, os arquivos de configuração individuais do NGINX são muito semelhantes a código, e as equipes de software já contam com uma ferramenta incrível para gerenciá-lo: o Git. O Git oferece às equipes de desenvolvimento e operações uma série de recursos voltados ao gerenciamento de fluxos de trabalho com arquivos de texto.

A nova integração do Instance Manager com o Git e outros sistemas externos oferece recursos como controle de versão, contribuição descentralizada, fluxos de trabalho de aprovação e coordenação de equipes. Plataformas como GitHub e GitLab ampliam esse conjunto de recursos com integração e implantação contínuas (CI/CD), colaboração, acompanhamento de problemas e outras funcionalidades valiosas por meio de uma interface de usuário baseada na Web.

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

API do Instance Manager

O Instance Manager oferece um amplo conjunto de APIs REST que complementam sua interface web. Um dos principais benefícios da API é a capacidade de atualizar os arquivos de configuração das instâncias do plano de dados sob gerenciamento. Recentemente, ampliamos essa funcionalidade ao permitir que as atualizações de configuração sejam vinculadas a uma versão específica do arquivo. Quando gerenciadas em um repositório Git, as configurações podem ser identificadas com o hash de um commit do Git. Além disso, implementamos um novo estado no Instance Manager para configurações gerenciadas externamente, que alerta possíveis editores de arquivos de que as configurações estão sob gerenciamento externo.

GitHub Actions

O GitHub permite que os desenvolvedores criem pipelines de implantação personalizados em seus repositórios usando um recurso chamado Actions. O usuário pode optar por definir suas próprias ações ou executar 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 um commit ou com a mesclagem de uma pull request.

No exemplo deste blog, usamos GitHub Actions prontos para uso e comandos do Linux. Você aprenderá a usá-los para atualizar, por meio da API do Instance Manager, os arquivos de configuração do NGINX gerenciados pelo GitHub em suas instâncias do NGINX. Para começar, siga estas etapas na documentação do GitHub para criar um novo arquivo YAML e executar Actions em seu repositório.

Configurando segredos do Actions

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 configurar a autenticação OIDC em ambientes de produção.

Em vez de armazenar as credenciais do Instance Manager no repositório, o GitHub permite que você defina segredos como variáveis do repositório. Essas variáveis podem ser acessadas pelo ambiente do 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 e usá-las para autenticar suas chamadas de API.

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

Como configurar variáveis do Actions

Da mesma forma, em vez de definir variáveis constantes no YAML, pode ser útil separá-las para gerenciá-las na interface do usuário do GitHub. Na página Variáveis, você encontra instruções sobre como definir variáveis que abrangem todas as Actions do repositório. Neste exemplo, aproveitamos para definir o FQDN ou o 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 optar por gerenciar as informações de identificação do Instance Manager, do sistema e do NGINX de outras maneiras. Por exemplo, você pode criar diretórios no repositório que contenham configurações específicas para diferentes instâncias e nomeá-los com IDs de sistema ou de instância. Em seguida, você pode modificar seu script YAML ou do Action para ler os nomes dos diretórios e atualizar os arquivos de configuração na instância correspondente.

Anatomia da chamada à API REST do Instance Manager para atualizar configurações do NGINX

A chamada à API REST de atualização de configuração do Instance Manager requer vários componentes essenciais para funcionar. Seu YAML precisará definir cada um desses parâmetros e incluí-los na chamada à 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 atualizar todas as instâncias de um grupo sempre que uma nova configuração for enviada pelo GitHub. Para obter mais informações, consulte nosso Guia prático sobre publicação de configurações.

Veja abaixo uma análise detalhada da chamada à 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 "Authorization: Basic {LOGIN CREDENTIALS}" 
--header 'Content-Type: application/json'
--data '{
    "configFiles": '{
        "rootDir": "/etc/nginx",
        "files": [{
            "contents": "{NGINX CONFIGURATION FILE}",
            "name": "{PATH TO CONFIGURATION FILE ON SYSTEM}"
        }]
    },
    "externalIdType": "{SOURCE OF CONFIGS}",
    "externalId": "{COMMIT HASH}",
    "updateTime": "{TIMESTAMP}"
}'}'

Parâmetros de 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 Variables do GitHub Actions.
• Identificador da instância do NGINX – Uma chave exclusiva que identifica uma instância específica do NGINX no sistema. Em nosso exemplo, esses dados são definidos na interface Variables do GitHub Actions.

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 à API. No exemplo, você usará a Autorização Básica com os dados das 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, juntamente com seus locais no sistema que executa o NGINX. Você também precisará fornecer o caminho para o diretório raiz dos arquivos de configuração do NGINX, geralmente configurado como: /etc/nginx.
• externalIdType – Um rótulo que identifica para o Instance Manager a origem do arquivo de configuração. Os valores possíveis são git ou other. Em nosso exemplo, definimos este parâmetro diretamente como git.
• externalId – O algoritmo de hash seguro (SHA) do commit do Git que identifica a alteração nos arquivos de configuração.
• updateTime – Uma string que contém a data e a hora atuais no formato %Y-%m-%dT%H:%M:%SZ.

Codificação Base64

Para atender à 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 GitHub Actions existentes, podemos recorrer a ferramentas do Linux acessíveis por meio do nosso YAML.

Credenciais do Instance Manager

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, exiba-a como uma variável do Linux (NMS_LOGIN) e acrescente o resultado a uma variável de ambiente predefinida (GITHUB_ENV), acessível pelo executor do Actions.

run: 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 carimbo de data/hora com uma formatação específica seja enviado com determinados payloads da API. Você pode criar o carimbo de data/hora nesse formato usando o comando date do Linux. Assim como no exemplo anterior, adicione a string criada como uma variável ao ambiente Linux.

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

Configurações do NGINX

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

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

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

Em nosso exemplo, repetimos esse processo para cada arquivo de configuração em nosso repositório do 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 um commit ou pull request. 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 multilinha (run: |) no seu YAML para executar o comando curl, pois isso instrui o interpretador YAML a tratar os dois-pontos “:” como texto na parte da entrada que contém os parâmetros.

name: Managing NGINX configs with GitHub and GitHub Actions 
# Controls when the workflow will run 
on: 
  # Triggers the workflow on push or pull request events but only for the "main" branch 
  push: 
    branches: [ "main" ] 
  pull_request: 
    branches: [ "main" ] 
  
  # Allows you to run this workflow manually from the Actions tab 
  workflow_dispatch: 

# A workflow run is made up of one or more jobs that can run sequentially or in parallel 
jobs: 
  # This workflow contains a single job called "build" 
  build: 
    # The type of runner that the job will run on 
    runs-on: ubuntu-latest 

    # Steps represent a sequence of tasks that will be executed as part of the job 
    steps: 
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it 
      - uses: actions/checkout@v4 

      - name: Set environment variable for NMS API login credentials 
        run: echo "NMS_LOGIN=`echo -n "${{ secrets.NMS_USERNAME }}:${{ secrets.NMS_PASSWORD }}" | base64`" >> $GITHUB_ENV 

      - name: Set environment variable for NMS API timestamp 
        run: echo "NMS_TIMESTAMP=`date -u +"%Y-%m-%dT%H:%M:%SZ"`" >> $GITHUB_ENV 

      - name: Set environment variable for base64 encoded config file 
        run: echo "NGINX_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/nginx.conf | base64 -w 0`" >> $GITHUB_ENV 

      - name: Set environment variable for base64 encoded config file 
        run: echo "MIME_TYPES_CONFIG_FILE=`cat app-sfo-01/etc/nginx/mime.types | base64 -w 0`" >> $GITHUB_ENV 

      - name: Set environment variable for base64 encoded config file 
        run: echo "DEFAULT_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/default.conf | base64 -w 0`" >> $GITHUB_ENV 

      - name: Set environment variable for base64 encoded config file 
        run: echo "SSL_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/ssl.conf | base64 -w 0`" >> $GITHUB_ENV 

      - name: API call to 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: Basic ${{ env.NMS_LOGIN }}" --header 'Content-Type: 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 }}","name": "/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 realizada de diferentes maneiras. Embora o GitHub Actions seja o método mais conveniente para quem usa o GitHub, ele não funcionará com o GitLab nem com implementações independentes do Git. Para atender a esses casos de uso, desenvolvemos um script shell complementar de implementação de referência que pode ser acionado pela linha de comando ou invocado por scripts personalizados.

Em conclusão, nossa nova extensão para a API do Instance Manager oferece uma ferramenta avançada para gerenciar atualizações de configuração, reversões e históricos de versões de forma moderna e descentralizada. A integração da extensão com uma plataforma de terceiros para gerenciamento de arquivos de texto e código, como o GitHub, disponibiliza recursos adicionais de fluxo de trabalho, CI/CD, colaboração e acompanhamento de problemas por meio de uma interface de usuário web intuitiva.

Adoraríamos saber a sua opinião! Experimente e conte para nós o que achou nos comentários ou participe do nosso canal da comunidade NGINX no Slack.

Sobre os autores

Michael Vernik

Mais publicações de Michael Vernik

Nina Forsyth

Mais publicações de Nina Forsyth