Annotations

Dernière publication : Oct 02, 2026
Related information
Configurer

Annotations d'entrée

Les annotations d'entrée suivantes sont prises en charge par NetScaler :
Annotations Type Obligatoire Description Par défaut Valeur possible
ingress.citrix.com/multicluster-policy-priority-order Chaîne Facultatif Lors de l'équilibrage de charge de différentes applications dans la configuration d'entrée multi-cluster, des stratégies de commutation de contenu distinctes sont créées pour chaque application. Dans de tels cas, si vous avez besoin d'une séquence particulière pour la liaison de stratégie, vous devez attribuer un numéro de priorité aux stratégies de commutation de contenu à l'aide de l'annotation ingress.citrix.com/multicluster-policy-priority-order. Pour plus d'informations, consultez Liaisons de stratégie. NA ingress.citrix.com/multicluster-policy-priority-order: '{"frontend": {"80": "3", "9443": "1"}, "backend": "2"}'
ingress.citrix.com/frontend-ip Chaîne Facultatif Spécifiez une adresse IP à utiliser comme adresse IP du serveur virtuel de commutation de contenu.Remarque : Il existe plusieurs façons de configurer l'adresse IP du serveur virtuel de commutation de contenu, telles que la configuration IPAM, le nsVIP par défaut, etc. N/A Adresse IP numérique. Par exemple, 1.2.3.4
ingress.citrix.com/frontend-ipset-name Chaîne Facultatif Spécifiez le nom de l'IPSET qui doit être lié au serveur virtuel de commutation de contenu. Utilisez cette annotation avec ingress.citrix.com/frontend-ip.Remarque : Le nom IPSET que vous spécifiez dans l'annotation doit déjà être configuré dans NetScaler. NA Nom de l'entité IPSET NetScaler
ingress.citrix.com/insecure-service-type Chaîne Facultatif Spécifiez les protocoles parmi HTTP/TCP/UDP/sip_UDP/any pour le serveur virtuel de commutation de contenu. http http, tcp, udp, sip_udp, ou any
ingress.citrix.com/insecure-port Chaîne Facultatif Configure le port pour le serveur virtuel de commutation de contenu pour les protocoles http/tcp/udp/sip_udp/any. 80 Numéro de port valide
ingress.citrix.com/secure-service-type Chaîne Facultatif Spécifiez les protocoles parmi SSL/SSL_TCP comme protocole pour le serveur virtuel de commutation de contenu. ssl ssl, ssl_tcp
ingress.citrix.com/secure-port Chaîne Facultatif Configurez le port pour le serveur virtuel de commutation de contenu pour le trafic HTTPS. 443 Numéro de port valide
ingress.citrix.com/insecure-termination Chaîne Facultatif Configurez le comportement pour le trafic HTTP. Utilisez allow pour autoriser le trafic HTTP ; utilisez redirect pour rediriger la requête HTTP vers HTTPS ; ou utilisez disallow si vous souhaitez abandonner le trafic HTTP. disallow allow, redirect, ou disallow
ingress.citrix.com/default-response-code Chaîne Facultatif Configurez la réponse par défaut que NetScaler envoie lorsqu'une requête atteint le serveur virtuel de commutation de contenu ou d'équilibrage de charge par défaut. Par exemple, lorsque la requête ne correspond à aucun hôte ou chemin configuré, ou lorsque le service backend n'a pas de points de terminaison prêts. Spécifiez le type d'action (respondwith, redirect ou respondwithhtmlpage), le code de réponse HTTP, et éventuellement une URL cible et une phrase de raison au format JSON. Pour plus d'informations, consultez Clé d'annotation ingress.citrix.com/default-response-code. N/A -
ingress.citrix.com/default-response-code: '{"type": "respondwithhtmlpage", "response-code": "521", "target": "https://status.example.com/service-unavailable.html", "reason-phrase": "Web server down"}'
ingress.citrix.com/secure-backend Chaîne/JSON Facultatif Spécifiez si vous souhaitez une connexion HTTPS sécurisée entre NetScaler et l'application Kubernetes backend. Si la valeur fournie est true ou false, elle s'applique à tous les services du fichier YAML d'entrée. Si vous souhaitez des paramètres différents pour chaque service, fournissez les valeurs au format JSON comme suit.Exemple : ingress.citrix.com/secure-backend: '{"app1":"True", "app2":"False", "app3":"True"}'. Ici, app1 et app3 communiqueront avec le backend via HTTPS. app2 sera en HTTP simple. False En tant que chaîne : True/False. En tant que JSON : '{"<Service_Name>": "True/False", ...}'.
ingress.citrix.com/backend-secret Chaîne/JSON Facultatif Spécifiez le certificat que vous souhaitez utiliser pour la communication backend entre NetScaler et les pods Kubernetes. N/A Sous forme de chaîne : "Kubernetes secret". Sous forme de JSON : '{"<Service_Name>": "<kubernetes secret>", ...}'
ingress.citrix.com/backend-ca-secret Chaîne/JSON Facultatif Spécifiez le certificat CA que vous souhaitez utiliser pour la communication backend entre NetScaler et les pods Kubernetes. N/A Sous forme de chaîne : "kubernetes secret" , Sous forme de JSON : '{"<Service_Name>": "<kubernetes secret>", ...}'
ingress.citrix.com/preconfigured-certkey JSON Facultatif Spécifiez les clés de certificat SSL déjà existantes sur NetScaler qui doivent être configurées pour le serveur virtuel de commutation de contenu.Exemple : ingress.citrix.com/preconfigured-certkey : '{"certs": [{"name": "certkey1", "type": "default"}, {"name": "certkey2", "type": "sni"}]}'. Ici, certkey1 est utilisé comme certificat par défaut non-SNI et certkey2 est utilisé comme certificat SNI. Voir cette section. N/A Un ou plusieurs noms d'entité sslcertkey NetScaler avec le type de certificat par défaut/sni/ca.
ingress.citrix.com/preconfigured-backend-certkey Chaîne Facultatif Spécifiez le nom d'une clé de certificat préconfigurée dans NetScaler à lier au groupe de services SSL de back-end. Ce certificat est envoyé au serveur pendant la négociation SSL pour l'authentification du serveur.Exemple : ingress.citrix.com/preconfigured-backend-certkey: '{"frontend-hotdrinks": "abc4cert", "coffee-beverage": "abc4cert"}' N/A Nom de l'entité sslcertkey NetScaler
ingress.citrix.com/preconfigured-backend-ca-certkey Chaîne Facultatif Spécifiez le nom d'une clé de certificat CA préconfigurée dans NetScaler à lier au groupe de services SSL de back-end pour l'authentification du serveur.Exemple : ingress.citrix.com/preconfigured-backend-ca-certkey: '{"frontend-hotdrinks": "ca3bun", "coffee-beverage": "ca3bun"}' N/A Nom de l'entité sslcertkey NetScaler
ingress.citrix.com/lbvserver JSON Facultatif Configure les paramètres de l'entité NetScaler LBVserver.Exemple : ingress.citrix.com/lbvserver: '{"app1":{"lbmethod":"SRCIPDESTIPHASH"}}'. Différents cas d'utilisation peuvent être réalisés en définissant ces paramètres. Voir cette section. N/A Paramètre d'entité NetScaler valide au format key:value.
ingress.citrix.com/servicegroup JSON Facultatif Configure les réglages/paramètres de l'entité NetScaler Servicegroup.Exemple : ingress.citrix.com/servicegroup: '{"appname":{"cip": "Enabled","cipHeader":"X-Forwarded-For"}}'. Différents cas d'utilisation peuvent être réalisés en définissant ces paramètres. Voir cette section. NA Paramètre d'entité NetScaler valide au format key:value.
ingress.citrix.com/monitor JSON Facultatif
  • Configure les paramètres/réglages de l'entité de surveillance NetScaler.Exemple : ingress.citrix.com/monitor: '{"appname":{"type":"http"}}'. Voir cette section.
  • Lier le même moniteur préconfiguré à plusieurs services backend.
 NA Paramètre d'entité NetScaler valide au format key:value.
