Configurar ApigConfig - API Gateway: Central de Documentação do Alibaba Cloud

Visão geral do ApigConfig

Configuração

ApigConfig é um CRD fornecido pelo APIG Controller para gerenciar o ciclo de vida e as configurações globais de instâncias de gateway APIG.

Cada ApigConfig corresponde a uma instância de gateway APIG. Para usar várias instâncias de gateway APIG, crie vários recursos ApigConfig.

Exceto em cenários de reutilização, a exclusão de um ApigConfig também exclui a instância de gateway APIG correspondente.

Importante

Para uma instância de gateway APIG criada por meio de um CRD (ApigConfig), gerencie as configurações de negócio, como APIs, rotas e certificados, no CRD. Use o console do APIG para operações como dimensionamento. Não modifique as configurações de negócio de uma instância criada por CRD no console, pois a sincronização do CRD pode sobrescrever suas alterações e causar conflitos de configuração.

A seguir, um exemplo completo de configuração do ApigConfig.

apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
  name: apig-ingress
spec:
  name: apig-ingress
  common:
    pay:
      payType: POSTPAY
    instance:
      spec: apigw.small.x1
    network:
      vSwitches:
      - "vsw-1"
      - "vsw-2"
      networkType: Internet
    securityGroupType: enterprise
  global:
    tls:
      enableHardwareAcceleration: true
    ipAccessControl:
      whitelist:
      - 1.1.XX.XX
      - 2.2.XX.XX
  monitor:
    logging:
      sls:
        reuseProject: "xxx" # Leave blank to use the default project.
    tracing:
      openTelemetry:
        sampleRate: "100"
  ingress:
    local:
      ingressClass:  apig
      watchNamespace: "" # An empty string ("") indicates Ingress resources in all namespaces.

Parâmetro	Descrição	Padrão
`name`	O nome do gateway.	apig-ingress
`common.pay.payType`	O método de faturamento. Somente o pagamento conforme o uso é suportado e é o padrão, caso não seja especificado.	POSTPAY
`common.instance.spec`	O tipo de instância do gateway. Valores válidos: apigw.small.x1 apigw.small.x2 apigw.small.x4 apigw.medium.x1 apigw.medium.x2 apigw.medium.x3 apigw.large.x1 apigw.large.x2 apigw.large.x3	apigw.small.x1
`common.network.vSwitches`	Os vSwitches primário e de standby, nessa ordem. Especifique um ou dois vSwitches. Se não forem especificados, os vSwitches serão herdados do nó em que o pod do APIG Controller está em execução.	Nenhum
`common.network.networkType`	A acessibilidade de rede do gateway. Valores válidos: Internet Intranet	Internet
`common.securityGroupType`	O tipo de grupo de segurança. Valores válidos: enterprise: grupo de segurança avançado normal: grupo de segurança básico	normal
`global.tls.enableHardwareAcceleration`	Define se a aceleração de hardware TLS deve ser ativada. Esse recurso pode melhorar significativamente o desempenho do tráfego HTTPS.	Ativado
`global.ipAccessControl.whitelist`	A lista de permissões global de IP.	Não configurado
`global.ipAccessControl.blacklist`	A lista de bloqueios global de IP.	Não configurado
`monitor.logging.sls`	Define se a coleta de logs do Simple Log Service (SLS) deve ser ativada. Para ativar esse recurso, conceda as permissões necessárias do SLS ao APIG Controller.	Desativado
`monitor.logging.sls.reuseProject`	O projeto do SLS para armazenar os logs de acesso. Valores válidos: Vazio: um projeto padrão é criado e utilizado. Valor especificado: um projeto existente é utilizado.	Vazio
`monitor.tracing.xTrace.sampleRate`	A taxa de amostragem para o Tracing Analysis (x-trace).	0
`monitor.tracing.openTelemetry`	Ativa ou desativa o rastreamento OpenTelemetry.	Desativado por padrão. Mutualmente exclusivo com a opção de rastreamento `xTrace`.
`monitor.tracing.openTelemetry.sampleRate`	A taxa de amostragem para o rastreamento OpenTelemetry.	100
`ingress.local.ingressClass`	Determina quais recursos de Ingress a instância de gateway APIG processa, com base na IngressClass. Valores válidos: Não configurado: o gateway não processa nenhum recurso de Ingress. Definido como `apig`: o gateway processa recursos de Ingress com a IngressClass `apig`. Uma string vazia (`""`): monitora todos os recursos de Ingress. Definido como `nginx`: monitora recursos de Ingress que tenham IngressClass nginx ou que não estejam associados a nenhuma IngressClass. Definido como outro valor: o gateway processa recursos de Ingress com uma IngressClass que corresponda ao valor especificado. Nota Esta configuração tem prioridade menor do que a associação de um ApigConfig por meio de uma IngressClass.	Não configurado
`ingress.local.watchNamespace`	Os namespaces nos quais o gateway monitora recursos de Ingress. Valores válidos: String vazia: monitora todos os namespaces. Valor especificado: monitora o namespace especificado. Somente um namespace pode ser especificado.	Vazio

