Partilhar via

Anotações para o Application Gateway Ingress Controller

  • Artigo

O recurso Kubernetes Ingress pode ser anotado com pares arbitrários de chave/valor. A AGIC depende de anotações para programar recursos do Application Gateway, que não são configuráveis usando o Ingress YAML. 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 um recurso Ingress seja observado pela AGIC, ele deve ser anotado com kubernetes.io/ingress.class: azure/application-gateway. Só então a AGIC trabalha com o recurso Ingress em questão.

Chave de anotação Tipo de Valor Valor Predefinido Valores Permitidos
appgw.ingress.kubernetes.io/backend-path-prefix string nil
appgw.ingress.kubernetes.io/backend-hostname string nil
appgw.ingress.kubernetes.io/health-probe-hostname string 127.0.0.1
appgw.ingress.kubernetes.io/health-probe-port int32 80
appgw.ingress.kubernetes.io/health-probe-path string /
appgw.ingress.kubernetes.io/health-probe-status-code string 200-399
appgw.ingress.kubernetes.io/health-probe-interval int32 30 (segundos)
appgw.ingress.kubernetes.io/health-probe-timeout int32 30 (segundos)
appgw.ingress.kubernetes.io/health-probe-unhealthy-threshold int32 3
appgw.ingress.kubernetes.io/ssl-redirect bool false
appgw.ingress.kubernetes.io/connection-draining bool false
appgw.ingress.kubernetes.io/connection-draining-timeout int32 (segundos) 30
appgw.ingress.kubernetes.io/use-private-ip bool false
appgw.ingress.kubernetes.io/override-frontend-port bool false
appgw.ingress.kubernetes.io/cookie-based-affinity bool false
appgw.ingress.kubernetes.io/request-timeout int32 (segundos) 30
appgw.ingress.kubernetes.io/use-private-ip bool false
appgw.ingress.kubernetes.io/backend-protocol string http http, https
appgw.ingress.kubernetes.io/hostname-extension string nil
appgw.ingress.kubernetes.io/waf-policy-for-path string nil
appgw.ingress.kubernetes.io/appgw-ssl-certificate string nil
appgw.ingress.kubernetes.io/appgw-ssl-profile string nil
appgw.ingress.kubernetes.io/appgw-trusted-root-certificate string nil
appgw.ingress.kubernetes.io/rewrite-rule-set string nil
appgw.ingress.kubernetes.io/rewrite-rule-set-custom-resource
appgw.ingress.kubernetes.io/rule-priority int32 nil

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 nessa anotação. Ele permite que os usuários exponham serviços cujos pontos de extremidade são diferentes dos nomes de ponto de extremidade usados 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

No exemplo anterior, você definiu um recurso de entrada nomeado go-server-ingress-bkprefix com uma anotação appgw.ingress.kubernetes.io/backend-path-prefix: "/test/". A anotação informa ao gateway de aplicativo para criar uma configuração HTTP, que tem uma substituição de prefixo de caminho para o caminho /hello para /test/.

Nota

No exemplo acima, apenas uma regra é definida. No entanto, as anotações são aplicáveis a todo o recurso de entrada, portanto, se um usuário definisse várias regras, o prefixo do caminho de back-end seria configurado para cada um dos caminhos especificados. Se um usuário quiser regras diferentes com prefixos de caminho diferentes (mesmo para o mesmo serviço), ele precisará definir recursos de entrada diferentes.

Nome do host de back-end

Essa anotação nos permite 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

O Application Gateway pode ser configurado para enviar testes de integridade personalizados para o pool de endereços de back-end. Quando essas anotações estão presentes, o controlador Kubernetes Ingress cria uma sonda personalizada para monitorar o aplicativo back-end e aplica as alterações ao gateway de aplicativo.

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 de teste de integridade personalizada.
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 em que a sonda de integridade é executada.
health-probe-timeout: Esta anotação define quanto tempo a sonda de integridade aguardará 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

O Application Gateway pode ser configurado para redirecionar automaticamente URLs HTTP para suas contrapartes HTTPS. Quando essa anotação está presente e o TLS está configurado corretamente, o controlador Kubernetes Ingress cria uma regra de roteamento com uma configuração de redirecionamento e aplica as alterações ao seu Application Gateway. O redirecionamento criado será 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

connection-draining: Esta anotação nos permite especificar se a drenagem de conexão deve ser ativada. connection-draining-timeout: Essa anotação nos permite especificar 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

A anotação a seguir permite que você especifique se deseja 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

A anotação a seguir permite especificar o tempo limite da solicitação em segundos, após o qual o Application Gateway falhará na 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

A anotação a seguir permite especificar se esse ponto de extremidade deve ser exposto no IP privado do Application Gateway.

Nota

  • Para o Application Gateway que não tem um IP privado, Ingresses with appgw.ingress.kubernetes.io/use-private-ip: "true" é ignorado. Isso se reflete nos logs do controlador e nos eventos de entrada para essas entradas com 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

