Manually reissue PKI web certificates

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

This document is for audiences within the platform administrator group who want to manage PKI web certificates. For more information, see Audiences for GDC air-gapped documentation.

Before you begin

Before manually reissuing web certificates, you must have the necessary permissions and prepare your environment.

Request IAM roles

To create, update, and delete PKI web certificates in a namespace, contact your Organization IAM Admin to request the Web TLS Certificate Admin (web-tls-cert-admin) role.

Consider the following account requirements:

  • A member of your infrastructure operator group must reissue PKI web certificates in the system namespace.
  • Members of the platform administrator group can reissue PKI web certificates in all other namespaces that they manage.

Prepare your environment

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: