全部產品
Search

搜尋本產品

    Microservices Engine：配置MseIngressConfig

    文件中心

    Microservices Engine：配置MseIngressConfig

    更新時間：Aug 14, 2025

    MseIngressConfig是由MSE Ingress Controller提供的CRD資源，用於管理MSE雲原生網關執行個體的生命週期，配置Ingress監聽選項以及全域配置。本文介紹MseIngressConfig的常見用法，包含如何通過MseIngressConfig建立、複用和刪除MSE雲原生網關執行個體，以及如何配置全域執行個體層級的IP黑白名單存取控制、開啟SLS日誌和開啟可觀測鏈路OpenTelemetry鏈路追蹤。

    背景資訊

    MSE Ingress Controller負責監聽叢集中建立的MseIngressConfig資源，即時動態維護該資源對應的雲原生網關執行個體的生命週期以及該網關與ACK託管版/ACK Serverless/ACS叢集的關聯性。

    通過關聯ACK託管版/ACK Serverless/ACS叢集的API Server，MSE雲原生網關的控制面可以擷取Ingress資源的變化，然後動態更新MSE雲原生網關的路由規則。收到請求時，MSE雲原生網關將匹配Ingress轉寄規則轉寄請求到後端Service所對應的Pod。

    Kubernetes中的Service、Ingress、IngressClass、MseIngressConfig和MSE Ingress Controller存在以下關係：

    • Service：後端真實服務的抽象，一個Service可以代表多個相同的後端服務。

    • Ingress：反向 Proxy規則，用來規定HTTP和HTTPS請求應該被轉寄到哪個Service上。例如，根據請求中不同的Host和URL路徑，使請求轉寄到不同的Service上。

    • IngressClass：Ingress處理器的描述，用於在K8s叢集中聲明一個Ingress處理器實現，關聯該IngressClass的Ingress資源會被該Ingress處理器解析。此外，需要通過IngressClass的Parameter欄位關聯一個MseIngressConfig（MSE雲原生網關），用於實施被解析的Ingress資源描述的流量管理規則。

    • MseIngressConfig：由MSE Ingress Controller提供的CRD，用於描述雲原生網關執行個體的基本資料。

    • MSE Ingress Controller：管理MSE雲原生網關執行個體以及配置的控制平面，本身不是網路資料平面。負責監聽叢集中的MseIngressConfig資源，協調MSE雲原生網關執行個體，以實施Ingress資源描述的流量管理規則。

    MSE Ingress Controller工作示意圖。ingress的應用情境

    MseIngressConfig說明

    配置說明

    MseIngressConfig是由MSE Ingress Controller提供的CRD資源，MSE Ingress Controller使用MseIngressConfig來管理MSE雲原生網關執行個體的生命週期以及全域配置。

    說明

    一個MseIngressConfig對應一個MSE雲原生網關執行個體。如果您需要使用多個MSE雲原生網關執行個體，需要建立多個MseIngressConfig配置。除複用情境外，刪除MseIngressConfig配置，會串聯刪除對應的MSE雲原生網關執行個體。

    以下範例程式碼為完整的MseIngressConfig配置。

    apiVersion: mse.alibabacloud.com/v1alpha1
kind: MseIngressConfig
metadata:
  name: test
