Stack APISIX — um gateway de API dinâmico composto como módulo
Este exemplo compila uma stack pequena e real — um gateway de API dinâmico — em manifestos do Kubernetes sintetizados a partir de um único Aggregate escrito pelo programador.
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 guarda estado local, e
- um repositório, etcd, que guarda a configuração do gateway e a persiste num 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 superior importa o módulo pelo nome e renderiza a stack composta; o operador dimensiona os componentes internos do módulo na Release.
Ficheiros
| Ficheiro | Papel |
|---|---|
aggregate.yaml | Intenção do programador: importa o módulo de gateway de API (core/apisix) e passa-lhe 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 anexa, 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 âmbito de módulo; tudo o resto fica com as predefinições do esquema. |
O que demonstra
- Composição como módulo. Uma capacidade com várias cargas de trabalho — um gateway de API que na realidade é um proxy mais um repositório de configuração — é empacotada como um subagregado que compõe dois componentes de carga de trabalho única, e não como um único componente monolítico. O módulo é importado pelo nome e reutilizado onde quer que seja necessário um gateway.
- 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 encaminhados para o gateway e compostos na sua ligação ao etcd. O compilador encaminha as strings sem as interpretar. - Um endpoint público. O módulo exporta o seu gateway como
proxy, o nome público estável ao qual um consumidor se liga — 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 âmbito de módulo (
gateway.store,gateway.gateway) para definir os recursos de computação, sem que o Aggregate do programador repita o dimensionamento físico. - Um ficheiro de configuração montado ao lado de ficheiros escritos em tempo de execução. O gateway lê a sua configuração a partir de um ficheiro num diretório no qual também escreve no arranque. A Recipe emite essa configuração como um ConfigMap e monta-a como um único ficheiro, pelo que configura o gateway sem ocultar os ficheiros que o gateway lá escreve.
- Uma chave da Admin API lida a partir de um Secret. O gateway administra as suas rotas através 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, pelo que não existe nenhuma chave predefinida. O módulo recebe a chave como parâmetro,
admin_key, e anexa com ela a Feature de credencialcore/referenced-secretao slot; este Aggregate declara um parâmetro próprio e passa-o para baixo, e a Release satisfá-lo. O Manifest mapeia a Feature parak8s-existing-secret, pelo que o valor é o nome de um Secret que já existe no namespace: a compilação não lê nenhuma chave nem renderiza nenhuma, e o gateway lê a chave desse Secret quando arranca. Uma Release que não forneça nenhum valor interrompe a compilação, nomeando o parâmetro. - Imagens reproduzíveis. Tanto o gateway como o repositório fixam tags de imagem explícitas, pelo que os manifestos renderizados referenciam imagens estáveis.
Gerar o exemplo
É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example apisix-stackDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd apisix-stackCompilação
Este workspace não contém nenhum .aggrega-config.yaml, pelo que as entidades da biblioteca standard são resolvidas a partir do registo do hub, hub.aggrega.ai, e não é necessária nenhuma flag de catálogo; --auto-pull escreve durante a compilação o lockfile que falta a um clone acabado de criar:
aggrega build --release release-helm-synth.yaml --auto-pullOs artefactos renderizados ficam em dist/. O destino Kubernetes renderiza manifestos simples offline — não é necessário nenhum pull de chart.
Antes de os aplicar, é necessário criar no namespace de destino o Secret que a Release nomeia, apisix-admin-key, com uma chave própria sob a chave de dados admin-key. A chave não pode estar vazia, o que faz parar o gateway no arranque, e não pode ser um valor que o APISIX leia como um número ou como verdadeiro ou falso, como uma chave composta apenas por dígitos, porque nesse caso o APISIX nunca a compara com a chave que um pedido apresenta.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole-lhe este prompt.
Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. Se a pasta do espaço de trabalho ainda não contiver uma pasta `apisix-stack`, chame a ferramenta `scaffold` uma única vez com `example` definido como `apisix-stack` e sem `dir`: esta escreve o exemplo numa 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 que ficheiros a compilação escreveu; encontram-se em `apisix-stack/dist/`.Como é a stack composta
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 ficheiro no diretório conf do contentor; a configuração contém 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 a partir da qual o APISIX lê a chave quando carrega o ficheiro:
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, pelo que a chave não aparece em nenhum ficheiro 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.