Upgrading a cluster

Upgrade your Stackland cluster version using the TargetInstallationState Kubernetes resource. Perform a rolling update with incremental load evacuation and node reboot.

Getting startedGetting started

1. Make sure you have admin access to the cluster.

2. Check the current version of your cluster:

   kubectl get targetinstallationstate main -o jsonpath='{.status.currentVersion}'
   

3. Find out which versions you can upgrade to. The available versions vary based on whether your cluster has internet access:

   • Cluster with internet access: Available versions are pulled automatically from the Stackland container registry.
   • Air-gapped cluster: Available versions are limited to the images manually imported into your local registry.

Selecting the release channelSelecting the release channel

The release channel determines which Stackland versions are available for the upgrade. The default channel is stable.

Available channels:

• stable: Stable releases for use in production environments. This channel is available to all customers by default.
• alpha: Channel with early releases for testing new features. You can access it upon request.

To switch channels, update the PlatformConfig resource:

kubectl edit platformconfig main

Indicate your preferred channel in the specification:

spec:
  releaseChannel: "stable"  # or "alpha"

Before upgrading to 27.xBefore upgrading to 27.x

Stackland 26.2 introduced a new Contour-based Ingress controller deprecating the legacy implementation based on ingress-nginx. Stackland 27 will completely remove ingress-nginx from the distribution, and this serves as prior notice of these plans. In Stackland 26 releases, ingress-nginx remains available for custom workloads, but you must migrate to the new controller before upgrading to Stackland 27.

In most cases, custom Ingress manifests with the stackland-default class will remain operational, but the new controller does not support nginx.ingress.kubernetes.io/* annotations, which are specific to ingress-nginx. Make sure to remove or replace them. For more information, see Checking custom Ingress resources.

Also note that operator action is required: the upgrade to version >= 27.0.0 will fail to initialize unless you explicitly disable the legacy Ingress controller.

Checking custom Ingress resourcesChecking custom Ingress resources

If your cluster contains custom Ingress resources:

1. Locate custom Ingress resources:

   kubectl get ingress -A
   

2. Check that they specify spec.ingressClassName: stackland-default or have no such field. In the latter case, the default class is used.

3. Make sure resource annotations do not contain nginx-specific nginx.ingress.kubernetes.io/* keys. If you find any such annotations, remove or replace them with the new Ingress controller alternatives, or the rules will fail to apply after the upgrade.

Testing the application before the upgradeTesting the application before the upgrade

While your cluster is still on version 26.x, you can proactively verify that your custom Ingress is compatible with the new Ingress controller.

1. In a temporary copy of the manifest, replace spec.ingressClassName: stackland-default with spec.ingressClassName: stackland-system and apply the manifest:

   kubectl apply -f <file_name>.yaml
   

2. Check application availability. There are two ways to do this:

   • Direct IP verification without DNS. This method works independently of DNS propagation or your application domain's DNS zone hosting.

     1. Get the external IP of the LoadBalancer serving the stackland-system class:

        kubectl get svc -A \
          -l app.kubernetes.io/name=contour,app.kubernetes.io/component=envoy
        

        If the selector does not work for your setup, manually locate the LoadBalancer service within your Contour namespace.

     2. Send a request to the application using the retrieved IP:

        curl --resolve <domain>:443:<Envoy_external_IP> https://<domain>/
        

   • Domain-based verification. You can only use this method if your DNS zone is delegated: the domain record will automatically migrate to the stackland-system LoadBalancer. Keep in mind there is a DNS propagation delay. If you manage a custom DNS, the domain will continue to point to the legacy LoadBalancer, i.e., you will get a false negative result. Use curl --resolve instead.

3. After verification, change the spec.ingressClassName value back to stackland-default or remove this field.

You can skip this step on version 27.x: the new Ingress controller serves the stackland-default class by default.

Disabling the legacy Ingress implementationDisabling the legacy Ingress implementation

1. Disable the legacy Ingress implementation within the IngressConfig resource:

   kubectl patch ingressconfig main --type=merge \
     -p '{"spec":{"settings":{"nginx":{"enabled":false}}}}'
   

Disabling ingress-nginx automatically restarts existing Ingress controllers on top of Contour.

1. Wait until the platform migrates to a single Ingress Controller. Check the current state:

   kubectl get ingressconfig main -o jsonpath='{.status.ingress.observedIngress}'
   

kubectl get availablereleases main -o yaml

apiVersion: stackland.yandex.cloud/v1alpha1
kind: AvailableReleases
metadata:
  name: main
status:
  releases:
    - version: "26.1.0"
      ready: true
    - version: "26.1.1"
      ready: true

sladm pull --image-bundle full

sladm push --local-registry --kubeconfig=<kubeconfig_path> --image-bundle-folder <directory_name>-oci

kubectl get availablereleases main -o yaml

Checking the upgrade statusChecking the upgrade status

After applying the manifest, you can monitor the upgrade status:

kubectl get targetinstallationstate main

Here is an example of the command output:

NAME   TARGET VERSION   CURRENT VERSION   PHASE     MESSAGE                           AGE
main   26.1.1           26.1.0            Running   Running upgrade to version 26.1.1 5m

Getting detailed informationGetting detailed information

Run this command:

kubectl describe targetinstallationstate main

The status field displays:

• currentVersion: Currently installed version.
• phase: Upgrade stage:
  • Pending: Upgrade awaiting start.
  • Running: Upgrade in progress.
  • Completed: Upgrade completed.
  • Failed: Upgrade failed.
• message: Current state message.
• jobName: Name of the Kubernetes upgrade job.
• lastUpdateTime: Status last update time.

Viewing upgrade logsViewing upgrade logs

To read logs of the upgrade job, run this command:

kubectl logs -n stackland-install job/<job_name>

You can get the job name from the status.jobName field in the TargetInstallationState resource.