Configure ApigConfig - Container Service for Kubernetes - Alibaba Cloud Documentation Center

ApigConfig overview

Configuration

ApigConfig is a CRD provided by the APIG Controller for managing the lifecycle and global configurations of APIG gateway instances.

Each ApigConfig corresponds to one APIG gateway instance. To use multiple APIG gateway instances, you must create multiple ApigConfig resources.

Except in reuse scenarios, deleting an ApigConfig also deletes the corresponding APIG gateway instance.

Important

For an APIG gateway instance created by using a CRD (ApigConfig), manage business configurations such as APIs, routes, and certificates in the CRD. You can use the APIG console for operations such as scaling. Do not modify the business configurations of a CRD-created instance in the console, because CRD synchronization may overwrite your changes and cause configuration conflicts.

The following is a complete ApigConfig configuration example.

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.

Parameter	Description	Default
`name`	The gateway name.	apig-ingress
`common.pay.payType`	The billing method. Only pay-as-you-go is supported and is the default if not specified.	POSTPAY
`common.instance.spec`	The gateway instance type. Valid values: 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`	The primary and standby vSwitches, in that order. Specify one or two vSwitches. If unspecified, the vSwitches are inherited from the node where the APIG Controller pod runs.	None
`common.network.networkType`	The network accessibility of the gateway. Valid values: Internet Intranet	Internet
`common.securityGroupType`	The security group type. Valid values: enterprise: advanced security group normal: basic security group	normal
`global.tls.enableHardwareAcceleration`	Specifies whether to enable TLS hardware acceleration. This feature can significantly improve HTTPS traffic performance.	Enabled
`global.ipAccessControl.whitelist`	The global IP whitelist.	Not configured
`global.ipAccessControl.blacklist`	The global IP blacklist.	Not configured
`monitor.logging.sls`	Specifies whether to enable Simple Log Service (SLS) log collection. To enable this feature, grant the required SLS permissions to the APIG Controller.	Disabled
`monitor.logging.sls.reuseProject`	The SLS project to store access logs. Valid values: Empty: A default project is created and used. Specified value: An existing project is used.	Empty
`monitor.tracing.xTrace.sampleRate`	The sample rate for Tracing Analysis (x-trace).	0
`monitor.tracing.openTelemetry`	Enables or disables OpenTelemetry tracing.	Disabled by default. Mutually exclusive with the `xTrace` tracing option.
`monitor.tracing.openTelemetry.sampleRate`	The sample rate for OpenTelemetry tracing.	100
`ingress.local.ingressClass`	Determines which Ingress resources the APIG gateway instance processes, based on their IngressClass. Valid values: Not configured: The gateway does not process any Ingress resources. Set to `apig`: The gateway processes Ingress resources with the IngressClass `apig`. An empty string (`""`): Listens to all Ingress resources. Set to `nginx`: Listens for Ingress resources that have an IngressClass of nginx or are not associated with any IngressClass. Set to another value: The gateway processes Ingress resources with an IngressClass that matches the specified value. Note This setting has a lower priority than associating an ApigConfig through an IngressClass.	Not configured
`ingress.local.watchNamespace`	The namespaces where the gateway watches for Ingress resources. Valid values: Empty string: Watches all namespaces. Specified value: Watches the specified namespace. Only one namespace can be specified.	Empty

Status

After creating an ApigConfig resource, run the kubectl get ApigConfig command to check its status. The resource transitions through the following states: Pending > Running > Listening.

Pending: The APIG gateway instance is being created. This process takes about 3 minutes.
Running: The APIG gateway instance is created and running.
Listening: The APIG gateway instance is running and listening for Ingress resources in the cluster.
Failed: The APIG gateway instance is in an invalid state. Check the Message in the Status field for the cause.

Create an APIG gateway instance

Configure ApigConfig.
The following example creates an APIG gateway instance named apig-ingress with the instance type apigw.small.x1. Modify other ApigConfig settings as needed.
```
apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
  name: apig-ingress
spec:
  name: apig-ingress
  common:
    instance:
      spec: apigw.small.x1
```
In your Container Service for Kubernetes (ACK) cluster, create an IngressClass and associate it with the ApigConfig by using spec.parameters. This declares an Ingress processor in the cluster.
Once configured, the linked APIG gateway instance processes any Ingress associated with this 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
```

Reuse an existing APIG gateway instance

To reuse an existing APIG gateway instance, specify its ID (for example, gw-xxx) in the spec.id field of your ApigConfig. Use spec.override to control whether the ApigConfig settings overwrite the existing instance configuration.

The following example reuses an existing APIG gateway instance. The ApigConfig associates the instance with a cluster and configures it to process Ingress resources with the apig IngressClass.

Important

In the following configuration, spec.override is set to false, which means that the Ingress listener options and global configuration of an existing APIG gateway are not overwritten. If an existing gateway instance is not associated with the container cluster, it is automatically associated with the cluster and its Ingress listener options are configured to listen for Ingress resources in the container cluster where the ingressClass is spec.ingress.local.ingressClass (in this case, apig). If the gateway instance is already associated with the container cluster, its existing Ingress listener options are not overwritten.
To overwrite the Ingress listener options and global configurations of an existing APIG gateway, ensure that the gateway parameters in the ApigConfig (Ingress listener options, hardware acceleration, global IP address blacklist and whitelist, and observability) are correctly configured before you enable spec.override. If these configurations are not specified in the ApigConfig, enabling spec.override overwrites the original gateway parameters (Ingress listener options, hardware acceleration, global IP address blacklist and whitelist, and observability), which may affect traffic.

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

Parameter

Description

spec.id

The ID of the target APIG gateway instance to reuse. The ID must start with gw-.

spec.override

Specifies whether to overwrite the reused APIG gateway instance configurations based on the ApigConfig settings.

Set to true: Overwrites the existing gateway configuration (Ingress listener options, hardware acceleration, global allowlists and blocklists, and observability).
If you set this parameter to false, the existing configurations of the gateway (such as Ingress listener options, hardware acceleration, global allowlists and blocklists, and observability) are not overwritten. However, if an existing gateway instance is not associated with the container cluster, the gateway instance is automatically associated with the container cluster and its Ingress listener options are configured to listen for Ingress resources in the container cluster whose ingressClass is set to the value of spec.ingress.local.ingressClass.

Delete an APIG gateway instance

Deleting an ApigConfig also deletes the corresponding APIG gateway instance, except for reused instances.

The following table describes the deletion policy.

Billing method	Created by APIG Controller	Reused console gateway
pay-as-you-go	Deleting the ApigConfig automatically deletes the gateway instance.	Deleting the ApigConfig retains the gateway instance.

To delete the ApigConfig, run the following command:

kubectl delete ApigConfig your-config-name

Configure global IP access control

Configure an IP whitelist

Configure a global IP whitelist to allow access to your APIG Ingress only from specific source IPs.

The following example allows access only from the source IP 1.1.XX.XX and CIDR block 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
   ...

Configure an IP blacklist

Configure a global, instance-level IP blacklist to deny access from specific source IPs.

The following example denies requests from the source IP 1.1.XX.XX and CIDR block 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 SLS logging

Before enabling log collection, ensure the APIG Controller has the required SLS permissions.

For ACK managed clusters, see Grant permissions to the APIG Controller .

The following example configures the gateway to deliver access logs to an SLS project named 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"
    ...

Enable OpenTelemetry tracing

Configure OpenTelemetry tracing for the gateway to build an end-to-end tracing system for diagnosing production issues.

The following example configures OpenTelemetry tracing with a sample rate (sampleRate) of 100%.

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

Additional configurations

The APIG Ingress gateway instance supports the following additional configurations:

To apply these settings, go to the Cloud-native API Gateway console. On the APIG Gateway > Gateway List page, select the gateway instance, and then click Parameter Settings in the left-side navigation pane.

