要求取得憑證

本文說明如何使用憑證授權單位服務 (CAS) 申請憑證。

如要在 Google Distributed Cloud (GDC) 氣隙環境中建立信任關係並確保通訊安全，請向憑證授權單位服務要求啟用或停用 ACME 的憑證。

本文適用於應用程式運算子群組中的對象，例如應用程式開發人員或資料科學家，他們負責管理專案中的憑證生命週期。詳情請參閱「GDC 無網路連線說明文件的適用對象」。

事前準備

您必須先要求必要權限並準備環境，才能要求憑證。

要求 IAM 角色

如要建立、查看及刪除憑證要求，請與機構 IAM 管理員聯絡，在憑證授權單位的專案命名空間中，授予您「CA 服務憑證要求者」(certificate-authority-service-certificate-requester) 角色。

準備環境

使用啟用 ACME 模式的 CA 要求憑證

如果憑證授權單位是以 ACME 模式代管，在準備就緒後，狀態會輸出 ACME 伺服器網址。

從 Distributed Cloud 環境收集 CA ACME 伺服器網址：

kubectl get certificateauthorities CA_NAME -n USER_PROJECT_NAMESPACE -ojson | jq -r '.status.acme.uri'

更改下列內容：

  • CA_NAME：CA 的名稱，可以是根 CA 或子 CA
  • USER_PROJECT_NAMESPACE：使用者專案所在的命名空間名稱

使用 CA 要求憑證 (已停用 ACME 模式)

如要建立停用 ACME 模式的憑證要求，您必須建立 CertificateRequest 資源，並套用至 Distributed Cloud 氣隙式例項。如要這樣做，方法有兩種：

  • 建立 CertificateResource，並在資源中加入 CSR。
  • 使用 GDC 自動產生的私密金鑰建立 CertificateResource，並以自訂值提供憑證設定。

使用 CSR 要求憑證

  1. 建立 CertificateRequest 資源，並儲存為名為 cert-request.yaml 的 YAML 檔案。使用私密金鑰建立憑證簽署要求 (CSR)，並將其新增至資源。

    您也可以在 certificateTemplate 欄位中輸入範本名稱，使用預先設定的 X.509 參數組合核發憑證。

    apiVersion: pki.security.gdc.goog/v1
kind: CertificateRequest
metadata:
  name: CERT_REQ_NAME
  namespace: USER_PROJECT_NAMESPACE
spec:
  certificateAuthorityRef:
    name: CA_NAME
    namespace: USER_PROJECT_NAMESPACE
  csr: CSR
  certificateTemplate: TEMPLATE_NAME
  signedCertificateSecret: SECRET_NAME
  notBefore: VALIDITY_START_TIME
  notAfter: VALIDITY_END_TIME
  subjectOverride: SUBJECT_OVERRIDE

    請替換下列變數：

    變數 說明
    CERT_REQ_NAME CertificateRequest 資源的名稱
    USER_PROJECT_NAMESPACE 使用者專案所在的命名空間名稱
    CA_NAME CA 名稱，可以是根 CA 或子 CA
    CSR 使用 CA 簽署的憑證簽署要求
    SECRET_NAME 儲存私密金鑰和已簽署 CA 憑證的 Kubernetes 密鑰名稱

    替換下列選用變數：

    變數 說明
    TEMPLATE_NAME 要使用的預先定義憑證範本名稱。如需可用範本清單和衝突相關詳細資料，請參閱「預先定義的憑證範本」。
    VALIDITY_START_TIME 憑證的有效起始時間。這個值必須採用 YYYY-MM-DDTHH:MM:SSZ 格式 (例如 2025-10-19T21:45:30Z)。如果未設定，憑證會在核發後立即生效。
    VALIDITY_END_TIME 憑證到期時間。這個值必須採用 YYYY-MM-DDTHH:MM:SSZ 格式 (例如 2026-01-17T18:25:40Z)。如果未設定，憑證會在開始時間的 90 天後到期。
    SUBJECT_OVERRIDE 要在核發的憑證中使用的自訂主體，會覆寫 CSR 中的主體資訊。請以原始的 ASN.1 DER 編碼 X.509 主體形式提供這個值。

  2. 將自訂資源套用至 Distributed Cloud 執行個體：

    kubectl apply -f cert-request.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG

    將 MANAGEMENT_API_SERVER_KUBECONFIG 替換為 Management API 伺服器的 kubeconfig 檔案路徑。

  3. 確認憑證要求是否準備就緒：

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r ' .status.conditions[] | select( .type as $id | "Ready" | index($id))'

    更改下列內容：

    • MANAGEMENT_API_SERVER_KUBECONFIG：Management API 伺服器的 kubeconfig 檔案路徑
    • USER_PROJECT_NAMESPACE：使用者專案所在的命名空間名稱
    • CERT_REQ_NAME 資源的名稱CertificateRequest

    輸出結果會與下列內容相似：

    {
  "lastTransitionTime": "2025-01-27T12:22:59Z",
  "message": "Certificate is issued",
  "observedGeneration": 1,
  "reason": "Issued",
  "status": "True",
  "type": "Ready"
}

  4. 取得憑證密鑰名稱：

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r '.spec.signedCertificateSecret'

    更改下列內容：

    • MANAGEMENT_API_SERVER_KUBECONFIG：Management API 伺服器的 kubeconfig 檔案路徑
    • USER_PROJECT_NAMESPACE：使用者專案所在的命名空間名稱
    • CERT_REQ_NAME 資源的名稱CertificateRequest

    輸出結果會顯示包含已簽署憑證的 SECRET_NAME：

    test-jwk-1

