Manually reissue PKI web certificates

This page provides instructions to manually trigger certificate reissuance for your Google Distributed Cloud (GDC) air-gapped web endpoints.

Before you begin

To get the permissions you need to access certificates in a namespace, ask your Organization IAM Admin to grant you the Web TLS Certificate Admin (web-tls-cert-admin) role.

Consider the following account requirements when performing certificate reissuance:

• Use an Infrastructure Operator (IO) account to access the certificate in the system namespace. Ask your IO to perform this task.

• Use a Platform Administrator account to access certificates in other namespaces.

Reissue a certificate

You can manually reissue a certificate with an annotation update. If the default certificate issuer changes, Distributed Cloud won't automatically reissue certificates signed by the previous default certificate issuer unless the certificate is about to expire.

To manually trigger the reissuance of a certificate, use the kubectl CLI to perform the following steps:

1. Set the manual-reissuance annotation to requested for target Certificate. The following example updates the default-wildcard-cert certificate in the istio-system namespace which uses the current default certificate issuer:

   kubectl annotate --overwrite certificate.pki.security.gdc.goog
   default-wildcard-cert -n istio-system
   pki.security.gdc.goog/manual-reissuance='requested'
   

2. You might see an in-progress annotation value as a transitioning state while the certificate is being reissued. Wait for the manual-reissuance annotation value to show finished:

   kubectl -n istio-system get
   certificate.pki.security.gdc.goog/default-wildcard-cert -ojson | jq -r '
   .metadata.annotations."pki.security.gdc.goog/manual-reissuance"'
   

   The output looks similar to the following:

   finished
   

3. Verify the certificate issuer; it must either match the issuer mentioned in the certificate specification or, if not specified, the issuer must match the current default issuer:

   kubectl -n istio-system get certificate.pki.security.gdc.goog/default-wildcard-cert -ojson | jq -r '
   .status.issuedBy'
   

   The output looks similar to the following:

   {
     "name": "byo-cert-issuer",
     "namespace": "pki-system"
   }
   

Bring-your-own certificate manual rotation

When you trigger and complete a manual bring-your-own certificate (BYO cert) rotation, you must sign the newly generated Certificate Signing Request (CSR) for a previously signed BYO cert. For more information, see Sign the BYO certificate.

During rotation, Distributed Cloud creates a new private and public key pair. This makes the signed certificate uploaded earlier incompatible with the new CSR. If the certificate specification hasn't changed since the initial upload, the previously uploaded certificate remains in use until it expires. If the specification changes, one of the following events occur:

• Distributed Cloud uses an existing matching certificate.
• A fallback Certificate Authority (CA) issues a new certificate.

BYO cert manual rotation example

In the following example, you see a previously signed BYO cert triggered for manual rotation:

• The byoCertStatus shows the certificate type value is Ready,

• The reason value is Issued with an earlier lastTransitionTime value than the previous value:

  {
   "byoCertStatus": {
     "csrStatus": {
       "conditions": [
         {
           "lastTransitionTime": "2024-05-03T22:38:43Z",
           "message": "",
           "observedGeneration": 2,
           "reason": "WaitingForSigning",
           "status": "False",
           "type": "Ready"
         }
       ],
       "csr": "LS0tLS1CRUdJTiBDRVJ..."
     },
     "signedCertStatus": {
       "conditions": [
         {
           "lastTransitionTime": "2024-05-03T22:38:43Z",
           "message": "RawSubjectPublickKeyInfo does not match with the CSR",
           "observedGeneration": 2,
           "reason": "Rejected",
           "status": "False",
           "type": "Ready"
         }
       ]
     }
   },
   ```
  

In the following example, you see output for a previously signed BYO cert triggered for manual rotation:

• In the signedCertStatus, the reason field shows Rejected because the previously signed certificate no longer matches the new CSR after rotation.

• The CSR reason states WaitingForSigning:

  "conditions": [
    {
      "lastTransitionTime": "2024-05-03T08:42:10Z",
      "message": "Certificate is issued",
      "observedGeneration": 2,
      "reason": "Issued",
      "status": "True",
      "type": "Ready"
    }
  ],
  "errorStatus": {
    "errors": [
      {
        "code": "PLATAUTH2002",
        "message": "Waiting for CSR signing"
      }
    ],
    "lastUpdateTime": "2024-05-03T22:38:43Z"
  },
  "issuedBy": {
    "name": "byo-cert-issuer",
    "namespace": "pki-system"
  }
  }
  

  Manage certificate signing alerts

Certificate signing alerts for initial issuance, rotation, and expiration must be addressed by your IO using the troubleshooting steps documented in these sections of the PKI runbook:

• For subCA errorCode: PLATAUTH2001, see PLATAUTH-R2001.

• For BYO cert errorCode: PLATAUTH2002, see PLATAUTH-R2002.