O que há de novo no ADC 0.8, 0.9 e 0.10?

Introdução

ADC (APISIX Declarative CLI) é uma ferramenta de configuração declarativa introduzida pela API7.ai, fornecendo um conjunto de ferramentas conveniente para os usuários implementarem GitOps. Os usuários podem facilmente integrá-la em seus pipelines de CI/CD para gerenciar o ciclo de vida completo da API, completando atualizações e lançamentos de APIs. Após o lançamento da versão 0.7, o ADC lançou três novas versões: 0.8, 0.9 e 0.10, com otimizações e atualizações em termos de funcionalidade, desempenho e experiência do usuário.

Novas Funcionalidades do ADC

Melhorias no Detector de Mudanças de Recursos: Differ

Essas modificações foram introduzidas nas versões 0.8 e 0.9.

Introduzimos uma nova versão do detector de mudanças de recursos Differ, v3, que apresenta melhorias significativas em funcionalidade e qualidade de código.

1. O novo Differ introduz um mecanismo de mesclagem de valores padrão para recursos locais, garantindo que os valores padrão do lado do servidor não interfiram nas verificações de mudanças de recursos do ADC.

   Quando o cliente envia uma solicitação para criar um recurso na API7 ou na API Admin do APISIX, o servidor realiza uma validação de Schema na solicitação enviada. Durante esse processo, alguns campos que possuem valores padrão marcados no Schema, mas não são enviados pelo cliente, serão automaticamente adicionados ao recurso enviado. Como resultado, quando lemos o recurso da API novamente, ele será diferente da submissão inicial.

   Versões anteriores do ADC listariam esses recursos como "modificados" e enviariam solicitações de atualização de API para a API Admin. Esse comportamento introduziu alguma incerteza para o ADC, e esse problema foi resolvido através do Differ.

2. O mecanismo de mesclagem de valores padrão foi implementado no backend da API7, garantindo que as diferenças de recursos sejam consideradas como modificações apenas quando o usuário alterou a configuração local do YAML.

3. Granularidade refinada do Differ: o ADC atualmente realiza verificações de mudanças de recursos separadamente nas dimensões do corpo do recurso e dos plugins, ajudando a reduzir anomalias na verificação.

4. Qualidade de código otimizada, simplificando código redundante para melhorar a legibilidade e corrigindo alguns bugs.

Filtros de Recursos

Adicionamos dois mecanismos de filtragem de recursos com base em rótulos de recursos e tipos de recursos. Eles podem ser usados para excluir recursos desnecessários durante as operações de busca, verificação de diferenças e sincronização.

Filtro de Rótulo de Recurso

A funcionalidade foi introduzida na versão 0.8.

Este filtro realiza a filtragem com base no campo de rótulos dos recursos. Os usuários podem habilitar o filtro usando o parâmetro --label-selector key=value na linha de comando. Ele suporta a configuração de múltiplas condições de filtro, e apenas os recursos remotos que atendem simultaneamente a essas regras serão considerados como existentes, enquanto os recursos locais serão automaticamente adicionados com esses rótulos.

Isso garante que realizemos verificações e sincronizações de recursos em um escopo reduzido, ajudando a dividir as tarefas executadas no pipeline de CI/CD e evitando que a sincronização acidental danifique recursos que não precisam ser modificados.

Filtro de Tipo de Recurso

A funcionalidade foi introduzida na versão 0.9.

Adicionamos dois novos parâmetros de linha de comando: --include-resource-type <type> e --exclude-resource-type <type>, que podem ser configurados várias vezes, mas os parâmetros include e exclude são mutuamente exclusivos.

Com esses dois parâmetros, podemos filtrar tipos específicos de recursos da operação atual. Por exemplo, usar include-resource-type pode ser usado para definir uma lista de permissões e selecionar os tipos de recursos a serem incluídos na operação; enquanto exclude-resource-type determinará os tipos de recursos a serem excluídos da operação.

Isso nos ajuda a lidar melhor com recursos que não precisam ser alterados com frequência, como metadados de plugins e regras globais de plugins.

Melhorias na Linha de Comando

Essas melhorias foram introduzidas na versão 0.9.

Configuração de Certificado TLS

Adicionamos uma série de parâmetros relacionados ao TLS na linha de comando, como:

• --ca-cert-file para especificar o arquivo de certificado CA do servidor
• --tls-skip-verify para desabilitar a verificação do certificado TLS do servidor
• --tls-client-cert-file e --tls-client-key-file para especificar os arquivos de certificado mTLS do cliente

Esses parâmetros ajudam o ADC a estabelecer uma conexão criptografada segura e prevenir ataques de intermediário.

