Upgrade package validation certificate

This document describes how to upgrade the root certificate authority (CA) used for package validation in Google Distributed Cloud (GDC) air-gapped appliance

GDC package validation uses a root certificate authority (CA) to validate release key certificates. You must upgrade this root CA if a release notice requires it, or if you see a warning message during a system upgrade.

Before you begin

To upgrade the package validation certificate, you must have the necessary identity and access roles:

• Ensure that you have write access to harbor-system/package-validation-root-certs ConfigMap.
• Ask your Security Admin to grant you the Upgrade Debugger (upgrade-debugger-cp) role.

Verify certificate upgrade is required

Verify a package validation certificate upgrade is required before performing the operation, by comparing the active ConfigMap in your cluster against the latest staging root certificate in the upgrade bundle:

1. Set the KUBECONFIG environment variable:

   $ KUBECONFIG=PATH_TO_KUBECONFIG_FILE
   

   Replace PATH_TO_KUBECONFIG_FILE with the path to the kubeconfig file that you obtained by running gdcloud auth login in the root admin cluster.

2. Determine if an upgrade is required by comparing the current trust anchor to the latest trust anchor. The ConfigMap data at harbor-system/package-validation-root-certs is compared against the local trust anchor:

   $ CURRENT_TRUST_ANCHOR=$(kubectl  --kubeconfig=$KUBECONFIG get cm package-validation-root-certs -n harbor-system -o jsonpath='{.data.ca\.crt}')
   
   $ LATEST_TRUST_ANCHOR=$(cat /root/release/staging_root_ca_certificate.crt)
   
   $ diff <( echo "$CURRENT_TRUST_ANCHOR" ) <( echo "$LATEST_TRUST_ANCHOR" ) && echo trust anchors are same  || echo trust anchors are different, upgrade required!
   

Upgrade the certificate

If an upgrade is required, update the ConfigMap object located at harbor-system/package-validation-root-certs in the root admin cluster. You must have write access to the ConfigMap to complete this task.

1. Set the KUBECONFIG environment variable:

   $ KUBECONFIG=PATH_TO_KUBECONFIG_FILE
   

   Replace PATH_TO_KUBECONFIG_FILE with the path to the kubeconfig file that you obtained by running gdcloud auth login in the root admin cluster.

2. Create and assign values to the following variables:

   USERNAME=USER_NAME #IO
   TARGET_FOLDER=/tmp/${USERNAME}
   OUTPUT="${TARGET_FOLDER}/package-validation-root-certs.yaml"
   LATEST_TRUST_ANCHOR_CA_FILE=/root/release/staging_root_ca_certificate.crt
   CONFIGMAP_NAME=package-validation-root-certs
   NAMESPACE=harbor-system
   

   Replace USER_NAME with the IO username.

3. Create the target folder that will contain the output files from the certificate upgrade process:

   mkdir -p "${TARGET_FOLDER}"
   

4. Get the current trust anchor and store it in local temporary file:

   CURRENT_TRUST_ANCHOR=$(kubectl  --kubeconfig=$KUBECONFIG get configmap "${CONFIGMAP_NAME}" -n "${NAMESPACE}" -o jsonpath="{.data.ca\.crt}" )
   CURRENT_TRUST_ANCHOR_CA_FILE=$(mktemp)
   echo "$CURRENT_TRUST_ANCHOR" > "${CURRENT_TRUST_ANCHOR_CA_FILE}"
   

5. Generate the updated trust anchor file:

   cat <<EOF  > "${OUTPUT}"
   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: ${CONFIGMAP_NAME}
     namespace: ${NAMESPACE}
   data:
     ca.crt: |
   $(sed 's/^/    /' "${LATEST_TRUST_ANCHOR_CA_FILE}")
   $(sed 's/^/    /' "${CURRENT_TRUST_ANCHOR_CA_FILE}")
   EOF
   

6. Verify the trust anchor was updated correctly:

   The trust anchor must contain both current and latest trust anchor certificate.

   $ cat "${OUTPUT}"
   apiVersion: v1
   data:
     ca.crt: |
       -----BEGIN CERTIFICATE-----
       (certificate content)
       -----END CERTIFICATE-----
       -----BEGIN CERTIFICATE-----
       (certificate content)
       -----END CERTIFICATE-----
       (other certificate)
   kind: ConfigMap
   metadata:
     name: package-validation-root-certs
     namespace: harbor-system
   

7. Apply the new configuration with kubectl:

     kubectl --kubeconfig=$KUBECONFIG apply -f ${OUTPUT}
   

8. Ensure that the newly applied ca.crt is present within the ConfigMap:

     kubectl --kubeconfig=$KUBECONFIG describe configmap package-validation-root-certs -n harbor-system
   

This takes care of upgrading a new certificate in the package-validation-root-cert.