通过CRD管理云原生网关实例配置-容器服务Kubernetes版ACK-阿里云

ApigConfig是由APIG Controller提供的CRD资源，用于管理APIG网关实例的生命周期、配置Ingress监听选项以及全局配置。可安装并管理ApigConfig，并配置实现全局实例级别的IP黑白名单访问控制、日志采集、链路追踪等功能。

ApigConfig说明

配置说明

ApigConfig是由APIG Controller提供的CRD资源，APIG Controller使用ApigConfig来管理APIG网关实例的生命周期以及全局配置。

一个ApigConfig对应一个APIG网关实例。如需使用多个APIG网关实例，需创建多个ApigConfig配置。

除复用场景外，删除ApigConfig配置，会级联删除对应的APIG网关实例。

以下示例代码为完整的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" # 为空，表示使用默认
    tracing:
      openTelemetry:
        sampleRate: "100"
  ingress:
    local:
      ingressClass:  apig
      watchNamespace: "" # ""表示所有命名空间中的Ingress资源

参数	说明	默认值
`name`	网关名称。	apig-ingress
`common.pay.payType`	付费类型。目前只支持按量付费。若不配置，默认使用按量付费。	POSTPAY
`common.instance.spec`	网关实例规格。可选值： 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`	主备交换机，主在前，备在后。主备交换机在填写时至少指定一个，至多两个；不填则从Controller Pod所在的节点上获取交换机。	无
`common.network.networkType`	网关代购的公网SLB规格。可选值： Internet Intranet	Internet
`common.securityGroupType`	安全组类型。可选值： enterprise：企业安全组 normal：普通安全组	normal
`global.tls.enableHardwareAcceleration`	TLS硬件加速开关。可以大幅提升HTTPS流量的性能。	开启
`global.ipAccessControl.whitelist`	全局IP访问白名单。	未配置
`global.ipAccessControl.blacklist`	全局IP访问黑名单。	未配置
`monitor.logging.sls`	SLS日志服务开关。开启需要赋予Controller有关SLS的权限。	关闭
`monitor.logging.sls.reuseProject`	SLS日志服务，投递访问日志的目标Project。可选值：空：表示使用默认Project（新建）。指定值：表示使用已有的Project。	配置为空
`monitor.tracing.xTrace.sampleRate`	OpenTelemetry链路追踪采样率。	0
`monitor.tracing.openTelemetry`	OpenTelemetry链路追踪开关。	默认关闭，与OpenTelemetry互斥开启。
`monitor.tracing.openTelemetry.sampleRate`	openTelemetry链路追踪采样率。	100
`ingress.local.ingressClass`	APIG网关监听集群中具体IngressClass下的Ingress资源。可选值：未配置：不监听任何Ingress资源。配置为`apig`：监听IngressClass为apig 的Ingress资源配置为空`""`：监听所有Ingress资源。配置为`nginx`：监听IngressClass为nginx或者未关联任何IngressClass的Ingress资源。配置为其他值：监听IngressClass为指定值的Ingress资源。说明该配置的优先级低于通过IngressClass资源关联ApigConfig的方式。	未配置
`ingress.local.watchNamespace`	APIG网关监听集群中哪些命名空间的Ingress资源。可选值：配置为空：监听所有命名空间。配置为指定值：监听指定命名空间，仅支持指定一个。	配置为空

状态说明

创建ApigConfig资源后，可以通过kubectl get ApigConfig查看资源状态。ApigConfig会按照Pending > Running > Listening的状态依次变化。各状态说明如下：

Pending：APIG网关正在创建中，需等待3min左右。
Running：APIG网关创建成功，并处于运行状态。
Listening：APIG网关处于运行状态，并监听集群中Ingress资源。
Failed：APIG网关处于非法状态，可以查看Status字段中Message来进一步明确原因。

标签说明

通过ApigConfig创建或者复用的APIG网关实例会被打上资源标签，可在APIG控制台基本信息中查看目标网关的标签信息。

重要

请勿在APIG网关控制台编辑下表中的标签，避免对您的网关实例造成影响。

标签名	说明
ack.aliyun.com	APIG网关管理的容器服务集群的入口流量。
ingress.k8s.alibaba/ApigConfig	APIG网关与ApigConfig关联。
kubernetes.reused.by.user	APIG网关是否是复用场景。当为复用场景时，删除与之关联的ApigConfig时，该APIG网关实例不会被删除。

创建APIG网关实例

配置ApigConfig。
通过以下是示例代码，创建一个名为apig-ingress，副本数为3，实例规格为2c4g的APIG网关实例。您可以按需修改ApigConfig的其他配置。
```
apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
  name: apig-ingress
