Tous les produits
Search

Ce produit

    API Gateway:Configure ApigConfig

    Centre de documentation

    API Gateway:Configure ApigConfig

    Dernière mise à jour :Oct 12, 2026

    ApigConfig est une ressource personnalisée (CRD) fournie par le contrôleur APIG pour gérer le cycle de vie des instances de passerelle APIG, configurer les options d'écouteur Ingress et définir des paramètres globaux tels que le contrôle d'accès par IP, la collecte de journaux et le traçage.

    Présentation d'ApigConfig

    Configuration

    ApigConfig est une CRD fournie par le contrôleur APIG pour gérer le cycle de vie et les configurations globales des instances de passerelle APIG.

    Chaque ApigConfig correspond à une instance de passerelle APIG. Pour utiliser plusieurs instances de passerelle APIG, créez plusieurs ressources ApigConfig.
    Sauf dans les scénarios de réutilisation , la suppression d'un ApigConfig entraîne également la suppression de l'instance de passerelle APIG correspondante.
    Important

    Pour une instance de passerelle APIG créée à l'aide d'une CRD (ApigConfig), gérez les configurations métier telles que les API, les routes et les certificats directement dans la CRD. Utilisez la console APIG pour des opérations telles que la mise à l'échelle. Ne modifiez pas les configurations métier d'une instance créée par CRD via la console, car la synchronisation de la CRD risque d'écraser vos modifications et de provoquer des conflits de configuration.

    Voici un exemple complet de configuration ApigConfig.

    apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
  name: apig-ingress
