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
| Arquivo | Papel |
|---|---|
aggregate.yaml | Intençã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.yaml | Mapeia 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.yaml | Documento 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
providesda 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 credencialcore/referenced-secretao slot; este Aggregate declara um parâmetro próprio e o repassa para baixo, e a Release o satisfaz. O Manifest mapeia a Feature parak8s-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:
aggrega scaffold --example apisix-stackEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd apisix-stackBuild
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:
aggrega build --release release-helm-synth.yaml --auto-pullOs 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: 9080deployment: 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: 30O 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-keyO repositório é renderizado como um StatefulSet com um volume persistente montado em /etcd-data, mais um Service ClusterIP e um Service headless.