Anotaciones para el controlador de entrada de Application Gateway
Puede anotar el recurso de entrada de Kubernetes con pares clave-valor arbitrarios. El controlador de entrada de Application Gateway (AGIC) depende de las anotaciones para programar las características de Azure Application Gateway, que no se pueden configurar a través del YAML de entrada. Las anotaciones de entrada se aplican a todas las configuraciones HTTP, los grupos de back-end y los clientes de escucha derivados de un recurso de entrada.
Sugerencia
Consulte también ¿Qué es la Puerta de enlace de aplicaciones para contenedores?.
Lista de anotaciones admitidas
Para que AGIC observe un recurso de entrada, el recurso debe anotarse con kubernetes.io/ingress.class: azure/application-gateway.
Prefijo de ruta de acceso de back-end
La anotación siguiente permite volver a escribir la ruta de acceso de back-end especificada en un recurso de entrada con el prefijo especificado. Úselo para exponer servicios cuyos puntos de conexión son diferentes de los nombres de puntos de conexión que usó para exponer un servicio en un recurso de entrada.
Uso
appgw.ingress.kubernetes.io/backend-path-prefix: <path prefix>
Ejemplo
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
El ejemplo anterior define un recurso de entrada denominado go-server-ingress-bkprefix con una anotación denominada appgw.ingress.kubernetes.io/backend-path-prefix: "/test/". La anotación le indica a Application Gateway que cree una configuración de HTTP, que tiene una invalidación de prefijo de ruta de acceso para la ruta de acceso /hello en /test/.
El ejemplo define solo una regla. Sin embargo, las anotaciones se aplican a todo el recurso de entrada. Por lo tanto, si define varias reglas, configure el prefijo de ruta de acceso de back-end para cada una de las rutas de acceso especificadas. Si quiere tener diferentes reglas con prefijos de ruta de acceso diferentes (incluso para el mismo servicio), tendrá que definir diferentes recursos de entrada.
Nombre de host de back-end
Use la siguiente anotación para especificar el nombre de host que Application Gateway debe usar al comunicarse con los pods.
Uso
appgw.ingress.kubernetes.io/backend-hostname: "internal.example.com"
Ejemplo
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
Sondeo de estado personalizado
Puede configurar Application Gateway para enviar sondeos de estado personalizados al grupo de direcciones de back-end. Cuando las siguientes anotaciones están presentes, el controlador de entrada de Kubernetes crea un sondeo personalizado para supervisar la aplicación back-end. A continuación, el controlador aplica los cambios a Application Gateway.
health-probe-hostname: esta anotación permite un nombre de host personalizado en el sondeo de estado.health-probe-port: esta anotación configura un puerto personalizado para el sondeo de estado.health-probe-path: esta anotación define una ruta de acceso para el sondeo de estado.health-probe-status-code: esta anotación permite que el sondeo de estado acepte códigos de estado HTTP diferentes.health-probe-interval: esta anotación define el intervalo en el que se ejecuta el sondeo de estado.health-probe-timeout: esta anotación define cuánto tiempo espera el sondeo de estado antes de que se produzca un error en el sondeo.health-probe-unhealthy-threshold: esta anotación define cuántos sondeos de estado deben producir un error para que el back-end se marque como incorrecto.
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
Ejemplo
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
Redirección de TLS
Puede configurar Application Gateway para redirigir automáticamente las direcciones URL HTTP a sus equivalentes HTTPS. Cuando esta anotación está presente y TLS está configurado correctamente, el controlador de entrada de Kubernetes crea una regla de enrutamiento con una configuración de redireccionamiento. A continuación, el controlador aplica los cambios a su instancia de Application Gateway. El redireccionamiento creado es HTTP 301 Moved Permanently.
Uso
appgw.ingress.kubernetes.io/ssl-redirect: "true"
Ejemplo
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
Purga de la conexión
Use las siguientes anotaciones si desea usar el drenaje de conexiones:
connection-draining: esta anotación especifica si se habilita el drenaje de conexiones.connection-draining-timeout: esta anotación especifica un tiempo de espera después del cual Application Gateway finaliza las solicitudes al punto de conexión de back-end de drenaje.
Uso
appgw.ingress.kubernetes.io/connection-draining: "true"
appgw.ingress.kubernetes.io/connection-draining-timeout: "60"
Ejemplo
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
Afinidad basada en cookies
Use la anotación siguiente para habilitar la afinidad basada en cookies.
Uso
appgw.ingress.kubernetes.io/cookie-based-affinity: "true"
Ejemplo
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
Tiempo de espera de solicitud
Use la siguiente anotación para especificar el tiempo de espera de la solicitud en segundos. Después del tiempo de espera, Application Gateway produce un error en una solicitud si no se recibe la respuesta.
Uso
appgw.ingress.kubernetes.io/request-timeout: "20"
Ejemplo
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
Uso de una dirección IP privada
Use la anotación siguiente para especificar si se va a exponer este punto de conexión en la dirección IP privada de Application Gateway.
En el caso de una instancia de Application Gateway sin una dirección IP privada, se omiten las entradas anotadas con appgw.ingress.kubernetes.io/use-private-ip: "true". Los registros del controlador y los eventos de entrada de dichas entradas muestra una advertencia NoPrivateIP.
Uso
appgw.ingress.kubernetes.io/use-private-ip: "true"
Ejemplo
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
Invalidar el puerto de front-end
Use la anotación siguiente para configurar un cliente de escucha de front-end para usar puertos diferentes distintos de 80 para HTTP y 443 para HTTPS.
Si el puerto está dentro del intervalo autorizado de Application Gateway (1 a 64999), este cliente de escucha se crea en este puerto específico. Si establece un puerto no válido o ningún puerto en la anotación, la configuración usa el valor predeterminado 80 o 443.
Uso
appgw.ingress.kubernetes.io/override-frontend-port: "port"
Ejemplo
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:
La solicitud externa debe tener como destino http://somehost:8080 en lugar de http://somehost.
Protocolo de back-end
Use la anotación siguiente para especificar el protocolo que Application Gateway debe usar al comunicarse con los pods. Los protocolos compatibles son HTTP y HTTPS.
Aunque los certificados autofirmados se admiten en Application Gateway, actualmente AGIC solo admite HTTPS cuando los pods usan un certificado que firma una entidad de certificación conocida.
No use el puerto 80 con HTTPS ni el puerto 443 con HTTP en los pods.
Uso
appgw.ingress.kubernetes.io/backend-protocol: "https"
Ejemplo
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
Extensión de nombre de host
Puede configurar Application Gateway para aceptar varios nombres de host. Use la anotación hostname-extension para definir varios nombres de host, incluidos los nombres de host comodín. Esta acción anexa los nombres de host al FQDN que se define en la información spec.rules.host de entrada en el cliente de escucha de front-end, por lo que se configura como un cliente de escucha multisitio.
Uso
appgw.ingress.kubernetes.io/hostname-extension: "hostname1, hostname2"
Ejemplo
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
En el ejemplo anterior se configura el cliente de escucha para aceptar el tráfico de los nombres de host hostname1.contoso.com y hostname2.contoso.com.
Directiva de WAF para ruta de acceso
Use la siguiente anotación para adjuntar una directiva de firewall de aplicaciones web (WAF) existente a las rutas de acceso de lista de un host dentro de un recurso de entrada de Kubernetes que se está anotando. La directiva WAF se aplica tanto a las URL /ad-server como a /auth.
Uso
appgw.ingress.kubernetes.io/waf-policy-for-path: "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/SampleRG/providers/Microsoft.Network/applicationGatewayWebApplicationFirewallPolicies/AGICWAFPolcy"
Ejemplo
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 de Application Gateway
Puede configurar el certificado SSL en Application Gateway desde un archivo de certificado PFX local o una referencia a un identificador de secreto sin versión de Azure Key Vault. Cuando la anotación está presente con un nombre de certificado y el certificado está preinstalado en Application Gateway, el controlador de entrada de Kubernetes crea una regla de enrutamiento con un cliente de escucha HTTPS y aplica los cambios a su instancia de Application Gateway. También puede usar la anotación appgw-ssl-certificate junto con una anotación ssl-redirect en el caso de una redirección SSL.
Nota:
La anotación appgw-ssl-certificate se omite cuando se define la especificación TLS en entrada al mismo tiempo. Si quiere certificados diferentes con diferentes hosts (terminación de certificado de varios TLS), tiene que definir recursos de entrada diferentes.
Uso
appgw.ingress.kubernetes.io/appgw-ssl-certificate: "name-of-appgw-installed-certificate"
Ejemplo
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 de Application Gateway
Puede configurar un perfil SSL en una instancia de Application Gateway por cliente de escucha. Cuando la anotación está presente con un nombre de perfil y el perfil está preinstalado en Application Gateway, el controlador de entrada de Kubernetes crea una regla de enrutamiento con un cliente de escucha HTTPS y aplica los cambios a su instancia de Application Gateway.
Uso
appgw.ingress.kubernetes.io/appgw-ssl-certificate: "name-of-appgw-installed-certificate"
appgw.ingress.kubernetes.io/appgw-ssl-profile: "SampleSSLProfile"
Ejemplo
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 raíz de confianza de Application Gateway
Ahora puede configurar sus propios certificados raíz en Application Gateway para que sean de confianza a través de AGIC. Puede usar la anotación appgw-trusted-root-certificate junto con la anotación backend-protocol para indicar el cifrado SSL de un extremo a otro. Si especifica varios certificados raíz, sepárelos con una coma; por ejemplo, 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"
Ejemplo
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
Conjunto de reglas de reescritura
Use la anotación siguiente para asignar un conjunto de reglas de reescritura existente a la regla de enrutamiento de solicitudes correspondiente.
Uso
appgw.ingress.kubernetes.io/rewrite-rule-set: <rewrite rule set name>
Ejemplo
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
Recurso de reescritura del conjunto de reglas personalizado
Nota:
La publicación de Puerta de enlace de aplicaciones para contenedores presenta numerosos cambios de rendimiento, resistencia y características. Considere la posibilidad de usar Puerta de enlace de aplicaciones para contenedores para su siguiente implementación.
Puede encontrar reglas de reescritura de URL para Puerta de enlace de aplicaciones para contenedores en este artículo sobre la API de puerta de enlace y este artículo sobre la API de entrada. Puede encontrar reglas de reescritura de encabezado para Puerta de enlace de aplicaciones para contenedores en este artículo sobre la API de puerta de enlace.
Application Gateway permite volver a escribir los contenidos seleccionados de las solicitudes y las respuestas. Con esta característica, puede traducir direcciones URL, cambiar parámetros de cadena de consulta y modificar encabezados de solicitud y respuesta. También puede usar esta característica para agregar las condiciones necesarias para asegurarse de que los encabezados especificados y las direcciones URL se reescriben solo cuando se cumplen ciertas condiciones. Reescribir el recurso personalizado del conjunto de reglas lleva esta característica a AGIC.
Los encabezados HTTP permiten que el cliente y el servidor pasen información adicional con la solicitud o la respuesta. Al reescribir estos encabezados, puede realizar tareas importantes, como agregar campos de encabezado relacionados con la seguridad (por ejemplo, HSTS o X-XSS-Protection), quitar campos de encabezado de respuesta que pueden revelar información confidencial o eliminar información de puertos de los encabezados X-Forwarded-For.
Con la funcionalidad de reescritura de URL, puede hacer lo siguiente:
- Volver a escribir el nombre de host, la ruta de acceso y la cadena de consulta de la dirección URL de solicitud.
- Elija volver a escribir la dirección URL de todas las solicitudes o solo las solicitudes que coincidan con una o varias de las condiciones establecidas. Estas condiciones se basan en las propiedades de solicitud y respuesta (solicitud, encabezado, encabezado de respuesta y variables de servidor).
- Elegir enrutar la solicitud en función de la dirección URL original o de la dirección URL reescrita.
Nota:
Esta característica se admite desde 1.6.0-rc1. Use appgw.ingress.kubernetes.io/rewrite-rule-set, que permite usar un conjunto de reglas de reescritura existente en Application Gateway.
Uso
appgw.ingress.kubernetes.io/rewrite-rule-set-custom-resource
Ejemplo
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
Prioridad de las reglas
La siguiente anotación permite que el controlador de entrada de Application Gateway establezca explícitamente la prioridad de las reglas de enrutamiento de solicitudes asociadas.
Uso
appgw.ingress.kubernetes.io/rule-priority:
Ejemplo
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
En el ejemplo anterior se establece una prioridad de 10 para la regla de enrutamiento de solicitudes.