Contrôleur d'entrée Citrix ADC

Annotations

Annotations d’entrée

Voici les annotations Ingress prises en charge par Citrix :

Annotations Valeur possible Description Défaut
ingress.citrix.com/frontend-ip Adresse IP Utilisez cette annotation pour personnaliser l’adresse IP virtuelle (VIP). Cette adresse IP est configurée dans Citrix ADC en tant qu’adresse IP virtuelle. L’annotation est obligatoire si vous utilisez Citrix ADC VPX ou MPX. L’adresse IP Citrix ADC est utilisée comme adresse IP virtuelle.
    Remarque : N’utilisez pas l’annotation si vous souhaitez utiliser l’adresse IP Citrix ADC en tant qu’adresse IP VIP.  
ingress.citrix.com/frontend-ipset-name Nom de l’IPSET Utilisez cette annotation pour spécifier le nom IPSET pour la configuration frontale. L’IPSET est lié au serveur virtuel de commutation de contenu. Utilisez cette annotation avec le ingress.citrix.com/frontend-ip. SO
    Remarque : Le nom IPSET que vous spécifiez dans l’annotation doit déjà être configuré dans Citrix ADC.  
ingress.citrix.com/secure-port Numéro de port Utilisez cette annotation pour configurer le port pour le trafic HTTPS. Ce port est configuré dans Citrix ADC en tant que valeur de port pour le serveur virtuel CS correspondant. 443
ingress.citrix.com/insecure-port Numéro de port Utilisez cette annotation pour configurer le port pour le trafic HTTP, TCP ou UDP. Ce port est configuré dans Citrix ADC en tant que valeur de port pour le serveur virtuel CS correspondant. 80
ingress.citrix.com/insecure-termination allowredirect, ou disallow Utilisez allow pour autoriser le trafic HTTP, Utilisez redirect pour rediriger la demande HTTP vers HTTPS ou Utilisez disallow si vous souhaitez supprimer le trafic HTTP. disallow
    Pa exemple : ingress.citrix.com/insecure-termination: "redirect"  
ingress.citrix.com/secure-backend Au format JSON, liste des services pour le backend sécurisé Utilisez True, si vous souhaitez établir un HTTPS sécurisé entre Citrix ADC et l’application, Utilisez False, si vous souhaitez établir une connexion HTTP non sécurisée Citrix ADC à l’application. False
    Pa exemple : ingress.citrix.com/secure-backend: {"app1":"True", "app2":"False", "app3":"True"}  
kubernetes.io/ingress.class nom de classe d’entrée Il s’agit d’un moyen d’associer une ressource d’entrée particulière à un contrôleur d’entrée. Configure toutes les entrées
    Pa exemple : kubernetes.io/ingress.class:"Citrix"  
ingress.citrix.com/secure-service-type ssl ou ssl_tcp L’annotation permet l’équilibrage de charge L4 avec SSL sur TCP en tant que protocole. Utilisez ssl_tcp, si vous souhaitez utiliser SSL sur TCP. ssl
ingress.citrix.com/insecure-service-type http, tcpudp, sip_udp, ou any L’annotation permet l’équilibrage de charge L4 avec le protocole tcp/udp/sip_udp. Utilisez tcp, si vous voulez que le protocole TCP soit utilisé. Utilisez udp, si vous voulez utiliser UDP comme protocole. http
ingress.citrix.com/path-match-method prefix ou exact Utilisez cette annotation pour la mise en correspondance du chemin d’entrée. Utilisez prefix pour Citrix ingress controller pour considérer n’importe quelle chaîne de chemin d’accès comme une expression de préfixe. Utilisez exact cette option pour que le Citrix ingress controller considère le chemin comme une correspondance exacte. prefix
    Par exemple, l’annotation ingress.citrix.com/path-match-method: "prefix" définit le Citrix ingress controller pour qu’il considère toute chaîne de chemin d’accès comme une expression de préfixe.  
ingress.citrix.com/deployment dsr Utilisez cette annotation pour créer une configuration de Direct Server Return (DSR) sur Citrix ADC.  
    Par exemple, l’ ingress.citrix.com/deployment: "dsr" annotation crée une configuration DSR sur Citrix ADC.  
ingress.citrix.com/preconfigured-certkey Clés et type de certificat préconfigurés. Le type de certificat peut être par défaut, SNI ou CA. Utilisez cette annotation pour spécifier la ou les clés de certificat préconfigurées dans Citrix ADC que vous souhaitez réutiliser et lier aux applications. Si le paramètre type n’est pas fourni avec le nom d’un certificat, le certificat est considéré comme le type par défaut (non-SNI).
    Par exemple, dans l’ ingress.citrix.com/preconfigured-certkey : '{"certs": [ {"name": "certkey1", "type": "default"}, {"name": "certkey2", "type": "sni"} ] } annotation, certkey1 est utilisé comme certificat non-SNI et certkey2 est utilisé comme certificat SNI.  

