最新消息：在Twitter和Mastodon上取得專案更新

已註解的 Ingress 資源

apiVersion: networking.k8s.io/v1
kind: Ingress

cert-manager 的常見用例是請求 TLS 簽署的憑證，以保護您的 Ingress 資源。這可以透過簡單地將註解新增到您的 Ingress 資源中來完成，而 cert-manager 將協助您建立 Certificate 資源。cert-manager 的一個小型子元件 ingress-shim 負責此操作。

運作方式

子元件 ingress-shim 會監視叢集中的 Ingress 資源。如果它觀察到一個具有支援的註解部分中描述的註解的 Ingress，它將確保在 tls.secretName 欄位中提供的名稱，以及 Ingress 中描述的設定的 Certificate 資源存在於 Ingress 的命名空間中。例如：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    # add an annotation indicating the issuer to use.
    cert-manager.io/cluster-issuer: nameOfClusterIssuer
  name: myIngress
  namespace: myIngress
spec:
  rules:
  - host: example.com
    http:
      paths:
      - pathType: Prefix
        path: /
        backend:
          service:
            name: myservice
            port:
              number: 80
  tls: # < placing a host in the TLS config will determine what ends up in the cert's subjectAltNames
  - hosts:
    - example.com
    secretName: myingress-cert # < cert-manager will store the created certificate in this secret.

支援的註解

您可以在 Ingress 資源上指定以下註解，以便觸發自動建立 Certificate 資源

  • cert-manager.io/issuer：應為此 Ingress 所需憑證簽發憑證的簽發者名稱。

    ⚠️ 此註解*不*假設命名空間範圍的簽發者。它預設為 cert-manager.io Issuer，但是對於外部簽發者類型，這應同時用於命名空間和叢集範圍的簽發者類型。

    ⚠️ 如果使用命名空間範圍的簽發者，則簽發者*必須*與 Ingress 資源位於相同的命名空間中。

  • cert-manager.io/cluster-issuer：cert-manager.io ClusterIssuer 的名稱，以取得此 Ingress 所需的憑證。您的 Ingress 位於哪個命名空間並不重要，因為 ClusterIssuer 是非命名空間資源。

    ⚠️ 此註解是引用 cert-manager.io ClusterIssuer 的快捷方式，無需指定群組和種類。它*不*打算用於指定外部叢集範圍的簽發者 - 請為這些使用 cert-manager.io/issuer 註解。

  • cert-manager.io/issuer-kind：外部簽發者資源的種類，例如 AWSPCAIssuer。這僅對於樹狀結構外的簽發者是必要的。

  • cert-manager.io/issuer-group：外部簽發者控制器的 API 群組，例如 awspca.cert-manager.io。這僅對於樹狀結構外的簽發者是必要的。

  • kubernetes.io/tls-acme: "true"：此註解需要對 ingress-shim 進行額外設定 請參閱下方。也就是說，必須將預設的簽發者指定為 ingress-shim 容器的引數。

  • acme.cert-manager.io/http01-ingress-class：此註解可讓您設定將用於解決此 Ingress 挑戰的 Ingress 類別。當您嘗試保護內部服務，並且需要使用與 Ingress 不同的 Ingress 類別來解決挑戰時，自訂此設定很有用。如果未指定且未設定 acme-http01-edit-in-place 註解，則預設為 Issuer 資源中定義的 Ingress 類別。

  • acme.cert-manager.io/http01-edit-in-place: "true"：這控制是「就地」修改 Ingress，還是專門為 HTTP01 挑戰建立一個新的 Ingress。如果存在且設定為 "true"，則會修改現有的 Ingress。任何其他值或缺少註解則假設為 "false"。此註解還會將註解 "cert-manager.io/issue-temporary-certificate": "true" 新增到建立的憑證上，這將導致在返回最終簽署的憑證之前，在產生的 Secret 上設定臨時憑證。這對於保持與 ingress-gce 元件的相容性非常有用。

  • cert-manager.io/common-name：（選用）此註解可讓您設定要產生的憑證的 spec.commonName。

  • cert-manager.io/email-sans：（選用）此註解可讓您設定要產生的憑證的 spec.emailAddresses 欄位。支援逗號分隔值，例如「me@example.com,you@example.com」

  • cert-manager.io/subject-organizations：（選用）此註解可讓您設定要產生的憑證的 spec.subject.organizations 欄位。支援逗號分隔值，例如「公司 1,公司 2」

  • cert-manager.io/subject-organizationalunits：（選用）此註解可讓您設定要產生的憑證的 spec.subject.organizationalUnits 欄位。支援逗號分隔值，例如「IT 服務,雲端服務」

  • cert-manager.io/subject-countries：（選用）此註解可讓您設定要產生的憑證的 spec.subject.countries 欄位。支援逗號分隔值，例如「國家 1,國家 2」

  • cert-manager.io/subject-provinces：（選用）此註解可讓您設定要產生的憑證的 spec.subject.provinces 欄位。支援逗號分隔值，例如「省份 1,省份 2」

  • cert-manager.io/subject-localities：（選用）此註解可讓您設定要產生的憑證的 spec.subject.localities 欄位。支援逗號分隔值，例如「城市 1,城市 2」

  • cert-manager.io/subject-postalcodes：（選用）此註解可讓您設定要產生的憑證的 spec.subject.postalCodes 欄位。支援逗號分隔值，例如「123ABC,456DEF」

  • cert-manager.io/subject-streetaddresses：（選用）此註解可讓您設定要產生的憑證的 spec.subject.streetAddresses 欄位。支援逗號分隔值，例如「範例街 123 號,其他大道 456 號」

  • cert-manager.io/subject-serialnumber：（選用）此註解可讓您設定要產生的憑證的 spec.subject.serialNumber 欄位。支援逗號分隔值，例如「10978342379280287615,1111144445555522228888」

  • cert-manager.io/duration：（選用）此註解可讓您設定要產生的憑證的 spec.duration 欄位。

  • cert-manager.io/renew-before：（選用）此註解可讓您設定要產生的憑證的 spec.renewBefore 欄位。

  • cert-manager.io/usages：（選用）此註解可讓您設定要產生的憑證的 spec.usages 欄位。傳遞具有逗號分隔值的字串，例如「金鑰協商、數位簽章、伺服器驗證」

  • cert-manager.io/revision-history-limit：（選用）此註解可讓您設定 spec.revisionHistoryLimit 欄位，以限制要為憑證保留的 CertificateRequest 數量。最小值為 1。如果未設定，則將保留所有 CertificateRequest。

  • cert-manager.io/private-key-algorithm：（選用）此註解可讓您設定 spec.privateKey.algorithm 欄位，以設定憑證私密金鑰產生的演算法。有效值為 RSA、ECDSA 和 Ed25519。如果未設定，則將使用演算法 RSA。

  • cert-manager.io/private-key-encoding：（選用）此註解可讓您設定 spec.privateKey.encoding 欄位，以設定憑證私密金鑰產生的編碼。有效值為 PKCS1 和 PKCS8。如果未設定，則將使用演算法 PKCS1。

  • cert-manager.io/private-key-size：(選用) 此註釋允許您設定 spec.privateKey.size 欄位，以設定憑證私鑰的大小。如果演算法設定為 RSA，則有效值為 2048、4096 或 8192，如果未指定，則預設為 2048。如果演算法設定為 ECDSA，則有效值為 256、384 或 521，如果未指定，則預設為 256。如果演算法設定為 Ed25519，則會忽略大小。

  • cert-manager.io/private-key-rotation-policy：(選用) 此註釋允許您設定 spec.privateKey.rotationPolicy 欄位，以設定憑證私鑰的輪換策略。有效值為 Never 和 Always。如果未設定，將使用 Never 的輪換策略。