使用自動產生的金鑰要求憑證

  1. 建立 CertificateRequest 資源，並儲存為名為 cert-request.yaml 的 YAML 檔案。填入所選憑證的值。

    您也可以在 certificateTemplate 欄位中輸入範本名稱，使用預先設定的 X.509 參數組合核發憑證。

    apiVersion: pki.security.gdc.goog/v1
kind: CertificateRequest
metadata:
  name: CERT_REQ_NAME
  namespace: USER_PROJECT_NAMESPACE
spec:
  certificateAuthorityRef:
    name: CA_NAME
    namespace: USER_PROJECT_NAMESPACE
  certificateConfig:
    subjectConfig:
      commonName: COMMON_NAME
      organization: ORGANIZATION
      locality: LOCALITY
      state: STATE
      country: COUNTRY
      dnsNames:
      - DNS_NAMES
      ipAddresses:
      - IP_ADDRESSES
      rfc822Names:
      - RFC822NAMES
      uris:
      - URIS
  certificateTemplate: TEMPLATE_NAME
  signedCertificateSecret: SECRET_NAME
  notBefore: VALIDITY_START_TIME
  notAfter: VALIDITY_END_TIME
  subjectOverride: SUBJECT_OVERRIDE

    請替換下列變數：

    變數 說明
    CERT_REQ_NAME CertificateRequest 資源的名稱
    USER_PROJECT_NAMESPACE 使用者專案所在的命名空間名稱
    CA_NAME CA 名稱，可以是根 CA 或子 CA
    SECRET_NAME 儲存私密金鑰和已簽署 CA 憑證的 Kubernetes 密鑰名稱

    請替換下列選用變數。您必須在 CertificateRequest 資源的 spec.certificateConfig.subjectConfig 區塊中，至少加入一個欄位：

    變數 說明
    COMMON_NAME 憑證的通用名稱
    ORGANIZATION 要顯示在憑證上的機構
    LOCALITY 憑證的所在地
    STATE 憑證上要使用的州或省
    COUNTRY 認證國家/地區
    DNS_NAMES 要為憑證設定的 dNSName subjectAltNames 清單
    IP_ADDRESS 要為憑證設定的 ipAddress subjectAltNames 清單
    RFC822_NAMES 要為憑證設定的 rfc822Name subjectAltNames 清單
    URIS 要設定在憑證上的 uniformResourceIdentifier subjectAltNames 清單
    TEMPLATE_NAME 要使用的預先定義憑證範本名稱。如需可用範本清單和衝突相關詳細資料，請參閱「預先定義的憑證範本」。
    VALIDITY_START_TIME 憑證的有效起始時間。這個值必須採用 YYYY-MM-DDTHH:MM:SSZ 格式 (例如 2025-10-19T21:45:30Z)。如果未設定，憑證會在核發後立即生效。
    VALIDITY_END_TIME 憑證到期時間。這個值必須採用 YYYY-MM-DDTHH:MM:SSZ 格式 (例如 2026-01-17T18:25:40Z)。如果未設定，憑證會在開始時間的 90 天後到期。
    SUBJECT_OVERRIDE 要在核發的憑證中使用的自訂主體，會覆寫 CSR 中的主體資訊。請以原始的 ASN.1 DER 編碼 X.509 主體形式提供這個值。

  2. 將自訂資源套用至 Distributed Cloud 執行個體：

    kubectl apply -f cert-request.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG

    將 MANAGEMENT_API_SERVER_KUBECONFIG 替換為 Management API 伺服器的 kubeconfig 檔案路徑。

  3. 確認憑證要求是否準備就緒：

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r ' .status.conditions[] | select( .type as $id | "Ready" | index($id))'

    更改下列內容：

    • MANAGEMENT_API_SERVER_KUBECONFIG：Management API 伺服器的 kubeconfig 檔案路徑
    • USER_PROJECT_NAMESPACE：使用者專案所在的命名空間名稱
    • CERT_REQ_NAME 資源的名稱CertificateRequest

    輸出結果會與下列內容相似：

    {
  "lastTransitionTime": "2025-01-27T12:22:59Z",
  "message": "Certificate is issued",
  "observedGeneration": 1,
  "reason": "Issued",
  "status": "True",
  "type": "Ready"
}

  4. 取得憑證密鑰名稱：

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r '.spec.signedCertificateSecret'

    更改下列內容：

    • MANAGEMENT_API_SERVER_KUBECONFIG：Management API 伺服器的 kubeconfig 檔案路徑
    • USER_PROJECT_NAMESPACE：使用者專案所在的命名空間名稱
    • CERT_REQ_NAME：資源的名稱CertificateRequest

    輸出結果會顯示包含已簽署憑證的 SECRET_NAME：

    test-jwk-1