Status

Após criar um recurso ApigConfig, execute o comando kubectl get ApigConfig para verificar seu status. O recurso passa pelos seguintes estados: Pending > Running > Listening.

Pending: a instância de gateway APIG está sendo criada. Esse processo leva cerca de 3 minutos.
Running: a instância de gateway APIG foi criada e está em execução.
Listening: a instância de gateway APIG está em execução e monitorando recursos de Ingress no cluster.
Failed: a instância de gateway APIG está em um estado inválido. Verifique o campo Message no campo Status para identificar a causa.

Criar uma instância de gateway APIG

Configure o ApigConfig.
O exemplo a seguir cria uma instância de gateway APIG chamada apig-ingress com o tipo de instância apigw.small.x1. Modifique outras configurações do ApigConfig conforme necessário.
```
apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
  name: apig-ingress
spec:
  name: apig-ingress
  common:
    instance:
      spec: apigw.small.x1
```
No cluster do Container Service for Kubernetes (ACK), crie uma IngressClass e associe-a ao ApigConfig usando spec.parameters. Isso declara um processador de Ingress no cluster.
Após a configuração, a instância de gateway APIG associada processa qualquer Ingress associado a essa IngressClass.
```
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: apig
spec:
  controller: apig.alibabacloud.com/ingress
  parameters:
    apiGroup: apig.alibabacloud.com
    kind: ApigConfig
    name: apig-ingress
```

Reutilizar uma instância de gateway APIG existente

Para reutilizar uma instância de gateway APIG existente, especifique o ID dela (por exemplo, gw-xxx) no campo spec.id do ApigConfig. Use spec.override para controlar se as configurações do ApigConfig sobrescrevem a configuração da instância existente.

O exemplo a seguir reutiliza uma instância de gateway APIG existente. O ApigConfig associa a instância a um cluster e a configura para processar recursos de Ingress com a IngressClass apig.

Importante

Na configuração a seguir, spec.override está definido como false, o que significa que as opções de listener de Ingress e a configuração global de um gateway APIG existente não serão sobrescritas. Se uma instância de gateway existente não estiver associada ao cluster de contêineres, ela será automaticamente associada ao cluster e suas opções de listener de Ingress serão configuradas para monitorar recursos de Ingress no cluster de contêineres cuja ingressClass seja spec.ingress.local.ingressClass (neste caso, apig). Se a instância de gateway já estiver associada ao cluster de contêineres, suas opções de listener de Ingress existentes não serão sobrescritas.
Para sobrescrever as opções de listener de Ingress e as configurações globais de um gateway APIG existente, certifique-se de que os parâmetros do gateway no ApigConfig (opções de listener de Ingress, aceleração de hardware, lista de permissões e lista de bloqueios global de endereços IP e observabilidade) estejam configurados corretamente antes de ativar spec.override. Se essas configurações não forem especificadas no ApigConfig, ativar spec.override sobrescreverá os parâmetros originais do gateway (opções de listener de Ingress, aceleração de hardware, lista de permissões e lista de bloqueios global de endereços IP e observabilidade), o que pode afetar o tráfego.

apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
  name: reuse
spec:
  id: gw-xxxx
  override: false
  ingress:
    local:
      ingressClass: apig

Parâmetro

Descrição

spec.id

O ID da instância de gateway APIG a ser reutilizada. O ID deve começar com gw-.

spec.override

Define se as configurações da instância de gateway APIG reutilizada devem ser sobrescritas com base nas configurações do ApigConfig.

Definido como true: sobrescreve a configuração existente do gateway (opções de listener de Ingress, aceleração de hardware, listas de permissões e bloqueios globais e observabilidade).
Se definido como false, as configurações existentes do gateway (como opções de listener de Ingress, aceleração de hardware, listas de permissões e bloqueios globais e observabilidade) não serão sobrescritas. No entanto, se uma instância de gateway existente não estiver associada ao cluster de contêineres, ela será automaticamente associada ao cluster e suas opções de listener de Ingress serão configuradas para monitorar recursos de Ingress no cluster cuja ingressClass esteja definida com o valor de spec.ingress.local.ingressClass.

