Skip to main content
Version: 1.47

Upgrade your Okteto instance

You upgrade your Okteto instance with helm upgrade. Some Okteto releases need extra steps, listed in the section for each release.

Upgrading your Okteto Instance​

tip

We recommend testing each Okteto upgrade on a dedicated test cluster first. Contact your sales representative to request a test license for your test cluster.

Running the Upgrade​

To upgrade to a new release, make your changes in config.yaml and run:

helm repo update
helm upgrade okteto okteto/okteto -f config.yaml --namespace=okteto --version <version_number>

For example:

helm repo update
helm upgrade okteto okteto/okteto -f config.yaml --namespace=okteto --version 1.47.0

Run helm ls to find the name of your release.

Review the release notes before upgrading: they list new features, known issues, and configuration changes.

Upgrading to Okteto 1.40.x – Default Registry Change to GitHub Container Registry​

Starting with Okteto 1.40, the default installation pulls Okteto images from GitHub Container Registry (ghcr.io) instead of Docker Hub. Images are still published to both registries, so you can choose which one to use.

Configuring Your Installation to Pull from Docker Hub​

To keep pulling images from Docker Hub, add the following configuration to your Helm values file (config.yaml):

globals:
registry: docker.io

cli:
image:
registry: docker.io

ingress-nginx:
controller:
image:
registry: docker.io

okteto-nginx:
controller:
image:
registry: docker.io

reloader:
global:
imageRegistry: docker.io

Then upgrade your Okteto instance:

helm repo update
helm upgrade okteto okteto/okteto -f config.yaml --namespace=okteto --version 1.47.0
tip

To use a different registry (neither ghcr.io nor docker.io), configure a custom registry as described in Air-Gapped Networks.

Upgrading to Okteto 1.38.x – Certificate Configuration Changes​

  • Internal Certificate Unification: Internal certificates have been unified into a single configuration. During the upgrade, you may see communication issues for a few seconds while the new certificate configuration takes effect. This is expected, and it should resolve on its own.
  • Argo CD Installations: If you manage your Okteto installation with Argo CD, review Argo CD. The certificate unification may need special attention during the Argo CD sync to avoid deployment interruptions.

Upgrading to Okteto 1.37.x – Redis Migration from Bitnami​

Starting with Okteto 1.37, the bundled Redis deployment no longer uses the Bitnami Helm chart. The workload has changed from a StatefulSet to a Deployment and Redis persistence is disabled. The available configuration options have been reduced and standardized.

If you customized Redis with Bitnami-specific Helm values, review and update your values file before upgrading. Unsupported Bitnami values are silently ignored, which can cause unexpected Redis behavior.

Upgrading to Okteto 1.35.x – Kubernetes 1.33 Support and Amazon Linux 2023 (AL2023) Compatibility​

Okteto 1.35 is the first release with official support for Kubernetes 1.33 and Amazon Linux 2023 (AL2023).

If you run Okteto on AWS, we recommend the following upgrade order to keep compatibility:

  1. Upgrade Okteto to version 1.35.
  2. (Recommended) Upgrade your node pool to Amazon Linux 2023 and verify that your workloads are healthy.
  3. Upgrade your EKS cluster to Kubernetes 1.33.

This order keeps your rollback options in case of unexpected issues. If you upgrade to Kubernetes 1.33 before you upgrade Okteto to 1.35, you may run into compatibility problems: Okteto 1.34 and earlier don't support Kubernetes 1.33.

Upgrading to Okteto 1.31.x – Schema 1 Image Deprecation​

Okteto 1.31 removed support for Docker Image Manifest Schema 1, because of upgrades in its dependencies.

What This Means for You

  • Older container images that rely on Schema 1 will fail to pull or deploy
  • This change aligns with the broader container ecosystem: Schema 1 images have been deprecated since 2021, and modern container runtimes no longer support them

Checking Your Images​

To check an image, run:

docker manifest inspect <image-name>
  • If the output contains "schemaVersion": 1, you need to update the image
  • If it contains "schemaVersion": 2, no action is required

Migrating to Schema 2​

  • If you use Schema 1 images, migrate them to Schema 2 before you upgrade to Okteto 1.31
  • If your image is outdated, look for an updated version, or rebuild and push it with a recent Docker version:
