Anotações para o Application Gateway Ingress Controller

Você pode anotar o recurso de entrada do Kubernetes com pares arbitrários de chave/valor. O Application Gateway Ingress Controller (AGIC) depende de anotações para programar recursos do Gateway de Aplicativo do Azure que não são configuráveis por meio do YAML de ingresso. As anotações de entrada são aplicadas a todas as configurações HTTP, pools de back-end e ouvintes derivados de um recurso de entrada.

Lista de anotações suportadas

Para que a AGIC observe um recurso de entrada, o recurso deve ser anotado com kubernetes.io/ingress.class: azure/application-gateway.

Prefixo do caminho de back-end

A anotação a seguir permite que o caminho de back-end especificado em um recurso de entrada seja reescrito com o prefixo especificado. Use-o para expor serviços cujos pontos de extremidade são diferentes dos nomes de ponto de extremidade que você usa para expor um serviço em um recurso de entrada.

Utilização

appgw.ingress.kubernetes.io/backend-path-prefix: <path prefix>

Exemplo

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-bkprefix
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/backend-path-prefix: "/test/"
spec:
  rules:
  - http:
      paths:
      - path: /hello/
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 80

O exemplo anterior define um recurso de entrada nomeado go-server-ingress-bkprefix com uma anotação chamada appgw.ingress.kubernetes.io/backend-path-prefix: "/test/". A anotação informa ao Application Gateway para criar uma configuração HTTP que tenha uma substituição de prefixo de caminho para o caminho /hello para /test/.

O exemplo define apenas uma regra. No entanto, as anotações se aplicam a todo o recurso de entrada. Portanto, se você definir várias regras, configurará o prefixo do caminho de back-end para cada um dos caminhos especificados. Se você quiser regras diferentes com prefixos de caminho diferentes (mesmo para o mesmo serviço), precisará definir recursos de entrada diferentes.

Nome do host de back-end

Use a anotação a seguir para especificar o nome do host que o Application Gateway deve usar ao falar com os pods.

Utilização

appgw.ingress.kubernetes.io/backend-hostname: "internal.example.com"

Exemplo

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-timeout
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/backend-hostname: "internal.example.com"
spec:
  rules:
  - http:
      paths:
      - path: /hello/
        backend:
          service:
            name: store-service
            port:
              number: 80
        pathType: Exact

Sonda de integridade personalizada

Você pode configurar o Application Gateway para enviar testes de integridade personalizados para o pool de endereços de back-end. Quando as anotações a seguir estão presentes, o controlador de entrada do Kubernetes cria uma sonda personalizada para monitorar o aplicativo de back-end. Em seguida, o controlador aplica as alterações ao Application Gateway.

• health-probe-hostname: Esta anotação permite um nome de host personalizado no teste de integridade.
• health-probe-port: Esta anotação configura uma porta personalizada para o teste de integridade.
• health-probe-path: Esta anotação define um caminho para a sonda de integridade.
• health-probe-status-code: Esta anotação permite que o teste de integridade aceite diferentes códigos de status HTTP.
• health-probe-interval: Esta anotação define o intervalo no qual a sonda de integridade é executada.
• health-probe-timeout: Esta anotação define quanto tempo a sonda de integridade aguarda por uma resposta antes de falhar na sonda.
• health-probe-unhealthy-threshold: Esta anotação define quantas sondas de integridade devem falhar para que o back-end seja marcado como não íntegro.

Utilização

appgw.ingress.kubernetes.io/health-probe-hostname: "contoso.com"
appgw.ingress.kubernetes.io/health-probe-port: 80
appgw.ingress.kubernetes.io/health-probe-path: "/"
appgw.ingress.kubernetes.io/health-probe-status-code: "100-599"
appgw.ingress.kubernetes.io/health-probe-interval: 30
appgw.ingress.kubernetes.io/health-probe-timeout: 30
appgw.ingress.kubernetes.io/health-probe-unhealthy-threshold: 2

Exemplo

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/health-probe-hostname: "contoso.com"
    appgw.ingress.kubernetes.io/health-probe-port: 81
    appgw.ingress.kubernetes.io/health-probe-path: "/probepath"
    appgw.ingress.kubernetes.io/health-probe-status-code: "100-599"
    appgw.ingress.kubernetes.io/health-probe-interval: 31
    appgw.ingress.kubernetes.io/health-probe-timeout: 31
    appgw.ingress.kubernetes.io/health-probe-unhealthy-threshold: 2
