Anotações do Controlador de Entrada do Gateway de Aplicativo
Você pode anotar o recurso de entrada do Kubernetes com pares de chave/valor arbitrários. O Controlador de Entrada do Gateway de Aplicativo (AGIC) depende de anotações para programar os recursos do Gateway de Aplicativo do Azure que não são configuráveis por meio do YAML de entrada. As anotações de entrada são aplicadas a todas as configurações de HTTP, pools de back-end e ouvintes derivados de um recurso de entrada.
Dica
Consulte também O que é Gateway de Aplicativo para Contêineres.
Lista de anotações com suporte
Para que o AGIC observe um recurso de entrada, o recurso precisa estar 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-a para expor serviços cujos pontos de extremidade sejam diferentes dos nomes de ponto de extremidade que você usa para expor um serviço em um recurso de entrada.
Uso
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 chamado go-server-ingress-bkprefix com uma anotação chamada appgw.ingress.kubernetes.io/backend-path-prefix: "/test/". A anotação pede ao Gateway de Aplicativo para criar uma configuração de HTTP que tenha uma substituição de prefixo de caminho do caminho /hello para /test/.
O exemplo define apenas uma regra. No entanto, as anotações se aplicam ao recurso de entrada inteiro. Portanto, se você definir várias regras, deverá configurar o prefixo do caminho de back-end para cada um dos caminhos especificados. Se quiser regras diferentes com prefixos de caminho diferentes (mesmo que para o mesmo serviço), você vai 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 Gateway de Aplicativo deve usar ao conversar com os pods.
Uso
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
Investigação de integridade personalizada
Você pode configurar o Gateway de Aplicativo para enviar investigações de integridade personalizadas 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 investigação personalizada para monitorar o aplicativo de back-end. Em seguida, o controlador aplica as alterações ao Gateway de Aplicativo.
health-probe-hostname: essa anotação permite um nome de host personalizado na investigação de integridade.health-probe-port: essa anotação configura uma porta personalizada para a investigação de integridade.health-probe-path: essa anotação define um caminho para a investigação de integridade.health-probe-status-code: essa anotação permite que a investigação de integridade aceite códigos de status HTTP diferentes.health-probe-interval: essa anotação define o intervalo no qual a investigação de integridade é executada.health-probe-timeout: essa anotação define por quanto tempo a investigação de integridade deve aguardar uma resposta antes de decidir que a investigação falhou.health-probe-unhealthy-threshold: essa anotação define quantas investigações de integridade precisam falhar para que o back-end seja marcado como não íntegro.
Uso
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 de TLS
Você pode configurar o Gateway de Aplicativo para redirecionar as URLs HTTP automaticamente para as respectivas contrapartes em HTTPS. Quando essa anotação estiver presente e o TLS estiver configurado corretamente, o controlador de entrada do Kubernetes criará uma regra de roteamento com uma configuração de redirecionamento. Em seguida, o controlador aplica as alterações à sua instância do Gateway de Aplicativo. O redirecionamento criado é um HTTP 301 Moved Permanently.
Uso
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
Esvaziamento de Conexões
Use as anotações a seguir se quiser usar o esvaziamento de conexões:
connection-draining: essa anotação especifica se o esvaziamento de conexões deve ser habilitado.connection-draining-timeout: essa anotação especifica um tempo limite após o qual o Gateway de Aplicativo encerra as solicitações para o ponto de extremidade de back-end de esvaziamento.
Uso
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.
Uso
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 da Solicitação
Use a anotação a seguir para especificar o tempo limite da solicitação em segundos. Após o tempo limite ser atingido, o Gateway de Aplicativo irá determinar que uma solicitação falhou se a resposta não for recebida.
Uso
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 Gateway de Aplicativo.
Para uma instância do Gateway de Aplicativo 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 eventos de entrada para essas entradas mostram um aviso de NoPrivateIP.
Uso
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
Substituição da porta de front-end
Use a anotação a seguir para configurar um ouvinte de front-end para usar portas diferentes de 80 para HTTP e 443 para HTTPS.
Se a porta estiver dentro do intervalo autorizado do Gateway de Aplicativo (1 a 64999), o ouvinte será criado nessa porta específica. Se você definir uma porta inválida ou porta nenhuma na anotação, a configuração usará o padrão de 80 ou 443.
Uso
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
Observação
A solicitação externa precisa ser direcionada a http://somehost:8080 em vez de http://somehost.
Protocolo de Back-end
Use o seguinte para especificar o protocolo que o Gateway de Aplicativo deve usar quando se comunicar com os pods. Os protocolos com suporte são HTTP e HTTPS.
Embora os certificados autoassinados tenham suporte no Gateway de Aplicativo, o AGIC atualmente dá suporte a HTTPS somente quando os pods usam um certificado assinado por uma autoridade de certificação de boa reputação.
Não use a porta 80 com HTTPS e a porta 443 com HTTP nos Pods.
Uso
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 de nome do host
Você pode configurar o Gateway de Aplicativo para aceitar vários nomes de host. Use a anotação hostname-extension para definir vários nomes de host, incluindo nomes de host com caracteres curinga. Essa ação anexa os nomes de host ao FQDN que estiver definido nas informações de spec.rules.host de entrada no ouvinte de front-end, de forma que este seja configurado como um ouvinte multissite.
Uso
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 o tráfego para os nomes de host hostname1.contoso.com e hostname2.contoso.com.
Política de WAF para 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 de WAF é aplicada tanto às URLs de /ad-server quanto de /auth.
Uso
appgw.ingress.kubernetes.io/waf-policy-for-path: "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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 Gateway de Aplicativo
Você pode configurar o certificado SSL para o Gateway de Aplicativo tanto a partir de um arquivo de certificado PFX local quanto de uma referência a uma ID secreta do Azure Key Vault sem controle de versão. Quando a anotação estiver presente com um nome de certificado e o certificado tiver sido pré-instalado no Gateway de Aplicativo, o controlador de entrada do Kubernetes criará uma regra de roteamento com um ouvinte HTTPS e aplicará as alterações à sua instância do Gateway de Aplicativo. Você também pode usar a anotação de appgw-ssl-certificate junto com uma anotação de ssl-redirect no caso de um redirecionamento SSL.
Observação
A anotação de appgw-ssl-certificate é ignorada quando a especificação do TLS é definida na entrada ao mesmo tempo. Se quiser certificados diferentes com hosts diferentes (terminação de vários certificados TLS), você vai precisar definir diferentes recursos de entrada.
Uso
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 Gateway de Aplicativo
Você pode configurar um perfil de SSL na instância do Gateway de Aplicativo para cada ouvinte. Quando a anotação estiver presente com um nome de perfil e o perfil tiver sido pré-instalado no Gateway de Aplicativo, o controlador de entrada do Kubernetes criará uma regra de roteamento com um ouvinte HTTPS e aplicará as alterações à sua instância do Gateway de Aplicativo.
Uso
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 Gateway de Aplicativo
Agora você pode configurar seus próprios certificados raiz para o Gateway de Aplicativo para serem confiáveis por meio do AGIC. Você pode usar a anotação de appgw-trusted-root-certificate junto com a anotação de backend-protocol para indicar uma 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.
Uso
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
Regenerar o conjunto de regras
Use a anotação a seguir para atribuir um conjunto de regras de reescrita existente à regra de roteamento de solicitação correspondente.
Uso
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 o recurso personalizado de conjunto de regras
Observação
A versão do Gateway de Aplicativo para Contêineres introduz várias alterações de desempenho, resiliência e recursos. Pense em aproveitar o Gateway de Aplicativo para Contêineres na sua próxima implantação.
Você pode encontrar as regras de reescrita de URL para o Gateway de Aplicativo para Contêineres neste artigo sobre a API do Gateway e neste artigo sobre a API de Entrada. Você pode encontrar as regras de reescrita de cabeçalho para o Gateway de Aplicativo para Contêineres neste artigo sobre a API do Gateway.
O Gateway de Aplicativo permite que você reescreva o conteúdo selecionado 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 as condições que garantam que a URL ou os cabeçalhos especificados sejam reescritos apenas quando determinadas condições forem atendidas. Reescrever o 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 possam revelar informações confidenciais e remover informações de porta de cabeçalhos X-Forwarded-For.
Com a funcionalidade de reescrita de URL, você pode:
- Reescrever o nome do host, o caminho e a cadeia de caracteres de consulta da URL de solicitação.
- Optar por reescrever a URL de todas as solicitações em um ouvinte ou apenas as solicitações que correspondam a uma ou mais das condições que você definir. Essas condições se baseiam nas propriedades da solicitação e da resposta (cabeçalho da solicitação, cabeçalho da resposta e variáveis do servidor).
- Optar por rotear a solicitação com base na URL original ou na URL reescrita.
Observação
Esse recurso tem suporte desde a versão 1.6.0-rc1. Use appgw.ingress.kubernetes.io/rewrite-rule-set, que permite usar um conjunto de regras de reescrita existente no Gateway de Aplicativo.
Uso
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 da regra
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.
Uso
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 estabelece uma prioridade de 10 para a regra de roteamento de solicitação.