配置ApigConfig - API Gateway

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: InternetAndIntranet # 公網+私網，僅 APIG Controller v1.1.0 及以上版本支援
    securityGroupType: enterprise
  global:
    tls:
      enableHardwareAcceleration: true
    ipAccessControl:
      whitelist:
        - 1.1.XX.XX
        - 2.2.XX.XX
  monitor:
    logging:
      sls:
        reuseProject: "xxx" # 為空白表示使用預設 Project
    tracing:
      openTelemetry:
        sampleRate: "100"
  ingress:
    local:
      ingressClass: apig
      watchNamespace: "" # 空值表示監聽所有命名空間中的 Ingress 資源
  gatewayAPI: # 僅 APIG Controller v1.1.0 及以上版本支援
    local:
      enable: true
      watchNamespace: "" # 空值表示監聽所有命名空間
      gatewayClass: "" # 空值表示監聽所有 GatewayClass

參數	說明	預設值
`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`	雲原生 API Gateway執行個體的網路訪問類型。可選值： Internet：公網 Intranet：私網 InternetAndIntranet：公網和私網說明：僅 APIG Controller v1.1.0 及以上版本支援 InternetAndIntranet。	Internet（公網）
`common.securityGroupType`	安全性群組類型。可選值： enterprise：企業安全性群組 normal：普通安全性群組	normal
`global.tls.enableHardwareAcceleration`	TLS硬體加速開關。可以大幅提升HTTPS流量的效能。	開啟
`global.ipAccessControl.whitelist`	全域 IP 訪問白名單。不能與黑名單同時配置。	未配置
`global.ipAccessControl.blacklist`	全域 IP 訪問黑名單。不能與白名單同時配置。	未配置
`monitor.logging.sls`	SLSLog Service開關。開啟需要賦予Controller有關SLS的許可權。	關閉
`monitor.logging.sls.reuseProject`	SLSLog Service，投遞訪問日誌的目標Project。可選值：空：表示使用預設Project（建立）。指定值：表示使用已有的Project。	配置為空白
`monitor.tracing.xTrace.sampleRate`	XTrace 鏈路追蹤採樣率，使用整數字串配置。	未配置
`monitor.tracing.openTelemetry`	OpenTelemetry 鏈路追蹤開關。	預設關閉。請勿與 XTrace 同時配置；如同時配置，OpenTelemetry 優先生效。
`monitor.tracing.openTelemetry.sampleRate`	OpenTelemetry 鏈路追蹤採樣率，使用整數字串配置。	未配置
`ingress.local.ingressClass`	APIG 網關監聽叢集中指定 IngressClass 下的 Ingress 資源。可選值：未配置：監聽 IngressClass 為 apig 的 Ingress 資源。配置為空白字串：監聽所有 Ingress 資源。配置為 nginx：監聽 IngressClass 為 nginx 或未關聯任何 IngressClass 的 Ingress 資源。配置為其他值：監聽指定 IngressClass 的 Ingress 資源。說明：通過 IngressClass 資源關聯 ApigConfig 的配置優先順序更高。	apig
`ingress.local.watchNamespace`	APIG網關監聽叢集中哪些命名空間的Ingress資源。可選值：配置為空白：監聽所有命名空間。配置為指定值：監聽指定命名空間，僅支援指定一個。	配置為空白
monitor.tracing.xTrace	XTrace 鏈路追蹤開關。	預設關閉。請勿與 OpenTelemetry 同時配置；如同時配置，OpenTelemetry 優先生效。
gatewayAPI.local.enable	是否監聽 Controller 所在叢集中的 Gateway API 資源。說明：僅 APIG Controller v1.1.0 及以上版本支援 Gateway API 監聽。	false（關閉）
gatewayAPI.local.watchNamespace	監聽 Gateway API 資源的命名空間。僅支援指定一個命名空間。	配置為空白，監聽所有命名空間。
gatewayAPI.local.gatewayClass	監聽的 GatewayClass。僅支援指定一個 GatewayClass。	配置為空白，監聽所有 GatewayClass。

狀態說明

建立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網關管理的Container Service叢集的入口流量。
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
```
在Container Service叢集中建立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授權。

以下範例程式碼，配置APIG Ingress網關投遞訪問日誌到名為demo的Project。

apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
   name: apig-ingress
spec:
   ...
  monitor:
    logging:
      sls:
        # 配置reuseProject才能開啟SLSLog Service。如需使用預設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 Gateway管理主控台。在云原生API网关 > 实例中找到由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資源。支援反過濾。

常見問題

刪除 APIG Ingress 後重建，端點為空白怎麼辦？

刪除 Ingress 後使用相同 YAML 重建，若等待較長時間端點仍為空白，通常是 ApigConfig 未配置 Ingress 監聽選項，導致 APIG 網關不監聽該 Ingress 資源。請按以下步驟排查：

檢查 ApigConfig 的spec.ingress.local.ingressClass是否已配置。未配置時 APIG 網關不監聽任何 Ingress 資源，重建 Ingress 後端點不會恢複。請將該欄位配置為apig。
確認 Ingress 的 IngressClass 與 ApigConfig 的ingress.local.ingressClass取值一致。Ingress 可通過kubernetes.io/ingress.class: apig註解或spec.ingressClassName欄位指定 IngressClass。
執行kubectl get apigconfig命令，檢查 ApigConfig 狀態是否為Listening。
無需重建 APIG 網關執行個體。以上配置正確後，重新建立 Ingress 即可自動回復端點。