Exemple : ingress.citrix.com/monitor: '{"appname": "<pre-configured-monitor-on-netscaler>", "appname2": "<pre-configured-monitor-on-netscaler>"}' .
  • Lier un moniteur préconfiguré différent à chaque service backend.Exemple : ingress.citrix.com/monitor: '{"appname": "<pre-configured-monitor1-on-netscaler>", "appname2": "<pre-configured-monitor2-on-netscaler>"}'.
ingress.citrix.com/deployment Chaîne Facultatif Créer une configuration de retour direct du serveur (DSR) sur NetScaler.Exemple : ingress.citrix.com/deployment: "dsr" NA dsr
ingress.citrix.com/path-match-method Chaîne Facultatif Spécifie la correspondance de chemin pour les applications dans l'ingress.Exemple : ingress.citrix.com/path-match-method: "prefix". Cette classe est maintenue pour la compatibilité ascendante. Utilisez pathType: dans la spécification à la place. prefix prefix ou exact.
ingress.citrix.com/ipam-range Chaîne Facultatif Sélectionnez une plage d'adresses IP particulière parmi un ensemble de plages spécifiées pour le contrôleur IPAM NetScaler.Exemple : ingress.citrix.com/ipam-range: 'Dev' NA Valeur correspondant à l'un des noms de plage configurés dans le contrôleur IPAM.
ingress.citrix.com/external-service JSON Facultatif Fournissez un nom de domaine pour configurer le serveur DNS sur NetScaler. Voir cette section.Exemple : ingress.citrix.com/external-service: '{"external-svc": {"domain": "www.externalsvc.com"}}' NA NA
ingress.citrix.com/canary-weight Chaîne Facultatif Spécifiez le pourcentage de trafic à diriger vers la version canary. Voir cette section.Exemple : ingress.citrix.com/canary-weight: "10" NA NA
ingress.citrix.com/canary-by-header Chaîne Facultatif Fournit une clé d'en-tête HTTP pour diriger le trafic vers la version canary. Voir cette section.Exemple : ingress.citrix.com/canary-by-header: 'some-header-info' NA
ingress.citrix.com/canary-by-header-value Liste Facultatif Fournissez des valeurs d'en-tête HTTP pour diriger le trafic vers la version canary. Voir cette section.Exemple : ingress.citrix.com/canary-by-header-value: '["value1","value2","value3"]' N/A Liste des valeurs d'en-tête sous forme de chaînes de caractères.
ingress.citrix.com/bot_crd Chaîne/JSON Facultatif Liez les stratégies créées par le CRD BOT au serveur virtuel d'équilibrage de charge de l'application. Voir cette section.Exemple : ingress.citrix.com/bot_crd: "botdefense" lie la stratégie à tous les services de l'ingress ou ingress.citrix.com/bot_crd: '{"appname": "botdefense"}' lie la stratégie uniquement au service frontal. N/A En tant que chaîne : "CRD_Instance_Name". En tant que JSON : '{"<Service_Name>":"CRD_Instance_Name"}'
ingress.citrix.com/ratelimit_crd Chaîne/JSON Facultatif Liez les stratégies créées par le CRD Ratelimit au serveur virtuel d'équilibrage de charge de l'application. Voir cette section. N/A En tant que chaîne : "CRD_Instance_Name". En tant que JSON : '{"<Service_Name>":"CRD_Instance_Name"}'.
Exemple : ingress.citrix.com/ratelimit_crd: "ratelimitexample" lie la politique à tous les services de l'ingress ou ingress.citrix.com/ratelimit_crd: '{"appname": "ratelimitexample"}' lie la politique uniquement au service frontal.
ingress.citrix.com/auth_crd Chaîne/JSON Facultatif Lie les politiques créées par Auth CRD au serveur virtuel d'équilibrage de charge de l'application. Voir cette section. N/A En tant que chaîne : "CRD_Instance_Name", En tant que JSON : {"<Service_Name>":"CRD_Instance_Name"}
Exemple : ingress.citrix.com/auth_crd: "authexample" lie la politique à tous les services de l'ingress ou ingress.citrix.com/auth_crd: '{"appname": "authexample"}' lie la politique uniquement au service frontal.
ingress.citrix.com/waf_crd String/JSON Facultatif Lie les politiques créées par le CRD WAF au serveur virtuel d'équilibrage de charge de l'application. Voir cette section. NA Sous forme de chaîne : "CRD_Instance_Name", Sous forme de JSON : '{"<Service_Name>":"CRD_Instance_Name"}'
Exemple : ingress.citrix.com/waf_crd: "wafbasic" lie la politique à tous les services de l'ingress ou ingress.citrix.com/waf_crd: '{"appname": "wafbasic"}' lie la politique uniquement au service frontal
ingress.citrix.com/rewrite_responder_crd Chaîne/JSON Facultatif Lie les stratégies créées par le CRD Rewrite-Responder au serveur virtuel d'équilibrage de charge de l'application. Voir cette section. NA Sous forme de chaîne : "CRD_Instance_Name", Sous forme de JSON : '{"<Service_Name>":"CRD_Instance_Name"}'
Exemple : ingress.citrix.com/rewrite_responder_crd: "blockurlpolicy" Lie la stratégie à tous les services de l'ingress ou ingress.citrix.com/rewrite_responder_crd: '{"appname": "blockurlpolicy"}' lie la stratégie uniquement au service frontal.
ingress.citrix.com/rewrite_responder_crd Chaîne/JSON Facultatif Lie les politiques créées par le CRD rewrite-responder au serveur virtuel d'équilibrage de charge de l'application. Voir cette section. NA En tant que chaîne : "CRD_Instance_Name". En tant que JSON : '{"<Service_Name>":"CRD_Instance_Name"}'.
Exemple : ingress.citrix.com/rewrite_responder_crd: "blockurlpolicy" lie la politique à tous les services de l'ingress ou ingress.citrix.com/rewrite_responder_crd: '{"appname": "blockurlpolicy"}' lie la politique uniquement au service frontal.