spec:
  rules:
  - http:
      paths:
      - path: /
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 80

Redirecionamento TLS

Você pode configurar o Application Gateway para redirecionar automaticamente URLs HTTP para suas contrapartes HTTPS. Quando essa anotação está presente e o TLS está configurado corretamente, o controlador de entrada do Kubernetes cria uma regra de roteamento com uma configuração de redirecionamento. Em seguida, o controlador aplica as alterações à sua instância do Application Gateway. O redirecionamento criado é HTTP 301 Moved Permanently.

Utilização

appgw.ingress.kubernetes.io/ssl-redirect: "true"

Exemplo

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-redirect
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  tls:
   - hosts:
     - www.contoso.com
     secretName: testsecret-tls
  rules:
  - host: www.contoso.com
    http:
      paths:
      - backend:
          service:
            name: websocket-repeater
            port:
              number: 80

Drenagem de conexões

Use as seguintes anotações se quiser usar a drenagem de conexão:

• connection-draining: Esta anotação especifica se a drenagem de conexão deve ser habilitada.
• connection-draining-timeout: Esta anotação especifica um tempo limite, após o qual o Application Gateway encerra as solicitações para o ponto de extremidade de back-end de drenagem.

Utilização

appgw.ingress.kubernetes.io/connection-draining: "true"
appgw.ingress.kubernetes.io/connection-draining-timeout: "60"

Exemplo

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-drain
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/connection-draining: "true"
    appgw.ingress.kubernetes.io/connection-draining-timeout: "60"
spec:
  rules:
  - http:
      paths:
      - path: /hello/
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 80

Afinidade baseada em cookies

Use a anotação a seguir para habilitar a afinidade baseada em cookies.

Utilização

appgw.ingress.kubernetes.io/cookie-based-affinity: "true"

Exemplo

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-affinity
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/cookie-based-affinity: "true"
spec:
  rules:
  - http:
      paths:
      - path: /hello/
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 80

Tempo Limite do Pedido

Use a anotação a seguir para especificar o tempo limite da solicitação em segundos. Após o tempo limite, o Application Gateway falhará uma solicitação se a resposta não for recebida.

Utilização

appgw.ingress.kubernetes.io/request-timeout: "20"

Exemplo

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-timeout
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/request-timeout: "20"
spec:
  rules:
  - http:
      paths:
      - path: /hello/
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 80

Usar IP privado

Use a anotação a seguir para especificar se esse ponto de extremidade deve ser exposto em um endereço IP privado do Application Gateway.

Para uma instância do Application Gateway que não tem um IP privado, as entradas com appgw.ingress.kubernetes.io/use-private-ip: "true" são ignoradas. Os logs do controlador e os eventos de entrada para essas entradas mostram um NoPrivateIP aviso.

Utilização

appgw.ingress.kubernetes.io/use-private-ip: "true"

Exemplo

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-privateip
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/use-private-ip: "true"
spec:
  rules:
  - http:
      paths:
      - path: /
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 80

Substituir porta de front-end

Use a anotação a seguir para configurar um ouvinte frontend para usar portas diferentes de 80 para HTTP e 443 para HTTPS.

Se a porta estiver dentro do intervalo autorizado do Application Gateway (1 a 64999), o ouvinte será criado nessa porta específica. Se você definir uma porta inválida ou nenhuma porta na anotação, a configuração usará o padrão de 80 ou 443.

Utilização

appgw.ingress.kubernetes.io/override-frontend-port: "port"

Exemplo

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-overridefrontendport
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/override-frontend-port: "8080"
spec:
  rules:
  - http:
      paths:
      - path: /hello/
        backend:
          service:
            name: store-service
            port:
              number: 80
        pathType: Exact

Protocolo de back-end

Use o seguinte para especificar o protocolo que o Application Gateway deve usar quando se comunicar com os pods. Os protocolos suportados são HTTP e HTTPS.

Embora os certificados autoassinados sejam suportados no Application Gateway, o AGIC atualmente suporta HTTPS apenas quando os pods usam um certificado assinado por uma autoridade de certificação conhecida.

