Upgrading a cluster

Written by

Updated at April 8, 2026

Getting started
Selecting the release channel
- Cluster with internet access
- Air-gapped cluster
Checking the upgrade status
Getting detailed information
Viewing upgrade logs

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

Getting started

Make sure you have admin access to the cluster.

Check the current version of your cluster:

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

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 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"

Management console

CLI

If the cluster has no internet access, you must first pull the new version images to your local registry using the CLI.

In the left-hand menu, select Settings.
In the submenu, select Upgrade.
Click the Upgrade link to open the cluster upgrade page.
On the Cluster update page, check the Current upgrade status:
- Target version: Version to upgrade to.
- Phase: Upgrade stage.
- Message: Current state message.
Under Available updates, specify the version to upgrade to.
Click Start update.

The CLI steps depend on whether your cluster has internet access.

Cluster with internet access

For clusters with internet access, new version images are automatically pulled from the Stackland container registry.

Setting up an upgrade

Wait for the new release to appear in the AvailableReleases resource. To check for available releases, run this command:

kubectl get availablereleases main -o yaml

Here is an example of the command output:

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

As soon as the list displays the target version with the ready: true status, you can start the upgrade.

Starting the upgrade

Create the manifest file, e.g., using the touch upgrade.yaml command.
Open the file and paste the configuration:
```
apiVersion: stackland.yandex.cloud/v1alpha1
kind: TargetInstallationState
metadata:
  name: main
spec:
  targetVersion: "<version>"
  installationTimeout: "2h"
```
Where:
- targetVersion: Target version for the upgrade. Specify the value from availablereleases[main].status.releases[<preferred_release>].version.
- installationTimeout: Upgrade timeout.
Apply the manifest:
```
kubectl apply -f upgrade.yaml
```

Air-gapped cluster

If the cluster has no internet access, you must first pull the new version images to your local registry.

Downloading SLADM

On an internet-connected machine, download the latest sladm version in the same way as during its initial installation.

Pulling images on an internet-connected machine

On an internet-connected machine, run this command:

sladm pull --image-bundle full

Where:

--image-bundle: Image bundle type, full to get all images.

Note

To upgrade images of separately licensed components, such as SpeechSense, run the command again with --image-bundle speechsense. For more information, see Uploading SpeechSense images.

Transferring artifacts into the internal infrastructure

Transfer the following to a machine with access to the local cluster registry:

sladm binary file
release.yaml
<release_name>-oci folder

Pushing images to the local registry

On a machine with cluster access, run this command:

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

Where:

--local-registry: Indicates the use of the cluster's local registry.
--kubeconfig: Path to the kubeconfig file for access to the cluster.
--image-bundle-folder: Path to the folder with images.

Verifying release availability

After pushing the images, wait until the new release appears in the AvailableReleases resource.

kubectl get availablereleases main -o yaml

As soon as the list displays the target version with the ready: true status, you can start the upgrade.

Starting the upgrade

Create the manifest file, e.g., using the touch upgrade.yaml command.
Open the file and paste the configuration:
```
apiVersion: stackland.yandex.cloud/v1alpha1
kind: TargetInstallationState
metadata:
  name: main
spec:
  targetVersion: "<version>"
  installationTimeout: "2h"
```
Where:
- targetVersion: Target version for the upgrade. Specify the value from availablereleases[main].status.releases[<preferred_release>].version.
- installationTimeout: Upgrade timeout.
Apply the manifest:
```
kubectl apply -f upgrade.yaml
```

Checking 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 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 logs

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

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

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

Upgrading a cluster

Getting startedGetting started

Selecting the release channelSelecting the release channel

Cluster with internet accessCluster with internet access

Setting up an upgradeSetting up an upgrade

Starting the upgradeStarting the upgrade

Air-gapped clusterAir-gapped cluster

Downloading SLADMDownloading SLADM

Pulling images on an internet-connected machinePulling images on an internet-connected machine

Transferring artifacts into the internal infrastructureTransferring artifacts into the internal infrastructure

Pushing images to the local registryPushing images to the local registry

Verifying release availabilityVerifying release availability

Starting the upgradeStarting the upgrade

Checking the upgrade statusChecking the upgrade status

Getting detailed informationGetting detailed information

Viewing upgrade logsViewing upgrade logs

Was the article helpful?

Getting started

Selecting the release channel

Cluster with internet access

Setting up an upgrade

Starting the upgrade

Air-gapped cluster

Downloading SLADM

Pulling images on an internet-connected machine

Transferring artifacts into the internal infrastructure

Pushing images to the local registry

Verifying release availability

Starting the upgrade

Checking the upgrade status

Getting detailed information

Viewing upgrade logs