Configure ApigConfig-API Gateway(API Gateway)-阿里云帮助中心

ApigConfig overview

Configuration

ApigConfig is a CRD that the APIG Controller uses to manage 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.

The following code 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`	Enables or disables TLS hardware acceleration. This feature can significantly improve the performance of HTTPS traffic.	Enabled
`global.ipAccessControl.whitelist`	The global IP whitelist.	Not configured
`global.ipAccessControl.blacklist`	The global IP blacklist.	Not configured
`monitor.logging.sls`	Enables or disables Simple Log Service (SLS). To enable this feature, grant the required SLS permissions to the APIG Controller.	Disabled
`monitor.logging.sls.reuseProject`	The destination Simple Log Service (SLS) project for 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`	Specifies 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 you create an ApigConfig resource, you can run the kubectl get ApigConfig command to check its status. The resource transitions through the following states in order: Pending > Running > Listening. The following describes each state:

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 code creates an APIG gateway instance named apig-ingress with the instance type apigw.small.x1. You can 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 the spec.override parameter to control whether the ApigConfig settings overwrite the instance's existing 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 configurations of the reused APIG gateway instance 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 in reuse scenarios.

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

Use 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 the 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 to APIG Ingress.

The following sample code denies requests from the source IP address 1.1.XX.XX or the CIDR block 2.0.XX.XX/8 to the APIG Ingress gateway instance.

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 permissions for Simple Log Service (SLS).

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

Configuring OpenTelemetry tracing for the gateway helps you build an end-to-end tracing system to quickly diagnose and troubleshoot production issues.

The following sample code configures OpenTelemetry tracing for the APIG Ingress gateway 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	Applies to requests. When enabled, a request ID is generated in the request header for tracing purposes.
`EnableGzip`	Bool	Applies to requests and responses. Enabling Gzip compresses requests and responses, reducing gateway traffic but increasing its CPU consumption.
`EnableSlashMerge`	Bool	This setting applies during the request phase. When enabled, it merges redundant `'/'` characters in requests. After this setting is enabled, the redundant `'/'` in `www.a.com//b` is merged, making the URL identical to `www.a.com/b`.
`DownstreamConnectionBufferLimits`	Int	Applies to gateway connections. The buffer size of a single connection, which affects throughput and gateway memory usage. Valid range: [0, 2147483647].
`XffTrustedNum`	Int	Applies to requests. 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	Applies to requests. The maximum number of concurrent streams on a single connection when the client uses HTTP/2. Value range: [0, 2147483647]. Unit: bytes.
`InitialStreamWindowSize`	Int	Applies to requests. The initial HTTP/2 `stream` window size negotiated between the gateway and the client. Value range: [65535, 2147483647]. Unit: bytes.
`InitialConnectionWindowSize`	Int	Applies to requests. 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>	开启压缩后使用的算法.如果此时`EnableGzip`未开启，将自动开启`EnableGzip`选项。可取值：`brotli`、`gzip`。
`EnableProxyProtocol`	Bool	Specifies whether to enable the PROXY protocol. If 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	Applies to scenarios that use a self-managed authorization service. When enabled, changes to authorization rules do not cause connection interruptions. This is suitable for WebSocket and other real-time online business scenarios.
`KeepaliveHeaderTimeout`	Int	Generates a `Keep-Alive` response header that is returned to the client to indicate the connection keep-alive time. For example, if set to 10, the response header `keep-alive: timeout=10` is returned. If set to 0, this response header is not returned. Value range: [0, 600]. Unit: seconds.
`WebsocketTermGracePeriod`	Int	The grace period for WebSocket connections when the gateway instance needs to close connections, such as during upgrades or restarts. Value range: [20, 900]. Unit: seconds.
EnableGzipHardwareAccelerate	Bool	Performs Gzip compression by using dedicated hardware. When enabled, it compresses requests and responses, significantly reducing gateway traffic with higher performance and lower CPU consumption than software Gzip. This option cannot be enabled 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.

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.