spec:
  name: apig-ingress
  common:
    pay:
      payType: POSTPAY
    instance:
      spec: apigw.small.x1
    network:
      vSwitches:
      - "vsw-1"
      - "vsw-2"
      networkType: Internet
    securityGroupType: enterprise
  global:
    tls:
      enableHardwareAcceleration: true
    ipAccessControl:
      whitelist:
      - 1.1.XX.XX
      - 2.2.XX.XX
  monitor:
    logging:
      sls:
        reuseProject: "xxx" # Leave blank to use the default project.
    tracing:
      openTelemetry:
        sampleRate: "100"
  ingress:
    local:
      ingressClass:  apig
      watchNamespace: "" # An empty string ("") indicates Ingress resources in all namespaces.

    Paramètre

    Description

    Valeur par défaut

    name

    Le nom de la passerelle.

    apig-ingress

    common.pay.payType

    La méthode de facturation.

    Seul le paiement à l'utilisation est pris en charge ; il s'agit de la valeur par défaut si aucune spécification n'est indiquée.

    POSTPAY

    common.instance.spec

    Le type d'instance de passerelle.

    Valeurs valides :

    • apigw.small.x1

    • apigw.small.x2

    • apigw.small.x4

    • apigw.medium.x1

    • apigw.medium.x2

    • apigw.medium.x3

    • apigw.large.x1

    • apigw.large.x2

    • apigw.large.x3

    apigw.small.x1

    common.network.vSwitches

    Les vSwitches primaire et de secours, dans cet ordre.

    Spécifiez un ou deux vSwitches. Si aucun n'est indiqué, les vSwitches sont hérités du nœud sur lequel s'exécute le pod du contrôleur APIG.

    Aucun

    common.network.networkType

    L'accessibilité réseau de la passerelle.

    Valeurs valides :

    • Internet

    • Intranet

    Internet

    common.securityGroupType

    Le type de groupe de sécurité.

    Valeurs valides :

    • enterprise : groupe de sécurité avancé

    • normal : groupe de sécurité basique

    normal

    global.tls.enableHardwareAcceleration

    Indique s'il faut activer l'accélération matérielle TLS.

    Cette fonctionnalité améliore considérablement les performances du trafic HTTPS.

    Activé

    global.ipAccessControl.whitelist

    La liste d'autorisation d'IP globale.

    Non configuré

    global.ipAccessControl.blacklist

    La liste de blocage d'IP globale.

    Non configuré

    monitor.logging.sls

    Indique s'il faut activer la collecte de journaux via Simple Log Service (SLS).

    Pour activer cette fonctionnalité, accordez les autorisations SLS requises au contrôleur APIG.

    Désactivé

    monitor.logging.sls.reuseProject

    Le projet SLS utilisé pour stocker les journaux d'accès.

    Valeurs valides :

    • Vide : un projet par défaut est créé et utilisé.

    • Valeur spécifiée : un projet existant est utilisé.

    Vide

    monitor.tracing.xTrace.sampleRate

    Le taux d'échantillonnage pour Tracing Analysis (x-trace).

    0

    monitor.tracing.openTelemetry

    Active ou désactive le traçage OpenTelemetry.

    Désactivé par défaut. Cette option est incompatible avec l'option de traçage xTrace.

    monitor.tracing.openTelemetry.sampleRate

    Le taux d'échantillonnage pour le traçage OpenTelemetry.

    100

    ingress.local.ingressClass

    Détermine quelles ressources Ingress l'instance de passerelle APIG traite, en fonction de leur IngressClass.

    Valeurs valides :

    • Non configuré : la passerelle ne traite aucune ressource Ingress.

    • Défini sur apig : la passerelle traite les ressources Ingress dont l'IngressClass est apig.

    • Une chaîne vide ("") : écoute toutes les ressources Ingress.

    • Défini sur nginx : écoute les ressources Ingress qui ont une IngressClass nginx ou qui ne sont associées à aucune IngressClass.

    • Défini sur une autre valeur : la passerelle traite les ressources Ingress dont l'IngressClass correspond à la valeur spécifiée.

    Remarque

    Ce paramètre a une priorité inférieure à l'association d'un ApigConfig via une IngressClass.

    Non configuré

    ingress.local.watchNamespace

    Les namespaces dans lesquels la passerelle surveille les ressources Ingress.

    Valeurs valides :

    • Chaîne vide : surveille tous les namespaces.

    • Valeur spécifiée : surveille le namespace spécifié. Un seul namespace peut être indiqué.

    Vide

    État

    Après avoir créé une ressource ApigConfig, exécutez la commande kubectl get ApigConfig pour vérifier son état. La ressource passe par les états suivants : Pending > Running > Listening.

    • Pending : l'instance de passerelle APIG est en cours de création. Ce processus prend environ 3 minutes.

    • Running : l'instance de passerelle APIG est créée et en cours d'exécution.

    • Listening : l'instance de passerelle APIG est en cours d'exécution et surveille les ressources Ingress dans le cluster.

    • Failed : l'instance de passerelle APIG est dans un état invalide. Consultez le champ Message dans le champ Status pour identifier la cause.

    Tags

    Les instances de passerelle APIG créées ou réutilisées via ApigConfig sont associées à des tags de ressource. Vous pouvez consulter les informations sur les tags dans la section Informations de base de la console APIG.

    Important

    Ne modifiez pas ces tags dans la console APIG, car cela pourrait perturber le fonctionnement de votre instance de passerelle.

    Tag

    Description

    ack.aliyun.com

    Indique que la passerelle APIG gère le trafic ingress d'un cluster Container Service for Kubernetes (ACK).

    ingress.k8s.alibaba/ApigConfig

    Associe l'instance de passerelle APIG à un ApigConfig.

    kubernetes.reused.by.user

    Indique si l'instance de passerelle APIG est réutilisée. Une instance réutilisée n'est pas supprimée lorsque l'ApigConfig associé est supprimé.

    Créer une instance de passerelle APIG

    1. Configurez ApigConfig.

      L'exemple suivant crée une instance de passerelle APIG nommée apig-ingress avec le type d'instance apigw.small.x1. Modifiez les autres paramètres ApigConfig selon vos besoins.

      apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
  name: apig-ingress
spec:
  name: apig-ingress
  common:
    instance:
      spec: apigw.small.x1

    2. Dans votre cluster Container Service for Kubernetes (ACK), créez une IngressClass et associez-la à l'ApigConfig en utilisant spec.parameters. Cela déclare un processeur Ingress dans le cluster.

      Une fois configuré, l'instance de passerelle APIG liée traite tout Ingress associé à cette IngressClass.

      apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: apig
