Venafi

簡介

Venafi Issuer 類型允許您從 Venafi as a Service (VaaS) 和 Venafi Trust Protection Platform (TPP) 執行個體取得憑證。

您可以在同一個叢集中安裝多個不同的 Venafi Issuer 類型，包括 Venafi as a Service 和 TPP 簽發者類型的混合。這可讓您彈性地使用您使用的 Venafi 帳戶類型。

使用 Venafi Issuer 為 Certificates 提供自動化的憑證更新與管理。

單一 Venafi Issuer 代表單一 Venafi「區域」，因此您必須為每個要使用的區域建立一個 Issuer 資源。一個區域是一個單一實體，結合了管理憑證頒發的政策，以及有關憑證如何在 Venafi 中組織的資訊，以識別業務應用程式並建立所有權。

您可以將 Issuer 資源設定為僅在單一命名空間內頒發憑證，或在叢集範圍內頒發憑證（使用 ClusterIssuer 資源）。有關 Issuer 和 ClusterIssuer 資源之間差異的更多資訊，請閱讀命名空間章節。

建立 Venafi as a Service Issuer

如果您尚未執行此操作，請在此頁面上建立您的 Venafi as a Service 帳戶，並從您的使用者偏好設定中複製 API 金鑰。然後，您可能想要建立自訂 CA 帳戶和頒發範本，或者選擇使用自動建立用於測試的預設值（分別為「內建 CA」和「預設」）。最後，您需要建立一個應用程式，以建立由您的 cert-manager Issuer 請求的所有憑證的所有權，並將頒發範本指派給它。

記下應用程式名稱和頒發範本的 API 別名，因為它們共同構成您在 Issuer 設定中需要的「區域」。

為了設定 Venafi as a Service Issuer，您必須先建立一個 Kubernetes Secret 資源，其中包含您的 Venafi as a Service API 憑證。

$ kubectl create secret generic \
       vaas-secret \
       --namespace='NAMESPACE OF YOUR ISSUER RESOURCE' \
       --from-literal=apikey='YOUR_VAAS_API_KEY_HERE'

注意：如果您將發行者設定為 ClusterIssuer 資源，以便在整個叢集中服務 Certificates，您必須將 --namespace 參數設定為 cert-manager，這是預設的 Cluster Resource Namespace。Cluster Resource Namespace 可以透過 cert-manager 控制器元件上的 --cluster-resource-namespace 旗標進行設定。

此 API 金鑰將由 cert-manager 用於代表您與 Venafi as a Service 互動。

一旦建立 API 金鑰 Secret，您就可以建立您的 Issuer 或 ClusterIssuer 資源。如果您要建立 ClusterIssuer 資源，您必須將 kind 欄位變更為 ClusterIssuer，並移除 metadata.namespace 欄位。

在對名為 vaas-issuer.yaml 的檔案進行修改後，儲存以下內容。

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: vaas-issuer
  namespace: <NAMESPACE YOU WANT TO ISSUE CERTIFICATES IN>
spec:
  venafi:
    zone: "My Application\My CIT" # Set this to <Application Name>\<Issuing Template Alias>
    cloud:
      apiTokenSecretRef:
        name: vaas-secret
        key: apikey

然後，您可以使用 kubectl create 建立 Issuer。

$ kubectl create -f vaas-issuer.yaml

使用 kubectl describe 驗證 Issuer 是否已正確初始化。

$ kubectl get issuer vaas-issuer --namespace='NAMESPACE OF YOUR ISSUER RESOURCE' -o wide
NAME           READY   STATUS                 AGE
vaas-issuer    True    Venafi issuer started  2m

您現在可以使用新佈建的 Venafi Issuer 和 Venafi as a Service 來頒發憑證了。

請閱讀請求憑證文件，以獲取有關如何建立憑證資源的更多資訊。

建立 Venafi Trust Protection Platform Issuer

Venafi Trust Protection Platform 整合允許您從正確設定的 Venafi TPP 實例取得憑證。

設定與上述 Venafi as a Service 設定類似，但某些連線參數略有不同。

注意：您必須允許「使用者提供的 CSR」作為您的 TPP 政策的一部分，因為這是目前 cert-manager 唯一支援的類型。

更具體地說，「CSR 處理」的有效配置為

已選取並解鎖「使用者提供的 CSR」，

已選取並鎖定「使用者提供的 CSR」，

已選取並解鎖「服務產生的 CSR」。

當使用「服務產生的 CSR」且已選取並解鎖時，您政策資料夾中的預設 CSR 設定將覆寫您的憑證資源的設定。主體 DN、金鑰演算法和金鑰大小將被政策資料夾中設定的值覆寫。

如果選取並鎖定「服務產生的 CSR」，憑證頒發將會系統性地失敗，並顯示以下訊息
400 PKCS#10 data will not be processed. Policy "\VED\Policy\foo" is locked to a Server Generated CSR.

為了設定 Venafi Trust Protection Platform Issuer，您必須先建立一個 Kubernetes Secret 資源，其中包含您的 Venafi TPP API 憑證。

存取權杖驗證

設定權杖驗證.

