Container Service for Kubernetes:Configure ApigConfig

Key concepts

One ApigConfig, one gateway instance. Each ApigConfig maps to exactly one APIG gateway instance. To run multiple gateway instances in a cluster, create a separate ApigConfig for each.

Deletion behavior. Deleting an ApigConfig cascades to the associated gateway instance — except in reuse scenarios, where the gateway instance is retained. See Delete an APIG gateway instance.

Resource tags. Every gateway instance created or reused through ApigConfig is assigned the following tags. Do not edit these tags from the APIG console — doing so can affect your gateway instance.

Create an APIG gateway instance

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

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

kubectl get ApigConfig

Reuse an existing APIG gateway instance

To associate an existing gateway with your cluster instead of creating a new one, specify the gateway ID in spec.id. Use spec.override to control whether ApigConfig overwrites the gateway's existing configuration.

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

Replace gw-xxxx with the actual gateway ID (format: gw-xxx).

`spec.override` behavior:

When override is false (recommended for most reuse scenarios):

• The gateway's existing Ingress listener options and global configurations are preserved.

• If the gateway is not yet associated with the cluster, it is automatically associated.

• The Ingress listener is configured to watch Ingress resources whose ingressClass matches spec.ingress.local.ingressClass (in this example, apig).

• If the gateway is already associated with the cluster, its original Ingress listener options are retained unchanged.

When override is true:

• All existing gateway configurations are overwritten — including Ingress listener options, hardware acceleration, global IP access control, and observability settings.

• Before setting override: true, specify every required gateway parameter in the ApigConfig. Missing parameters will erase the corresponding existing settings, which may disrupt live traffic.

Delete an APIG gateway instance

Deleting an ApigConfig deletes the corresponding gateway instance, except when the gateway was reused from the console.

Run the following command to delete an ApigConfig:

kubectl delete ApigConfig your-config-name

Configure IP access control

Configure a global, instance-level IP whitelist or blacklist to control which source IPs can reach the APIG Ingress.

apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
  name: apig-ingress
spec:
  ...
  global:
    ipAccessControl:
      whitelist:
      - 1.1.XX.XX
      - 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
  ...

Enable Simple Log Service (SLS) logs

Before enabling SLS logs, grant the required SLS permissions to the APIG Controller.

The following example delivers access logs to an existing SLS project named demo. To use a default project instead, leave reuseProject blank.

apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
  name: apig-ingress
spec:
  ...
  monitor:
    logging:
      sls:
        reuseProject: "demo"
  ...

Enable OpenTelemetry Tracing Analysis

Configure OpenTelemetry Tracing Analysis to build an end-to-end tracing system for diagnosing live traffic issues.

The following example enables tracing with a 100% sample rate:

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

ApigConfig parameter reference

The following table lists all ApigConfig parameters. Parameters marked Yes in the Required column must be set; all others are optional.

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: "" # "" watches all namespaces.

Additional gateway configurations

Some gateway parameters are not configurable through ApigConfig and must be set in the console. In the Cloud-native API Gateway console, go to APIG Gateway > Gateway List, click the instance ID, and then click Parameter Settings in the left navigation pane.