Controle de Tempo Limite

Adicionamos o parâmetro --timeout <duration> para controlar a duração do tempo limite das chamadas de API, suportando sintaxe como 1m30s. Quando uma chamada de API Admin demora muito ou fica travada, o mecanismo de tempo limite entrará em ação para evitar que ela espere indefinidamente.

Modo de Depuração

Esta funcionalidade foi introduzida na versão 0.9.

Quando o ADC realiza operações de recursos internamente, ele precisa chamar um grande número de APIs. Às vezes, podemos precisar verificar essas chamadas de API para analisar se estão sendo enviadas corretamente ou para verificar se as respostas do servidor atendem às expectativas. Embora a captura de pacotes possa ser usada para isso, a operação não é conveniente e há dificuldades significativas quando o TLS está habilitado.

Portanto, adicionamos um modo de depuração embutido ao ADC, que pode ser habilitado usando o parâmetro --verbose <integer>. Quando esse parâmetro é definido como 2, o ADC imprimirá as partes de solicitação e resposta de cada chamada de API interna para ajudar na depuração.

Esse parâmetro também pode ser usado para ocultar logs. Quando definido como 0, o ADC ocultará todos os logs gerais, exceto erros.

Fortalecimento do Processamento de Recursos Remotos

Esta funcionalidade foi introduzida na versão 0.9.

Como o ADC não é a única maneira de configurar serviços, rotas, etc., os usuários também podem usar o painel de controle da API7 Enterprise para fazer isso através de operações simples. Isso levou a um problema: as operações no painel de controle usarão IDs de recursos gerados aleatoriamente, enquanto o ADC usa o nome do recurso na configuração YAML para gerar um ID de recurso fixo para localização precisa do recurso.

Isso significa que, se o usuário criar um recurso no painel de controle, o ADC não poderá localizá-lo pelo ID do recurso. O ADC não pode modificar ou excluir os recursos criados no painel de controle, mas esses recursos ainda aparecerão na detecção de mudanças, mas não poderão ser operados corretamente.

Portanto, otimizamos a lógica relevante do backend da API7 ADC. Se o remoto e o local contiverem recursos com o mesmo nome, mas os IDs não puderem ser correspondidos, o ADC poderá excluir corretamente o recurso remoto e criar um novo com base na configuração local, caso em que o ID será gerado pelo ADC com base no nome do recurso e poderá ser usado para buscas subsequentes de recursos. Os usuários do painel de controle da API7 não serão afetados, e os recursos criados pelo ADC ainda poderão ser visualizados no painel de controle.

Suporte a Campos de Extensão ADC no Conversor OpenAPI

Esta funcionalidade foi introduzida na versão 0.10.

Para construir um pipeline coerente do OpenAPI para o ADC e para a API7, o conversor OpenAPI precisa injetar os campos necessários no arquivo de configuração YAML do ADC com base em nossas necessidades.

Por exemplo, para modificar o campo pass_host no upstream do serviço, anteriormente só podíamos usar manualmente o conversor para converter o OpenAPI para o arquivo de configuração do ADC, modificar manualmente o campo pass_host e, em seguida, enviar o arquivo modificado para o repositório Git para o pipeline de CI/CD executar a sincronização do ADC. Esse processo não é coerente e requer muita intervenção manual.

Agora, através das extensões x-adc introduzidas, os usuários só precisam escrever os campos de extensão em locais específicos no documento OpenAPI, e o ADC escreverá corretamente esses campos no arquivo de configuração gerado. Com essas extensões, os usuários podem modificar diretamente qualquer conteúdo na configuração do ADC no OpenAPI, como adicionar rótulos, adicionar plugins e substituir a configuração padrão de serviços/upstreams/rotas.

Como resultado, mantendo apenas um arquivo OpenAPI, o pipeline OpenAPI-ADC-API7 pode ser implementado de forma integrada, simplificando muito o fluxo de trabalho GitOps para configuração de gateway de API.

Conclusão

A ferramenta de configuração declarativa ADC lançada pela API7.ai pode ajudar as empresas a realizar a gestão GitOps de gateways de API. Nas novas versões 0.8, 0.9 e 0.10, a ferramenta foi otimizada e atualizada em termos de funcionalidade, adicionando recursos como monitoramento e filtragem de mudanças de recursos. Essas novas funcionalidades injetam novo impulso na gestão do ciclo de vida completo da API.

Essas novas capacidades permitem que o ADC atenda melhor às necessidades das empresas para a gestão GitOps de gateways de API, melhorando a eficiência e a flexibilidade da gestão de APIs.