Annotations de service

Voici les annotations de service prises en charge par NetScaler.
Dans les annotations de service, index est l'index ordonné des ports dans un fichier de spécification de service. Par exemple, s'il y a deux ports dans la spécification de service, l'index du premier port est zéro et celui du second port est un.
Annotations Type Obligatoire Description Par défaut Valeur possible
service.citrix.com/frontend-ip Chaîne Facultatif Spécifiez une adresse IP à utiliser comme adresse IP du serveur virtuel de commutation de contenu.Il existe plusieurs façons de fournir l'adresse IP du serveur virtuel de commutation de contenu. N/A Adresse IP numérique, par exemple, '1.2.3.4'
service.citrix.com/ipam-range Chaîne Facultatif Sélectionnez une plage d'adresses IP particulière parmi un ensemble de plages spécifiées au contrôleur IPAM NetScaler. Cette annotation est utilisée pour les services de type LoadBalancer.Exemple : service.citrix.com/ipam-range: 'Dev' NA Valeur correspondant à l'un des noms de plage configurés dans le contrôleur IPAM
service.citrix.com/insecure-redirect JSON Facultatif Rediriger le trafic HTTP vers un port sécurisé.Exemple : service.citrix.com/insecure-redirect: '{"port-443": 80 }' ou service.citrix.com/insecure-redirect: '{"443-tcp": 80 }' NA
service.citrix.com/ssl-termination-<index> Chaîne Facultatif Spécifier la terminaison SSL.Exemple : service.citrix.com/ssl-termination-0: 'EDGE' NA EDGE et REENCRYPT
service.citrix.com/service-type-<index> Chaîne Facultatif Spécifiez un protocole pour les entités NetScaler à créer.Exemple : service.citrix.com/service-type-0: ‘SSL’. HTTP TCP, HTTP, SSL, UDP, ANY, SSL_TCP et SIP_UDP.
service.citrix.com/ssl-certificate-data-<index> Chaîne Facultatif Spécifiez la valeur du certificat de serveur au format PEM.Exemple : service.citrix.com/ssl-certificate-data-0: \| <certificate> NA Données de certificat au format PEM
service.citrix.com/ssl-key-data-<index> Chaîne Facultatif Spécifiez la valeur de la clé de serveur au format PEM.Exemple : service.citrix.com/ssl-key-data-0: \| <key> N/A Données de clé au format PEM
service.citrix.com/ssl-ca-certificate-data-<index> Chaîne Facultatif Spécifiez la valeur du certificat CA du serveur pour vérifier le certificat client au format PEM.Exemple : service.citrix.com/ssl-ca-certificate-data-0: \| <certificate> NA Données du certificat CA au format PEM
service.citrix.com/ssl-backend-ca-certificate-data-<index> Chaîne Facultatif Spécifiez la valeur du certificat CA pour vérifier le certificat du serveur du backend au format PEM.Exemple : service.citrix.com/ssl-backend-ca-certificate-data-0: \| <certificate> NA Données de certificat CA au format PEM
service.citrix.com/secret Chaîne Facultatif Spécifiez le nom d'une ressource secrète pour le certificat de serveur frontal. Pour lier plusieurs certificats de serveur frontal, fournissez une liste de secrets séparés par des virgules configurés pour les certificats. Pour plus d'informations et un exemple, consultez Certificat SSL pour les services de type LoadBalancer.Exemples : service.citrix.com/secret: hotdrink-secret, service.citrix.com/secret: apache-secret1,apache-secret2 NA Nom du secret Kubernetes
service.citrix.com/ca-secret Chaîne Facultatif Fournit un certificat CA pour l'authentification par certificat client. Ce certificat est lié au serveur virtuel SSL frontal dans NetScaler. Pour plus d'informations et un exemple, consultez Certificat SSL pour les services de type LoadBalancer.Exemple : service.citrix.com/ca-secret: 'hotdrink-ca-secret' NA Nom du secret Kubernetes
service.citrix.com/backend-secret Chaîne Facultatif Utilisez cette annotation si la communication back-end entre NetScaler et votre charge de travail s'effectue sur un canal chiffré et que vous avez besoin de l'authentification client dans votre charge de travail. Ce certificat est envoyé au serveur pendant la négociation SSL et il est lié au groupe de services SSL back-end. Pour plus d'informations et un exemple, consultez Certificat SSL pour les services de type LoadBalancer.Exemple : service.citrix.com/backend-secret: 'hotdrink-secret' NA Nom du secret Kubernetes
service.citrix.com/backend-ca-secret Chaîne Facultatif Active l'authentification du serveur qui authentifie le certificat du serveur back-end. Pour plus d'informations et un exemple, consultez Certificat SSL pour les services de type LoadBalancer.Exemple : service.citrix.com/backend-ca-secret: 'hotdrink-ca-secret' N/A Nom du secret Kubernetes
service.citrix.com/preconfigured-certkey Chaîne Facultatif Spécifiez le nom d'une clé de certification SSL existante de NetScaler à utiliser comme certificat de serveur frontal. Pour lier plusieurs certificats de serveur frontal, fournissez une liste de clés de certificat séparées par des virgules qui sont déjà configurées pour les certificats.Exemples : - service.citrix.com/preconfigured-certkey: coffee-cert, service.citrix.com/preconfigured-certkey: preconfcert1,preconfcert2 N/A Nom de l'entité sslcertkey NetScaler
service.citrix.com/preconfigured-ca-certkey Chaîne Facultatif Spécifiez le nom d'une clé de certificat préconfigurée dans NetScaler à utiliser comme certificat CA pour l'authentification par certificat client. Ce certificat est lié au serveur virtuel SSL frontal dans NetScaler.Exemple : service.citrix.com/preconfigured-backend-certkey: 'coffee-cert' NA Nom de l'entité sslcertkey NetScaler
service.citrix.com/preconfigured-backend-certkey Chaîne Facultatif Spécifiez le nom d'une clé de certificat préconfigurée dans NetScaler à lier au groupe de services SSL de back-end. Ce certificat est envoyé au serveur lors de la négociation SSL pour l'authentification du serveur.Exemple : service.citrix.com/preconfigured-ca-certkey: 'coffee-ca-cert' NA Nom de l'entité sslcertkey NetScaler
service.citrix.com/preconfigured-backend-ca-certkey Chaîne Facultatif Spécifiez le nom d'une clé de certificat CA préconfigurée dans NetScaler à lier au groupe de services SSL back-end pour l'authentification du serveur.Exemple : service.citrix.com/preconfigured-backend-ca-certkey: 'coffee-ca-cert' NA Nom d'entité sslcertkey NetScaler

Annotations intelligentes pour les profils HTTP, TCP ou SSL

Annotations Type Obligatoire Description Par défaut Valeur possible
ingress.citrix.com/frontend-httpprofile Chaîne/JSON Facultatif Créer le profil HTTP frontal (plan client) N/A Exemple : ingress.citrix.com/frontend-httpprofile: '{"dropinvalreqs":"enabled", "websocket" : "enabled"}'
ingress.citrix.com/backend-httpprofile Chaîne/JSON Facultatif Créer le profil HTTP dorsal (plan serveur). N/A Exemple : ingress.citrix.com/backend-httpprofile: '{"app-1": {"dropinvalreqs":"enabled", "websocket" : "enabled"}}'
ingress.citrix.com/frontend-tcpprofile Chaîne/JSON Facultatif Créer le profil TCP frontal (plan client) N/A Exemple : ingress.citrix.com/frontend-tcpprofile: '{"ws":"enabled", "sack" : "enabled"}'
ingress.citrix.com/backend-tcpprofile Chaîne/JSON Facultatif Créer le profil TCP dorsal (plan serveur) N/A Exemple :ingress.citrix.com/backend-tcpprofile: '{"citrix-svc":{"ws":"enabled", "sack" : "enabled"}}'
ingress.citrix.com/frontend-sslprofile Chaîne/JSON Facultatif Créez le profil SSL frontal (plan client). Le profil SSL frontal n'est requis que si vous avez activé TLS sur le plan client. N/A Exemple : ingress.citrix.com/frontend-sslprofile: '{"hsts":"enabled", "tls12" : "enabled"}'
ingress.citrix.com/backend-sslprofile Chaîne/JSON Facultatif Créez le profil SSL dorsal (plan serveur). Le profil dorsal SSL n'est requis que si vous utilisez ingress.citrix.com/secure-backend. N/A Exemple : ingress.citrix.com/backend-sslprofile: '{"citrix-svc":{"hsts":"enabled", "tls1" : "enabled"}}'

Annotations intelligentes pour Ingress

L'annotation intelligente est une option fournie par NetScaler Ingress Controller pour activer efficacement les fonctionnalités NetScaler à l'aide du nom d'entité NetScaler. NetScaler Ingress Controller convertit l'Ingress de Kubernetes en un ensemble d'objets NetScaler. Vous pouvez contrôler efficacement ces objets à l'aide d'annotations intelligentes.
Remarque
Pour utiliser les annotations intelligentes, vous devez avoir une bonne compréhension des fonctionnalités de NetScaler et de leurs noms d'entité respectifs. Pour plus d'informations sur les fonctionnalités et les noms d'entité NetScaler, consultez la documentation NetScaler.
L'annotation intelligente prend le format JSON en entrée. La clé et la valeur que vous transmettez au format JSON doivent correspondre au format NetScaler NITRO. Pour plus d'informations sur l'API NetScaler NITRO, consultez Documentation des API REST NetScaler - NITRO.
Par exemple, si vous souhaitez activer la méthode d'équilibrage de charge basée sur SRCIPDESTIPHASH, vous devez utiliser le format de clé et de valeur NITRO correspondant lbmethod, SRCIPDESTIPHASH respectivement.
Le tableau suivant détaille les annotations intelligentes fournies par NetScaler Ingress Controller :
Nom de l'entité NetScaler Annotation intelligente Exemple
lbvserver ingress.citrix.com/lbvserver ingress.citrix.com/lbvserver: '{"appname":{"lbmethod":"SRCIPDESTIPHASH"}}'
groupe de services ingress.citrix.com/servicegroup ingress.citrix.com/servicegroup: '{"appname":{"cip": "Enabled","cipHeader":"X-Forwarded-For"}}'
moniteur ingress.citrix.com/monitor ingress.citrix.com/monitor: '{"appname":{"type":"http"}}'
serveur CSV ingress.citrix.com/csvserver ingress.citrix.com/csvserver: '{"stateupdate": "ENABLED"}'
Pour plus d'informations sur les annotations intelligentes pour les profils HTTP, TCP et SSL, consultez Configurer les profils HTTP, TCP ou SSL sur NetScaler.

Exemple de YAML d'Ingress avec des annotations intelligentes

L'exemple de YAML d'Ingress suivant inclut des annotations intelligentes pour activer les fonctionnalités NetScaler en utilisant des entités telles que lbvserver, servicegroup et monitor :
kubectl apply -f - <<EOF
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.citrix.com/frontend-ip: 192.168.1.1
    ingress.citrix.com/insecure-port: "80"
    ingress.citrix.com/lbvserver: '{"appname":{"lbmethod":"LEASTCONNECTION", "persistenceType":"SOURCEIP"}}'
    ingress.citrix.com/monitor: '{"appname":{"type":"http"}}'
    ingress.citrix.com/servicegroup: '{"appname":{"usip":"yes"}}'
  name: citrix
spec:
  rules:
  - host: citrix.org
    http:
      paths:
      - backend:
          service:
            name: appname
            port:
              number: 80
        path: /
        pathType: Prefix
EOF
L'exemple de YAML d'Ingress inclut des cas d'utilisation liés au service, citrix-svc, et le tableau suivant explique les annotations intelligentes utilisées dans l'exemple :
Annotation intelligente Description
ingress.citrix.com/lbvserver: '{"appname":{"lbmethod":"LEASTCONNECTION", "persistenceType":"SOURCEIP"}}' Définit la méthode d'équilibrage de charge comme Moins de connexions et configure également la persistance de l'adresse IP source.
ingress.citrix.com/servicegroup: '{"appname":{"usip":"yes"}}' Active le mode d'utilisation de l'adresse IP source (USIP) sur l'appareil NetScaler. Lorsque vous activez l'USIP sur NetScaler, il utilise l'adresse IP du client pour la communication avec les pods back-end.
ingress.citrix.com/monitor: '{"appname":{"type":"http"}}' Crée un moniteur HTTP personnalisé pour le groupe de services.
Remarque :
Lorsque plusieurs ingresses partagent la même adresse IP frontale et le même port, vous ne pouvez pas avoir de configurations conflictuelles fournies par le biais de plusieurs configurations d'ingress.
Par défaut, le serveur virtuel de commutation de contenu ne dépend pas de l'état des serveurs virtuels d'équilibrage de charge cibles qui lui sont liés. L'annotation ingress.citrix.com/csvserver: '{"stateupdate": "ENABLED"}' configure le serveur virtuel de commutation de contenu pour qu'il prenne en compte son état en fonction de l'état du serveur virtuel d'équilibrage de charge qui lui est lié à l'aide des politiques de commutation de contenu.

Annotations intelligentes pour les routes

Comme pour Ingress, vous pouvez également utiliser des annotations intelligentes avec les routes OpenShift. NetScaler Ingress Controller convertit les routes d'OpenShift en un ensemble d'objets NetScaler.
Le tableau suivant détaille les annotations intelligentes fournies par NetScaler Ingress Controller :
Nom de l'entité NetScaler Annotation intelligente Exemple
lbvserver route.citrix.com/lbvserver route.citrix.com/lbvserver: '{"appname":{"lbmethod":"SRCIPDESTIPHASH"}}'
servicegroup route.citrix.com/servicegroup route.citrix.com/servicegroup: '{"appname":{"cip": "Enabled","cipHeader":"X-Forwarded-For"}}'
monitor route.citrix.com/monitor route.citrix.com/monitor: '{"appname":{"type":"http"}}'
certificates route.citrix.com/preconfigured-certkey route.citrix.com/preconfigured-certkey : '{"certs": [{"name": "certkey1", "type": "default"}, {"name": "certkey2", "type": "sni"}]}'

