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

Visão geral do ApigConfig

Configuração

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

Cada ApigConfig corresponde a uma instância de gateway da APIG. Para usar múltiplas instâncias de gateway da APIG, crie vários recursos do ApigConfig.

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

Importante

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

Veja abaixo 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`	Nome do gateway.	apig-ingress
`common.pay.payType`	Método de faturamento. Somente o pagamento conforme o uso é suportado e definido como padrão caso não seja especificado.	POSTPAY
`common.instance.spec`	Tipo da 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`	vSwitches primário e de standby, nesta ordem. Especifique um ou dois vSwitches. Se não forem especificados, os vSwitches serão herdados do nó onde o pod do APIG Controller está em execução.	Nenhum
`common.network.networkType`	Acessibilidade de rede do gateway. Valores válidos: Internet Intranet	Internet
`common.securityGroupType`	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. Este recurso melhora significativamente o desempenho do tráfego HTTPS.	Ativado
`global.ipAccessControl.whitelist`	Lista de permissões global de IPs.	Não configurado
`global.ipAccessControl.blacklist`	Lista de bloqueios global de IPs.	Não configurado
`monitor.logging.sls`	Define se a coleta de logs do Simple Log Service (SLS) deve ser ativada. Para ative este recurso, conceda as permissões necessárias do SLS ao APIG Controller.	Desativado
`monitor.logging.sls.reuseProject`	Projeto do SLS para armazenar 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`	Taxa de amostragem para o Tracing Analysis (x-trace).	0
`monitor.tracing.openTelemetry`	Ativa ou desativa o rastreamento OpenTelemetry.	Desativado por padrão. Mutuamente exclusivo com a opção de rastreamento `xTrace`.
`monitor.tracing.openTelemetry.sampleRate`	Taxa de amostragem para rastreamento OpenTelemetry.	100
`ingress.local.ingressClass`	Determina quais recursos de Ingress a instância de gateway da APIG processa, com base em sua 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`. String vazia (`""`): Monitora todos os recursos de Ingress. Definido como `nginx`: Monitora recursos de Ingress que possuem IngressClass nginx ou que não estão associados a nenhuma IngressClass. Definido como outro valor: O gateway processa recursos de Ingress cuja IngressClass corresponda ao valor especificado. Nota Esta configuração tem prioridade menor do que associar um ApigConfig por meio de uma IngressClass.	Não configurado
`ingress.local.watchNamespace`	Namespaces onde o gateway monitora recursos de Ingress. Valores válidos: String vazia: Monitora todos os namespaces. Valor especificado: Monitora o namespace indicado. Apenas um namespace pode ser especificado.	Vazio

Status

Após crie um recurso do 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 da APIG está sendo criada. Este processo leva cerca de 3 minutos.
Running: A instância de gateway da APIG foi criada e está em execução.
Listening: A instância de gateway da APIG está em execução e monitorando recursos de Ingress no cluster.
Failed: A instância de gateway da APIG está em um estado inválido. Verifique o campo Message dentro de Status para identificar a causa.

Crie uma instância de gateway da APIG

Configure o ApigConfig.
O exemplo abaixo cria uma instância de gateway da 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 seu 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 da APIG vinculada processará qualquer Ingress associado a esta 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 existente de gateway da APIG