Excluir uma instância de gateway APIG

A exclusão de um ApigConfig também exclui a instância de gateway APIG correspondente, exceto no caso de instâncias reutilizadas.

A tabela a seguir descreve a política de exclusão.

Método de faturamento	Criado pelo APIG Controller	Gateway do console reutilizado
pagamento conforme o uso	A exclusão do ApigConfig exclui automaticamente a instância de gateway.	A exclusão do ApigConfig mantém a instância de gateway.

Para excluir o ApigConfig, execute o seguinte comando:

kubectl delete ApigConfig your-config-name

Configurar o controle de acesso global por IP

Configurar uma lista de permissões de IP

Configure uma lista de permissões global de IP para permitir o acesso ao APIG Ingress somente a partir de IPs de origem específicos.

O exemplo a seguir permite acesso somente a partir do IP de origem 1.1.XX.XX e do bloco CIDR 2.0.XX.XX/8.

apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
   name: apig-ingress
spec:
   ...
  global:
    ipAccessControl:
      whitelist:
      - 1.1.XX.XX
      - 2.0.XX.XX/8
   ...

Configurar uma lista de bloqueios de IP

Configure uma lista de bloqueios global no nível da instância para negar acesso a partir de IPs de origem específicos.

O exemplo a seguir nega requisições do IP de origem 1.1.XX.XX e do bloco CIDR 2.0.XX.XX/8.

apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
   name: apig-ingress
spec:
   ...
  global:
    ipAccessControl:
      blacklist:
      - 1.1.XX.XX
      - 2.0.XX.XX/8
   ...

Ativar o logging do SLS

Antes de ativar a coleta de logs, certifique-se de que o APIG Controller tenha as permissões necessárias do SLS.

Para clusters gerenciados do ACK, consulte Conceder autorizações ao APIG Controller .

O exemplo a seguir configura o gateway para enviar logs de acesso a um projeto do SLS chamado demo.

apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
   name: apig-ingress
spec:
   ...
  monitor:
    logging:
      sls:
        # Configure reuseProject to enable Simple Log Service. If you want to use the default project, leave this field blank.
        reuseProject: "demo"
    ...

Ativar o rastreamento OpenTelemetry

Configure o rastreamento OpenTelemetry no gateway para criar um sistema de rastreamento ponta a ponta, útil para diagnosticar problemas em produção.

O exemplo a seguir configura o rastreamento OpenTelemetry com uma taxa de amostragem (sampleRate) de 100%.

apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
   name: apig-ingress
spec:
   ...
  monitor:
    tracing:
      openTelemetry:
        sampleRate: "100"
   ...

Configurações adicionais

A instância de gateway APIG Ingress suporta as seguintes configurações adicionais:

Para aplicar essas configurações, acesse o console do Cloud-native API Gateway. Na página APIG Gateway > Gateway List, selecione a instância de gateway e clique em Parameter Settings no painel de navegação à esquerda.