Manifeste d'itinéraire exemple avec des annotations intelligentes

L'exemple suivant est un fichier YAML d'itinéraire.
kubectl apply -f - <<EOF
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: citrix
  annotations:
    route.citrix.com/lbvserver: '{"appname":{"lbmethod":"LEASTCONNECTION", "persistenceType":"SOURCEIP"}}'
    route.citrix.com/servicegroup: '{"appname":{"usip":"yes"}}'
    route.citrix.com/monitor: '{"appname":{"type":"http"}}'
    route.citrix.com/preconfigured-certkey : '{"certs": [{"name": "certkey1", "type": "default"}, {"name": "certkey2", "type": "sni"}]}'
spec:
  host:  citrix.org
  port:
    targetPort: 80
  to:
    kind: Service
    name: appname
    weight: 100
  wildcardPolicy: None
EOF
Le manifeste d'itinéraire exemple inclut des cas d'utilisation liés au service citrix-svc et le tableau suivant explique les annotations intelligentes utilisées dans l'itinéraire exemple :
Annotation intelligente Description
route.citrix.com/lbvserver: '{"appname":{"lbmethod":"LEASTCONNECTION", "persistenceType":"SOURCEIP"}}' Définit la méthode d'équilibrage de charge comme Moins de connexions et configure également la persistance de l'adresse IP source.
route.citrix.com/servicegroup: '{"appname":{"usip":"yes"}}' Active le mode d'utilisation de l'adresse IP source (USIP) sur NetScaler. Lorsque vous activez l'USIP sur le NetScaler, il utilise l'adresse IP du client pour la communication avec les pods back-end.
route.citrix.com/monitor: '{"appname":{"type":"http"}}' Crée un moniteur HTTP personnalisé pour le groupe de services.
route.citrix.com/preconfigured-certkey : '{"certs": [{"name": "certkey1", "type": "default"}, {"name": "certkey2", "type": "sni"}]}' Crée un ou plusieurs noms d'entité NetScaler sslcertkey avec le type de certificat default/sni/c.

Exemple de YAML avec l'annotation de service pour rediriger le trafic non sécurisé

Cet exemple montre comment rediriger le trafic des clients effectuant des requêtes sur un port non sécurisé (80) vers le port sécurisé (443).
L'annotation suivante est spécifiée dans le fichier YAML du service pour rediriger le trafic :
service.citrix.com/insecure-redirect: '{"port-443": 80}'
Exemple de définition de service :
kubectl apply -f - <<EOF
apiVersion: v1
kind: Service
metadata:
  name: frontend-service
  annotations:
    service.citrix.com/service-type-0: SSL
    service.citrix.com/frontend-ip: '192.2.170.26'
    service.citrix.com/secret: '{"port-443": "web-ingress-secret"}'
    service.citrix.com/ssl-termination-0: 'EDGE'
    service.citrix.com/insecure-redirect: '{"port-443": 80}'
spec:
  type: LoadBalancer
  selector:
    app: frontend
  ports:
  - port: 443
    targetPort: 80
    name: port-443
EOF

Annotations intelligentes pour les services

Les annotations intelligentes pour les services sont utilisées pour configurer NetScaler avec des valeurs personnalisées pour les paramètres de configuration NetScaler. Les annotations sont utilisées pour les services de type LoadBalancer et pour les services dans NetScaler CPX utilisés pour le trafic Est-Ouest.
Remarque :
Si vous avez configuré un service avec NodePort ou ClusterIP pour le trafic Nord-Sud, NetScaler est alors configuré à l'aide des annotations intelligentes d'entrée applicables plutôt que des annotations de service.
Les annotations intelligentes pour les services prennent le format JSON en entrée. La clé et la valeur que vous transmettez au format JSON doivent correspondre au format NetScaler NITRO. Pour plus d'informations sur l'API NetScaler NITRO, consultez NetScaler REST APIs - NITRO Documentation.
Exemple d'annotation intelligente pour les services :
service.citrix.com/lbvserver: '{"80-tcp":{"lbmethod":"SRCIPDESTIPHASH"}}'
Cette annotation définit la méthode d'équilibrage de charge comme SRCIPDESTIPHASH dans le serveur virtuel d'équilibrage de charge pour le port 80-tcp du service donné.
Le tableau suivant décrit les annotations intelligentes pour les services :
Nom de l'entité NetScaler Annotation intelligente pour le service Exemple
vserver LB service.citrix.com/lbvserver service.citrix.com/lbvserver: '{"80-tcp":{"lbmethod":"SRCIPDESTIPHASH"}}'
vserver CS service.citrix.com/csvserver service.citrix.com/csvserver: '{"l2conn":"on"}'
groupe de services service.citrix.com/servicegroup service.citrix.com/servicegroup: '{"80-tcp":{"usip":"yes"}}'
moniteur service.citrix.com/monitor service.citrix.com/monitor: '{"80-tcp":{"type":"http"}}', service.citrix.com/monitor: '{"80-tcp": "<pre-configured-monitor1-on-NetScaler>", "443-tcp": "<pre-configured-monitor2-on-NetScaler>"}'
profil analytique service.citrix.com/analyticsprofile service.citrix.com/analyticsprofile: '{"80-tcp":{"webinsight": {"httpurl":"ENABLED", "httpuseragent":"ENABLED"}}}'
Vous pouvez utiliser les annotations intelligentes pour les services comme suit :
  • En fournissant la valeur port-protocol dans l'annotation : Dans la définition du service, si vous fournissez la valeur port-protocol dans l'annotation, alors l'annotation est limitée au port particulier de ce service.
  • En ne fournissant pas la valeur port-protocol dans l'annotation : Si vous ne fournissez pas la valeur port-protocol dans l'annotation, alors l'annotation s'applique à tous les ports utilisés par le service.

