配置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: 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`	SLSLog Service開關。開啟需要賦予Controller有關SLS的許可權。	關閉
`monitor.logging.sls.reuseProject`	SLSLog Service，投遞訪問日誌的目標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網關管理的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授予SLS相關許可權。

ACK託管叢集：參見為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管理主控台。在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資源。支援反過濾。