Annotations intelligentes pour Ingress

L’annotation intelligente est une option fournie par le Citrix ingress controller pour activer efficacement les fonctionnalités Citrix ADC à l’aide du nom d’entité Citrix ADC. Le Citrix ingress controller convertit l’entrée dans Kubernetes en un ensemble d’objets Citrix ADC. Vous pouvez contrôler efficacement ces objets à l’aide d’annotations intelligentes.

Remarque : Pour utiliser les annotations intelligentes, vous devez bien comprendre les fonctionnalités de Citrix ADC et leurs noms d’entités respectifs. Pour plus d’informations sur les fonctionnalités et les noms d’entités Citrix ADC, consultez la documentation Citrix ADC.

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 Citrix ADC NITRO. Pour plus d’informations sur l’API Citrix ADC NITRO, consultez la section API REST Citrix ADC 12.1 - Documentation NITRO.

Par exemple, si vous souhaitez activer la méthode lb SRCIPDESTIPHASH basée sur la base, 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 le Citrix ingress controller :

Nom de l’entité Citrix ADC Annotation intelligente Exemple
lbvserver ingress.citrix.com/lbvserver ingress.citrix.com/lbvserver: '{"citrix-svc":{"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"}}'
csvserver 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 des profils HTTP, TCP ou SSL sur Citrix ADC.

YAML d’entrée d’échantillon avec annotations intelligentes

Voici un exemple de YAML d’entrée. Il inclut des annotations intelligentes pour activer les fonctionnalités Citrix ADC à l’aide d’entités telles que lbvserver, servicegroup et monitor :

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: '{"citrix-svc":{"lbmethod":"LEASTCONNECTION", "persistenceType":"SOURCEIP"}}'
    ingress.citrix.com/monitor: '{"citrix-svc":{"type":"http"}}'
    ingress.citrix.com/servicegroup: '{"citrix-svc":{"usip":"yes"}}'
  name: citrix
spec:
  rules:
  - host: citrix.org
    http:
      paths:
      - backend:
          service:
            name: citrix-svc
            port:
              number: 80
        path: /
        pathType: Prefix
<!--NeedCopy-->

L’exemple YAML 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: '{"citrix-svc":{"lbmethod":"LEASTCONNECTION", "persistenceType":"SOURCEIP"}}' Définit la méthode d’équilibrage de charge sur Connexion minimale et configure également la persistance de l’adresse IP source.
ingress.citrix.com/servicegroup: '{"citrix-svc":{"usip":"yes"}}' Active l’option Utiliser le mode IP source (USIP) sur l’appareil Citrix ADC d’entrée. Lorsque vous activez l’USIP sur Citrix ADC, il utilise l’adresse IP du client pour communiquer avec les espaces principaux.
ingress.citrix.com/monitor: '{"citrix-svc":{"type":"http"}}' Crée un moniteur HTTP personnalisé pour le groupe de services.

Remarque :

Lorsque plusieurs entrées 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’entrée.

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"}' définit le serveur virtuel de commutation de contenu pour qu’il considère son état en fonction de l’état du serveur virtuel d’équilibrage de charge qui lui est lié via les stratégies de commutation de contenu.

Annotations intelligentes pour les itinéraires

Comme pour Ingress, vous pouvez également utiliser des annotations intelligentes avec des itinéraires OpenShift. Le Citrix ingress controller convertit les routes dans OpenShift en un ensemble d’objets Citrix ADC.

Le tableau suivant détaille les annotations intelligentes fournies par le Citrix ingress controller :

Nom de l’entité Citrix ADC Annotation intelligente Exemple
lbvserver route.citrix.com/lbvserver route.citrix.com/lbvserver: '{"citrix-svc":{"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"}}'

Exemple de manifeste d’itinéraire avec annotations intelligentes

Voici un exemple de fichier YAML de routage.

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: citrix
  annotations:
    route.citrix.com/lbvserver: '{"citrix-svc":{"lbmethod":"LEASTCONNECTION", "persistenceType":"SOURCEIP"}}'
    route.citrix.com/servicegroup: '{"citrix-svc":{"usip":"yes"}}'
    route.citrix.com/monitor: '{"citrix-svc":{"type":"http"}}'