A anotação permite configurar um ouvinte frontend para usar portas diferentes de 80/443 para http/https.

Se a porta estiver dentro do intervalo autorizado do App Gw (1 - 64999), esse ouvinte será criado nessa porta específica. Se uma porta inválida ou nenhuma porta for definida na anotação, a configuração retornará ao padrão 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

Nota

Solicitação externa precisará segmentar http://somehost:8080 em vez de http://somehost.

Protocolo de back-end

A anotação a seguir permite especificar o protocolo que o Application Gateway deve usar durante a comunicação com os pods. Os protocolos suportados são http e https.

Nota

Embora os certificados autoassinados sejam suportados no Application Gateway, atualmente o AGIC só oferece suporte https quando os pods estão usando um certificado assinado por uma CA 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

O Application Gateway pode ser configurado para aceitar vários nomes de host. A anotação de extensão de nome de host permite isso, permitindo que você defina vários nomes de host, incluindo nomes de host curinga. Isso acrescentará os nomes de host ao FQDN definido no ingress spec.rules.host no ouvinte frontend para que ele seja 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

Nota

No exemplo acima, o ouvinte seria configurado para aceitar tráfego para os nomes de host "hostname1.contoso.com" e "hostname2.contoso.com"

Política do WAF para o caminho

Essa anotação permite anexar uma política WAF já criada aos caminhos de lista para um host dentro de um recurso de Ingresso do Kubernetes que está sendo anotado.

Utilização

appgw.ingress.kubernetes.io/waf-policy-for-path: "/subscriptions/00000000-0000-0000-0000-000000000000/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

Nota

A política WAF será aplicada às URLs /ad-server e /auth.

Certificado SSL do Application Gateway

O certificado SSL pode ser configurado 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 estiver presente com um nome de certificado e o certificado estiver pré-instalado no Application Gateway, o controlador Kubernetes Ingress criará uma regra de roteamento com um ouvinte HTTPS e aplicará as alterações ao seu App Gateway. A anotação appgw-ssl-certificate também pode ser usada em conjunto com a anotação ssl-redirect em caso de redirecionamento SSL.

Consulte o recurso appgw-ssl-certificate para obter mais detalhes.

Nota

A anotação "appgw-ssl-certificate" será ignorada quando a especificação TLS for definida na entrada ao mesmo tempo. Se um usuário quiser certificados diferentes com hosts diferentes (terminação de certificado multi tls), ele precisará definir recursos de entrada diferentes.

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

Os usuários podem configurar um perfil ssl no Application Gateway por ouvinte. Quando a anotação estiver presente com um nome de perfil e o perfil estiver pré-instalado no Application Gateway, o controlador Kubernetes Ingress criará uma regra de roteamento com um ouvinte HTTPS e aplicará as alterações ao seu App 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

Os usuários agora podem configurar seus próprios certificados raiz para o Application Gateway para serem confiáveis via AGIC. A anotação appgw-trusted-root-certificate pode ser usada em conjunto com o protocolo de back-end de anotação para indicar criptografia ssl de ponta a ponta, vários certificados raiz, separados por vírgula, se especificado, por exemplo, "name-of-my-root-cert1,name-of-my-root-certificate2".

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

A anotação a seguir permite 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

Nota

Foi lançado o Application Gateway for Containers , que introduz inúmeras alterações de desempenho, resiliência e recursos. Considere aproveitar o Application Gateway for Containers para sua próxima implantação. As regras de reconfiguração de URL para o Application Gateway for Containers podem ser encontradas aqui para a API do Gateway e aqui para a API de Ingresso. As regras de reconfiguração de cabeçalho para o Application Gateway for Containers podem ser encontradas aqui para a API do gateway.

Nota

Este recurso é suportado desde 1.6.0-rc1. Use appgw.ingress.kubernetes.io/rewrite-rule-set, que permite usar um conjunto de regras de reescrita existente no Application Gateway.

O Application Gateway permite reescrever o conteúdo selecionado de solicitações e respostas. Com esse recurso, você pode traduzir URLs, parâmetros de cadeia de caracteres de consulta, bem como modificar cabeçalhos de solicitação e resposta. Ele também permite que você adicione condições para garantir que a URL ou os cabeçalhos especificados sejam reescritos somente quando determinadas condições forem atendidas. Estas condições baseiam-se nas informações do pedido e da resposta. 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, como HSTS/ X-XSS-Protection, remover campos de cabeçalho de resposta que possam revelar informações confidenciais e remover informações de porta de cabeçalhos X-Forwarded-For.

Com o recurso de regravação de URL, você pode: - Reescrever o nome do host, o caminho e a cadeia de caracteres de consulta da URL da solicitação - Optar por reescrever a URL de todas as solicitações ou apenas as solicitações que correspondem a uma ou mais das condições que você 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 do servidor). - Escolha rotear 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

Essa anotação permite que o controlador de entrada do gateway de aplicativo 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

No exemplo acima, a regra de roteamento de solicitação teria uma prioridade de 10 set.