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](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/appliance/resources/gdcloud-auth) 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](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/appliance/resources/gdcloud-auth) 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`.