spec:
  host:  citrix.org
  port:
    targetPort: 80
  to:
    kind: Service
    name: citrix-svc
    weight: 100
  wildcardPolicy: None
<!--NeedCopy-->

L’exemple de manifeste d’itinéraire inclut des cas d’utilisation liés au service citrix-svc et le tableau suivant explique les annotations intelligentes utilisées dans l’exemple d’itinéraire :

Annotation intelligente Description
route.citrix.com/lbvserver: '{"citrix-svc":{"lbmethod":"LEASTCONNECTION", "persistenceType":"SOURCEIP"}}' Définit la méthode d’équilibrage de charge sur Connexion minimale et configure également la persistance de l’adresse IP source.
route.citrix.com/servicegroup: '{"citrix-svc":{"usip":"yes"}}' Active l’option Utiliser le mode IP source (USIP) sur l’appareil Citrix ADC. Lorsque vous activez l’USIP sur Citrix ADC, il utilise l’adresse IP du client pour communiquer avec les espaces principaux.
route.citrix.com/monitor: '{"citrix-svc":{"type":"http"}}' Crée un moniteur HTTP personnalisé pour le groupe de services.

Annotations de service

Voici les annotations de service prises en charge par Citrix.

Remarque : 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’indice du premier port est zéro et le second est un.

Annotations Description Exemple
service.citrix.com/service-type-<index> Utilisez cette annotation pour spécifier le type de service pour les entités Citrix ADC créées. Les valeurs acceptables sont TCP, HTTP, SSL, UDP, ANY, SSL_TCP et SIP_UDP. service.citrix.com/service-type-0: ‘SSL’
service.citrix.com/ssl-certificate-data-<index> Utilisez cette annotation pour spécifier la valeur du certificat de serveur au format PEM. service.citrix.com/ssl-certificate-data-0: | <certificate>
service.citrix.com/ssl-key-data-<index> Utilisez cette annotation pour spécifier la valeur de la clé du serveur au format PEM. service.citrix.com/ssl-key-data-0: | <key>
service.citrix.com/ssl-ca-certificate-data-<index> Utilisez cette annotation pour spécifier la valeur du certificat de l’autorité de certification du serveur afin de vérifier le certificat client au format PEM. service.citrix.com/ssl-ca-certificate-data-0: | <certificate>
service.citrix.com/ssl-backend-ca-certificate-data-<index> Utilisez cette annotation pour spécifier la valeur du certificat de l’autorité de certification afin de vérifier le certificat de serveur du serveur principal au format PEM. service.citrix.com/ssl-backend-ca-certificate-data-0: | <certificate>
service.citrix.com/ssl-termination-<index> Utilisez cette annotation pour spécifier la terminaison SSL. Les valeurs acceptées sont EDGE et REENCRYPT. service.citrix.com/ssl-termination-0: ‘EDGE’
service.citrix.com/insecure-redirect Utilisez cette annotation pour rediriger le trafic non sécurisé vers un port sécurisé. Vous pouvez spécifier le port sécurisé en utilisant {secure-portname : port-number} ou {secure-portnumber- secure-port-protocol  : insecure-portnumber } pour rediriger le trafic à partir d’un port non sécurisé. service.citrix.com/insecure-redirect: ‘{“port-443”: 80 }’ or service.citrix.com/insecure-redirect: ‘{“443-tcp”: 80 }’
service.citrix.com/frontend-ip Utilisez cette annotation pour transmettre l’adresse IP virtuelle pour les services de type LoadBalancer. service.citrix.com/frontend-ip: ‘192.168.1.1’
service.citrix.com/ipam-range Utilisez cette annotation pour sélectionner une plage d’adresses IP particulière parmi un ensemble de plages spécifiées pour le contrôleur IPAM Citrix. Cette annotation est utilisée pour les services de type LoadBalancer. service.citrix.com/ipam-range: ‘Dev’
service.citrix.com/secret Utilisez cette annotation pour spécifier le nom de la ressource secrète pour le certificat du serveur frontal. Pour plus d’informations et pour obtenir un exemple, consultez Certificat SSL pour les services de type LoadBalancer. service.citrix.com/secret: ‘hotdrink-secret’
service.citrix.com/ca-secret Utilisez cette annotation pour fournir un certificat d’autorité de certification pour l’authentification du certificat client. Ce certificat est lié au serveur virtuel SSL frontal dans Citrix ADC. Pour plus d’informations et pour obtenir un exemple, consultez Certificat SSL pour les services de type LoadBalancer. service.citrix.com/ca-secret: ‘hotdrink-ca-secret’
service.citrix.com/backend-secret Utilisez cette annotation si la communication principale entre Citrix ADC et votre charge de travail se fait sur un canal chiffré et que vous avez besoin de l’authentification du client dans votre charge de travail. Ce certificat est envoyé au serveur pendant l’établissement de liaison SSL et il est lié au groupe de services SSL principal. Pour plus d’informations et pour obtenir un exemple, consultez Certificat SSL pour les services de type LoadBalancer. service.citrix.com/backend-secret: ‘hotdrink-secret’
service.citrix.com/backend-ca-secret Utilisez cette annotation pour activer l’authentification du serveur qui authentifie le certificat du serveur principal. Cette configuration lie le certificat d’autorité de certification du serveur au service SSL sur Citrix ADC. Pour plus d’informations et pour obtenir un exemple, consultez Certificat SSL pour les services de type LoadBalancer. service.citrix.com/backend-ca-secret: ‘hotdrink-ca-secret’
service.citrix.com/preconfigured-certkey Utilisez cette annotation pour spécifier le nom de la clé de certificat préconfigurée dans Citrix ADC à utiliser en tant que certificat de serveur frontal. service.citrix.com/preconfigured-certkey: ‘coffee-cert’
service.citrix.com/preconfigured-ca-certkey Utilisez cette annotation pour spécifier le nom de la clé de certificat préconfigurée dans Citrix ADC à utiliser comme certificat d’autorité de certification pour l’authentification du certificat client. Ce certificat est lié au serveur virtuel SSL frontal dans Citrix ADC. service.citrix.com/preconfigured-backend-certkey: ‘coffee-cert’
service.citrix.com/preconfigured-backend-certkey Utilisez cette annotation pour spécifier le nom de la clé de certificat préconfigurée dans Citrix ADC à lier au groupe de services SSL principal. Ce certificat est envoyé au serveur lors de la prise de contact SSL pour l’authentification du serveur. service.citrix.com/preconfigured-ca-certkey: ‘coffee-ca-cert’
service.citrix.com/preconfigured-backend-ca-certkey Utilisez cette annotation pour spécifier le nom de la clé de certificat d’autorité de certification préconfigurée dans Citrix ADC à lier au groupe de services SSL principal pour l’authentification du serveur. service.citrix.com/preconfigured-backend-ca-certkey: ‘coffee-ca-cert’

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