spec:
  name: mse-ingress
  common:
    pay:
      payType: POSTPAY
    instance:
      spec: 4c8g
      replicas: 3
    network:
      vSwitches:
      - "vsw-1"
      - "vsw-2"
      publicSLBSpec: slb.s2.small
    securityGroupType: normal
  global:
    downstreamIdleTimeout: 15
    enableHttp2: true
    enableXffTrustedCidrs: |-
      {"enable":true,"ipListContent":"x.x.x.x/24
      x.x.x.x"}
    preserveHeaderFormat: true
    upstreamIdleTimeout: 30
    tls:
      enableHardwareAcceleration: true
    ipAccessControl:
      whitelist:
      - 1.1.XX.XX
      - 2.2.XX.XX
  monitor:
    logging:
      sls:
        reuseProject: "xxx" # 為空白，表示使用預設
        compatibleNginx: false
    tracing:
      openTelemetry:
        sampleRate: "100"
  ingress:
    local:
      ingressClass:  mse
      watchNamespace: "" # ""表示所有命名空間中的Ingress資源

    參數

    說明

    是否可選

    預設值

    name

    網關的名稱。

    可選

    mse-ingress

    common.pay.payType

    付費類型。

    目前只支援隨用隨付。

    可選

    若不配置，系統預設選擇隨用隨付。

    POSTPAY

    common.instance.spec

    網關執行個體規格。

    可選值：

    • 2c4g

    • 4c8g

    • 8c16g

    • 16c32g

    可選

    4c8g

    common.instance.replicas

    網關執行個體副本數。

    網關執行個體副本數為0~30個。

    可選

    3個

    common.network.vSwitches

    主備交換器，主在前，備在後。

    主備交換器在填寫時至少指定一個，至多兩個；不填則從Controller Pod所在的Node上擷取交換器。

    可選

    無

    common.network.publicSLBSpec

    網關代購的公網SLB規格。

    可選值：

    • slb.s1.small

    • slb.s2.small

    • slb.s2.medium

    • slb.s3.small

    • slb.s3.medium

    • slb.s3.large

    可選

    slb.s2.small

    common.network.privateSLBSpec

    網關代購的私網SLB規格。

    可選值：

    • slb.s1.small

    • slb.s2.small

    • slb.s2.medium

    • slb.s3.small

    • slb.s3.medium

    • slb.s3.large

    可選

    slb.s2.small

    common.securityGroupType

    安全性群組類型。

    可選值：

    • enterprise：企業安全性群組

    • normal：普通安全性群組

    可選

    normal

    global.tls.enableHardwareAcceleration

    TLS硬體加速開關。

    可以大幅提升HTTPS流量的效能。

    可選

    開啟

    global.ipAccessControl.whitelist

    全域IP訪問白名單。

    可選

    未配置

    global.ipAccessControl.blacklist

    全域IP訪問黑名單。

    可選

    未配置

    global.downstreamIdleTimeout

    下遊用戶端與網關之間的串連空閑逾時時間。如果在此時間內沒有任何讀寫活動，網關將主動斷開此串連。單位：秒。

    可選

    15

    global.enableHttp2

    是否為網關啟用 HTTP/2 協議支援。

    可選

    false

    global.enableXffTrustedCidrs

    配置可信任的中間代理 IP 位址段（CIDR 格式），例如阿里雲 WAF 或 CDN。此配置使網關在解析 X-Forwarded-For (XFF) 要求標頭時，能夠跳過這些可信代理的 IP，從而準確擷取到最終的用戶端真實 IP。

    可選

    未配置

    global.preserveHeaderFormat

    是否保留用戶端要求標頭（Header）的原始大小寫格式。

    可選

    false

    global.upstreamIdleTimeout

    網關與上遊後端服務之間的串連空閑逾時時間。如果在此時間內沒有任何活動，網關將主動關閉它。單位：秒。

    可選

    30

    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

    雲原生網關監聽叢集中具體IngressClass下的Ingress資源。

    可選值：

    • 未配置：不監聽任何Ingress資源。

    • 配置為mse：監聽IngressClass為mse的Ingress資源

    • 配置為空白""：監聽所有Ingress資源。

    • 配置為nginx：監聽IngressClass為nginx或者未關聯任何IngressClass的Ingress資源。

    • 配置為其他值：監聽IngressClass為指定值的Ingress資源。

    說明

    該配置的優先順序低於使用者通過IngressClass資源關聯MseIngressConfig的方式。

    可選

    未配置

    ingress.local.watchNamespace

    雲原生網關監聽叢集中哪些命名空間的Ingress資源。

    可選值：

    • 配置為空白：監聽所有命名空間。

    • 配置為指定值：監聽指定命名空間，僅支援指定一個。

    可選

    配置為空白

    狀態說明

    當您建立MseIngressConfig資源後，可以通過kubectl get mseingressconfig的方式查看資源的狀態。MseIngressConfig會按照Pending > Running > Listening的狀態依次變化。各狀態說明如下：

    • Pending：雲原生網關正在建立中，需等待3min左右。

    • Running：雲原生網關建立成功，並處於運行狀態。

    • Listening：雲原生處於運行狀態，並監聽叢集中Ingress資源。

    • Failed：雲原生網關處於非法狀態，可以查看Status欄位中Message來進一步明確原因。

    標籤說明

    通過MseIngressConfig建立或者複用的MSE雲原生網關執行個體會被打上資源標籤，您可以在MSE網關管理主控台的基本資料中查看目標網關的標籤資訊。

    重要

    請勿在MSE雲原生網關控制台編輯下表中的標籤，避免對您的網關執行個體造成影響。

    標籤名

    說明

    ack.aliyun.com

    MSE雲原生網關管理的Container Service叢集的入口流量。

    ingress.k8s.alibaba/MseIngressConfig

    MSE雲原生網關與MseIngressConfig關聯。

    kubernetes.reused.by.user

    MSE雲原生網關是否是複用情境。當為複用情境時，刪除與之關聯的MseIngressConfig時，該MSE雲原生網關執行個體不會被刪除。

    建立MSE雲原生網關執行個體

    1. 配置MseIngressConfig。

      通過以下是範例程式碼，建立一個名為mse-ingress，副本數為3，執行個體規格為2c4g的MSE雲原生網關執行個體。您可以按需修改MseIngressConfig的其他配置。

      apiVersion: mse.alibabacloud.com/v1alpha1
kind: MseIngressConfig
metadata:
  name: test
spec:
  name: mse-ingress
  common:
    instance:
      spec: 2c4g
      replicas: 3

    2. 在Container Service叢集中建立IngressClass資源，並關聯MseIngressConfig。

      在Container Service叢集中建立IngressClass資源，並通過spec.parameters關聯以上的MseIngressConfig配置，完成在Container Service叢集中聲明一個Ingress處理器。通過這種方式，叢集中關聯該IngressClass的Ingress資源就會被以上MseIngressConfig關聯的MSE雲原生網關執行個體處理並實施。

      apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: mse
spec:
  controller: mse.alibabacloud.com/ingress
  parameters:
    apiGroup: mse.alibabacloud.com
    kind: MseIngressConfig
    name: test

    複用已有MSE雲原生網關執行個體

    如果您希望複用已有MSE雲原生網關執行個體，在建立MseIngressConfig時通過spec.id指定MSE雲原生網關執行個體唯一ID （格式為gw-xxx)，並通過參數spec.override來控制是否根據MseIngressConfig覆蓋被複用的MSE雲原生網關執行個體的相關配置。

    以下範例程式碼，通過MseIngressConfig複用已有MSE雲原生網關執行個體，設定該網關執行個體關聯容器叢集並監聽該容器叢集中ingressClass為mse的Ingress資源。

    重要

    • 以下配置中spec.override設定為false，表示不覆蓋已有的MSE雲原生網關的Ingress監聽選項和全域配置。如果已有的網關執行個體沒有關聯該容器叢集，將會自動化佈建該網關執行個體關聯容器叢集並設定Ingress監聽選項，監聽該容器叢集中ingressClass為spec.ingress.local.ingressClass值的Ingress資源 （此處設定的mse）；如果已有的網關執行個體已經關聯過該容器叢集，則不會覆蓋原有的Ingress監聽選項。

    • 如果您希望覆蓋掉已有的MSE雲原生網關的Ingress監聽選項和全域配置，請確保MseIngressConfig中網關參數配置 （Ingress監聽選項、硬體加速、全域黑白名單、可觀測）正確之後，再開啟spec.override。當這些配置在MseIngressConfig未指定，開啟spec.override會覆蓋網關原有的參數配置 （Ingress監聽選項、硬體加速、全域黑白名單、可觀測），並可能對您的流量造成影響。

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

    參數

    說明

    spec.id

    複用的目標MSE雲原生網關執行個體ID，格式gw-開頭。

    spec.override

    是否根據MseIngressConfig配置覆蓋被複用的MSE雲原生網關執行個體的相關配置。

    • 設定為true：覆蓋修改網關原有的參數配置 （Ingress監聽選項、硬體加速、全域黑白名單、可觀測）

    • 設定為false，不會覆蓋修改網關原有的參數配置 （Ingress監聽選項、硬體加速、全域黑白名單、可觀測）。但是如果已有的網關執行個體沒有關聯該容器叢集，將會自動化佈建該網關執行個體關聯容器叢集並設定Ingress監聽選項，監聽該容器叢集中ingressClass為spec.ingress.local.ingressClass值的Ingress資源。

    刪除MSE雲原生網關執行個體

    一個MseIngressConfig對應一個MSE雲原生網關執行個體。除複用情境除外，刪除MseIngressConfig配置，會串聯刪除對應的MSE雲原生網關執行個體。

    刪除策略如下表所示。

    網關付費類型

    MSE Ingress Controller自動建立

    複用控制台已購網關

    隨用隨付

    刪除MseIngressConfig，自動刪除網關執行個體。

    刪除MseIngressConfig，保留網關執行個體。

    訂用帳戶

    不涉及。

    刪除MseIngressConfig，保留網關執行個體。

    執行如下命令，刪除MseIngressConfig配置。

    kubectl delete mseingressconfig your-config-name

    配置全域執行個體層級的IP存取控制

    配置IP白名單

    配置全域執行個體層級的IP白名單，可以只允許目標源IP訪問MSE Ingress。

    以下範例程式碼，配置只允許源IP地址為1.1.XX.XX或者網段為2.0.XX.XX訪問MSE Ingress網關執行個體。

    apiVersion: mse.alibabacloud.com/v1alpha1