Parâmetro	Tipo	Descrição
`EnableGenerateRequestId`	Bool	Quando ativado, um ID de requisição é gerado no cabeçalho da requisição para fins de rastreamento.
`EnableGzip`	Bool	Ativa a compressão Gzip para requisições e respostas, reduzindo o tráfego do gateway, mas aumentando o consumo de CPU.
`EnableSlashMerge`	Bool	Quando ativado, mescla caracteres `'/'` redundantes nos caminhos de requisição. Por exemplo, `www.a.com//b` se torna `www.a.com/b`.
`DownstreamConnectionBufferLimits`	Int	O tamanho do buffer de uma conexão individual, que afeta o throughput e o uso de memória do gateway. Intervalo válido: [0, 2147483647].
`XffTrustedNum`	Int	O número de proxies confiáveis à frente do gateway. Isso afeta se o gateway utiliza cabeçalhos de requisição adicionados por proxies, como `x-forwarded-for` e `x-request-id`. Intervalo de valores: [0, 10]. Unidade: itens.
`DownstreamHttp2MaxConcurrentStream`	Int	O número máximo de streams simultâneos em uma conexão individual quando o cliente usa HTTP/2. Intervalo de valores: [0, 2147483647]. Unidade: bytes.
`InitialStreamWindowSize`	Int	O tamanho inicial da janela de `stream` HTTP/2 negociado entre o gateway e o cliente. Intervalo de valores: [65535, 2147483647]. Unidade: bytes.
`InitialConnectionWindowSize`	Int	O tamanho inicial da janela de conexão HTTP/2 negociado entre o gateway e o cliente. Intervalo de valores: [65535, 2147483647]. Unidade: bytes.
`EnableHttp3`	Bool	Define se o protocolo HTTP/3 deve ser suportado. O HTTP/3 é incompatível com a aceleração de hardware TLS. Desative a aceleração de hardware antes de ativar o HTTP/3.
`PathWithEscapedSlashes`	String	Determina a ação para requisições cujos caminhos de URI contêm caracteres escapados, como %2F, %2f, %5C ou %5c. O padrão é `KEEP_UNCHANGED`, que mantém os caracteres como estão. Valores válidos: `KEEP_UNCHANGED`, `REJECT_REQUEST`, `UNESCAPE_AND_REDIRECT` e `UNESCAPE_AND_FORWARD`.
`ZipAlgorithm`	List<String>	O algoritmo de compressão a ser usado após a ativação da compressão. Se a opção `EnableGzip` não estiver ativada quando este parâmetro for definido, ela será ativada automaticamente. Valores válidos: `brotli`, `gzip`.
`EnableProxyProtocol`	Bool	Define se o protocolo PROXY deve ser ativado. Quando o tráfego de ingress é roteado por meio de um Network Load Balancer (NLB), ative esta opção para obter o endereço IP real do cliente. Ativá-la não afeta requisições sem o protocolo PROXY.
`EnableCustomAuthConfigPush`	Bool	Para serviços de autorização autogerenciados. Quando ativado, alterações nas regras de autorização não interrompem conexões ativas, sendo adequado para WebSocket e outros cenários em tempo real.
`KeepaliveHeaderTimeout`	Int	Define o valor do cabeçalho de resposta `Keep-Alive` retornado ao cliente. Por exemplo, se definido como 10, a resposta inclui `keep-alive: timeout=10`. Se definido como 0, esse cabeçalho não é retornado. Intervalo de valores: [0, 600]. Unidade: segundos.
`WebsocketTermGracePeriod`	Int	O período de carência para conexões WebSocket ativas quando o gateway fecha conexões, como durante atualizações ou reinícios. Intervalo de valores: [20, 900]. Unidade: segundos.
EnableGzipHardwareAccelerate	Bool	Ativa a compressão Gzip acelerada por hardware. Em comparação com o Gzip por software, oferece maior desempenho com menor consumo de CPU. Esta opção não está disponível em regiões não suportadas ou se a aceleração de hardware Gzip não foi especificada na compra. Quando ativada, as configurações `EnableGzip` e `ZipAlgorithm` não têm efeito.
EnableK8sSourceWorkloadFilter	Bool	Filtra recursos de Ingress, Service e Pod com base em rótulos especificados ao adicionar uma fonte de serviço. A filtragem inversa também é suportada.

Perguntas frequentes

O que fazer se o endpoint estiver vazio após excluir e recriar um APIG Ingress?

Se você excluir um Ingress e recriá-lo usando o mesmo arquivo YAML, mas o endpoint permanecer vazio após esperar um período, geralmente as opções de listener de Ingress não estão configuradas no ApigConfig. Como resultado, a instância de gateway APIG não monitora o recurso de Ingress. Solucione o problema da seguinte forma:

Verifique se spec.ingress.local.ingressClass está configurado no ApigConfig. Se esse campo não estiver configurado, a instância de gateway APIG não monitora nenhum recurso de Ingress, e o endpoint não é restaurado após recriar o Ingress. Defina esse campo como apig.
Certifique-se de que a IngressClass do Ingress corresponda ao valor de ingress.local.ingressClass no ApigConfig. Especifique a IngressClass de um Ingress usando a anotação kubernetes.io/ingress.class: apig ou o campo spec.ingressClassName.
Execute o comando kubectl get apigconfig para verificar se o status do ApigConfig é Listening.
Recrie o Ingress após as configurações acima estarem corretas. O endpoint será restaurado automaticamente. Não é necessário recriar a instância de gateway APIG.

Tag	Descrição
ack.aliyun.com	Indica que o gateway APIG gerencia o tráfego de ingress de um cluster do Container Service for Kubernetes (ACK).
ingress.k8s.alibaba/ApigConfig	Associa a instância de gateway APIG a um ApigConfig.
kubernetes.reused.by.user	Indica se a instância de gateway APIG é reutilizada. Uma instância reutilizada não é excluída quando o ApigConfig associado é excluído.

API Gateway:Configurar ApigConfig