spec:
  name: apig-ingress
  common:
    instance:
      spec: apigw.small.x1
```
在容器服务集群中创建IngressClass资源，并通过spec.parameters关联ApigConfig，以在集群中声明一个Ingress处理器。
配置后，集群中关联该IngressClass的Ingress资源就会被以上ApigConfig关联的APIG网关实例处理并实施。
```
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
```

复用已有APIG网关实例

如需复用已有APIG网关实例，在创建ApigConfig时可通过spec.id指定APIG网关实例唯一ID （格式为gw-xxx)，并通过参数spec.override来控制是否根据ApigConfig覆盖被复用的APIG网关实例的相关配置。

以下示例代码，通过ApigConfig复用已有APIG网关实例，设置该网关实例关联容器集群并监听该容器集群中ingressClass为apig的Ingress资源。

重要

以下配置中spec.override设置为false，表示不覆盖已有的APIG网关的Ingress监听选项和全局配置。如果已有的网关实例没有关联该容器集群，将会自动设置该网关实例关联容器集群并设置Ingress监听选项，监听该容器集群中ingressClass为spec.ingress.local.ingressClass值的Ingress资源（此处设置的apig）；如果已有的网关实例已经关联过该容器集群，则不会覆盖原有的Ingress监听选项。
如需覆盖已有的APIG网关的Ingress监听选项和全局配置，请确保ApigConfig中网关参数配置（Ingress监听选项、硬件加速、全局黑白名单、可观测）正确之后，再开启spec.override。当这些配置在ApigConfig未指定，开启spec.override会覆盖网关原有的参数配置（Ingress监听选项、硬件加速、全局黑白名单、可观测），可能对流量造成影响。

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

参数

说明

spec.id

复用的目标APIG网关实例ID，格式gw-开头。

spec.override

是否根据ApigConfig配置覆盖被复用的APIG网关实例的相关配置。

设置为true：覆盖修改网关原有的参数配置（Ingress监听选项、硬件加速、全局黑白名单、可观测）
设置为false，不会覆盖修改网关原有的参数配置（Ingress监听选项、硬件加速、全局黑白名单、可观测）。但是如果已有的网关实例没有关联该容器集群，将会自动设置该网关实例关联容器集群并设置Ingress监听选项，监听该容器集群中ingressClass为spec.ingress.local.ingressClass值的Ingress资源。

删除APIG网关实例

一个ApigConfig对应一个APIG网关实例。除复用场景除外，删除ApigConfig配置，会级联删除对应的APIG网关实例。

删除策略如下表所示。

网关付费类型	APIG Controller自动创建	复用控制台已购网关
按量付费	删除ApigConfig，自动删除网关实例。	删除ApigConfig，保留网关实例。

执行如下命令，删除ApigConfig配置。

kubectl delete ApigConfig your-config-name

配置全局实例级别的IP访问控制

配置IP白名单

配置全局实例级别的IP白名单，只允许目标源IP访问APIG Ingress。

以下示例代码，配置只允许源IP地址为1.1.XX.XX或者网段为2.0.XX.XX/8访问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
   ...

配置IP黑名单

配置全局实例级别的IP黑名单，拒绝目标源IP访问APIG Ingress。

以下示例代码，配置拒绝源IP地址为1.1.XX.XX或者网段为2.0.XX.XX/8访问APIG Ingress网关实例。

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

开启SLS日志

开启SLS日志之前，请确保已为APIG Controller授予SLS相关权限。

ACK托管集群：参见为APIG Controller授权。

以下示例代码，配置APIG Ingress网关投递访问日志到名为demo的Project。

apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
   name: apig-ingress
spec:
   ...
  monitor:
    logging:
      sls:
        # 配置reuseProject才能开启SLS日志服务。如需使用默认Project，可配置为空。
        reuseProject: "demo"
    ...

开启OpenTelemetry链路追踪

为网关配置阿里云OpenTelemetry链路追踪服务后，可实现构建端到端的全链路追踪监控体系，方便线上问题快速诊断和定位。

以下示例代码，配置APIG Ingress网关的OpenTelemetry链路追踪，其中采样率（sampleRate）为100%。

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

更多配置

APIG Ingress使用的网关实例支持下列的更多配置。

如需使用这些配置，请登录云原生API网关管理控制台。在APIG网关 > 网关列表中找到由APIG Controller使用的已有或自动创建的网关实例，单击实例ID，然后单击左侧的参数配置。

配置项	类型	说明
`EnableGenerateRequestId`	Bool	作用于请求范围，根据配置会在请求头中生成requestId，以便追踪请求。
`EnableGzip`	Bool	作用于请求与响应环节，启用gzip会对请求响应进行压缩，会减少网关流量，增加网关CPU消耗。
`EnableSlashMerge`	Bool	作用于请求环节，是否合并请求中多余的`'/'` 开启后`www.a.com//b`多余的`'/'`会被合并，将会同`www.a.com/b`一致。
`DownstreamConnectionBufferLimits`	Int	作用于网关连接，单条链接的buffer大小，配置后会影响吞吐和网关的内存使用。取值范围：[0, 2147483647]。
`XffTrustedNum`	Int	作用于请求环节，网关前可信任的代理个数，会影响网关是否会使用客户端产生的`x-forwarded-for`和`x-request-id`等请求头。取值范围：[0, 10]。单位：个。
`DownstreamHttp2MaxConcurrentStream`	Int	作用于请求环节，客户端使用HTTP 2时一条链接上最大并发数。取值范围：[0, 2147483647]。单位：byte。
`InitialStreamWindowSize`	Int	作用于请求环节，网关同客户端使用HTTP 2时协商的`stream`初始窗口大小。取值范围：[65535, 2147483647]。单位：byte。
`InitialConnectionWindowSize`	Int	作用于请求环节，网关同客户端使用http2时连接级别初始窗口大小。取值范围：[65535, 2147483647]。单位：byte。
`EnableHttp3`	Bool	是否支持HTTP 3协议。 HTTP 3 与硬件加速功能不兼容，请先关闭硬件加速功能后再开启 HTTP3 支持。
`PathWithEscapedSlashes`	String	确定 URI 路径中包含 %2F、%2f、%5C 或 %5c 这些转义的请求的操作, 默认为`KEEP_UNCHANGED`，即保持不变。可取值：`KEEP_UNCHANGED`、`REJECT_REQUEST`、`UNESCAPE_AND_REDIRECT`、`UNESCAPE_AND_FORWARD`。
`ZipAlgorithm`	List<String>	开启压缩后使用的算法.如果此时`EnableGzip`未开启，将自动开启`EnableGzip`选项。可取值：`brotli`、`gzip`。
`EnableProxyProtocol`	Bool	是否开启Proxy协议，如果网关入口流量使用NLB接入，如果不开启则无法获取客户端的真实IP，开启后对于非Proxy协议请求没有影响。
`EnableCustomAuthConfigPush`	Bool	作用于使用自建的鉴权服务的场景，开启后鉴权规则变更不会引起连接中断，适用于WebSocket和在线业务场景。
`KeepaliveHeaderTimeout`	Int	用于生成Keep-Alive响应头返回给客户端，告知连接的保活时间。例如配置为10时，会返回响应头`keep-alive: timeout=10`。配置为0时，不会返回该响应头。可取值：[0, 600]。单位：s。
`WebsocketTermGracePeriod`	Int	当网关实例升级、重启等需要关闭连接的场景下，为 Websocket 连接维持的保活时间。取值范围：[20, 900]。单位：s。
EnableGzipHardwareAccelerate	Bool	基于专用硬件进行Gzip压缩。启用后会对请求响应进行压缩，大幅降低网关流量，相比软件Gzip性能更高，CPU消耗更小。不支持的地域，或者购买时未指定开启Gzip硬件加速将无法开启。开启后，`EnableGzip`和`ZipAlgorithm`将不会生效。
EnableK8sSourceWorkloadFilter	Bool	添加服务来源时根据指定标签过滤Ingress、Service、Pod资源。支持反过滤。