Cet exemple montre comment rediriger le trafic des clients effectuant des demandes 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}'

Voici un exemple de définition de service :


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

<!--NeedCopy-->

Annotations intelligentes pour les services

Les annotations intelligentes pour les services sont utilisées pour configurer Citrix ADC avec des valeurs personnalisées pour les paramètres de configuration Citrix ADC. Les annotations sont utilisées pour les services de type LoadBalancer et pour les services dans Citrix ADC CPX utilisés pour le trafic Est-Ouest.

Remarque :

Si vous avez configuré un service avec NodePort ou ClusterIP pour le trafic Nord-Sud, Citrix ADC est 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 Citrix ADC NITRO. Pour plus d’informations sur l’API Citrix ADC NITRO, consultez la section API REST Citrix ADC 12.1 - Documentation NITRO.

Voici un 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étaille les annotations intelligentes pour les services :

Nom de l’entité Citrix ADC Annotation intelligente pour le service Exemple
lbvserver service.citrix.com/lbvserver service.citrix.com/lbvserver: '{"80-tcp":{"lbmethod":"SRCIPDESTIPHASH"}}'
csvserver 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"}}'
analyticsprofile 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, 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, l’annotation s’applique à tous les ports utilisés par le service.

Exemple d’entrée YAML avec annotations intelligentes pour les services

Voici un exemple de déploiement et de définition de service pour une application basée sur un serveur Web Apache de base. Il inclut des annotations intelligentes pour les services afin d’activer les fonctionnalités Citrix ADC à l’aide des entités telles que lbvserver, csvserver, servicegroup, monitor et analyticsprofile :

# If using this on GKE, eusure sure you have cluster-admin role for your account
#The sample is a basic apache web server as application for illustration
apiVersion: apps/v1beta2
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: 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
---
<!--NeedCopy-->

Exemples

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

Voici un exemple YAML d’entrée qui inclut la configuration pour activer la prise en charge SIP sur UDP à l’aide de l’annotation ingress.citrix.com/insecure-service-type.

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"}}'
    kubernetes.io/ingress.class: cic-vpx
  name: sip-ingress
spec:
  defaultBackend:
    service:
      name: asterisk17
      port:
        number: 5060
<!--NeedCopy-->
Annotations