Para reutilizar uma instância existente de gateway da APIG, especifique seu ID (por exemplo, gw-xxx) no campo spec.id do seu 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 existente de gateway da APIG. 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 abaixo, 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 da 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 onde a ingressClass é spec.ingress.local.ingressClass (neste caso, apig). Se a instância do 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 da APIG existente, garanta que os parâmetros do gateway no ApigConfig (opções de listener de Ingress, aceleração de hardware, lista de bloqueios e permissões global de endereços IP e observabilidade) estejam corretamente configurados antes de ative spec.override. Se essas configurações não forem especificadas no ApigConfig, ative spec.override sobrescreverá os parâmetros originais do gateway (opções de listener de Ingress, aceleração de hardware, lista de bloqueios e permissões 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

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

spec.override

Define se as configurações da instância de gateway da APIG reutilizada devem ser sobrescritas com base nas definiçõ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 você definir este parâmetro 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, a instância do gateway será automaticamente associada ao cluster de contêineres e suas opções de listener de Ingress serão configuradas para monitorar recursos de Ingress no cluster de contêineres cuja ingressClass esteja definida com o valor de spec.ingress.local.ingressClass.

Exclua uma instância de gateway da APIG

Exclua um ApigConfig também exclui a instância de gateway da 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

Exclua o ApigConfig exclui automaticamente a instância do gateway.

Exclua o ApigConfig mantém a instância do gateway.

Para exclua o ApigConfig, execute o seguinte comando:

kubectl delete ApigConfig your-config-name

Configure controle global de acesso por IP

Configure uma lista de permissões de IP

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

O exemplo abaixo 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
   ...

Configure uma lista de bloqueios de IP

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

O exemplo a seguir nega requisições provenientes 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
   ...

Ative logs do SLS

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

Para clusters gerenciados do ACK, consulte Grant permissions to the 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"
    ...

Ative rastreamento OpenTelemetry

Configure o rastreamento OpenTelemetry no gateway para construir um sistema de rastreamento ponta a ponta, útil no diagnóstico de problemas em produção.

O exemplo abaixo 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 de Ingress da APIG suporta as seguintes configurações adicionais:

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

Parâmetro	Tipo	Descrição
`EnableGenerateRequestId`	Bool	Quando ativado, gera um ID de requisição 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 da requisição. Por exemplo, `www.a.com//b` torna-se `www.a.com/b`.
`DownstreamConnectionBufferLimits`	Int	Tamanho do buffer de uma única conexão, o que afeta o throughput e o uso de memória do gateway. Intervalo válido: [0, 2147483647].
`XffTrustedNum`	Int	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	Número máximo de streams simultâneos em uma única conexão quando o cliente usa HTTP/2. Intervalo de valores: [0, 2147483647]. Unidade: bytes.
`InitialStreamWindowSize`	Int	Tamanho inicial da janela de `stream` HTTP/2 negociado entre o gateway e o cliente. Intervalo de valores: [65535, 2147483647]. Unidade: bytes.
`InitialConnectionWindowSize`	Int	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 ative o HTTP/3.
`PathWithEscapedSlashes`	String	Determina a ação para requisições cujos caminhos de URI contenham 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>	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 entrada é 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 que não utilizam o protocolo PROXY.
`EnableCustomAuthConfigPush`	Bool	Destinado a 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 incluirá `keep-alive: timeout=10`. Se definido como 0, este cabeçalho não será retornado. Intervalo de valores: [0, 600]. Unidade: segundos.
`WebsocketTermGracePeriod`	Int	Período de carência para conexões WebSocket ativas quando o gateway fecha conexões, como durante atualizações ou reinicializações. Intervalo de valores: [20, 900]. Unidade: segundos.
EnableGzipHardwareAccelerate	Bool	Ativa a compressão Gzip acelerada por hardware. Em comparação com o Gzip via 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 source de serviço. A filtragem inversa também é suportada.

FAQ

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

Se você exclua um Ingress e recriá-lo usando o mesmo arquivo YAML, mas o endpoint permanecer vazio após aguardar algum tempo, geralmente as opções de listener de Ingress não estão configuradas no ApigConfig. Como resultado, a instância de gateway da 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 este campo não estiver configurado, a instância de gateway da APIG não monitorará nenhum recurso de Ingress, e o endpoint não será restaurado após recriar o Ingress. Defina este 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 anteriores estarem corretas. O endpoint será então restaurado automaticamente. Não é necessário recriar a instância de gateway da APIG.

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

API Gateway:Configure ApigConfig