使用多個 Ingress 產生多個憑證

如果您需要從多個 Ingress 產生憑證，請確保它具有簽發者註釋。除了註釋之外，每個 Ingress 都必須具有唯一的 tls.secretName。

選用設定

ingress-shim 子元件會作為安裝的一部分自動部署。

如果您想使用舊的 kube-lego kubernetes.io/tls-acme: "true" 註釋來實現完全自動化的 TLS，則在部署 cert-manager 時，您需要設定一個預設的 Issuer。這可以透過在使用 Helm 部署時新增以下 --set 來完成

--set ingressShim.defaultIssuerName=letsencrypt-prod \
   --set ingressShim.defaultIssuerKind=ClusterIssuer \
   --set ingressShim.defaultIssuerGroup=cert-manager.io

或者透過將以下引數新增至 cert-manager 部署 podTemplate 容器引數中。

- --default-issuer-name=letsencrypt-prod
  - --default-issuer-kind=ClusterIssuer
  - --default-issuer-group=cert-manager.io

在上述範例中，對於所有具有 kubernetes.io/tls-acme: "true" 註釋的 Ingress，cert-manager 將建立參考 ClusterIssuer letsencrypt-prod 的 Certificate 資源。

透過註釋設定的簽發者優先於預設簽發者。如果透過 CLI 標誌設定預設簽發者，並且 Ingress 也新增了 cert-manager.io/cluster-issuer 或 cert-manager.io/issuer 註釋，則建立的 Certificate 將參考透過註釋設定的簽發者。

有關部署 cert-manager 的詳細資訊，請閱讀安裝指南。

疑難排解

如果在套用 ingress-shim 註釋後未看到建立 Certificate 資源，請檢查是否至少設定了 cert-manager.io/issuer 或 cert-manager.io/cluster-issuer。如果您想使用 kubernetes.io/tls-acme: "true"，請務必檢查上述所有步驟，如果問題未解決，您可能需要在 cert-manager pod 日誌中尋找錯誤。

開發人員的內部運作圖

[1] https://cert-manager.dev.org.tw/docs/usage/certificate