Exemple de YAML d'entrée avec des annotations intelligentes pour les services

Le YAML suivant est un exemple de déploiement et de définition de service pour une application de base basée sur un serveur web Apache. Il inclut des annotations intelligentes pour les services afin d'activer les fonctionnalités NetScaler en utilisant des entités telles que lbvserver, csvserver, servicegroup, monitor et analyticsprofile :
kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: apache
  labels:
      name: apache
spec:
  selector:
    matchLabels:
      app: apache
  replicas: 8
  template:
    metadata:
      labels:
        app: apache
    spec:
      containers:
      - name: apache
        image: httpd:latest
        ports:
        - name: http
          containerPort: 80
        imagePullPolicy: IfNotPresent

---
#Expose the apache web server as a service
apiVersion: apps/v1
kind: Service
metadata:
  name: apache
  annotations:
    service.citrix.com/csvserver: '{"l2conn":"on"}'
    service.citrix.com/lbvserver: '{"80-tcp":{"lbmethod":"SRCIPDESTIPHASH"}}'
    service.citrix.com/servicegroup: '{"80-tcp":{"usip":"yes"}}'
    service.citrix.com/monitor: '{"80-tcp":{"type":"http"}}'
    service.citrix.com/frontend-ip: '10.217.212.16'
    service.citrix.com/analyticsprofile: '{"80-tcp":{"webinsight": {"httpurl":"ENABLED", "httpuseragent":"ENABLED"}}}'
    NETSCALER_VPORT: '80'
  labels:
    name: apache
spec:
  externalTrafficPolicy: Local
  type: LoadBalancer
  selector:
    name: apache
  ports:
  - name: http
    port: 80
    targetPort: http
  selector:
    app: apache
---
EOF

ServicetypeLB : Modification d'événement pour les annotations intelligentes

À partir de la version 4.0.16 du NetScaler Ingress Controller, si vous modifiez l'une des annotations suivantes dans ServiceTypeLB, le NetScaler Ingress Controller modifie la configuration plutôt que de la supprimer et de la recréer dans NetScaler :
"service.citrix.com/lbvserver",
"service.citrix.com/csvserver",
"service.citrix.com/servicegroup",
"service.citrix.com/monitor",
"service.citrix.com/analyticsprofile",
"service.citrix.com/insecure-redirect",
"service.citrix.com/secret",
"service.citrix.com/preconfigured-certkey",
"service.citrix.com/ca-secret",
"service.citrix.com/preconfigured-ca-certkey",
"service.citrix.com/backend-secret",
"service.citrix.com/preconfigured-backend-certkey",
"service.citrix.com/backend-ca-secret",
"service.citrix.com/preconfigured-backend-ca-certkey",
'service.citrix.com/ssl-termination-<index>',
'service.citrix.com/frontend-tcpprofile-<index>',
'service.citrix.com/backend-tcpprofile-<index>',
'service.citrix.com/frontend-httpprofile-<index>',
'service.citrix.com/backend-httpprofile-<index>',
'service.citrix.com/frontend-sslprofile-<index>',
'service.citrix.com/backend-sslprofile-<index>'

Exemples

Exemple de YAML d'entrée pour la prise en charge de SIP_UDP dans l'annotation de type de service non sécurisé

L'exemple de YAML d'entrée suivant inclut la configuration pour activer la prise en charge de SIP sur UDP en utilisant l'annotation ingress.citrix.com/insecure-service-type.
kubectl apply -f - <<EOF
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.citrix.com/frontend-ip: 1.1.1.1
    ingress.citrix.com/insecure-port: "5060"
    ingress.citrix.com/insecure-service-type: sip_udp
    ingress.citrix.com/lbvserver: '{"asterisk17":{"lbmethod":"CALLIDHASH","persistenceType":"CALLID"}}'
  name: sip-ingress
spec:
  defaultBackend:
    service:
      name: asterisk17
      port:
        number: 5060
EOF

Clé d'annotation ingress.citrix.com/default-response-code

Le NetScaler Ingress Controller traite un JSON valide pour l'annotation.
ingress.citrix.com/default-response-code: '{"type": "<action-type>", "response-code": "<code>", "target": "<target>", "reason-phrase": "<text>"}'
Clé Obligatoire Description
type Non — la valeur par défaut respondwith s'applique uniquement lorsque la clé est absente Type d'action du répondeur. Doit être exactement l'une des chaînes en minuscules respondwith, respondwithhtmlpage, redirect. La correspondance est sensible à la casse et n'est pas tronquée : Redirect, RESPONDWITH, "redirect ", "" et null sont toutes invalides et rejettent l'annotation entière — il n'y a pas de retour à respondwith. Attention au templating qui peut rendre la clé comme une chaîne vide.
response-code Oui, pour les trois types Accepté uniquement s'il s'agit de trois chiffres ASCII dont le premier chiffre est compris entre 1 et 5 — en pratique 100-599. Un nombre JSON est accepté ainsi qu'une chaîne entre guillemets ({"response-code": 404} fonctionne). 99, 0404, 600, 999, les nombres à virgule flottante et les booléens sont rejetés. La vérification est uniquement syntaxique.
target Oui pour respondwithhtmlpage et redirect; facultatif pour respondwith respondwithhtmlpage : l'URL source à partir de laquelle NetScaler importe la page. redirect : l'URL envoyée dans l'en-tête Location. Pour les deux, il doit s'agir d'une URL http/https absolue valide. Pour respondwith, il s'agit d'une expression de politique avancée NetScaler brute facultative qui devient l'intégralité de la charge utile de la réponse ; son contenu n'est délibérément pas validé, mais il doit s'agir d'une chaîne JSON — un nombre, un objet ou un tableau rejette l'annotation entière.
reason-phrase Non Envoyé comme champ NITRO -reasonPhrase pour respondwithhtmlpage. Honoré pour respondwith uniquement lorsque target est omis, où il est interpolé dans la charge utile générée. Ignoré silencieusement pour redirect. Les guillemets doubles, les barres obliques inverses, les retours chariot (CR) et les sauts de ligne (LF) sont supprimés et le résultat est tronqué. Une valeur non-chaîne est traitée comme vide.