列出憑證要求

使用 certificaterequests 參數列出所有 CertificateRequest 資源：

kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog

更改下列內容：

  • MANAGEMENT_API_SERVER_KUBECONFIG：Management API 伺服器的 kubeconfig 檔案路徑
  • USER_PROJECT_NAMESPACE：使用者專案所在的命名空間名稱

以下範例指令使用 agtest-project 命名空間：

kubectl --kubeconfig /root/release/root-admin/root-admin-kubeconfig  -n agtest-project get certificaterequest.pki.security.gdc.goog

預期輸出內容如下：

NAME                                               READY   AGE
test-externalca-subca-cert-req-with-csr            True    17h
test-externalca-subca-cert-req-with-csr-override   True    17h

刪除憑證

如要刪除憑證，請刪除對應的CertificateRequest自訂資源。這項動作會從 CAS 資料庫中移除資源。

  1. 找出要刪除的 CertificateRequest 名稱。您可以列出憑證要求，協助找出名稱。

  2. 刪除 CertificateRequest 資源：

    kubectl --kubeconfig  MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE delete certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME

    更改下列內容：

    • MANAGEMENT_API_SERVER_KUBECONFIG：Management API 伺服器的 kubeconfig 檔案路徑
    • USER_PROJECT_NAMESPACE：使用者專案所在的命名空間名稱
    • CERT_REQ_NAME：資源的名稱CertificateRequest

憑證要求限制和清理

為維持系統穩定性並避免資源使用率過高，CAS 會強制限制CertificateRequest自訂資源的數量，並提供選用的自動清除功能。

憑證要求配額

CAS 會對每個機構的CertificateRequest自訂資源數量強制執行配額，預設上限為 5,000 個。超過此限制可能會導致 CAS 和 Management API 伺服器效能降低。

當 CertificateRequest 資源總數接近配額時 (例如達到上限的 80% 和 90%)，建立新要求時，指令輸出內容會顯示警告。如果嘗試在達到配額後建立 CertificateRequest，系統會拒絕要求。您可能會看到類似下列內容的錯誤訊息：

Error from server (Forbidden): error when creating "cert-request.yaml":
admission webhook "certificaterequests.pki.security.gdc.goog" denied the
request: the number of certificate requests has exceeded the per organization
limit of {LIMIT}. Please refer to the guide PLATAUTH-G2102 for troubleshooting
this issue

如果遇到這個錯誤，您可能需要刪除舊的或不必要的 CertificateRequest 資源。如要調整配額，請與貴機構的基礎架構營運商群組成員聯絡。他們可以按照 runbook PLATAUTH-G2102 中的操作說明，覆寫配額。

自動清除

您可以啟用自動清除功能，刪除過期的CertificateRequest資源。這項功能會在可設定的寬限期過後移除資源，藉此釋出資源。寬限期是指憑證到期後，到 CertificateRequest 資源遭到刪除之間的時間長度。

自動清除功能預設為停用。貴機構基礎架構運算子群組的成員可以啟用這項功能，並按照 Runbook PLATAUTH-G2103 中的操作說明設定寬限期。如果未設定寬限期或寬限期為零，這項功能會維持停用狀態。