注意：不要選取「啟用重新整理權杖」並設定較長的「權杖有效期限（天數）」。cert-manager 的 Venafi Issuer 不支援重新整理權杖功能。
建立一個新使用者，該使用者具有在特定政策資料夾（區域）中管理和撤銷憑證的足夠權限。

例如：k8s-xyz-automation
建立新的應用程式整合

建立一個名稱和 ID 為 cert-manager 的應用程式整合。將「API 存取設定」設定為 憑證：讀取、管理、撤銷。

「編輯存取權」至新的應用程式整合，並允許您先前建立的使用者使用它。

產生存取權杖

vcert getcred \
  --username k8s-xyz-automation \
  --password somepassword \
  -u https://tpp.example.com/vedsdk \
  --client-id cert-manager \
  --scope "certificate:manage,revoke"

這將在 stdout 中列印存取權杖。例如：

vCert: 2020/10/07 16:34:27 Getting credentials
access_token:  I69n.............y1VjNJT3o9U0Wko19g==
access_token_expires:  2021-01-05T15:34:30Z

將存取權杖儲存到 Kubernetes 叢集中的 Secret

$ kubectl create secret generic \
       tpp-secret \
       --namespace=<NAMESPACE OF YOUR ISSUER RESOURCE> \
       --from-literal=access-token='YOUR_TPP_ACCESS_TOKEN'

使用者名稱/密碼驗證

⚠️ 當您提供 Venafi TPP 使用者名稱和密碼時，cert-manager 會使用較舊的驗證方法，稱為「API 金鑰」，該方法自 Venafi TPP 19.2 起已棄用。

從 Venafi TPP 22.2 開始，「API 金鑰」預設為停用。您需要聯絡 Venafi 客戶支援以取得特殊的授權金鑰，這將允許您重新啟用「API 金鑰」功能，以便您可以繼續使用使用者名稱和密碼驗證與 cert-manager。

在 Venafi TPP 22.3 中，「API 金鑰」功能將被永久移除，您需要改用存取權杖驗證。

📖 請閱讀Venafi 平台中已棄用的功能和計畫棄用的功能以取得更多資訊。

$ kubectl create secret generic \
       tpp-secret \
       --namespace=<NAMESPACE OF YOUR ISSUER RESOURCE> \
       --from-literal=username='YOUR_TPP_USERNAME_HERE' \
       --from-literal=password='YOUR_TPP_PASSWORD_HERE'

注意：如果您將您的簽發者設定為 ClusterIssuer 資源，以便在整個叢集中簽發 Certificates，您必須將 --namespace 參數設定為 cert-manager，這是預設的 叢集資源命名空間。叢集資源命名空間 可以透過 cert-manager 控制器元件上的 --cluster-resource-namespace 標誌進行配置。

這些憑證將被 cert-manager 用來與您的 Venafi TPP 實例互動。使用者名稱屬性必須符合 <身分提供者>:<使用者名稱> 格式。例如：local:admin。

一旦包含憑證的 Secret 被建立，您就可以建立您的 Issuer 或 ClusterIssuer 資源。如果您正在建立 ClusterIssuer 資源，您必須將 kind 欄位更改為 ClusterIssuer 並移除 metadata.namespace 欄位。

在您進行修改後，將以下內容儲存到名為 tpp-issuer.yaml 的檔案中。

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: tpp-issuer
  namespace: <NAMESPACE YOU WANT TO ISSUE CERTIFICATES IN>
spec:
  venafi:
    zone: \VED\Policy\devops\cert-manager # Set this to the Venafi policy folder you want to use
    tpp:
      url: https://tpp.venafi.example/vedsdk # Change this to the URL of your TPP instance
      caBundle: <base64 encoded string of caBundle PEM file, or empty to use system root CAs>
      ## Use only caBundle above or the caBundleSecretRef below. Secret can be created from a ca.crt file by running below command
      ## kubectl create secret generic custom-tpp-ca --from-file=/my/certs/ca.crt -n <cert-manager-namespace>
      # caBundleSecretRef:
      #  name: custom-tpp-ca
      #  key: ca.crt
      credentialsRef:
        name: tpp-secret

然後您可以使用 kubectl create -f 建立 Issuer。

$ kubectl create -f tpp-issuer.yaml

使用 kubectl describe 驗證 Issuer 是否已正確初始化。

$ kubectl describe issuer tpp-issuer --namespace='NAMESPACE OF YOUR ISSUER RESOURCE'

您現在可以使用新佈建的 Venafi Issuer 和 Trust Protection Platform 來簽發憑證。

請閱讀請求憑證文件，以獲取有關如何建立憑證資源的更多資訊。

簽發者特定註解

自訂欄位

從 v0.14 開始，您可以使用 Certificate 資源上的 venafi.cert-manager.io/custom-fields 註解將自訂欄位傳遞給 Venafi（TPP 版本 v19.2 及更高版本）。該值是一個 JSON 編碼的自訂欄位物件陣列，其中包含 name 和 value 鍵。例如

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com-certificate
  annotations:
    venafi.cert-manager.io/custom-fields: |-
      [
        {"name": "field-name", "value": "field value"},
        {"name": "field-name-2", "value": "field value 2"}
      ]
...