Parameter	Type	Description
`EnableGenerateRequestId`	Bool	When enabled, a request ID is generated in the request header for tracing purposes.
`EnableGzip`	Bool	Enables Gzip compression for requests and responses, reducing gateway traffic but increasing CPU consumption.
`EnableSlashMerge`	Bool	When enabled, merges redundant `'/'` characters in request paths. For example, `www.a.com//b` becomes `www.a.com/b`.
`DownstreamConnectionBufferLimits`	Int	The buffer size of a single connection, which affects throughput and gateway memory usage. Valid range: [0, 2147483647].
`XffTrustedNum`	Int	The number of trusted proxies in front of the gateway. This affects whether the gateway uses request headers added by proxies, such as `x-forwarded-for` and `x-request-id`. Value range: [0, 10]. Unit: items.
`DownstreamHttp2MaxConcurrentStream`	Int	The maximum number of concurrent streams on a single connection when the client uses HTTP/2. Value range: [0, 2147483647]. Unit: bytes.
`InitialStreamWindowSize`	Int	The initial HTTP/2 `stream` window size negotiated between the gateway and the client. Value range: [65535, 2147483647]. Unit: bytes.
`InitialConnectionWindowSize`	Int	The initial HTTP/2 connection-level window size negotiated between the gateway and the client. Value range: [65535, 2147483647]. Unit: bytes.
`EnableHttp3`	Bool	Specifies whether to support the HTTP/3 protocol. HTTP/3 is incompatible with TLS hardware acceleration. You must disable hardware acceleration before enabling HTTP/3.
`PathWithEscapedSlashes`	String	Determines the action for requests whose URI paths contain escaped characters such as %2F, %2f, %5C, or %5c. The default is `KEEP_UNCHANGED`, which keeps the characters as they are. Valid values: `KEEP_UNCHANGED`, `REJECT_REQUEST`, `UNESCAPE_AND_REDIRECT`, and `UNESCAPE_AND_FORWARD`.
`ZipAlgorithm`	List<String>	The compression algorithm to use after compression is enabled. If the `EnableGzip` option is not enabled when this parameter is set, it will be enabled automatically. Valid values: `brotli`, `gzip`.
`EnableProxyProtocol`	Bool	Specifies whether to enable the PROXY protocol. When ingress traffic is routed through a Network Load Balancer (NLB), enable this option to retrieve the real client IP address. Enabling it does not affect non-PROXY protocol requests.
`EnableCustomAuthConfigPush`	Bool	For self-managed authorization services. When enabled, changes to authorization rules do not interrupt active connections, which is suitable for WebSocket and other real-time scenarios.
`KeepaliveHeaderTimeout`	Int	Sets the `Keep-Alive` response header value returned to the client. For example, if set to 10, the response includes `keep-alive: timeout=10`. If set to 0, this header is not returned. Value range: [0, 600]. Unit: seconds.
`WebsocketTermGracePeriod`	Int	The grace period for active WebSocket connections when the gateway closes connections, such as during upgrades or restarts. Value range: [20, 900]. Unit: seconds.
EnableGzipHardwareAccelerate	Bool	Enables hardware-accelerated Gzip compression. Compared to software Gzip, this delivers higher performance with lower CPU consumption. This option is unavailable in unsupported regions or if Gzip hardware acceleration was not specified at purchase. When enabled, the `EnableGzip` and `ZipAlgorithm` settings do not take effect.
EnableK8sSourceWorkloadFilter	Bool	Filters Ingress, Service, and Pod resources based on specified labels when you add a service source. Inverse filtering is also supported.

FAQ

What do I do if the endpoint is empty after I delete and re-create an APIG Ingress?

If you delete an Ingress and re-create it by using the same YAML file, but the endpoint remains empty after you wait for a period of time, the Ingress listener options are usually not configured in the ApigConfig. As a result, the APIG gateway instance does not watch the Ingress resource. Troubleshoot the issue as follows:

Check whether spec.ingress.local.ingressClass is configured in the ApigConfig. If this field is not configured, the APIG gateway instance does not watch any Ingress resources, and the endpoint is not restored after you re-create the Ingress. Set this field to apig.
Make sure that the IngressClass of the Ingress matches the ingress.local.ingressClass value in the ApigConfig. You can specify the IngressClass of an Ingress by using the kubernetes.io/ingress.class: apig annotation or the spec.ingressClassName field.
Run the kubectl get apigconfig command to check whether the status of the ApigConfig is Listening.
Re-create the Ingress after the preceding configurations are correct. The endpoint is then automatically restored. You do not need to re-create the APIG gateway instance.

Tag	Description
ack.aliyun.com	Indicates that the APIG gateway manages the ingress traffic of a Container Service for Kubernetes (ACK) cluster.
ingress.k8s.alibaba/ApigConfig	Associates the APIG gateway instance with an ApigConfig.
kubernetes.reused.by.user	Indicates if the APIG gateway instance is reused. A reused instance is not deleted when its associated ApigConfig is deleted.

Container Service for Kubernetes:Configure ApigConfig