respondwith (par défaut)

  • response-code n'est pas envoyé à NetScaler en tant que champ d'état. Il est interpolé dans une expression de charge utile construite manuellement, et la ligne d'état se trouve à l'intérieur de cette charge utile.
  • Sans target : 404 et 503 conservent leurs messages intégrés exacts lorsque reason-phrase est également absent. Tout autre code, ou 404/503 avec un reason-phrase, produit un corps généré : HTTP/1.1 <code> <reason>\r\n\r\nRequest to <host><url> could not be served. — où <reason> est le reason-phrase assaini, ou le mot littéral Error si aucun n'a été donné.
  • Avec un target personnalisé : votre expression est utilisée telle quelle et NetScaler Ingress Controller ne la cite ni ne l'échappe. response-code et reason-phrase n'ont alors aucun effet sur la réponse — mettez la vraie ligne d'état dans votre expression. NetScaler Ingress Controller n'enregistre aucun avertissement concernant l'incohérence. Une chaîne simple telle que "Service down" n'est pas une expression de politique avancée valide : NetScaler rejette add responder action et l'ensemble du LB par défaut est désactivé.
  • Ni -responseStatusCode ni -reasonPhrase ne sont jamais envoyés pour ce type.

redirection

  • target est émis comme une chaîne littérale entre guillemets, et non comme une expression. L'hôte, le chemin et la requête de la demande originale ne sont ni ajoutés ni conservés : chaque demande atteignant le vserver LB par défaut est envoyée exactement à cette URL unique. Cette annotation ne peut pas transmettre l'URI original.
  • response-code est transmis comme -responseStatusCode. NetScaler Ingress Controller ne vérifie pas qu'il s'agit d'un 3xx, donc {"type":"redirect","response-code":"404"} est accepté et configuré — et personne n'est redirigé.
  • reason-phrase est ignoré.

Répondre avec une page HTML

  • NetScaler Ingress Controller émet import responder htmlpage <page-name> <target> -overwrite puis pointe l'action du répondeur vers l'objet de page importé par son nom (-htmlpage <page-name>), jamais vers l'URL. Votre URL apparaît sur l'appliance uniquement comme le src de l'objet importé.
  • -responseStatusCode et -reasonPhrase sont tous deux envoyés.
  • L'hôte de la page doit être accessible depuis l'appliance.

Exemples et règles d'URL cible

a. respondwith — code de statut plus un corps généré par NetScaler Ingress Controller.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: defaultlb-respondwith
  annotations:
    kubernetes.io/ingress.class: citrix
    ingress.citrix.com/frontend-ip: 5.5.5.5
    ingress.citrix.com/default-response-code: '{"response-code": "404"}'
spec:
  rules:
  - host: www.example.com
    http:
      paths:
      - pathType: Prefix
        path: /
        backend:
          service:
            name: frontend
            port:
              number: 80
b. respondwithhtmlpage — servir votre propre page HTML (même Ingress, valeur d'annotation différente)
ingress.citrix.com/default-response-code: '{"type": "respondwithhtmlpage", "response-code": "521", "target": "https://status.example.com/service-unavailable.html", "reason-phrase": "Web server down"}'
c. redirect — envoyer le client ailleurs.
ingress.citrix.com/default-response-code: '{"type": "redirect", "response-code": "302", "target": "https://status.example.com/service-unavailable.html"}'
Remarque
  • Avec path: / et pathType: Prefix, chaque requête pour www.example.com correspond à la règle, de sorte que la réponse par défaut est appliquée aux requêtes pour un hôte différent sur la même IP frontale, ou aux requêtes pour www.example.com lorsque le service frontal n'a pas de points de terminaison prêts.
  • Règles d'acceptation/rejet d'URL target (redirect et respondwithhtmlpage uniquement), appliquées lors de l'analyse de l'annotation, avant l'envoi de quoi que ce soit à NetScaler :
Règle Exemples acceptés Exemples rejetés
Doit être absolu avec un schéma http ou https https://example.com/p.html, HTTP://EXAMPLE.COM/P (le schéma est insensible à la casse) /service-unavailable.html, p.html, example.com/x, //evil.com/x, ftp://a.com/p, javascript:alert(1), data:text/html,x, file:///etc/passwd
Doit avoir un hôte ; un port, s'il est présent, doit être un nombre valide https://h.example.com:8443/a/b?q=1&r=2, http://192.0.2.10/maintenance, https://[2001:db8::1]:8443/p.html http://, http:///p.html, http://:8080/p.html, http://host:notaport/, http://host:99999/, http://host:-1/
Ne doit pas intégrer d'informations d'identification (userinfo), sous quelque forme que ce soit Un @ dans le chemin ou la requête est acceptable : http://example.com/path@foo, https://example.com/a?b=1@2 http://user:pass@host/x, https://user@host/x, http://@host/, https://:pass@host/, https://user:@host/
Ne doit pas contenir de guillemet double, d'antislash, de caractère de contrôle C0, de DEL, ou d'espace blanc — encoder en pourcentage à la place https://example.com/p%20q https://example.com/p q, une URL contenant un guillemet double, un antislash, TAB, CR ou LF
Doit être une chaîne non vide — "", JSON null, un nombre/objet/tableau JSON