Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Stack APISIX — um gateway de API dinâmico composto como módulo

Este exemplo compila um stack pequeno e real — um gateway de API dinâmico — para manifestos do Kubernetes sintetizados a partir de um único Aggregate escrito pelo desenvolvedor.

O gateway não é um único componente. É um módulo: um subagregado reutilizável que compõe dois componentes de carga de trabalho única —

  • um gateway que termina o tráfego dos clientes na sua porta de proxy e não mantém estado local, e
  • um repositório, etcd, que guarda a configuração do gateway e a persiste em um volume.

O módulo liga a sua própria aresta interna do gateway ao repositório e exporta o gateway como o seu endpoint público proxy. O Aggregate de nível mais alto importa o módulo pelo nome e renderiza o stack composto; o operador dimensiona os componentes internos do módulo na Release.

Arquivos

ArquivoPapel
aggregate.yamlIntenção do desenvolvedor: importa o módulo de gateway de API (core/apisix) e lhe passa a chave da Admin API do gateway a partir de um parâmetro próprio.
manifest-helm-synth.yamlMapeia os tipos gateway e repositório para as suas Recipes helm synth, e a Feature de credencial que o módulo vincula, para a realização que lê um Secret já presente no namespace.
release-helm-synth.yamlDocumento do operador para o destino Kubernetes. Nomeia o Secret que contém a chave da Admin API e dimensiona os componentes internos do módulo pelos seus IDs com escopo de módulo; todo o resto fica com os valores padrão do esquema.

O que ele demonstra

  • Composição como módulo. Uma capacidade com várias cargas de trabalho — um gateway de API que na verdade é um proxy mais um repositório de configuração — é empacotada como um subagregado que compõe dois componentes de carga de trabalho única, não como um único componente monolítico. O módulo é importado pelo nome e reutilizado onde quer que um gateway seja necessário.
  • Uma aresta interna dentro do módulo. O gateway declara um uso do repositório; o host e a porta dos provides da Recipe do repositório são canalizados para o gateway e compostos na sua conexão com o etcd. O compilador roteia as strings sem interpretá-las.
  • Um endpoint público. O módulo exporta o seu gateway como proxy, o nome público estável ao qual um consumidor se conecta — desacoplado dos nomes dos componentes internos do módulo.
  • Dimensionamento dos componentes internos pelo operador. A Release endereça os componentes internos do módulo pelos seus IDs com escopo de módulo (gateway.store, gateway.gateway) para definir os recursos de computação, sem que o Aggregate do desenvolvedor repita o dimensionamento físico.
  • Um arquivo de configuração montado ao lado de arquivos escritos em tempo de execução. O gateway lê a sua configuração de um arquivo em um diretório no qual também escreve na inicialização. A Recipe emite essa configuração como um ConfigMap e a monta como um único arquivo, de modo que configura o gateway sem ocultar os arquivos que o gateway escreve ali.
  • Uma chave da Admin API lida de um Secret. O gateway administra as suas rotas por meio de uma Admin API, e a sua chave chega por um slot de credencial no gateway, que o gateway exige enquanto nada estiver ligado ao seu socket de modelos, como aqui, então não existe nenhuma chave padrão. O módulo recebe a chave como parâmetro, admin_key, e vincula com ela a Feature de credencial core/referenced-secret ao slot; este Aggregate declara um parâmetro próprio e o repassa para baixo, e a Release o satisfaz. O Manifest mapeia a Feature para k8s-existing-secret, então o valor é o nome de um Secret que já existe no namespace: o build não lê nenhuma chave e não renderiza nenhuma, e o gateway lê a chave desse Secret quando inicia. Uma Release que não fornece nenhum valor interrompe o build, nomeando o parâmetro.
  • Imagens reproduzíveis. Tanto o gateway quanto o repositório fixam tags de imagem explícitas, então os manifestos renderizados referenciam imagens estáveis.

Gerar o exemplo

Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.

Escreva o exemplo em uma nova pasta com o nome dele:

Terminal window
aggrega scaffold --example apisix-stack

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

Terminal window
cd apisix-stack

Build

Este workspace não traz nenhum .aggrega-config.yaml, então as entidades da biblioteca padrão são resolvidas a partir do registro do hub, hub.aggrega.ai, e nenhuma flag de catálogo é necessária; --auto-pull escreve durante o build o lockfile que falta a um clone novo:

Terminal window
aggrega build --release release-helm-synth.yaml --auto-pull

Os artefatos renderizados ficam em dist/. O destino Kubernetes renderiza manifestos simples offline — nenhum pull de chart é necessário.

Antes de aplicá-los, crie no namespace de destino o Secret que a Release nomeia, apisix-admin-key, contendo uma chave sua sob a chave de dados admin-key. A chave não pode estar vazia, o que faz o gateway parar na inicialização, e não pode ser um valor que o APISIX lê como número ou como verdadeiro ou falso, como uma chave só de dígitos, porque então o APISIX nunca a compara com a chave que uma requisição apresenta.

Com um assistente de IA

Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.

Use apenas as ferramentas do Aggrega e não crie nenhuma pasta você mesmo. Se a pasta do workspace ainda não contiver uma pasta `apisix-stack`, chame a ferramenta `scaffold` uma única vez com `example` definido como `apisix-stack` e sem `dir`: ela escreve o exemplo em uma nova pasta `apisix-stack`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `apisix-stack`, `release` definido como `release-helm-synth.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos o build escreveu; eles ficam em `apisix-stack/dist/`.

Como fica o stack composto

O gateway é renderizado como um Deployment sem estado mais um Service ClusterIP na porta de proxy. A sua configuração é entregue como um ConfigMap montado como um único arquivo no diretório conf do contêiner; a configuração traz o nome do Service interno ao cluster do repositório e, onde vai a chave da Admin API, o nome da variável de ambiente da qual o APISIX lê a chave quando carrega o arquivo:

apisix:
node_listen: 9080
deployment:
role: traditional
role_traditional:
config_provider: etcd
admin:
[… omitted: the client range the Admin API accepts]
admin_key:
- name: admin
key: ${{APISIX_ADMIN_KEY}}
role: admin
admin_listen:
ip: 0.0.0.0
port: 9180
etcd:
host:
- "http://gateway-zdstore-default:2379"
prefix: "/apisix"
timeout: 30

O Deployment entrega essa variável a partir do Secret, então a chave não aparece em nenhum arquivo renderizado:

env:
- name: APISIX_ADMIN_KEY
valueFrom:
secretKeyRef:
name: apisix-admin-key
key: admin-key

O repositório é renderizado como um StatefulSet com um volume persistente montado em /etcd-data, mais um Service ClusterIP e um Service headless.