kind: MseIngressConfig
metadata:
   name: test
spec:
   ...
  global:
    ipAccessControl:
      whitelist:
      - 1.1.XX.XX
      - 2.0.XX.XX/8
   ...

    配置IP黑名單

    配置全域執行個體層級的IP黑名單，可以拒絕目標源IP訪問MSE Ingress。

    以下範例程式碼，配置拒絕源IP地址為1.1.XX.XX或者網段為2.0.XX.XX訪問MSE Ingress網關執行個體。

    apiVersion: mse.alibabacloud.com/v1alpha1
kind: MseIngressConfig
metadata:
   name: test
spec:
   ...
  global:
    ipAccessControl:
      blacklist:
      - 1.1.XX.XX
      - 2.0.XX.XX/8
   ...

    開啟SLS日誌

    開啟SLS日誌之前，請確保已為MSE Ingress Controller授予SLS相關許可權。

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

    apiVersion: mse.alibabacloud.com/v1alpha1
kind: MseIngressConfig
metadata:
   name: test
spec:
   ...
  monitor:
    logging:
      sls:
        # 為空白，表示使用預設
        reuseProject: "demo"
    ...
    說明

    配置reuseProject欄位才能開啟SLSLog Service。如果您希望使用預設Project，可將reuseProject配置為空白。

    開啟OpenTelemetry鏈路追蹤

    為網關配置阿里雲OpenTelemetry鏈路追蹤服務後，可以實現構建端到端的全鏈路追蹤監控體系，方便線上問題快速診斷和定位。

    以下範例程式碼，配置MSE Ingress網關的OpenTelemetry鏈路追蹤，其中採樣率（sampleRate）為100%。

    apiVersion: mse.alibabacloud.com/v1alpha1
