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

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

FicheiroPapel
aggregate.yamlIntençã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.yamlMapeia 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.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 â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 provides da 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 credencial core/referenced-secret ao slot; este Aggregate declara um parâmetro próprio e passa-o para baixo, e a Release satisfá-lo. O Manifest mapeia a Feature para k8s-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:

Terminal window
aggrega scaffold --example apisix-stack

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd apisix-stack

Compilaçã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:

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

Os 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: 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, pelo que a chave não aparece em nenhum ficheiro 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.