docker pull <old-image>
docker tag <old-image> myrepo/myimage:v2
docker push myrepo/myimage:v2

Upgrading to Okteto 1.26.x – Hostname Limits, Helm Release Name Changes​

  • ACTION REQUIRED: Hostname Length Limit
    Deployments now fail with an error message if a service hostname exceeds 63 characters. This limit applies automatically to all resources. Previously, application environments could deploy successfully even if their endpoints didn't work. This change may affect environments that deployed without issues before.
  • Helm Release Name Limit:
    Helm release names are now limited to 63 characters. While this limit is automatically enforced for most resources, the DefaultBackend service can still fail during installation if its name exceeds this limit.
    To avoid installation errors, use the defaultBackend.nameOverride setting to shorten the DefaultBackend service name. If you need to rename the DefaultBackend during an upgrade,follow this guide as it may impact the installation.
  • Private Repository Deploys: Deploying private repositories now uses the Okteto backend as the SSH agent, rather than mounting the local SSH agent. This change ensures feature parity between remote and local deploys but may impact scenarios where private repositories are cloned as part of commands defined in the deploy section during remote execution
  • Buildkit Persistence Enabled: Buildkit persistence is now enabled by default, with a 100Gi disk and cache set to 90% of the disk size. If you previously used buildkit.persistence.cache, adjust to the new ratio, as this setting is no longer applicable

Upgrading to Okteto 1.25.x – CLI 3.0.0 Upgrade​

Starting with the 1.25 release, Okteto will use CLI version 3.0.0 when deploying and destroying pipelines. Please familiarize yourself with the changes in Okteto CLI 3.0.0 before upgrading your cluster.

Upgrading to Okteto 1.22.x – Role & Binding Config Migration​

The 1.22 release reorganizes the Helm settings that configure the annotations, labels, and role bindings for users' service accounts. These settings moved:

For example, if you configured some or all of these settings the old way:

clusterRole: cluster-admin

globalClusterRole: example-cluster-role

user:
serviceAccount:
annotations:
custom.annotation/one: one
custom.annotation/two: two
labels:
custom.label/one: one
custom.label/two: two
extraRoleBindings:
enabled: true
roleBindings:
namespace-name1:
- cluster-role1
- cluster-role2
namespace-name2:
- cluster-role3

The 1.22 configuration is:

serviceAccounts:
annotations:
custom.annotation/one: one
custom.annotation/two: two
labels:
custom.label/one: one
custom.label/two: two
roleBindings:
namespaces: cluster-admin
clusterRoleBinding: example-cluster-role
extraRoleBindings:
namespace-name1:
- cluster-role1
- cluster-role2
namespace-name2:
- cluster-role3
note

Okteto still reads the old settings, and they take precedence, but their support will be removed in a future version. Migrate them as soon as possible.

Okteto 1.22 also stops automatically binding the custom service accounts created in the Namespaces it manages to the cluster role set in serviceAccounts.roleBindings.namespaces (clusterRole in previous versions). If your application creates a custom service account, also create the roles and role bindings it needs.

If this causes permission issues, we recommend creating an explicit role and role binding. As an alternative, you can bind the service account to the cluster-admin role manually:

  1. Create the k8s/rb.yml.tpl file with the following content:
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: <service-account-name>
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: cluster-admin
subjects:
- kind: ServiceAccount
name: <service-account-name>
namespace: ${OKTETO_NAMESPACE}
  1. Replace <service-account-name> with the name of the service account you want to bind to the cluster-admin role.
  2. In the deploy commands of your Okteto Manifest, use envsubst to replace the ${OKTETO_NAMESPACE} variable:
deploy:
- envsubst < k8s/rb.yml.tpl > k8s/rb.yml
- kubectl apply -f k8s

Upgrading to Okteto 1.20.x – Pull Secrets Enabled by Default​

The Okteto 1.20 release enables Pull Secrets by default. If you don't want Okteto to manage Pull Secrets, disable the following Helm values:

  • Set regcredsManager.pullSecrets.enabled to false
  • Set daemonset.configurePrivateRegistriesInNodes.enabled to false (if you already prevent Okteto from managing credentials in the nodes, this may already be configured)