Skip to main content
Version: 1.27

Upgrade your Okteto instance

Upgrade your Okteto Instance​

To ensure a successful Okteto upgrade, we recommend testing it on a dedicated test cluster. Please contact your sales representative to request a test license for your test cluster.

To upgrade a new release, modify the config.yaml with your desired changes and then use:

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.27.1

You can use helm ls to find the name of your release.

Please review the release notes before upgrading. New features, known issues, and configuration changes will be listed there.

Upgrading to Okteto 1.26.x​

  • ACTION REQUIRED: Hostname Length Limit
    Deployments now fail if a service hostname exceeds 63 characters, and an error message is shown. This limit is automatically applied to all resources. Previously, dev environments could deploy successfully even if 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​

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​

As part of the 1.22 release, we have reorganized some helm settings that allow you to configure annotations, labels, and role bindings to apply to user's service accounts. Settings changed are the following:

Summarizing, in case you have all or some of these settings configured as they were before:

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 configuration for 1.22 versions would be the following:

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

Old settings are still considered and have preference, but their support will be removed in a future version. Please consider migrating them as soon as possible.

We have also made another relevant change to consider when migrating to 1.22. We have stopped creating an automatic role binding to any custom service account created on namespaces managed by Okteto to the cluster role specified on serviceAccounts.roleBindings.namespaces (clusterRole in previous versions). If you create any custom service account as part of your application, make sure you also create any role or role binding needed.

If you experience issues with permissions in this regard, we recommend creating an explicit role and role-binding, but as an alternative solution you can also manually create the role-binding to the cluster-admin role, using the following approach:

  1. Create the 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 Okteto Manifest deploy commands, 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​

In the Okteto 1.20 release, we have enabled Pull Secrets by default. If you do no wish to manage Pull Secrets the following helm values should be disabled:

  • regcredsManager.pullSecrets.enabled should be set to false
  • daemonset.configurePrivateRegistriesInNodes.enabled should be set to false (if you are already preventing Okteto to manage credentials in the node, this may already be configured correctly)