This is a draft document that was built and uploaded automatically. It may document beta software and be incomplete or even incorrect. Use this document at your own risk.

Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
SUSE Edge Documentation|Day 2 Operations|Edge 3.5 migration
Applies to SUSE Edge 3.6

31 Edge 3.5 migration

 

This section explains how to migrate your management and downstream clusters from Edge 3.5 to Edge 3.6.0.

Important
Important

Always perform cluster migrations from the latest Z-stream release of Edge 3.5.

Always migrate to the Edge 3.6.0 release. For subsequent post-migration upgrades, refer to the management (Chapter 32, Management Cluster) and downstream (Chapter 33, Downstream clusters) cluster sections.

The following table lists the different types of clusters and the methods to upgrade clusters:

Table 31.1: Clusters and methods to upgrade downstream clusters
 
Cluster typeMethod

EIB provisioned clusters

See Section 31.1.3, “Fleet” for details.

Phone-home provisioned clusters

See Upgrading the Kubernetes Version for Kubernetes version upgrade and Downstream clusters (Chapter 33, Downstream clusters) for SUC, Operating system, and other components.

31.1 Management Cluster

 

This section covers the following topics:

Section 31.1.1, “Prerequisites” - prerequisite steps to complete before starting the migration.

Section 31.1.2, “Upgrade Controller” - how to do a management cluster migration using the Chapter 19, Upgrade Controller.

Section 31.1.3, “Fleet” - how to do a management cluster migration using Chapter 6, Fleet.

31.1.1 Prerequisites

 

31.1.1.1 Migrate Metal3 CA Certificate Configuration

 
Note
Note

Applies only to Metal3 deployments that use additional trusted CAs for external media servers with TLS.

The Metal3 Helm chart has changed how trusted CA certificates are configured. Previously, additional CAs were provided via a Secret (tls-ca-additional) with the additionalTrustedCAs boolean flag. The new version uses a ConfigMap containing the complete CA bundle referenced by the global.trustedCA value.

If you have configured additional trusted CAs for Metal3, you need to migrate from the Secret-based approach to the ConfigMap-based approach:

  1. Create a ConfigMap containing your CA bundle from the existing Secret:

    Extract the certificates from the old Secret:

    kubectl get secret tls-ca-additional -n metal3-system -o jsonpath='{.data}' | \
  jq -r 'to_entries[] | .value' | base64 -d > ca-bundle.pem

    Optional - Include system CA bundle: If your Metal3 deployment also needs to trust public CAs (for example, when accessing external resources over HTTPS), you need to include the system CA bundle in addition to your custom CAs. Extract the system CA bundle from a container image and prepend it to your custom CAs:

    # Extract system CAs from a container image (using podman or docker)
podman run --rm registry.suse.com/bci/bci-base:latest cat /etc/ssl/certs/ca-certificates.crt > system-cas.pem

# Combine system CAs with your custom CAs
cat system-cas.pem ca-bundle.pem > combined-ca-bundle.pem
mv combined-ca-bundle.pem ca-bundle.pem
    Important
    Important

    If you include the system CA bundle, it becomes your responsibility to keep it up-to-date. The system CAs in the container image may become outdated over time as CA certificates expire or are revoked. You should periodically refresh the system CA bundle by re-extracting it from an updated container image.

    Create the ConfigMap with the final CA bundle:

    kubectl create configmap tls-ca-bundle -n metal3-system --from-file=ca-bundle.pem=ca-bundle.pem

  2. Update your Metal3 Helm values to use the new ConfigMap reference:

    Change from:

    global:
  additionalTrustedCAs: true

    To:

    global:
  trustedCA: tls-ca-bundle

  3. After upgrading the Metal3 Helm chart with the new configuration, you can delete the old Secret:

    kubectl delete secret tls-ca-additional -n metal3-system

31.1.2 Upgrade Controller

 
Important
Important

The Upgrade Controller currently supports Edge release migrations only for non air-gapped management clusters.

The following topics are covered as part of this section:

Section 31.1.2.1, “Prerequisites” - prerequisites specific to the Upgrade Controller.

Section 31.1.2.2, “Migration steps” - steps for migrating a management cluster to a new Edge version using the Upgrade Controller.

31.1.2.1 Prerequisites

 
31.1.2.1.1 Edge 3.5 Upgrade Controller
 

Before using the Upgrade Controller, you must first ensure that it is running a version that is capable of migrating to the desired Edge release.

To do this:

  1. If you already have Upgrade Controller deployed from a previous Edge release, upgrade its chart:

    helm upgrade upgrade-controller -n upgrade-controller-system oci://registry.suse.com/edge/charts/upgrade-controller --version 305.0.3+up0.1.3

  2. If you do not have Upgrade Controller deployed, follow Section 19.3, “Installing the Upgrade Controller”.

31.1.2.2 Migration steps

 

Performing a management cluster migration with the Upgrade Controller is fundamentally similar to executing an upgrade.

The only difference is that your UpgradePlan must specify the 3.6.0 release version:

apiVersion: lifecycle.suse.com/v1alpha1
kind: UpgradePlan
metadata:
  name: upgrade-plan-mgmt
  # Change to the namespace of your Upgrade Controller
  namespace: CHANGE_ME
spec:
  releaseVersion: 3.6.0

For information on how to use the above UpgradePlan to do a migration, refer to Upgrade Controller upgrade process (Section 32.1, “Upgrade Controller”).

31.1.3 Fleet

 
Note
Note

Whenever possible, use the Section 31.1.2, “Upgrade Controller” for migration.

Refer to this section only for use cases not covered by the Upgrade Controller.

Performing a management cluster migration with Fleet is fundamentally similar to executing an upgrade.

The key differences being that:

  1. The fleets must be used from the release-3.6.0 release of the suse-edge/fleet-examples repository.

  2. Charts scheduled for an upgrade must be upgraded to versions compatible with the Edge 3.6.0 release. For a list of the Edge 3.6.0 components, refer to Section 41.3, “Release 3.5.0”.

Important
Important

To ensure a successful Edge 3.6.0 migration, it is important that users comply with the points outlined above.

Considering the points above, users can follow the management cluster Fleet (Section 32.2, “Fleet”) documentation for a comprehensive guide on the steps required to perform a migration.

31.2 Downstream Clusters

 

Section 31.2.1, “Fleet” - how to do a downstream cluster migration using Chapter 6, Fleet.

31.2.1 Fleet

 

Performing a downstream cluster migration with Fleet is fundamentally similar to executing an upgrade.

The key differences being that:

  1. The fleets must be used from the release-3.6.0 release of the suse-edge/fleet-examples repository.

  2. Charts scheduled for an upgrade must be upgraded to versions compatible with the Edge 3.6.0 release. For a list of the Edge 3.6.0 components, refer to Section 41.3, “Release 3.5.0”.

Important
Important

To ensure a successful Edge 3.6.0 migration, it is important that users comply with the points outlined above.

Considering the points above, users can follow the downstream cluster Fleet (Section 33.1, “Fleet”) documentation for a comprehensive guide on the steps required to perform a migration.