kind: MseIngressConfig
metadata:
   name: test
spec:
   ...
  monitor:
    tracing:
      openTelemetry:
        sampleRate: "100"
   ...

    更多配置

    MSE Ingress使用的雲原生網關執行個體支援下列的更多配置。

    如需使用這些配置，請登入MSE網關管理主控台。在雲原生網關 > 網關列表中找到由MSE Ingress Controller使用的已有或自動建立的網關執行個體（執行個體ID為mse_ingresspost-*****格式），單擊執行個體ID，然後單擊左側的參數配置。

    配置項

    類型

    說明

    EnableGenerateRequestId

    Bool

    作用於請求範圍，根據配置會在要求標頭中產生requestId，以便追蹤請求

    EnableGzip

    Bool

    作用於請求與響應環節，啟用gzip會對請求響應進行壓縮，會減少網關流量，增加網關cpu消耗

    EnableSlashMerge

    Bool

    作用於請求環節，是否合并請求中多餘的‘/’, 開啟後www.a.com//b多餘的'/'會被合并，將會同www.a.com/b一致

    DownstreamConnectionBufferLimits

    Int

    取值範圍：[0, 2147483647]

    作用於網關串連，單條連結的buffer大小，配置後會影響吞吐和網關的記憶體使用量

    XffTrustedNum

    Int

    取值範圍：[0, 10](個)

    作用於請求環節，網關前可信任的代理個數，會影響網關是否會使用用戶端產生的x-forwarded-for和x-request-id等要求標頭

    DownstreamHttp2MaxConcurrentStream

    Int

    取值範圍：[0, 2147483647](byte)

    作用於請求環節，用戶端使用http2時一條連結上最大並發數

    InitialStreamWindowSize

    Int

    取值範圍：[65535, 2147483647](byte)

    作用於請求環節，網關同用戶端使用http2時協商的stream初始視窗大小

    InitialConnectionWindowSize

    Int

    取值範圍：[65535, 2147483647](byte)

    作用於請求環節，網關同用戶端使用http2時串連層級初始視窗大小

    EnableHttp3

    Bool

    是否支援http3協議（HTTP3 與硬體加速功能不相容，請先關閉硬體加速功能後再開啟 HTTP3 支援。）

    PathWithEscapedSlashes

    String

    取值範圍：[KEEP_UNCHANGED, REJECT_REQUEST, UNESCAPE_AND_REDIRECT, UNESCAPE_AND_FORWARD]

    確定 URI 路徑中包含 %2F、%2f、%5C 或 %5c 這些轉義的請求的操作, 預設為KEEP_UNCHANGED(保持不變)

    ZipAlgorithm

    List<String>

    取值範圍：[brotli, gzip]

    開啟壓縮後使用的演算法，可以選擇brotli，gzip，如果此時EnableGzip未開啟，將自動開啟EnableGzip選項

    EnableProxyProtocol

    Bool

    是否開啟Proxy協議，如果網關入口流量使用NLB接入，如果不開啟則無法擷取用戶端的真實IP，開啟後對於非Proxy協議請求沒有影響

    EnableCustomAuthConfigPush

    Bool

    作用於使用自建的鑒權服務的情境，開啟後鑒權規則變更不會引起串連中斷，適用於WebSocket和線上業務情境。

    KeepaliveHeaderTimeout

    Int

    取值範圍：[0, 600](s)

    用於產生Keep-Alive回應標頭返回給用戶端，告知串連的保活時間。例如配置為10時，會返迴響應頭: `keep-alive: timeout=10`。配置為0時，不會返回該回應標頭。

    WebsocketTermGracePeriod

    Int

    取值範圍：[20, 900](s)

    當網關執行個體升級、重啟等需要關閉串連的情境下，為 Websocket 串連維持的保活時間。

    EnableGzipHardwareAccelerate

    Bool

    基於專用硬體進行Gzip壓縮。啟用後會對請求響應進行壓縮，大幅降低網關流量，相比軟體Gzip效能更高，CPU消耗更小。不支援的地區，或者購買時未指定開啟Gzip硬體加速將無法開啟。開啟後，EnableGzip和ZipAlgorithm將不會生效。

    EnableK8sSourceWorkloadFilter

    Bool

    添加服務來源時根據指定標籤過濾Ingress、Service、Pod資源。支援取反過濾。