Upgrade your Okteto instance

Upgrade your Okteto Instance

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

$ helm repo update
$ helm upgrade <your-release-name> 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.7.0

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

As part of 1.7.0, we have changed the default behavior of BuildKit to don't use a persistent volume. You have to include the following setting in your configuration file to keep using persistency:

buildkit:
  persistence:
    enabled: true

We have also moved the configuration settings needed to configure the external storage for the registry. Before, it was configured under cloud key and now it has to be configured under registry key.

So, before 1.7.X, the configuration to configure external storage would look like this:

cloud:
  provider:
    aws:
      enabled: true
      region: us-west-2
      bucket: okteto-private-images
      iam:
        accessKeyID: "XXXXXX"

That configuration will still work for backward compatibility, but we recommmend you to update it to the new keys. In order to do so, you need to change to this:

registry:
  secret:
    name: "okteto-cloud-secret"
    secretKey: "key"
  storage:
    provider:
      aws:
        enabled: true
        region: us-west-2
        bucket: okteto-private-images
        iam:
          accessKeyID: "XXXXXX"

If you didn't override a value for cloud.secret, you need to include the registry.secret section as posted in the previous snippet to keep working with the previous default values specified by the Okteto chart.

If you had a custom value for cloud.secret, you need to specify the right values under registry.secret key.

Upgrading from Okteto 0.x to 1.x

Okteto 1.x has two major breaking changes that you need to be aware of before upgrading:

• Support for Kubernetes 1.19 has been removed, and 1.20 is deprecated.
• The helm chart has been renamed from okteto-enterprise to okteto. All the resources created by the chart will have okteto as their prefix instead of okteto-enterprise. This change will cause all resources to be recreated upon upgrade. Depending on your cloud provider and your networking configuration, you might need to update the DNS entry of the build service after upgrading your Okteto instance.
• The helm chart doesn't install cert-manager by default.

We recommend that you follow the steps below to reduce the disruption of the service to a minimum:

Before upgrade

Skip this step if you are bringing your own certificates. Check if this is the case by seeing that the wildcard creation is disabled in the Okteto helm values configuration:

wildcardCertificate:
  create: false

If Okteto was generating the certificates for you, run the following command from your command line to make sure helm upgrade doesn't remove the existing cert-manager issuer and certificates:

kubectl -n okteto annotate issuer okteto-okteto-enterprise helm.sh/resource-policy=keep
kubectl -n okteto annotate certificate default-ssl-certificate helm.sh/resource-policy=keep

Then, add the following configuration to your Okteto helm values file to use the existing certificate:

wildcardCertificate:
  create: false
  name: default-ssl-certificate

ingress-nginx:
  controller:
    extraArgs:
      default-ssl-certificate: $(POD_NAMESPACE)/default-ssl-certificate

Keeping the same issuer and certificate reduces moving parts during the upgrade, but we recommend you to bring your own certificate once the Okteto upgrade has been complete succesfully.

Upgrade Okteto

Run the following commands to upgrade your Okteto instance:

helm repo update

helm upgrade --install okteto okteto/okteto -f config.yaml --namespace=okteto

After upgrade

Use kubectl to get the new address of the build service:

kubectl get service -l=app.kubernetes.io/instance=okteto,app.kubernetes.io/component=buildkit --namespace=okteto

The output will look something like this:

NAME                TYPE           CLUSTER-IP      EXTERNAL-IP                           PORT(S)          AGE
okteto-buildkit     LoadBalancer   10.245.142.73   a519c8b3b27f95...elb.amazonaws.com    1234:32449/TCP   5m

Update your DNS configuration with the EXTERNAL-IP address.

If you are bringing your own certificates, your Okteto instance is now fully upgraded. The rest of the guide doesn't apply to your configuration.

Install cert-manager

Okteto will remove the instance of cert-manager that was installed by older versions of the helm chart. If you plan on using cert-manager as your certificate provider, you'll need to install it manually in your cluster using the instructions below:

helm repo add jetstack https://charts.jetstack.io

helm repo update

helm install cert-manager jetstack/cert-manager --namespace=okteto --version=v1.10.2 --set global.podSecurityPolicy.enabled=true

Once installed, cert-manager will continue to renew your existing certificates. Please refer to their docs if you run into any installation or certificate renewal issues.

Upgrade to Kubernetes 1.25

Kubernetes version 1.25 no longer supports pod security policies. If you are running Okteto in Kubernetes < 1.25, the default installation of Okteto creates pod security policies. If you upgrade Kubernetes to version 1.25 before upgrading Okteto, you will encounter the following error during the upgrade process:

Error: UPGRADE FAILED: unable to build kubernetes objects from current release manifest: [resource mapping not found for name: "okteto-permissive" namespace: "" from "": no matches for kind "PodSecurityPolicy" in version "policy/v1beta1"
ensure CRDs are installed first, resource mapping not found for name: "okteto-restrictive" namespace: "" from "": no matches for kind "PodSecurityPolicy" in version "policy/v1beta1"
ensure CRDs are installed first]

You can find more information about how to recover from this state in this community link.

To avoid this issue, upgrade Okteto before upgrading Kubernetes to version 1.25 and add the following configuration to your helm values file:

podSecurityPolicy:
   enabled: false