MigrationPreview

Introduction

Instructions for migrating TLS Protect for Kubernetes software installation to be managed by the operator [1].

To set up a TLS Protect for Kubernetes installation using the operator, existing cert-manager and other TLS Protect for Kubernetes component installations, including custom resource definitions, need to be uninstalled. This is so that the operator can own these resources and manage/upgrade them over time. Uninstalling custom resource definitions means that custom resources, such as Certificates will be uninstalled. Users will then need to reconfigure the installation of TLS Protect for Kubernetes components and issuers via the Operator API and re-apply Certificate resources.

Read about the operator to understand the installation flow and which components and resources will need to be migrated to be managed by the operator.

Migration steps

The following steps use jsctl CLI. You can install the CLI for your architecture from GitHub releases.

1. Check current cluster status

Discover what TLS Protect for Kubernetes components and resources are currently installed in the cluster.

jsctl clusters status

This command will display what is currently installed in the cluster:

• TLS Protect for Kubernetes components, such as cert-manager or approver-policy
• TLS Protect for Kubernetes component-related CustomResourceDefinitions such as certificates.cert-manager.io
• cert-manager.io or external issuers
• ingress-shim Ingresses
• CertificateRequestPolicy resources

Read About the operator to verify that the operator can manage all discovered TLS Protect for Kubernetes components. If the component versions in cluster are older than those supported by the latest operator, you might want to read through component release notes to ensure that the component versions that the operator supports will work for your installation.

Ensure that you understand how the discovered components and resources have been installed and that you will be able to uninstall them.

The status command currently does not show Certificate custom resources. You want to ensure that you understand how those are deployed and what is the best way to re-apply them after the software components have been re-installed by the operator. The following steps include a command that takes a backup including Certificates that you can use to re-apply those if you don't have them version controlled.

If you are currently using CertificateRequestPolicy resources you might need to manually reconfigure policies for each issuer via Installation spec once the components have been re-installed using the operator. Take a look at Policy to understand operator's policy model.

2. Verify that uninstallation can be performed safely

Verify that TLS Protect for Kubernetes components and resources can be safely uninstalled and reinstalled without causing downtime.

jsctl experimental clusters uninstall verify

This command will display any potential issues related to uninstalling:

• Whether any Certificate Secrets with issued TLS certificates have Certificate owner references that would cause them to be garbage collected when Certificates are uninstalled. If the issued certificates are being used, you probably want to remove the owner references by ensuring that --enable-certificate-owner-ref flag is set to false as well as running jsctl experimental clusters cleanup secrets remove-certificate-owner-refs

• Whether any issued certificates are about to expire soon. You will want to ensure that you allocate enough time to complete the migration before that. You can use cmctl renew command to renew certificates now.

• Whether any Certificate resources are failing issuance or not in Ready state. You might want to debug the causes for any failure before making additional changes to cluster installation.

• Whether any Certificate resources are to be renewed soon. You might want to postpone uninstalling cert-manager until after these certificates have been renewed. Or you might use cmctl renew to renew these certificates before you uninstall cert-manager.

• Whether there is cert-manager csi-driver, cert-manager csi-driver-spiffe and/or istio-csr installed in the cluster. You will need to uninstall these components to move them to operator managed installation. Make sure that you understand how those components are used to ensure that uninstalling them won't cause downtime in the cluster, when, for example, new Pods are created in Istio mesh and need certificates or new Pods with csi-driver/csi-driver-spiffe certificate volumes are being created.

3. Backup TLS Protect for Kubernetes issuers and policies

jsctl x clusters backup --format=json > backup.json

This command will back up some of the TLS Protect for Kubernetes custom resources:

• cert-manager.io and external issuers. The backup file can then be used to generate Installation spec for operator with the same issuers

• CertificateRequestPolicy resources. These cannot be directly translated to operator managed policies (take a look at Policy). They are included in backup in case there is a need to rollback migration and re-apply non-operator managed policies.

• Certificate resources. Certificates are not managed by the operator and need to be re-applied after the components are re-installed and issuers re-applied via Installation resource

Certificate resources created via ingress-shim are not included in the backup as they will get automatically re-created by cert-manager.

CertificateRequests, Orders and Challenges are not included in backup as there should be no reason to backup and restore those (but you might want to make sure that you are not re-installing mid-issuance - see jsctl experimental clusters uninstall verify command).

TLS Protect for Kubernetes software components, such as cert-manager, are not included in the backup.

4. Generate Installation manifest for operator with issuers from the backup file

jsctl operator installations apply \
  --stdout \
 # --auto-registry-credentials \
  --experimental-issuers-backup-file backup.json > installation.yaml

Uncomment --auto-registry-credentials flag to add an image pull secret to allow pulling images from Jetstack Secure Enterprise GCR.

The Installation will contain the components that the operator installs by default (cert-manager and approver-policy) and issuers from the backup file. Edit the Installation spec to make any required changes and add additional components, configure policies for issuers etc.

5. Uninstall TLS Protect for Kubernetes components and resources

Uninstall the TLS Protect for Kubernetes components including custom resource definitions. The uninstall steps will depend on how the software was installed.

See cert-manager uninstall docs to understand the uninstall process for cert-manager.

Ensure that you have updated any GitOps pipelines etc that might be attempting to reapply components or issuers.

6. Authenticate against TLS Protect for Kubernetes platform

jsctl auth login
jsctl config set organization <organization>

7. [Optional- if not already installed] Install TLS Protect for Kubernetes agent

jsctl clusters connect <cluster-name>

8. Install the operator

Follow Installing js-operator

9. Apply the created Installation manifest

kubectl apply -f installation.yaml

Wait for it to become Ready, observe its status to see what components and issuers got installed.

10. Re-apply Certificate resources.

If needed you can use the backup file:

cat backup.json | jq -r '.items[] | select(.kind=="Certificate")' | kubectl apply -f -

11. Wait for Certificate resources to become Ready

Constraints

• CertificateRequestPolicy resources existing in cluster will need to be manually translated to operator policy model

• The documented flow does not include migrating TLS Protect for Kubernetes components and their configuration to Installation. (However the base components such as cert-manager are included in the default Installation generated by jsctl).

• Currently there is only a limited set of configuration options for components when deployed via operator

• Currently only core cert-manager.io and jetstack.io issuers can be configured via the operator API. If you create other issuer types, you will need to ensure that you also create CertificateRequestPolicy resources and associated RBAC as the operator disables cert-manager's default policy approver and deploys approver-policy or approver-policy-enterprise instead.

• In cases where TLS Protect for Kubernetes components and/or custom resources are owned by another entity (i.e another installer controller), users will have to manually update cluster state to remove the ownership (i.e remove resources from installer's configuration, remove resource owner refs etc)