Não use a porta 80 com HTTPS e a porta 443 com HTTP nos pods.

Utilização

appgw.ingress.kubernetes.io/backend-protocol: "https"

Exemplo

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-timeout
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/backend-protocol: "https"
spec:
  rules:
  - http:
      paths:
      - path: /
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 443

Extensão Hostname

Você pode configurar o Application Gateway para aceitar vários nomes de host. Use a anotação para definir vários nomes de host, incluindo nomes de host curinga hostname-extension . Essa ação acrescenta os nomes de host ao FQDN definido nas informações de entrada spec.rules.host no ouvinte frontend, portanto, ele é configurado como um ouvinte multissite.

Utilização

appgw.ingress.kubernetes.io/hostname-extension: "hostname1, hostname2"

Exemplo

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-multisite
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/hostname-extension: "hostname1, hostname2"
spec:
  rules:
  - host: contoso.com
    http:
      paths:
      - path: /
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 443

O exemplo anterior configura o ouvinte para aceitar tráfego para os nomes hostname1.contoso.com de host e hostname2.contoso.com.

Política do WAF para o caminho

Use a anotação a seguir para anexar uma política de firewall de aplicativo Web (WAF) existente aos caminhos de lista para um host dentro de um recurso de entrada do Kubernetes que está sendo anotado. A política WAF é aplicada a ambos e /ad-server /auth URLs.

Utilização

appgw.ingress.kubernetes.io/waf-policy-for-path: "/subscriptions/aaaa0000-bb11-2222-33cc-444444dddddd/resourceGroups/SampleRG/providers/Microsoft.Network/applicationGatewayWebApplicationFirewallPolicies/AGICWAFPolcy"

Exemplo

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ad-server-ingress
  namespace: commerce
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/waf-policy-for-path: "/subscriptions/abcd/resourceGroups/rg/providers/Microsoft.Network/applicationGatewayWebApplicationFirewallPolicies/adserver"
spec:
  rules:
  - http:
      paths:
      - path: /ad-server
        backend:
          service:
            name: ad-server
            port:
              number: 80
        pathType: Exact
      - path: /auth
        backend:
          service:
            name: auth-server
            port:
              number: 80
        pathType: Exact

Certificado SSL do Application Gateway

Você pode configurar o certificado SSL para o Gateway de Aplicativo a partir de um arquivo de certificado PFX local ou de uma referência a uma ID secreta sem versão do Cofre da Chave do Azure. Quando a anotação está presente com um nome de certificado e o certificado é pré-instalado no Application Gateway, o controlador de entrada do Kubernetes cria uma regra de roteamento com um ouvinte HTTPS e aplica as alterações à sua instância do Application Gateway. Você também pode usar a appgw-ssl-certificate anotação junto com uma ssl-redirect anotação no caso de um redirecionamento SSL.

Utilização

appgw.ingress.kubernetes.io/appgw-ssl-certificate: "name-of-appgw-installed-certificate"

Exemplo

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-certificate
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/appgw-ssl-certificate: "name-of-appgw-installed-certificate"
spec:
  rules:
  - host: www.contoso.com
    http:
      paths:
      - backend:
          service:
            name: websocket-repeater
            port:
              number: 80

Perfil SSL do Application Gateway

Você pode configurar um perfil SSL na instância do Application Gateway por ouvinte. Quando a anotação está presente com um nome de perfil e o perfil é pré-instalado no Application Gateway, o controlador de entrada do Kubernetes cria uma regra de roteamento com um ouvinte HTTPS e aplica as alterações à sua instância do Application Gateway.

Utilização

appgw.ingress.kubernetes.io/appgw-ssl-certificate: "name-of-appgw-installed-certificate"
appgw.ingress.kubernetes.io/appgw-ssl-profile: "SampleSSLProfile"

Exemplo

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-certificate
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/appgw-ssl-certificate: "name-of-appgw-installed-certificate"
    appgw.ingress.kubernetes.io/appgw-ssl-profile: "SampleSSLProfile"
spec:
  rules:
  - host: www.contoso.com
    http:
      paths:
      - backend:
          service:
            name: websocket-repeater
            port:
              number: 80