spec:
  controller: apig.alibabacloud.com/ingress
  parameters:
    apiGroup: apig.alibabacloud.com
    kind: ApigConfig
    name: apig-ingress

    Réutiliser une instance de passerelle APIG existante

    Pour réutiliser une instance de passerelle APIG existante, spécifiez son ID (par exemple, gw-xxx) dans le champ spec.id de votre ApigConfig. Utilisez spec.override pour contrôler si les paramètres ApigConfig écrasent la configuration de l'instance existante.

    L'exemple suivant réutilise une instance de passerelle APIG existante. L'ApigConfig associe l'instance à un cluster et la configure pour traiter les ressources Ingress avec l'IngressClass apig.

    Important

    • Dans la configuration suivante, spec.override est défini sur false, ce qui signifie que les options d'écouteur Ingress et la configuration globale d'une passerelle APIG existante ne sont pas écrasées. Si une instance de passerelle existante n'est pas associée au cluster de conteneurs, elle est automatiquement associée au cluster et ses options d'écouteur Ingress sont configurées pour écouter les ressources Ingress dans le cluster de conteneurs où ingressClass est spec.ingress.local.ingressClass (dans ce cas, apig). Si l'instance de passerelle est déjà associée au cluster de conteneurs, ses options d'écouteur Ingress existantes ne sont pas écrasées.

    • Pour écraser les options d'écouteur Ingress et les configurations globales d'une passerelle APIG existante, assurez-vous que les paramètres de passerelle dans l'ApigConfig (options d'écouteur Ingress, accélération matérielle, listes d'autorisation et de blocage d'IP globales, et observabilité) sont correctement configurés avant d'activer spec.override. Si ces configurations ne sont pas spécifiées dans l'ApigConfig, l'activation de spec.override écrase les paramètres de passerelle d'origine (options d'écouteur Ingress, accélération matérielle, listes d'autorisation et de blocage d'IP globales, et observabilité), ce qui peut affecter le trafic.

    apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
  name: reuse
spec:
  id: gw-xxxx
  override: false
  ingress:
    local:
      ingressClass: apig

    Paramètre

    Description

    spec.id

    L'ID de l'instance de passerelle APIG cible à réutiliser. L'ID doit commencer par gw-.

    spec.override

    Indique s'il faut écraser les configurations de l'instance de passerelle APIG réutilisée en fonction des paramètres ApigConfig.

    • Défini sur true : écrase la configuration de passerelle existante (options d'écouteur Ingress, accélération matérielle, listes d'autorisation et de blocage globales, et observabilité).

    • Si vous définissez ce paramètre sur false, les configurations existantes de la passerelle (telles que les options d'écouteur Ingress, l'accélération matérielle, les listes d'autorisation et de blocage globales, et l'observabilité) ne sont pas écrasées. Toutefois, si une instance de passerelle existante n'est pas associée au cluster de conteneurs, l'instance de passerelle est automatiquement associée au cluster de conteneurs et ses options d'écouteur Ingress sont configurées pour écouter les ressources Ingress dans le cluster de conteneurs dont ingressClass est défini sur la valeur de spec.ingress.local.ingressClass.

    Supprimer une instance de passerelle APIG

    La suppression d'un ApigConfig entraîne également la suppression de l'instance de passerelle APIG correspondante, sauf pour les instances réutilisées.

    Le tableau suivant décrit la politique de suppression.

    Méthode de facturation

    Créé par le contrôleur APIG

    Passerelle de console réutilisée

    Paiement à l'utilisation

    La suppression de l'ApigConfig supprime automatiquement l'instance de passerelle.

    La suppression de l'ApigConfig conserve l'instance de passerelle.

    Pour supprimer l'ApigConfig, exécutez la commande suivante :

    kubectl delete ApigConfig your-config-name

    Configurer le contrôle d'accès par IP global

    Configurer une liste d'autorisation d'IP

    Configurez une liste d'autorisation d'IP globale pour autoriser l'accès à votre Ingress APIG uniquement depuis des adresses IP source spécifiques.

    L'exemple suivant autorise l'accès uniquement depuis l'adresse IP source 1.1.XX.XX et le bloc CIDR 2.0.XX.XX/8.

    apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
   name: apig-ingress
spec:
   ...
  global:
    ipAccessControl:
      whitelist:
      - 1.1.XX.XX
      - 2.0.XX.XX/8
   ...

    Configurer une liste de blocage d'IP

    Configurez une liste de blocage d'IP globale au niveau de l'instance pour refuser l'accès depuis des adresses IP source spécifiques.

    L'exemple suivant refuse les requêtes provenant de l'adresse IP source 1.1.XX.XX et du bloc CIDR 2.0.XX.XX/8.

    apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
   name: apig-ingress
spec:
   ...
  global:
    ipAccessControl:
      blacklist:
      - 1.1.XX.XX
      - 2.0.XX.XX/8
   ...

    Activer la journalisation SLS

    Avant d'activer la collecte de journaux, assurez-vous que le contrôleur APIG dispose des autorisations SLS requises.

    L'exemple suivant configure la passerelle pour envoyer les journaux d'accès à un projet SLS nommé demo.

    apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
   name: apig-ingress
spec:
   ...
  monitor:
    logging:
      sls:
        # Configure reuseProject to enable Simple Log Service. If you want to use the default project, leave this field blank.
        reuseProject: "demo"
    ...

    Activer le traçage OpenTelemetry

    Configurez le traçage OpenTelemetry pour la passerelle afin de mettre en place un système de traçage de bout en bout pour diagnostiquer les problèmes de production.

    L'exemple suivant configure le traçage OpenTelemetry avec un taux d'échantillonnage (sampleRate) de 100 %.

    apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
   name: apig-ingress
spec:
   ...
  monitor:
    tracing:
      openTelemetry:
        sampleRate: "100"
   ...

    Configurations supplémentaires

    L'instance de passerelle Ingress APIG prend en charge les configurations supplémentaires suivantes :

    Pour appliquer ces paramètres, accédez à la console Cloud-native API Gateway. Sur la page APIG Gateway > Gateway List, sélectionnez l'instance de passerelle, puis cliquez sur Parameter Settings dans le volet de navigation de gauche.

    Paramètre

    Type

    Description

    EnableGenerateRequestId

    Bool

    Lorsqu'elle est activée, un ID de requête est généré dans l'en-tête de la requête à des fins de traçage.

    EnableGzip

    Bool

    Active la compression Gzip pour les requêtes et les réponses, réduisant le trafic de la passerelle mais augmentant la consommation de CPU.

    EnableSlashMerge

    Bool

    Lorsqu'elle est activée, fusionne les caractères '/' redondants dans les chemins de requête. Par exemple, www.a.com//b devient www.a.com/b.

    DownstreamConnectionBufferLimits

    Int

    La taille du tampon d'une connexion unique, qui affecte le débit et l'utilisation de la mémoire de la passerelle.

    Plage valide : [0, 2147483647].

    XffTrustedNum

    Int

    Le nombre de proxys de confiance situés devant la passerelle. Cela affecte l'utilisation par la passerelle des en-têtes de requête ajoutés par les proxys, tels que x-forwarded-for et x-request-id.

    Plage de valeurs : [0, 10]. Unité : éléments.

    DownstreamHttp2MaxConcurrentStream

    Int

    Le nombre maximal de flux simultanés sur une connexion unique lorsque le client utilise HTTP/2.

    Plage de valeurs : [0, 2147483647]. Unité : octets.

    InitialStreamWindowSize

    Int

    La taille initiale de la fenêtre de stream HTTP/2 négociée entre la passerelle et le client.

    Plage de valeurs : [65535, 2147483647]. Unité : octets.

    InitialConnectionWindowSize

    Int

    La taille initiale de la fenêtre de connexion HTTP/2 négociée entre la passerelle et le client.

    Plage de valeurs : [65535, 2147483647]. Unité : octets.

    EnableHttp3

    Bool

    Indique s'il faut prendre en charge le protocole HTTP/3.

    HTTP/3 est incompatible avec l'accélération matérielle TLS. Vous devez désactiver l'accélération matérielle avant d'activer HTTP/3.

    PathWithEscapedSlashes

    String

    Détermine l'action pour les requêtes dont les chemins URI contiennent des caractères échappés tels que %2F, %2f, %5C ou %5c. La valeur par défaut est KEEP_UNCHANGED, qui conserve les caractères tels quels.

    Valeurs valides : KEEP_UNCHANGED, REJECT_REQUEST, UNESCAPE_AND_REDIRECT et UNESCAPE_AND_FORWARD.

    ZipAlgorithm

    List<String>

    L'algorithme de compression à utiliser après l'activation de la compression. Si l'option EnableGzip n'est pas activée lors de la définition de ce paramètre, elle sera activée automatiquement. Valeurs valides : brotli, gzip.

    EnableProxyProtocol

    Bool

    Indique s'il faut activer le protocole PROXY. Lorsque le trafic ingress est acheminé via un Network Load Balancer (NLB), activez cette option pour récupérer l'adresse IP réelle du client. L'activation n'affecte pas les requêtes ne utilisant pas le protocole PROXY.

    EnableCustomAuthConfigPush

    Bool

    Pour les services d'autorisation gérés par l'utilisateur. Lorsqu'elle est activée, les modifications apportées aux règles d'autorisation n'interrompent pas les connexions actives, ce qui convient aux scénarios WebSocket et autres scénarios en temps réel.

    KeepaliveHeaderTimeout

    Int

    Définit la valeur de l'en-tête de réponse Keep-Alive renvoyée au client. Par exemple, si défini sur 10, la réponse inclut keep-alive: timeout=10. Si défini sur 0, cet en-tête n'est pas renvoyé.

    Plage de valeurs : [0, 600]. Unité : secondes.

    WebsocketTermGracePeriod

    Int

    La période de grâce pour les connexions WebSocket actives lorsque la passerelle ferme les connexions, par exemple lors de mises à niveau ou de redémarrages.

    Plage de valeurs : [20, 900]. Unité : secondes.

    EnableGzipHardwareAccelerate

    Bool

    Active la compression Gzip accélérée matériellement. Par rapport au Gzip logiciel, cela offre des performances plus élevées avec une consommation de CPU plus faible. Cette option n'est pas disponible dans les régions non prises en charge ou si l'accélération matérielle Gzip n'a pas été spécifiée lors de l'achat. Lorsqu'elle est activée, les paramètres EnableGzip et ZipAlgorithm ne prennent pas effet.

    EnableK8sSourceWorkloadFilter

    Bool

    Filtre les ressources Ingress, Service et Pod en fonction des libellés spécifiés lorsque vous ajoutez une source de service. Le filtrage inverse est également pris en charge.

    FAQ

    Que faire si l'endpoint est vide après la suppression et la recréation d'un Ingress APIG ?

    Si vous supprimez un Ingress et le recréez en utilisant le même fichier YAML, mais que l'endpoint reste vide après un certain temps, cela signifie généralement que les options d'écouteur Ingress ne sont pas configurées dans l'ApigConfig. Par conséquent, l'instance de passerelle APIG ne surveille pas la ressource Ingress. Procédez au dépannage comme suit :

    1. Vérifiez si spec.ingress.local.ingressClass est configuré dans l'ApigConfig. Si ce champ n'est pas configuré, l'instance de passerelle APIG ne surveille aucune ressource Ingress et l'endpoint n'est pas restauré après la recréation de l'Ingress. Définissez ce champ sur apig.

    2. Assurez-vous que l'IngressClass de l'Ingress correspond à la valeur ingress.local.ingressClass dans l'ApigConfig. Vous pouvez spécifier l'IngressClass d'un Ingress en utilisant l'annotation kubernetes.io/ingress.class: apig ou le champ spec.ingressClassName.

    3. Exécutez la commande kubectl get apigconfig pour vérifier si l'état de l'ApigConfig est Listening.

    4. Recréez l'Ingress une fois les configurations précédentes correctes. L'endpoint est alors automatiquement restauré. Il n'est pas nécessaire de recréer l'instance de passerelle APIG.