Certificado raiz confiável do Application Gateway

Agora você pode configurar seus próprios certificados raiz para o Application Gateway para serem confiáveis via AGIC. Você pode usar a appgw-trusted-root-certificate anotação junto com a backend-protocol anotação para indicar criptografia SSL de ponta a ponta. Se você especificar vários certificados raiz, separe-os com uma vírgula; por exemplo, name-of-my-root-cert1,name-of-my-root-cert2.

Utilização

appgw.ingress.kubernetes.io/backend-protocol: "https"
appgw.ingress.kubernetes.io/appgw-trusted-root-certificate: "name-of-my-root-cert1"

Exemplo

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-certificate
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/backend-protocol: "https"
    appgw.ingress.kubernetes.io/appgw-trusted-root-certificate: "name-of-my-root-cert1"
spec:
  rules:
  - host: www.contoso.com
    http:
      paths:
      - backend:
          service:
            name: websocket-repeater
            port:
              number: 80

Reescrever conjunto de regras

Use a anotação a seguir para atribuir um conjunto de regras de regravação existente à regra de roteamento de solicitação correspondente.

Utilização

appgw.ingress.kubernetes.io/rewrite-rule-set: <rewrite rule set name>

Exemplo

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-bkprefix
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/rewrite-rule-set: add-custom-response-header
spec:
  rules:
  - http:
      paths:
      - path: /
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 8080

Reescrever recurso personalizado do conjunto de regras

O Application Gateway permite reescrever conteúdos selecionados de solicitações e respostas. Com esse recurso, você pode traduzir URLs, alterar parâmetros de cadeia de caracteres de consulta e modificar cabeçalhos de solicitação e resposta. Você também pode usar esse recurso para adicionar condições para garantir que a URL ou os cabeçalhos especificados sejam reescritos somente quando determinadas condições forem atendidas. Reescrever recurso personalizado do conjunto de regras traz esse recurso para o AGIC.

Os cabeçalhos HTTP permitem que um cliente e um servidor passem informações adicionais com uma solicitação ou resposta. Ao reescrever esses cabeçalhos, você pode realizar tarefas importantes, como adicionar campos de cabeçalho relacionados à segurança (por exemplo, HSTS ou X-XSS-Protection), remover campos de cabeçalho de resposta que podem revelar informações confidenciais e remover informações de porta de X-Forwarded-For cabeçalhos.

Com o recurso de regravação de URL, você pode:

• Reescreva o nome do host, o caminho e a cadeia de caracteres de consulta da URL da solicitação.
• Opte por reescrever o URL de todos os pedidos ou apenas pedidos que correspondam a uma ou mais das condições que definiu. Essas condições são baseadas nas propriedades de solicitação e resposta (cabeçalho da solicitação, cabeçalho da resposta e variáveis de servidor).
• Escolha encaminhar a solicitação com base no URL original ou no URL reescrito.

Utilização

appgw.ingress.kubernetes.io/rewrite-rule-set-custom-resource

Exemplo

apiVersion: appgw.ingress.azure.io/v1beta1 
kind: AzureApplicationGatewayRewrite 
metadata: 
  name: my-rewrite-rule-set-custom-resource 
spec: 
  rewriteRules: 
  - name: rule1 
    ruleSequence: 21
    conditions:
  - ignoreCase: false
    negate: false
    variable: http_req_Host
    pattern: example.com
  actions:
    requestHeaderConfigurations:
    - actionType: set
      headerName: incoming-test-header
      headerValue: incoming-test-value
    responseHeaderConfigurations:
    - actionType: set
      headerName: outgoing-test-header
      headerValue: outgoing-test-value
    urlConfiguration:
      modifiedPath: "/api/"
      modifiedQueryString: "query=test-value"
      reroute: false

Prioridade das Regras

A anotação a seguir permite que o controlador de entrada do Application Gateway defina explicitamente a prioridade das regras de roteamento de solicitação associadas.

Utilização

appgw.ingress.kubernetes.io/rule-priority:

Exemplo

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-rulepriority
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/rule-priority: 10
spec:
  rules:
  - http:
      paths:
      - path: /
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 8080

O exemplo anterior define uma prioridade de 10 para a regra de roteamento de solicitação.