From b8c4791f7ccfea792e4790faa7f99faa0f4166b6 Mon Sep 17 00:00:00 2001 From: Nacho Fuertes Date: Thu, 8 Oct 2026 13:26:21 +0200 Subject: [PATCH 1/2] Release version 1.49 documentation Snapshots src/content into versioned_docs/version-1.49, rolls the docusaurus and netlify version config forward (1.49 official, 1.50 unreleased), finalizes the 1.49.0 release-notes date and CLI link, and archives 1.37. Also corrects the README versioning steps: the docusaurus.config.js versions object only lists the official version and the five before it, so the entry to remove is NEW_VERSION - 6, not the oldest version in versions.json. Co-Authored-By: Claude Opus 5.5 (1M context) Signed-off-by: Nacho Fuertes --- README.md | 4 +- docusaurus.config.js | 20 +- netlify.toml | 9 +- src/content/archived-release-notes.mdx | 64 ++ src/content/release-notes.mdx | 71 +-- src/pages/archives.md | 4 +- versioned_docs/version-1.37/byoc/index.mdx | 39 -- .../version-1.37/development/index.mdx | 18 - .../okteto-ai/ai-getting-started.mdx | 268 -------- .../version-1.37/okteto-ai/index.mdx | 79 --- .../okteto-ai/okteto-ai-admin-config.mdx | 220 ------- .../version-1.37/previews/index.mdx | 28 - .../version-1.37/reference/faqs.mdx | 164 ----- .../version-1.37/reference/index.mdx | 7 - .../version-1.37/reference/known-issues.mdx | 32 - versioned_docs/version-1.37/release-notes.mdx | 599 ------------------ .../version-1.37/saas-vs-self-hosted.mdx | 24 - .../install/certificates/cert-manager.mdx | 25 - .../self-hosted/manage/okteto-license.mdx | 45 -- .../self-hosted/manage/troubleshooting.mdx | 69 -- versioned_docs/version-1.37/variables.json | 7 - versioned_docs/version-1.49/admin/billing.mdx | 169 +++++ .../version-1.49/admin/build-service.mdx | 114 ++++ .../admin/catalog.mdx | 2 +- .../admin/cleanup.mdx | 36 +- .../admin/cloud-credentials/aws.mdx | 12 +- .../admin/cloud-credentials/gcp.mdx | 4 +- .../admin/cloud-credentials/index.mdx | 0 .../admin/custom-installer-image.mdx | 10 +- .../admin/dashboard.mdx | 84 +-- .../admin/index.mdx | 12 +- .../integrations/okta-user-deprovisioning.mdx | 0 .../admin/okteto-api.mdx | 2 +- .../admin/okteto-insights.mdx | 115 ++-- .../version-1.49/admin/previews.mdx | 68 ++ .../admin/private-repositories/github.mdx | 4 +- .../admin/private-repositories/ssh-key.mdx | 4 +- .../admin/registry-credentials/amazon-ecr.mdx | 6 +- .../admin/registry-credentials/azure-acr.mdx | 0 .../admin/registry-credentials/dockerhub.mdx | 0 .../google-artifact-registry.mdx | 6 +- .../admin/registry-credentials/index.mdx | 44 +- .../admin/resource-manager.mdx | 14 +- .../admin/ssh-known-hosts.mdx | 2 +- .../agentic/autonomous-workflows.mdx | 119 ++++ .../version-1.49/agentic/best-practices.mdx | 173 +++++ .../agentic/collaborative-workflows.mdx | 61 ++ versioned_docs/version-1.49/agentic/index.mdx | 123 ++++ .../archived-release-notes.mdx | 532 +++++++++++++++- .../version-1.49/byoc-vs-self-hosted.mdx | 24 + .../byoc/aws/index.mdx | 19 +- .../byoc/gcp/index.mdx | 24 +- versioned_docs/version-1.49/byoc/index.mdx | 74 +++ .../core/build-service.mdx | 65 +- .../core/container-registry.mdx | 0 .../credentials/environment-variables.mdx | 0 .../credentials/kubernetes-credentials.mdx | 21 +- .../credentials/personal-access-tokens.mdx | 19 +- versioned_docs/version-1.49/core/divert.mdx | 238 +++++++ .../core/endpoints/automatic-ssl.mdx | 0 .../core/endpoints/private-endpoints.mdx | 3 +- versioned_docs/version-1.49/core/index.mdx | 69 ++ .../core/namespaces.mdx | 10 +- .../core/okteto-insights-dashboards.mdx | 60 +- .../core/okteto-manifest.mdx | 8 +- .../core/okteto-variables.mdx | 57 +- .../core/remote-execution.mdx | 6 +- .../core/use-volume-snapshots.mdx | 53 +- .../core/user-roles-and-permissions.mdx | 48 +- .../containers/file-sync/aspnetcore.mdx | 4 +- .../containers/file-sync/golang.mdx | 6 +- .../containers/file-sync/index.mdx | 0 .../development/containers/file-sync/java.mdx | 6 +- .../development/containers/file-sync/node.mdx | 2 +- .../development/containers/file-sync/php.mdx | 4 +- .../containers/file-sync/python.mdx | 7 +- .../development/containers/file-sync/ruby.mdx | 4 +- .../containers/hybrid/frontend.mdx | 0 .../development/containers/hybrid/index.mdx | 0 .../development/containers/hybrid/java.mdx | 2 +- .../development/containers/index.mdx | 0 .../deploy/deploy-from-catalog.mdx | 22 +- .../development/deploy/deploy-from-git.mdx | 14 +- .../deploy/develop-on-okteto-button.mdx | 0 .../deploy/from-private-repositories.mdx | 31 +- .../development/deploy/index.mdx | 0 .../development/images.mdx | 0 .../version-1.49/development/index.mdx | 17 + .../version-1.49/development/using-divert.mdx | 416 ++++++++++++ .../development/using-okteto-cli.mdx | 2 +- .../advanced-commands-and-concepts.mdx | 4 +- .../get-started/deploy-your-app/build.mdx | 0 .../deploy-your-app/dependencies.mdx | 2 +- .../get-started/deploy-your-app/deploy.mdx | 0 .../get-started/deploy-your-app/endpoints.mdx | 0 .../get-started/deploy-your-app/index.mdx | 0 .../get-started/dev-quickstart.mdx | 2 +- .../get-started/install-okteto-cli.mdx | 2 +- .../get-started/install/amazon-eks.mdx | 43 +- .../get-started/install/civo.mdx | 0 .../get-started/install/digitalocean-doks.mdx | 0 .../get-started/install/google-gke.mdx | 2 + .../get-started/install/index.mdx | 3 +- .../get-started/install/microsoft-aks.mdx | 0 .../get-started/install/nutanix-nkp.mdx | 348 ++++++++++ .../get-started/install/openshift.mdx | 4 +- .../using-okteto-cli-and-dashboard.mdx | 40 +- .../{version-1.37 => version-1.49}/index.md | 32 +- .../version-1.49/previews/index.mdx | 127 ++++ .../previews/using-github-actions.mdx | 2 +- .../previews/using-gitlab-cicd.mdx | 54 +- .../reference/docker-compose.mdx | 243 ++++++- .../version-1.49/reference/faqs.mdx | 268 ++++++++ .../reference/feature-flags.mdx | 9 +- .../reference/file-synchronization.mdx | 6 +- .../version-1.49/reference/index.mdx | 8 + .../version-1.49/reference/known-issues.mdx | 51 ++ .../reference/manifest-migration.mdx | 22 +- .../reference/okteto-cli.mdx | 190 +++--- .../reference/okteto-manifest.mdx | 179 ++++-- .../reference/ssh-server.mdx | 8 +- .../reference/supported-github-actions.mdx | 0 versioned_docs/version-1.49/release-notes.mdx | 472 ++++++++++++++ .../self-hosted/aks/config.yaml | 0 .../self-hosted/civo/config.yaml | 0 .../self-hosted/digitalocean/config.yaml | 0 .../self-hosted/digitalocean/marketplace.md | 7 +- .../self-hosted/eks/config.yaml | 0 .../self-hosted/gke/config.yaml | 0 .../self-hosted/helm-configuration.mdx | 358 +++++++++-- .../self-hosted/index.mdx | 7 +- .../self-hosted/install/auth/azure-ad.mdx | 8 +- .../self-hosted/install/auth/bitbucket.mdx | 0 .../self-hosted/install/auth/github.mdx | 20 +- .../self-hosted/install/auth/gitlab.mdx | 0 .../self-hosted/install/auth/google.mdx | 0 .../self-hosted/install/auth/index.mdx | 0 .../self-hosted/install/auth/okta.mdx | 0 .../install/auth/openid-connect.mdx | 15 + .../self-hosted/install/auth/token.mdx | 16 +- .../install/certificates/aws-acm.mdx | 0 .../bring-your-own-certificate.mdx | 16 +- .../install/certificates/cert-manager.mdx | 45 ++ .../install/certificates/index.mdx | 0 .../self-hosted/install/config.yaml | 0 .../self-hosted/install/divert/index.mdx | 186 ++++++ .../install/divert/istio-installation.mdx | 419 ++++++++++++ .../install/divert/linkerd-installation.mdx | 304 +++++++++ .../self-hosted/install/github.mdx | 4 +- .../okteto-registry-storage/aws-s3-bucket.mdx | 0 .../azure-storage-container.mdx | 0 .../digitalocean-spaces.mdx | 0 .../okteto-registry-storage/filesystem.mdx | 0 .../google-cloud-storage.mdx | 0 .../install/okteto-registry-storage/index.mdx | 0 .../self-hosted/install/volume-snapshots.mdx | 38 +- .../self-hosted/manage/air-gapped.mdx | 27 +- .../self-hosted/manage/argocd.mdx | 6 + .../self-hosted/manage/arm-support.mdx | 161 +++++ .../self-hosted/manage/backup-restore.mdx | 0 .../manage/buildkit-high-performance.mdx | 86 +-- .../self-hosted/manage/crds.mdx | 67 +- .../self-hosted/manage/diagnostics.mdx | 0 .../self-hosted/manage/okteto-license.mdx | 57 ++ .../self-hosted/manage/troubleshooting.mdx | 505 +++++++++++++++ .../self-hosted/manage/uninstall-okteto.mdx | 2 +- .../self-hosted/manage/upgrade.mdx | 53 +- .../testing/getting-started-test.mdx | 2 +- .../testing/index.mdx | 8 +- versioned_docs/version-1.49/variables.json | 7 + ...debars.json => version-1.49-sidebars.json} | 73 ++- versions.json | 4 +- 172 files changed, 7005 insertions(+), 2464 deletions(-) delete mode 100644 versioned_docs/version-1.37/byoc/index.mdx delete mode 100644 versioned_docs/version-1.37/development/index.mdx delete mode 100644 versioned_docs/version-1.37/okteto-ai/ai-getting-started.mdx delete mode 100644 versioned_docs/version-1.37/okteto-ai/index.mdx delete mode 100644 versioned_docs/version-1.37/okteto-ai/okteto-ai-admin-config.mdx delete mode 100644 versioned_docs/version-1.37/previews/index.mdx delete mode 100644 versioned_docs/version-1.37/reference/faqs.mdx delete mode 100644 versioned_docs/version-1.37/reference/index.mdx delete mode 100644 versioned_docs/version-1.37/reference/known-issues.mdx delete mode 100644 versioned_docs/version-1.37/release-notes.mdx delete mode 100644 versioned_docs/version-1.37/saas-vs-self-hosted.mdx delete mode 100644 versioned_docs/version-1.37/self-hosted/install/certificates/cert-manager.mdx delete mode 100644 versioned_docs/version-1.37/self-hosted/manage/okteto-license.mdx delete mode 100644 versioned_docs/version-1.37/self-hosted/manage/troubleshooting.mdx delete mode 100644 versioned_docs/version-1.37/variables.json create mode 100644 versioned_docs/version-1.49/admin/billing.mdx create mode 100644 versioned_docs/version-1.49/admin/build-service.mdx rename versioned_docs/{version-1.37 => version-1.49}/admin/catalog.mdx (97%) rename versioned_docs/{version-1.37 => version-1.49}/admin/cleanup.mdx (90%) rename versioned_docs/{version-1.37 => version-1.49}/admin/cloud-credentials/aws.mdx (92%) rename versioned_docs/{version-1.37 => version-1.49}/admin/cloud-credentials/gcp.mdx (95%) rename versioned_docs/{version-1.37 => version-1.49}/admin/cloud-credentials/index.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/admin/custom-installer-image.mdx (86%) rename versioned_docs/{version-1.37 => version-1.49}/admin/dashboard.mdx (80%) rename versioned_docs/{version-1.37 => version-1.49}/admin/index.mdx (79%) rename versioned_docs/{version-1.37 => version-1.49}/admin/integrations/okta-user-deprovisioning.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/admin/okteto-api.mdx (97%) rename versioned_docs/{version-1.37 => version-1.49}/admin/okteto-insights.mdx (89%) create mode 100644 versioned_docs/version-1.49/admin/previews.mdx rename versioned_docs/{version-1.37 => version-1.49}/admin/private-repositories/github.mdx (97%) rename versioned_docs/{version-1.37 => version-1.49}/admin/private-repositories/ssh-key.mdx (91%) rename versioned_docs/{version-1.37 => version-1.49}/admin/registry-credentials/amazon-ecr.mdx (97%) rename versioned_docs/{version-1.37 => version-1.49}/admin/registry-credentials/azure-acr.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/admin/registry-credentials/dockerhub.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/admin/registry-credentials/google-artifact-registry.mdx (94%) rename versioned_docs/{version-1.37 => version-1.49}/admin/registry-credentials/index.mdx (67%) rename versioned_docs/{version-1.37 => version-1.49}/admin/resource-manager.mdx (91%) rename versioned_docs/{version-1.37 => version-1.49}/admin/ssh-known-hosts.mdx (97%) create mode 100644 versioned_docs/version-1.49/agentic/autonomous-workflows.mdx create mode 100644 versioned_docs/version-1.49/agentic/best-practices.mdx create mode 100644 versioned_docs/version-1.49/agentic/collaborative-workflows.mdx create mode 100644 versioned_docs/version-1.49/agentic/index.mdx rename versioned_docs/{version-1.37 => version-1.49}/archived-release-notes.mdx (64%) create mode 100644 versioned_docs/version-1.49/byoc-vs-self-hosted.mdx rename versioned_docs/{version-1.37 => version-1.49}/byoc/aws/index.mdx (80%) rename versioned_docs/{version-1.37 => version-1.49}/byoc/gcp/index.mdx (51%) create mode 100644 versioned_docs/version-1.49/byoc/index.mdx rename versioned_docs/{version-1.37 => version-1.49}/core/build-service.mdx (64%) rename versioned_docs/{version-1.37 => version-1.49}/core/container-registry.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/core/credentials/environment-variables.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/core/credentials/kubernetes-credentials.mdx (92%) rename versioned_docs/{version-1.37 => version-1.49}/core/credentials/personal-access-tokens.mdx (86%) create mode 100644 versioned_docs/version-1.49/core/divert.mdx rename versioned_docs/{version-1.37 => version-1.49}/core/endpoints/automatic-ssl.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/core/endpoints/private-endpoints.mdx (98%) create mode 100644 versioned_docs/version-1.49/core/index.mdx rename versioned_docs/{version-1.37 => version-1.49}/core/namespaces.mdx (94%) rename versioned_docs/{version-1.37 => version-1.49}/core/okteto-insights-dashboards.mdx (84%) rename versioned_docs/{version-1.37 => version-1.49}/core/okteto-manifest.mdx (96%) rename versioned_docs/{version-1.37 => version-1.49}/core/okteto-variables.mdx (88%) rename versioned_docs/{version-1.37 => version-1.49}/core/remote-execution.mdx (94%) rename versioned_docs/{version-1.37 => version-1.49}/core/use-volume-snapshots.mdx (67%) rename versioned_docs/{version-1.37 => version-1.49}/core/user-roles-and-permissions.mdx (66%) rename versioned_docs/{version-1.37 => version-1.49}/development/containers/file-sync/aspnetcore.mdx (98%) rename versioned_docs/{version-1.37 => version-1.49}/development/containers/file-sync/golang.mdx (97%) rename versioned_docs/{version-1.37 => version-1.49}/development/containers/file-sync/index.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/development/containers/file-sync/java.mdx (98%) rename versioned_docs/{version-1.37 => version-1.49}/development/containers/file-sync/node.mdx (98%) rename versioned_docs/{version-1.37 => version-1.49}/development/containers/file-sync/php.mdx (97%) rename versioned_docs/{version-1.37 => version-1.49}/development/containers/file-sync/python.mdx (96%) rename versioned_docs/{version-1.37 => version-1.49}/development/containers/file-sync/ruby.mdx (98%) rename versioned_docs/{version-1.37 => version-1.49}/development/containers/hybrid/frontend.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/development/containers/hybrid/index.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/development/containers/hybrid/java.mdx (99%) rename versioned_docs/{version-1.37 => version-1.49}/development/containers/index.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/development/deploy/deploy-from-catalog.mdx (80%) rename versioned_docs/{version-1.37 => version-1.49}/development/deploy/deploy-from-git.mdx (91%) rename versioned_docs/{version-1.37 => version-1.49}/development/deploy/develop-on-okteto-button.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/development/deploy/from-private-repositories.mdx (61%) rename versioned_docs/{version-1.37 => version-1.49}/development/deploy/index.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/development/images.mdx (100%) create mode 100644 versioned_docs/version-1.49/development/index.mdx create mode 100644 versioned_docs/version-1.49/development/using-divert.mdx rename versioned_docs/{version-1.37 => version-1.49}/development/using-okteto-cli.mdx (96%) rename versioned_docs/{version-1.37 => version-1.49}/get-started/advanced-commands-and-concepts.mdx (97%) rename versioned_docs/{version-1.37 => version-1.49}/get-started/deploy-your-app/build.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/get-started/deploy-your-app/dependencies.mdx (96%) rename versioned_docs/{version-1.37 => version-1.49}/get-started/deploy-your-app/deploy.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/get-started/deploy-your-app/endpoints.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/get-started/deploy-your-app/index.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/get-started/dev-quickstart.mdx (98%) rename versioned_docs/{version-1.37 => version-1.49}/get-started/install-okteto-cli.mdx (96%) rename versioned_docs/{version-1.37 => version-1.49}/get-started/install/amazon-eks.mdx (92%) rename versioned_docs/{version-1.37 => version-1.49}/get-started/install/civo.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/get-started/install/digitalocean-doks.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/get-started/install/google-gke.mdx (97%) rename versioned_docs/{version-1.37 => version-1.49}/get-started/install/index.mdx (90%) rename versioned_docs/{version-1.37 => version-1.49}/get-started/install/microsoft-aks.mdx (100%) create mode 100644 versioned_docs/version-1.49/get-started/install/nutanix-nkp.mdx rename versioned_docs/{version-1.37 => version-1.49}/get-started/install/openshift.mdx (97%) rename versioned_docs/{version-1.37 => version-1.49}/get-started/using-okteto-cli-and-dashboard.mdx (80%) rename versioned_docs/{version-1.37 => version-1.49}/index.md (52%) create mode 100644 versioned_docs/version-1.49/previews/index.mdx rename versioned_docs/{version-1.37 => version-1.49}/previews/using-github-actions.mdx (99%) rename versioned_docs/{version-1.37 => version-1.49}/previews/using-gitlab-cicd.mdx (50%) rename versioned_docs/{version-1.37 => version-1.49}/reference/docker-compose.mdx (61%) create mode 100644 versioned_docs/version-1.49/reference/faqs.mdx rename versioned_docs/{version-1.37 => version-1.49}/reference/feature-flags.mdx (79%) rename versioned_docs/{version-1.37 => version-1.49}/reference/file-synchronization.mdx (88%) create mode 100644 versioned_docs/version-1.49/reference/index.mdx create mode 100644 versioned_docs/version-1.49/reference/known-issues.mdx rename versioned_docs/{version-1.37 => version-1.49}/reference/manifest-migration.mdx (94%) rename versioned_docs/{version-1.37 => version-1.49}/reference/okteto-cli.mdx (92%) rename versioned_docs/{version-1.37 => version-1.49}/reference/okteto-manifest.mdx (81%) rename versioned_docs/{version-1.37 => version-1.49}/reference/ssh-server.mdx (96%) rename versioned_docs/{version-1.37 => version-1.49}/reference/supported-github-actions.mdx (100%) create mode 100644 versioned_docs/version-1.49/release-notes.mdx rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/aks/config.yaml (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/civo/config.yaml (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/digitalocean/config.yaml (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/digitalocean/marketplace.md (96%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/eks/config.yaml (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/gke/config.yaml (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/helm-configuration.mdx (76%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/index.mdx (84%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/auth/azure-ad.mdx (89%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/auth/bitbucket.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/auth/github.mdx (64%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/auth/gitlab.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/auth/google.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/auth/index.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/auth/okta.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/auth/openid-connect.mdx (66%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/auth/token.mdx (79%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/certificates/aws-acm.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/certificates/bring-your-own-certificate.mdx (61%) create mode 100644 versioned_docs/version-1.49/self-hosted/install/certificates/cert-manager.mdx rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/certificates/index.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/config.yaml (100%) create mode 100644 versioned_docs/version-1.49/self-hosted/install/divert/index.mdx create mode 100644 versioned_docs/version-1.49/self-hosted/install/divert/istio-installation.mdx create mode 100644 versioned_docs/version-1.49/self-hosted/install/divert/linkerd-installation.mdx rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/github.mdx (96%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/okteto-registry-storage/aws-s3-bucket.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/okteto-registry-storage/azure-storage-container.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/okteto-registry-storage/digitalocean-spaces.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/okteto-registry-storage/filesystem.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/okteto-registry-storage/google-cloud-storage.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/okteto-registry-storage/index.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/install/volume-snapshots.mdx (69%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/manage/air-gapped.mdx (86%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/manage/argocd.mdx (97%) create mode 100644 versioned_docs/version-1.49/self-hosted/manage/arm-support.mdx rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/manage/backup-restore.mdx (100%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/manage/buildkit-high-performance.mdx (51%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/manage/crds.mdx (86%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/manage/diagnostics.mdx (100%) create mode 100644 versioned_docs/version-1.49/self-hosted/manage/okteto-license.mdx create mode 100644 versioned_docs/version-1.49/self-hosted/manage/troubleshooting.mdx rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/manage/uninstall-okteto.mdx (98%) rename versioned_docs/{version-1.37 => version-1.49}/self-hosted/manage/upgrade.mdx (81%) rename versioned_docs/{version-1.37 => version-1.49}/testing/getting-started-test.mdx (99%) rename versioned_docs/{version-1.37 => version-1.49}/testing/index.mdx (86%) create mode 100644 versioned_docs/version-1.49/variables.json rename versioned_sidebars/{version-1.37-sidebars.json => version-1.49-sidebars.json} (87%) diff --git a/README.md b/README.md index d82fd374b..7fe50771d 100644 --- a/README.md +++ b/README.md @@ -119,7 +119,7 @@ Modify the `presets.docs.versions` section of [`docusaurus.config.js`](docusauru }, ``` -5. **Remove the oldest version entry** from the `versions` object (to maintain 12 versions total) +5. **Remove the oldest version entry** from the `versions` object. The object lists only the official version and the five versions before it, so its oldest entry is not the oldest version in `versions.json`. For example, when releasing `1.41`, remove the `'1.35'` entry. Versions in `versions.json` without an entry still build with the default label, path, and `unmaintained` banner. ### Step 4: Update netlify.toml Redirects @@ -232,7 +232,7 @@ For agents or scripts automating this process, here are the key parameters: - `current.path: '{NEXT_VERSION}'` - Add `'{NEW_VERSION}': { label: '{NEW_VERSION}', path: '/', banner: 'none' }` at top of versions - Change `'{PREV_VERSION}'` path from `'/'` to `'{PREV_VERSION}'` and banner from `'none'` to `'unmaintained'` - - Remove `'{OLDEST_VERSION}'` entry from versions + - Remove the oldest entry from versions, which is `NEW_VERSION - 6` (e.g., `'1.35'` when releasing `1.41`). This is not `{OLDEST_VERSION}`: the config lists only the official version and the five before it 4. **netlify.toml:** - Official redirect: `from = "/docs/{NEW_VERSION}/*"` - Unreleased redirect: `to = "/docs/{NEXT_VERSION}/:splat"` diff --git a/docusaurus.config.js b/docusaurus.config.js index 7b01828a5..5f7b35a45 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -368,21 +368,26 @@ module.exports = { editUrl: 'https://github.com/okteto/docs/edit/main', breadcrumbs: false, sidebarPath: require.resolve('./sidebars.js'), - lastVersion: '1.48', + lastVersion: '1.49', versions: { current: { // aka unreleased version in development // Remember to also update "unreleased" redirect if changing the value! - label: '1.49', - path: '1.49', + label: '1.50', + path: '1.50', }, - '1.48': { + '1.49': { // aka latest/official version // Remember to also update docs root redirect if changing the value! - label: '1.48', + label: '1.49', path: '/', banner: 'none', }, + '1.48': { + label: '1.48', + path: '1.48', + banner: 'unmaintained', + }, '1.47': { label: '1.47', path: '1.47', @@ -403,11 +408,6 @@ module.exports = { path: '1.44', banner: 'unmaintained', }, - '1.43': { - label: '1.43', - path: '1.43', - banner: 'unmaintained', - }, }, include: ['**/*.md', '**/*.mdx'], }, diff --git a/netlify.toml b/netlify.toml index e5a6cffa5..3a98046a2 100644 --- a/netlify.toml +++ b/netlify.toml @@ -643,17 +643,22 @@ # Redirect official version to docs root [[redirects]] - from = "/docs/1.48/*" + from = "/docs/1.49/*" to = "/docs/:splat" status = 301 # Redirect unreleased to "current" version [[redirects]] from = "/docs/unreleased/*" - to = "/docs/1.49/:splat" + to = "/docs/1.50/:splat" status = 302 # Redirect deprecated versions +[[redirects]] + from = "/docs/1.37/*" + to = "/docs/:splat" + status = 302 + [[redirects]] from = "/docs/1.36/*" to = "/docs/:splat" diff --git a/src/content/archived-release-notes.mdx b/src/content/archived-release-notes.mdx index acff9a089..0cabc5af8 100644 --- a/src/content/archived-release-notes.mdx +++ b/src/content/archived-release-notes.mdx @@ -7,6 +7,70 @@ id: archived-release-notes Here you can find the release notes for archived versions of Okteto. +## 1.37.3 + +21 November 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) + +### Bug Fixes + +- [Okteto CLI 3.12.3](https://github.com/okteto/okteto/releases/tag/3.12.3): Fixed a timeout error contacting with the SSH agent on remote deploys when some of the commands defined in the Okteto Manifest were performing SSH operations + +## 1.37.2 + +15 October 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) + +### Bug Fixes {#bug-fixes-1.37} + +- Fixed repository cloning failures with SSH host verification - Resolved conflicts between automatic SSH scanning and admin-configured known hosts that could cause deployment failures. + +## 1.37.1 + +7 October 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) + +### Improvements {#improvements-1.37.1} + +- Upgrade Redis to 8.2.2 to fix [CVE-2025-49844](https://www.wiz.io/blog/wiz-research-redis-rce-cve-2025-49844) + +## 1.37.0 + +1 October 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) + +### Breaking Changes {#breaking-changes-1.37} + +- Removed the dependency on the Bitnami Redis Helm chart. Okteto now ships its own Kubernetes templates to deploy Redis. As part of this change, the workload has been updated from a StatefulSet to a Deployment, and the available Redis configuration options [have been reduced and standardized](self-hosted/helm-configuration.mdx#redis). If you previously customized Redis using Bitnami-specific values, review and update your Helm values to align with the supported configuration before upgrading. +- We've changed the [default value of `pullAlways` to **false**](self-hosted/helm-configuration.mdx#pullalways) for pods deployed in Okteto-managed namespaces. This speeds up pod creation when images are already present on the node, while still allowing `pullAlways` to be explicitly enabled if needed + +### New Features {#new-features-1.37} + +- Added a centralized [Known Hosts feature to the Admin UI](admin/ssh-known-hosts.mdx) (Admin → Settings → Known Hosts). Admins can now pin trusted SSH host keys and disable automatic ssh-keyscan, ensuring secure, consistent cloning of repositories and submodules without custom runner images + +### Improvements {#improvements-1.37} + +- Improved error handling in the Okteto AI Agent UI for API errors and "Prompt too long" warnings +- Temporal rate limit (QPS exceeded) errors now return as "progressing" instead of failing immediately +- We've renamed AI Agent Fleets to Okteto AI throughout the product +- [Okteto CLI 3.12.0](https://github.com/okteto/okteto/releases/tag/3.12.0): Updated Syncthing to 2.0.x for improved synchronization performance +- [Okteto CLI 3.12.0](https://github.com/okteto/okteto/releases/tag/3.12.0): Added support for `endpoint_mode` in Compose files ([see documentation](reference/docker-compose.mdx#endpoint_mode-string-optional)). + +### Bug Fixes {#bug-fixes-1.37} + +- Fixed issues with endpoint handling in the Okteto AI Agent view, including non-scrollable lists and incorrect display of custom endpoints +- Fixed an "unable to load agent" error when returning focus to the window +- Fixed autoscroll behavior when sending a new prompt in the Agent UI +- [Okteto CLI 3.12.0](https://github.com/okteto/okteto/pull/4760): Improved CLI stability by waiting for SSE when streaming logs for pipeline, preview, deploy, and destroy operations + ## 1.36.2 12 September 2025 diff --git a/src/content/release-notes.mdx b/src/content/release-notes.mdx index fd31fd05a..2d572508e 100644 --- a/src/content/release-notes.mdx +++ b/src/content/release-notes.mdx @@ -9,10 +9,10 @@ import Image from '@theme/Image'; ## 1.49.0 -9 October 2026 +8 October 2026 This version is compatible with Kubernetes versions 1.34 to 1.36 \ -Okteto Chart release 1.49 is designed to work with [Okteto CLI 3.24.x](https://github.com/okteto/okteto/releases) +Okteto Chart release 1.49 is designed to work with [Okteto CLI 3.24.x](https://github.com/okteto/okteto/releases/tag/3.24.0) ### Breaking Changes {#breaking-changes-1.49} @@ -26,14 +26,13 @@ Okteto Chart release 1.49 is designed to work with [Okteto CLI 3.24.x](https://g ### New Features {#new-features-1.49} -- You can now configure the default [compression](https://docs.docker.com/build/exporters/#compression) used by BuildKit at instance level using the helm setting `buildOpts` or the admin variables `OKTETO_BUILD_COMPRESSION`, `OKTETO_BUILD_COMPRESSION_LEVEL` and `OKTETO_BUILD_FORCE_COMPRESSION`. You can define the variables per operation using User Variables or Deployment Variables +- You can now configure the default [compression](https://docs.docker.com/build/exporters/#compression) used by BuildKit at instance level using the [`buildOpts`](self-hosted/helm-configuration.mdx#buildopts) Helm setting or the [Admin Variables](reference/feature-flags.mdx) `OKTETO_BUILD_COMPRESSION`, `OKTETO_BUILD_COMPRESSION_LEVEL` and `OKTETO_BUILD_FORCE_COMPRESSION`. You can define the variables per operation using User Variables or Deployment Variables - **Kubernetes 1.36 Support**: Added support for Kubernetes [1.36](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.36.md) ### Improvements {#improvements-1.49} - OpenID Connect now returns a clear error when different users from the [authentication provider](self-hosted/install/auth/openid-connect.mdx) map to the same Okteto user - ## 1.48.1 10 September 2026 @@ -407,67 +406,3 @@ Okteto Chart release 1.38 is designed to work with [Okteto CLI 3.13.x](https://g - [Okteto CLI 3.13.0](https://github.com/okteto/okteto/releases/tag/3.13.0): Fixed nil pointer exception in build command when the specified Dockerfile doesn't exist - [Okteto CLI 3.13.0](https://github.com/okteto/okteto/releases/tag/3.13.0): Improved error handling in log streaming during resource destruction as logs were not being fully displayed - [Okteto CLI 3.13.0](https://github.com/okteto/okteto/releases/tag/3.13.0): Fixed cache isolation in `okteto test` where different test containers sharing the same cached directory could reuse each other's cache. Caches are now properly isolated and only reused across executions of the same test container - -## 1.37.3 - -21 November 2025 - -This version is compatible with Kubernetes versions 1.31 to 1.33 \ -Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) - -### Bug Fixes - -- [Okteto CLI 3.12.3](https://github.com/okteto/okteto/releases/tag/3.12.3): Fixed a timeout error contacting with the SSH agent on remote deploys when some of the commands defined in the Okteto Manifest were performing SSH operations - -## 1.37.2 - -15 October 2025 - -This version is compatible with Kubernetes versions 1.31 to 1.33 \ -Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) - -### Bug Fixes {#bug-fixes-1.37} - -- Fixed repository cloning failures with SSH host verification - Resolved conflicts between automatic SSH scanning and admin-configured known hosts that could cause deployment failures. - -## 1.37.1 - -7 October 2025 - -This version is compatible with Kubernetes versions 1.31 to 1.33 \ -Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) - -### Improvements {#improvements-1.37.1} - -- Upgrade Redis to 8.2.2 to fix [CVE-2025-49844](https://www.wiz.io/blog/wiz-research-redis-rce-cve-2025-49844) - -## 1.37.0 - -1 October 2025 - -This version is compatible with Kubernetes versions 1.31 to 1.33 \ -Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) - -### Breaking Changes {#breaking-changes-1.37} - -- Removed the dependency on the Bitnami Redis Helm chart. Okteto now ships its own Kubernetes templates to deploy Redis. As part of this change, the workload has been updated from a StatefulSet to a Deployment, and the available Redis configuration options [have been reduced and standardized](self-hosted/helm-configuration.mdx#redis). If you previously customized Redis using Bitnami-specific values, review and update your Helm values to align with the supported configuration before upgrading. -- We've changed the [default value of `pullAlways` to **false**](self-hosted/helm-configuration.mdx#pullalways) for pods deployed in Okteto-managed namespaces. This speeds up pod creation when images are already present on the node, while still allowing `pullAlways` to be explicitly enabled if needed - -### New Features {#new-features-1.37} - -- Added a centralized [Known Hosts feature to the Admin UI](admin/ssh-known-hosts.mdx) (Admin → Settings → Known Hosts). Admins can now pin trusted SSH host keys and disable automatic ssh-keyscan, ensuring secure, consistent cloning of repositories and submodules without custom runner images - -### Improvements {#improvements-1.37} - -- Improved error handling in the Okteto AI Agent UI for API errors and "Prompt too long" warnings -- Temporal rate limit (QPS exceeded) errors now return as "progressing" instead of failing immediately -- We've renamed AI Agent Fleets to Okteto AI throughout the product -- [Okteto CLI 3.12.0](https://github.com/okteto/okteto/releases/tag/3.12.0): Updated Syncthing to 2.0.x for improved synchronization performance -- [Okteto CLI 3.12.0](https://github.com/okteto/okteto/releases/tag/3.12.0): Added support for `endpoint_mode` in Compose files ([see documentation](reference/docker-compose.mdx#endpoint_mode-string-optional)). - -### Bug Fixes {#bug-fixes-1.37} - -- Fixed issues with endpoint handling in the Okteto AI Agent view, including non-scrollable lists and incorrect display of custom endpoints -- Fixed an "unable to load agent" error when returning focus to the window -- Fixed autoscroll behavior when sending a new prompt in the Agent UI -- [Okteto CLI 3.12.0](https://github.com/okteto/okteto/pull/4760): Improved CLI stability by waiting for SSE when streaming logs for pipeline, preview, deploy, and destroy operations diff --git a/src/pages/archives.md b/src/pages/archives.md index a510a1522..162058fe8 100644 --- a/src/pages/archives.md +++ b/src/pages/archives.md @@ -13,7 +13,7 @@ Here you can find the documentation for the current released version of Okteto. | Version | Documentation | Release Notes | | :------ | :----------------: | -------------------------------: | -| 1.48 | [Documentation](/) | [Release Notes](/release-notes/) | +| 1.49 | [Documentation](/) | [Release Notes](/release-notes/) | ## Previously released versions @@ -21,6 +21,7 @@ Here you can find the documentation for previously released versions of Okteto. | Version | Documentation | Release Notes | | :------ | :--------------------: | ---------------------------------------------------: | +| 1.48 | [Documentation](pathname:///1.48) | [Release Notes](/1.48/release-notes/) | | 1.47 | [Documentation](pathname:///1.47) | [Release Notes](/1.47/release-notes/) | | 1.46 | [Documentation](pathname:///1.46) | [Release Notes](/1.46/release-notes/) | | 1.45 | [Documentation](pathname:///1.45) | [Release Notes](/1.45/release-notes/) | @@ -31,6 +32,5 @@ Here you can find the documentation for previously released versions of Okteto. | 1.40 | [Documentation](pathname:///1.40) | [Release Notes](/1.40/release-notes/) | | 1.39 | [Documentation](pathname:///1.39) | [Release Notes](/1.39/release-notes/) | | 1.38 | [Documentation](pathname:///1.38) | [Release Notes](/1.38/release-notes/) | -| 1.37 | [Documentation](pathname:///1.37) | [Release Notes](/1.37/release-notes/) | Release notes for previous versions can be found here: [Archived Release Notes](/archived-release-notes/) diff --git a/versioned_docs/version-1.37/byoc/index.mdx b/versioned_docs/version-1.37/byoc/index.mdx deleted file mode 100644 index e8c62beaf..000000000 --- a/versioned_docs/version-1.37/byoc/index.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Okteto Bring Your Own Cloud (BYOC) -description: Introduction to Okteto Bring Your Own Cloud (BYOC) ---- - -Okteto’s Bring Your Own Cloud (BYOC) offering allows you to run Okteto on your own cloud infrastructure while still enjoying the benefits of a fully managed experience. - -This is ideal for teams who need to meet strict security or compliance requirements, operate at high-scale, require custom infrastructure configurations, or simply want to maintain full control over their environments with a SaaS-like experience. - -We currently support BYOC on: - -- [**Amazon Web Services (AWS)**](byoc/aws/index.mdx) -- [**Google Cloud Platform (GCP)**](byoc/gcp/index.mdx) - -## How the BYOC Model Works - -With BYOC, you bring the cloud provider account; we bring the platform and operational expertise. - -- You provision and secure the cloud account -- Okteto creates the all the necessary cloud infrastructure and software components -- Our team manages and maintains Okteto on your cloud, including upgrades, monitoring, and incident response -- You retain full ownership of your cloud environment and data - -## 🤝 What You Can Expect from Okteto - -When you connect your cloud to Okteto: - -- Okteto installs and manages its components in your cloud -- Our team handles upgrades, patching, and observability of Okteto services -- You retain full control of your cluster and data, Okteto only interacts with workloads required for our platform to function -- Continuous monitoring and observability of Okteto services -- Support and guidance is provided by our team throughout your journey -- We encourage you to install your own tools, but please consult with Okteto first as those may be reverted automatically and/or cause service degradation - - -Ready to get started? Head to the BYOC Onboarding Guide for your cloud provider: - -- [**Amazon Web Services (AWS)**](byoc/aws/index.mdx) -- [**Google Cloud Platform (GCP)**](byoc/gcp/index.mdx) \ No newline at end of file diff --git a/versioned_docs/version-1.37/development/index.mdx b/versioned_docs/version-1.37/development/index.mdx deleted file mode 100644 index e2e405dba..000000000 --- a/versioned_docs/version-1.37/development/index.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Development Environments -description: In this section, we'll see how you can use Development Environments on Okteto ---- - -Development Environments enable developers to develop applications on Kubernetes with a joyful development experience. -Developers write code locally on their machine with the tools they love, and Okteto transparently updates their application on Kubernetes **in real-time as they code**! - -Developers don't have to spend time configuring and deploying their applications. -Everything is pre-configured in the [Okteto Manifest](core/okteto-manifest.mdx). -This way developers spend less time troubleshooting your development environment and more time coding cool features for their users 😎 - -In this section you will learn about: - -- Using the [Okteto CLI](development/using-okteto-cli.mdx) -- Configure [Development Containers](development/containers/index.mdx) to hot reload and debug your application on Okteto -- Customize your [development images](development/images.mdx) for a better developer experience -- Learn more about different ways to [deploy](development/deploy/index.mdx) your Development Environments diff --git a/versioned_docs/version-1.37/okteto-ai/ai-getting-started.mdx b/versioned_docs/version-1.37/okteto-ai/ai-getting-started.mdx deleted file mode 100644 index 954f5f63c..000000000 --- a/versioned_docs/version-1.37/okteto-ai/ai-getting-started.mdx +++ /dev/null @@ -1,268 +0,0 @@ ---- -title: Okteto AI - Getting Started -description: This guide will help you get up and running quickly with AI-powered development agents in your Okteto environments -sidebar_label: Getting Started -id: ai-getting-started ---- - -Welcome to Okteto AI! This guide will help you get up and running quickly with AI-powered development agents in your Okteto environments. - -## 📋 Prerequisites - -Before you begin: -- ✅ Your administrator has enabled Okteto AI for your organization -- ✅ You have access to the Okteto Dashboard -- ✅ You can see the **Agents** tab in your dashboard - -Don't see the Agents tab? Contact your administrator to request access. - -## 🚀 Your First Agent in 3 Minutes - -### Step 1: Open the Agents Tab -Navigate to the **Agents** tab in your Okteto Dashboard. - -### Step 2: Choose Your Starting Point - -You have two options: - -#### Option A: Work with an Existing Repository -- Paste your repository URL (e.g., `https://github.com/yourorg/yourrepo`) -- The agent will clone and analyze your codebase -- Perfect for adding features or fixing bugs - -#### Option B: Start Fresh -- Select "New Project" -- Describe what you want to build -- The agent will create everything from scratch - -### Step 3: Describe Your Task - -Write a clear, specific prompt. For example: - -``` -Create a Python FastAPI application with: -- User registration endpoint with email validation -- Login endpoint returning JWT tokens -- PostgreSQL database with SQLAlchemy -- Automated tests for all endpoints -``` - -### Step 4: Launch and Monitor - -1. Press **Enter** or click **Launch Agent** -2. Watch the real-time logs as your agent: - - Sets up the environment - - Installs dependencies - - Writes code - - Runs tests - - Validates the implementation -3. Click on **Open Editor** to view an embedded Visual Studio Code where you can monitor and audit all code changes - -### Step 5: Review and Deploy - -Once complete: -- **Preview**: Click any generated endpoints to see your app live -- **Review**: Check the code changes and test results -- **Accept**: Just ask the agent to create a pull request - -## 💡 Quick Tips for Success - -### Writing Effective Prompts - -**Do This ✅** -``` -"Add a REST endpoint at /api/users/:id/avatar that accepts -image uploads (JPEG/PNG only, max 5MB), resizes to 200x200, -stores in S3, and returns the CDN URL" -``` - -**Not This ❌** -``` -"Add image upload" -``` - -### Common First Tasks - -Start with these proven scenarios: - -1. **Add an API Endpoint** - ``` - Add a health check endpoint at /health that returns - server status, database connectivity, and uptime - ``` - -2. **Create a New Service** - ``` - Create a Node.js microservice for sending emails with - SendGrid, including templates and retry logic - ``` - -3. **Fix a Bug** - ``` - Debug why the user authentication is failing with - 401 errors after 15 minutes and implement a fix - ``` - -4. **Add Tests** - ``` - Write comprehensive unit tests for the OrderService - class with at least 80% coverage - ``` - -## 📖 Download the Complete Prompt Guide - -Want to master Okteto AI? Download our comprehensive prompt guide with: -- The 5-pillar framework that transforms frustrating AI interactions into -production-ready solutions -- Advanced techniques for complex tasks - -**[📥 Download the Okteto AI Prompt Guide (PDF)](https://okteto.link/4mTWk1e)** - -## 🎯 Best Practices - -### 1. Start Small, Think Big -- Begin with simple, well-defined tasks -- Build confidence with successful completions -- Gradually increase complexity - -### 2. Provide Context -Good prompts include: -- **What**: The specific feature or fix needed -- **Where**: Relevant files, endpoints, or services -- **How**: Technical requirements or constraints -- **Why**: Business logic or user needs (when relevant) - -### 3. Leverage Parallel Agents -Run multiple agents simultaneously: -- Agent 1: Adding new features to the frontend -- Agent 2: Optimizing database queries -- Agent 3: Writing documentation - -### 4. Review Before Merging -Always: -- Run the preview environment -- Check test results -- Review code for security and best practices -- Validate against your requirements - -### 5. Iterate and Refine -If the first result isn't perfect: -- Provide specific feedback -- Ask for modifications -- Guide the agent with additional context - -## 🔧 Common Workflows - -### Feature Development Workflow - -1. **Describe the feature** with acceptance criteria -2. **Let agent implement** the initial version -3. **Test in preview** environment -4. **Request adjustments** if needed -5. **Create PR** when satisfied - -### Bug Fixing Workflow - -1. **Describe symptoms** and error messages -2. **Let agent investigate** and propose fix -3. **Verify fix** in preview environment -4. **Run regression tests** -5. **Deploy fix** via PR - -### Refactoring Workflow - -1. **Specify refactoring goals** (performance, readability, etc.) -2. **Define constraints** (maintain API compatibility, etc.) -3. **Review changes** carefully -4. **Validate** all tests still pass -5. **Deploy incrementally** - -## 🚨 When to Use Okteto AI - -### Perfect For ✅ -- CRUD operations -- API endpoints -- Data transformations -- Test writing -- Bug fixes with clear symptoms -- Documentation updates -- Boilerplate code -- Database migrations - -### Think Twice About 🤔 -- Core authentication/authorization logic -- Payment processing -- Complex architectural decisions -- Cryptographic implementations -- Performance-critical algorithms - -### Not Recommended For ❌ -- Production secrets/credentials -- Regulatory compliance code (without review) -- Mission-critical security features (without expert review) - - -## 🔍 Understanding Agent Capabilities - -AI Agents can: -- ✅ Read and understand your entire codebase -- ✅ Install packages and dependencies -- ✅ Create new files and modify existing ones -- ✅ Run commands and scripts -- ✅ Execute and debug tests -- ✅ Access [Okteto environment variables](core/okteto-variables.mdx) and configs -- ✅ Interact with databases -- ✅ Call external APIs -- ✅ Generate comprehensive documentation - -AI Agents cannot: -- ❌ Access production environments -- ❌ Bypass your CI/CD pipeline -- ❌ Merge code without approval -- ❌ Access secrets not provided to the environment -- ❌ Modify Okteto platform settings - - - -## 🆘 Quick Troubleshooting - -### Agent is taking too long -- Break complex tasks into smaller steps -- Provide more specific instructions -- Check to see if your environment is running low on resources - -### Agent doesn't understand my codebase -- Ensure repository is accessible -- Provide context about architecture -- Reference specific files/patterns - -### Tests are failing -- Specify test requirements clearly -- Provide example test cases -- Check environment dependencies - -### Can't see preview environment -- Wait for deployment to complete -- Check service health endpoints -- Verify port configurations - -## 💬 Get Help - -- **Documentation**: [Full Okteto AI Docs](okteto-ai/index.mdx) -- **Support**: support@okteto.com -- **Community**: [Join the Okteto Community](https://community.okteto.com/) - -## 🚀 What's Next? - -Now that you're familiar with the basics: - -1. **Download the [Prompt Guide](https://okteto.link/4mTWk1e)** for advanced techniques -2. **Try the examples** in your test environment -3. **Join the community** to share tips and learn from others -4. **Experiment** with parallel agents for complex projects - -Ready to accelerate your development? Launch your first agent now! - ---- - -**Pro Tip**: Keep this guide bookmarked and refer to the prompt guide for specific use cases. The more specific your prompts, the better your results! \ No newline at end of file diff --git a/versioned_docs/version-1.37/okteto-ai/index.mdx b/versioned_docs/version-1.37/okteto-ai/index.mdx deleted file mode 100644 index 07a949ba1..000000000 --- a/versioned_docs/version-1.37/okteto-ai/index.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Okteto AI -description: Create a preview environment for your application using Okteto ---- - -Okteto AI is Okteto's orchestration layer for running multiple AI agents inside Okteto's isolated, ephemeral development environments. Powered by Claude Code from Anthropic, each agent operates independently with its own container, filesystem, logs, and access policies, ensuring safe, observable, and reproducible workflows for modern software development. - -Whether you're adding a new feature to your application, spinning up a new project, or exploring multiple features in parallel, Okteto AI lets you move faster without compromising on safety or control. - -> **Beta Notice:** Okteto AI is currently in beta. If you don't yet have access, you can request to be added to our Beta by visiting [okteto.com/ai](https://www.okteto.com/ai). - - -## What is Okteto AI? - -Okteto AI enables you to run a fleet of AI agents in parallel, each working independently on different tasks. An Okteto Agent is a Claude Code-powered assistant that can write, modify, test, and debug code inside an Okteto development environment. Unlike traditional AI coding assistants, these agents have full access to a real, containerized development environment where they can perform independent tasks such as: - -- **Repository Onboarding**: Understanding existing codebases, analyzing architecture, and preparing to work with your specific tech stack -- **Application Scaffolding**: Creating new services, APIs, or full applications from natural language descriptions -- **Feature Development**: Adding new functionality, endpoints, or UI components -- **Code Refactoring**: Modernizing legacy code, improving performance, or updating to new patterns -- **Bug Fixing**: Identifying and resolving issues with full context of your environment -- **Test Writing**: Creating comprehensive test suites for existing or new code -- **Documentation**: Generating or updating technical documentation, READMEs, and API specs - -Each agent runs inside its own Kubernetes namespace, backed by Okteto’s dev environment stack. This gives you: -- **Full isolation**: Agents don’t share state or files unless explicitly configured -- **Production-like environment**: Access to the same runtime, secrets, and configuration as your real dev setup -- **Test-first execution**: Agents run tests, validate changes, and generate logs before making pull requests -- **No local dependencies**: Nothing is run or installed on your machine -- **Complete observability**: Full logs, metrics, and traces of all agent actions - - - -## 🚀 Getting Started - -### For Administrators -Before team members can use Okteto AI, organization administrators must configure the feature. See the [Administrator Configuration Guide](okteto-ai/okteto-ai-admin-config.mdx) for detailed setup instructions. - -### For Developers - -Review our [**Okteto AI Getting Started Guide**](okteto-ai/ai-getting-started.mdx) - - -## Security and Isolation - -Each AI Agent runs in a sandboxed Namespace with limited access to only the resources it needs. All actions occur inside an ephemeral environment, with observability built in. This ensures safe experimentation and protects production environments. - - -## Example Use Cases - -- **Spin up a new service** from a prompt like: - _“Create a new TypeScript REST API with an /alive endpoint and a README”_ - -- **Refactor legacy code** with: - _“Update this repo to use async/await instead of callbacks”_ - -- **Add a feature in parallel** to existing work: - _“Add a banner to the homepage announcing the beta launch”_ - - -## FAQs - -**Can I run multiple agents at once?** -Yes! You can launch multiple agents in parallel, each working independently. - -**Do I need to install anything locally?** -No. Okteto handles everything in the cloud. You don't need Docker or Kubernetes installed. - -**Can I bring my own LLM key?** -Yes. You can optionally provide your own Anthropic LLM key in the agent settings if you want to use your own quota or a different provider. - -**Do you plan on adding support for additional LLM Providers?** -Yes! We plan on adding support for additional models based on your feedback in a coming release. - ---- - -## 📣 Feedback - -Okteto AI is currently in **beta**. To request access, visit [okteto.com/ai](https://www.okteto.com/ai). We welcome your feedback as we continue to improve the experience. \ No newline at end of file diff --git a/versioned_docs/version-1.37/okteto-ai/okteto-ai-admin-config.mdx b/versioned_docs/version-1.37/okteto-ai/okteto-ai-admin-config.mdx deleted file mode 100644 index abce41503..000000000 --- a/versioned_docs/version-1.37/okteto-ai/okteto-ai-admin-config.mdx +++ /dev/null @@ -1,220 +0,0 @@ ---- -title: Okteto AI - Admin Configuration Guide -description: In this section, we will show you how to configure Okteto AI for your team -sidebar_label: Admin Configuration Guide -id: okteto-ai-admin-config ---- - -import Image from "@theme/Image"; - -This guide covers the complete setup and configuration process for enabling Okteto AI in your Okteto organization. - -## Prerequisites -Before configuring Okteto AI, ensure you have: - -- Administrator access to your Okteto organization -- An API key from either Anthropic or AWS (for Amazon Bedrock) -- A Git token for repository integration (if not, we'll help you set one up) - -## Enabling Okteto AI for your organization - -### Step 1: Enable Okteto AI - -- From the Okteto Admin Dashboard, navigate to **Admin -> Okteto AI** underneath the Settings Section -- Toggle the Okteto AI switch to enable the feature for your organization - -

- Okteto AI Admin Dashboard -

- - -### Step 2: Configure Access Control - -Choose who can use Okteto AI in your organization: - -#### Option A: Enable for All Users - -- Select All users to grant access to everyone in your organization -- This is recommended for smaller teams or companies already familiar with the product - -#### Option B: Enable for Selected Users - -- Select `Selected users` -- Click the users view link to navigate to the user management tab -- Select the specific users who should have access to Okteto AI - -Note: Users without access will not see the Agents tab in their dashboard. - -### Step 4: Configure Your LLM Provider - -Okteto AI requires an LLM provider to power the Okteto Agents. Choose between Anthropic (direct) or via Amazon Bedrock. - -#### Option A: Anthropic Configuration -Use this option for direct integration with Anthropic's API. - -

- Okteto AI LLM Provider Configuration -

- -1. **Select Provider**: Choose **Anthropic** from the Provider dropdown -2. Obtain API Key: - - Click the "Get your Anthropic API key →" link - - Sign in to your [Anthropic account](https://console.anthropic.com/) (or create one) - - Navigate to [API Keys section](https://console.anthropic.com/settings/keys) - - Create a new API key with appropriate permissions - - Copy the key - -3. **Enter API Key**: Click Update and paste your Anthropic API key in the field -4. **Save Configuration**: Click Save to save your settings - -#### Option B: Amazon Bedrock Configuration -Use this option if your organization prefers AWS-managed AI services. - -

- Okteto AI LLM Provider Configuration for Bedrock -

- -1. **Select Provider**: Choose **Amazon Bedrock** from the Provider dropdown -2. **Configure Region**: - - Select the AWS region where you have Bedrock enabled - - Common regions: `us-east-1`, `us-west-2`, `eu-west-1` - - Ensure Claude models are available in your selected region - -3. **Set Up AWS Credentials**: - - Click "[Get your Bedrock API key →](https://aws.amazon.com/es/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)" for instructions on retrieving your API key - - Generate and copy your API key - - -4. **Enter Credentials**: Back in the Okteto Admin Dashboard, add your AWS credentials in the API Key field -5. **Save Configuration**: Click Save to complete the configuration - -### Step 5: Configure LLM Model -The LLM Model section shows which Claude model is being used: -- Currently, agents use Claude Sonnet 4, optimized for software development tasks -- This model provides the best balance of speed and capability for code generation -- Additional models will be available in future releases - -:::note -Note: The model selection is currently managed by Okteto to ensure optimal performance. Custom model selection will be added in a future update. -::: - -### Step 6: Set Up Git Integration -Configure Git integration to enable agents to clone private git repositories: - -1. **Generate Token**: - - Click "Generate a new GitHub token →" - - You'll be redirected to GitHub (or continue to your Git provider) - - Create a token with these permissions: - - repo (full repository access) - - workflow (Update GitHub Action workflows) - - read:user (read user profile) - - -2. **Configure Token**: -- Copy the generated token from your git provider -- Click on Configure (Update if you previously had one configured) and paste it in the Git Token field -- Click on save - -**Supported Git Providers**: -- GitHub -- GitLab -- Bitbucket (coming soon) - - -### Step 7: Verify Configuration -After completing setup: - -1. Launch Test Agent: -- Create a simple test agent to verify full functionality -- Example: "Create a hello world Python script" - - -2. Check User Access: -- Verify the Agents tab appears for authorized users - - -## Configuration Best Practices -### API Key Management -- Rotate keys regularly: Change API keys every 90 days -- Use separate keys: Don't share keys between environments -- Monitor usage: Track token consumption and costs -- Set alerts: Configure notifications for high usage patterns in Anthropic - -### Access Control - -- Start small: Begin with selected users during initial rollout -- Train users: Provide guidelines before granting access -- Review regularly: Audit user access monthly -- Document policies: Create clear usage guidelines - -## Cost Management -### For Anthropic Direct: - -- Monitor token usage in your Anthropic dashboard -- Set spending limits if available -- Consider prepaid credits for predictable costs - -### For Amazon Bedrock: - -- Use AWS Cost Explorer to track Bedrock usage -- Set up AWS Budgets for cost alerts -- Consider Reserved Capacity for consistent workloads - -## Troubleshooting -### Common Issues - -**Users Can't See Agents Tab** - -- Confirm user is in selected users list -- Have user log out and back in -- Clear browser cache - -**Git Integration Not Working** - -- Verify token has correct permissions -- Check token hasn't expired -- Ensure repository access is configured -- Ensure you are using one of the supported providers (GitHub or GitLab) - -## Getting Help - -- Contact support at support@okteto.com -- Join Okteto Community for discussions - -## Security Considerations -### API Key Security - -- Store API keys that you wish to share with Agents securely using Okteto's [Admin Variables](admin/dashboard.mdx#admin-variables) -- Never share API keys in code or documentation -- Use environment-specific keys (dev, staging, prod) -- Enable API key access logs where available - - -### Compliance - -- Review your organization's AI usage policies -- Ensure compliance with data residency requirements -- Document AI usage for audit purposes -- Consider GDPR/CCPA implications for generated code - - - -### Next Steps -After configuration: - -Create Usage Guidelines: Document best practices for your team -Run Training Sessions: Help users understand effective prompting -Plan Rollout: Phase adoption across teams -Gather Feedback: Create channels for user feedback \ No newline at end of file diff --git a/versioned_docs/version-1.37/previews/index.mdx b/versioned_docs/version-1.37/previews/index.mdx deleted file mode 100644 index 5731951bf..000000000 --- a/versioned_docs/version-1.37/previews/index.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Preview Environments -description: Create a preview environment for your application using Okteto ---- - -import Image from "@theme/Image"; - -Preview environments allow you to include a live preview of your changes on every pull request. This is a fantastic way to collaborate with your team's technical, as well as non-technical members, to receive early feedback. - -

- Preview Environments -

- -Okteto's preview environments are powered by Kubernetes and easily integrate with your favorite source control and CI/CD provider. They work using the [Okteto manifest](core/okteto-manifest.mdx), so are very simple to get started with. - -To unlock the full potential of Okteto Preview Environments, you can also combine it with our [testing infrastructure](reference/okteto-cli.mdx#test) and run integration test against your environments. - -- [GitHub](previews/using-github-actions.mdx) -- [GitLab](previews/using-gitlab-cicd.mdx) -- Bitbucket Pipelines (coming soon!) -- Azure DevOps (coming soon!) - -## Prerequisites - -Preview environments deploy the code in a pull request to [Okteto](index.md). You can configure the way your code gets deployed using the [Okteto manifest](core/okteto-manifest.mdx)'s `deploy` section. diff --git a/versioned_docs/version-1.37/reference/faqs.mdx b/versioned_docs/version-1.37/reference/faqs.mdx deleted file mode 100644 index 485f6aca4..000000000 --- a/versioned_docs/version-1.37/reference/faqs.mdx +++ /dev/null @@ -1,164 +0,0 @@ ---- -title: Frequently Asked Questions (FAQs) -description: Frequently asked questions about Okteto -sidebar_label: FAQs -id: faqs ---- - -## Can I use Okteto CLI with Minikube? - -Yes. Okteto CLI accelerates your development workflow regardless of where your Kubernetes cluster is running. - -If you can run `kubectl apply`, you can benefit from Okteto CLI. - -For Minikube, k3s, or similar local Kubernetes distributions, you can directly use our [open source project](https://github.com/okteto/okteto). For shared remote clusters, we recommend you take a look at [Okteto](https://okteto.com/) to handle credential management, namespace isolation, integration with GitHub among other things. - -## Why is Okteto better than traditional development? - -Among the many advantages, Okteto allows developers to: - -- Reduce local setup and eliminate integration issues by developing the same way your application runs in production -- Test your application as fast as you type code, without needing to use `docker` or `kubectl` in your inner loop cycle -- No more CPU cycles wasted in your machine. Hardware and network just limited by the power of the cloud -- Your development endpoints are always available. No need to expose your local machine to the internet through remote tunnels - -## How is Okteto different from other tools like Skaffold? - -Skaffold automates the workflow for building, pushing, and deploying your application. You iterate on your application source code locally and then deploy to local or remote Kubernetes clusters. - -Okteto's philosophy is to move development entirely to Kubernetes. The Skaffold pipeline, even though automated, is still slow. With Okteto, you code locally in your favorite IDE and Okteto automatically synchronizes your changes to your remote development environment. No commit, build, push, or deploy required. - -The main differences from tools like Skaffold are: - -- Okteto decouples deployment from development. You can deploy your application with `kubectl`, `Helm`, a serverless framework or even a CI job and use Okteto later to develop any component of your application -- Use any docker image as your remote development environment, with your favorite tools. Okteto doesn't require you to change the way you build, debug, or deploy your applications. Since builds are executed in your remote development environment, you benefit from fast incremental builds, hot reloaders, or the dependency caching offered by your programming language. Native builds are always faster than building images and redeploying containers -- You can integrate Okteto with your local IDE remote plugins, making it possible to execute your favorite IDE extensions and debuggers as you develop your application directly in Kubernetes -- Okteto provides bidirectional synchronization. For example, you can execute package managers like `npm` or `pip` in your remote development environment and the changes are synchronized back to your local file system - -## Is Okteto compatible with Flux/ArgoCD? - -Okteto decouples deployment from development, making it possible to use it with tools like Flux or ArgoCD. - -We recommend you to stop the Flux/ArgoCD reconciliation loop while running `okteto up`. For example, add this field to your Okteto Manifest to stop the Flux reconciliation loop: - -```yaml -annotations: - fluxcd.io/ignore: "true" -``` - -:::tip -Please see our [ArgoCD Configuration Guide](self-hosted/manage/argocd.mdx) for our full recommendation on deploying Okteto with ArgoCD -::: - - -## How to use private images? - -In order to use your private registry credentials, use the Okteto's built-in [Registry Credentials](/admin/registry-credentials/index.mdx) feature. - -## Why are my [Endpoints](core/endpoints/automatic-ssl.mdx) not present in the CLI or UI? - -Endpoint links are not present within Okteto if there are no services actively running. If your endpoints are missing, consider the following states and their implications: - -#### Progressing: -* Description: Your deployment is in the process of being rolled out -* Possible Causes: - * Your service is still being started - * Okteto is waiting for all healthchecks to pass - * There are pending updates or new deployments -* Actions: - * Wait for the deployment to complete - * Look at the events of the deployment for any issues - -#### Pulling: -* Description: The image for your deployment is in the process of being pulled -* Possible Causes: - * Your service is still being started -* Actions: - * Wait for the deployment to complete - * Look at the events of the deployment for any issues - -#### Booting: -* Description: Starting the containers for your deployment -* Possible Causes: - * All containers for your service are not yet ready -* Actions: - * Wait for all containers to finish starting and enter their ready state - * Look at the events of the deployment for any issues - -#### Running: -* Description: Your deployment is active, and the service should be running correctly -* Possible Causes: - * Network policies or firewall rules could be blocking the endpoint -* Actions: - * Verify the service annotations in your manifest to ensure `dev.okteto.com/auto-ingress: "true"` is present - * Verify your [Docker Compose endpoints](reference/docker-compose.mdx#endpoints-object-optional) are configured correctly - -#### Unschedulable: -* Description: At least one of the pods of your service cannot be scheduled. -* Possible Causes: - * You cluster doesn't have enough resources to allocate the pods - * Some of the pod tolerations are preventing the pods from being scheduled -* Actions: - * Check the events for the pods that belong to your service: `kubectl events --for pod/my-pod-1234 -n my-ns` - * Contact your cluster administrator and check if your cluster is at capacity - -#### Error: -* Description: There is an issue with your deployment preventing the service from running correctly -* Possible Causes: - * Errors in the application code or container image - * Misconfiguration in your service or deployment manifest - * Insufficient resources or quota limits in the cluster -* Actions: - * Check the logs of the affected service through the UI or with [`okteto logs`](reference/okteto-cli.mdx#logs) - * Validate the container image and configuration settings - * Ensure that resource requests and limits are properly set and the cluster has enough capacity - - -## Every time I make a change, tsc detects two changes: - -This is related to how syncthing interacts with `tsc`. Syncthing creates a temporary file and replaces the original file with the new one. - -To solve the problem you just add the flag `--synchronousWatchDirectory` to your `tsc` command. - -## I cannot connect to the Kubernetes cluster using the kubeconfig file generated by Okteto - -Starting with Okteto CLI version `2.20`, the kubeconfig file generated by Okteto uses a [credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins) to get the credentials for your Kubernetes clusters from your Okteto instance. It is a typical pattern used by many Kubernetes providers, such as Google Kubernetes Engine (GKE), Azure Kubernetes Service (AKS), or Amazon Elastic Kubernetes Service (EKS) to connect to Kubernetes clusters. - -We recommend you add the Okteto CLI to your PATH and run the 'okteto context' command to connect your CLI to your Okteto instance before executing the `okteto kubeconfig` command. You can also optionally download your Kubeconfig from the Okteto UI. Please refer to [our documentation](get-started/install-okteto-cli.mdx) for more information on this topic. - -Once you have the CLI installed you have to connect to your instance using the command `okteto context use https://okteto.example.com` as is described [here](get-started/install-okteto-cli.mdx). If you're not logged into Okteto yet, it will also run the login sequence. - -Once your Okteto context is configured to access Okteto, you should be able to connect to your Kubernetes cluster using the kubeconfig file generated by Okteto or generate a new one running [`okteto kubeconfig`](reference/okteto-cli.mdx#kubeconfig). - -You can also disable the usage of the credential plugin by setting the environment variable `OKTETO_USE_STATIC_KUBETOKEN` to `true` before running any Okteto command. Be aware that using those static tokens are not recommended by Kubernetes and you will start getting warnings in your `kubectl` output starting with Kubernetes version `1.27`. - -## How can I use the `--platform` flag with `okteto build`? - -With `okteto build --platform` you can specify the platform (or architecture) for which you'd like to build the container images. For example, you could use a multiplatform image and the `okteto build --platform` command to deploy your web application on a Kubernetes cluster that consists of nodes running on both x86-64 and ARMv7 architectures. -By using the multiplatform images built using this method, you can deploy the same images across the cluster without worrying about the underlying hardware differences. - -Let's consider an example where you have a Node.js application that you want to build and deploy on both x86_64 and ARM-based platforms. You have a Dockerfile in your project directory that defines the build process. -Here's how Okteto CLI can help you build multiplatform images for your application: - -1. Building the image for x86_64 architecture: - -```console -okteto build -f Dockerfile -t myapp:latest --platform linux/amd64 -``` - -2. Building the image for ARMv7 architecture: - -```console -okteto build -f Dockerfile -t myapp:latest --platform linux/arm/v7 -``` - -3. Building a multiarchitectural image: - -```console -okteto build -f Dockerfile -t myapp:latest --platform linux/amd64,linux/arm/v7 -``` - -This command builds a multi-architecture Docker image named `myapp` with the latest tag for both x86_64 and ARM platforms. - -By using these commands, you can easily build the application image for different platforms without needing to maintain separate Dockerfiles or perform manual modifications. -This is particularly useful when you want to deploy your application to heterogeneous environments where you have both x86_64 and ARM-based devices, such as a mixed-cluster Kubernetes setup. diff --git a/versioned_docs/version-1.37/reference/index.mdx b/versioned_docs/version-1.37/reference/index.mdx deleted file mode 100644 index fff2b48aa..000000000 --- a/versioned_docs/version-1.37/reference/index.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: References ---- - -import CardsList from "@theme/CardsList" - - diff --git a/versioned_docs/version-1.37/reference/known-issues.mdx b/versioned_docs/version-1.37/reference/known-issues.mdx deleted file mode 100644 index 402da5635..000000000 --- a/versioned_docs/version-1.37/reference/known-issues.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Known Issues -description: List of known issues -sidebar_label: Known Issues -id: known-issues ---- - -## Development environments do not hot-reload code changes - -If you are using a hot reloader in your development environment, it might happen that your hot reloader does not pick the code changes even when they are properly synchronized to your development environment. - -This is usually because the default *max watchers* value on your Kubernetes nodes is too low. To fix this issue, update the value of `/proc/sys/fs/inotify/max_user_watches` in all your Kubernetes nodes (we recommend the value `10048576`). - -For example, you can do it by running this command on each node: - -```console -$ sudo sysctl -w fs.inotify.max_user_watches=10048576 -``` - -[Okteto](https://okteto.com) uses a Daemon Set to apply this change automatically to every Kubernetes node. - -## The okteto prompt doesn't look right in Windows - -Okteto's remote prompt uses [ANSI escape sequences](https://devblogs.microsoft.com/commandline/whats-new-in-windows-console-in-windows-10-fall-creators-update/) to display the namespace and development environment name in different colors. - -If you're using PowerShell and the terminal looks funky, this feature might not enabled. Run the command below to enable ANSI Color globally: - -```console -Set-ItemProperty HKCU:\Console VirtualTerminalLevel -Type DWORD 1 -``` - -This [stackoverflow answer](https://stackoverflow.com/questions/51680709/colored-text-output-in-powershell-console-using-ansi-vt100-codes) has more information on this topic. diff --git a/versioned_docs/version-1.37/release-notes.mdx b/versioned_docs/version-1.37/release-notes.mdx deleted file mode 100644 index 36a9390d5..000000000 --- a/versioned_docs/version-1.37/release-notes.mdx +++ /dev/null @@ -1,599 +0,0 @@ ---- -title: Release notes -description: Release Notes -sidebar_label: Release notes -id: release-notes ---- - -## 1.37.3 - -21 November 2025 - -This version is compatible with Kubernetes versions 1.31 to 1.33 \ -Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) - -### Bug Fixes - -- [Okteto CLI 3.12.3](https://github.com/okteto/okteto/releases/tag/3.12.3): Fixed a timeout issue when contacting the SSH agent during remote deploys where commands in the Okteto Manifest performed SSH operations - -## 1.37.2 - -15 October 2025 - -This version is compatible with Kubernetes versions 1.31 to 1.33 \ -Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) - -### Bug Fixes {#bug-fixes-1.37} - -- Fixed repository cloning failures with SSH host verification - Resolved conflicts between automatic SSH scanning and admin-configured known hosts that could cause deployment failures. - -## 1.37.1 - -7 October 2025 - -This version is compatible with Kubernetes versions 1.31 to 1.33 \ -Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) - -### Improvements {#improvements-1.37.1} - -- Upgrade Redis to 8.2.2 to fix [CVE-2025-49844](https://www.wiz.io/blog/wiz-research-redis-rce-cve-2025-49844) - -## 1.37.0 - -1 October 2025 - -This version is compatible with Kubernetes versions 1.31 to 1.33 \ -Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) - -### Breaking Changes {#breaking-changes-1.37} - -- Removed the dependency on the Bitnami Redis Helm chart. Okteto now ships its own Kubernetes templates to deploy Redis. As part of this change, the workload has been updated from a StatefulSet to a Deployment, and the available Redis configuration options [have been reduced and standardized](self-hosted/helm-configuration.mdx#redis). If you previously customized Redis using Bitnami-specific values, review and update your Helm values to align with the supported configuration before upgrading. -- We've changed the [default value of `pullAlways` to **false**](self-hosted/helm-configuration.mdx#pullalways) for pods deployed in Okteto-managed namespaces. This speeds up pod creation when images are already present on the node, while still allowing `pullAlways` to be explicitly enabled if needed - -### New Features {#new-features-1.37} - -- Added a centralized [Known Hosts feature to the Admin UI](admin/ssh-known-hosts.mdx) (Admin → Settings → Known Hosts). Admins can now pin trusted SSH host keys and disable automatic ssh-keyscan, ensuring secure, consistent cloning of repositories and submodules without custom runner images - -### Improvements {#improvements-1.37} - -- Improved error handling in the Okteto AI Agent UI for API errors and "Prompt too long" warnings -- Temporal rate limit (QPS exceeded) errors now return as "progressing" instead of failing immediately -- We've renamed AI Agent Fleets to Okteto AI throughout the product -- [Okteto CLI 3.12.0](https://github.com/okteto/okteto/releases/tag/3.12.0): Updated Syncthing to 2.0.x for improved synchronization performance -- [Okteto CLI 3.12.0](https://github.com/okteto/okteto/releases/tag/3.12.0): Added support for `endpoint_mode` in Compose files ([see documentation](reference/docker-compose.mdx#endpoint_mode-string-optional)). - -### Bug Fixes {#bug-fixes-1.37} - -- Fixed issues with endpoint handling in the Okteto AI Agent view, including non-scrollable lists and incorrect display of custom endpoints -- Fixed an "unable to load agent" error when returning focus to the window -- Fixed autoscroll behavior when sending a new prompt in the Agent UI -- [Okteto CLI 3.12.0](https://github.com/okteto/okteto/pull/4760): Improved CLI stability by waiting for SSE when streaming logs for pipeline, preview, deploy, and destroy operations - -## 1.36.2 - -12 September 2025 - -This version is compatible with Kubernetes versions 1.31 to 1.33 \ -Okteto Chart release 1.36 is designed to work with [Okteto CLI 3.11.x](https://github.com/okteto/okteto/releases/tag/3.11.0) - -### Improvements - -- Improve Okteto UI UX by showing "Pulling" status when encountering transient pull QPS exceeded errors - -### Bug Fixes - -- Fixed an issue with Kubernetes credential configuration in the delete agent job -- Fixed a UI issue where the list of endpoints in the agent view was not scrollable - -## 1.36.1 - -9 September 2025 - -This version is compatible with Kubernetes versions 1.31 to 1.33 \ -Okteto Chart release 1.36 is designed to work with [Okteto CLI 3.11.x](https://github.com/okteto/okteto/releases/tag/3.11.0) - -### Bug Fixes -- Fixed an issue with streaming Okteto Agent installation logs that was preventing the agent chat from loading - -## 1.36.0 - -5 September 2025 - -This version is compatible with Kubernetes versions 1.31 to 1.33 \ -Okteto Chart release 1.36 is designed to work with [Okteto CLI 3.11.x](https://github.com/okteto/okteto/releases/tag/3.11.0) - -### [Okteto AI Now Available (Beta)](okteto-ai/index.mdx) -Okteto AI brings the power of AI directly into your development workflow, powered by Claude Code from Anthropic. Each agent operates independently in its own Kubernetes namespace with full isolation, giving you the safety and control you need for AI-assisted development. - -#### Key Capabilities - -- **Intelligent Repository Onboarding**: Agents can quickly understand and work with existing codebases, analyzing project structure, dependencies, and patterns to get up to speed faster than ever -- **Application Scaffolding**: Generate new services, APIs, and applications from natural language descriptions, complete with best practices and proper project structure -- **Task Automation**: Automate common development tasks like adding endpoints, refactoring code, updating dependencies, or implementing new features -- **Real Containerized Environments**: All agents run in production-like Kubernetes environments with access to the same runtime, secrets, and configurations as your actual development setup -- **Parallel Execution**: Launch multiple agents simultaneously to work on different features or experiments independently - -#### For Administrators -Organization administrators have [full control over Okteto AI deployment](okteto-ai/okteto-ai-admin-config.mdx): -- Enable the feature for your organization through the Admin Dashboard under Admin > Okteto AI -- Toggle access per user to control who can launch AI agents in your organization -- Configure LLM keys - Provide your own Anthropic API key (directly from Anthropic or via Amazon Bedrock) - -We're continuously improving Okteto AI based on your feedback. Try it today and let us know how it transforms your development workflow! - -### New Features {#new-features-1.36} - -- Added a [new Public API endpoint to delete users](admin/okteto-api.mdx) -- Added support for [configuring custom init containers](self-hosted/helm-configuration.mdx#installer) in the installer job -- Pre-pull Okteto images used by jobs to accelerate job start times. This deploys a new [DaemonSet in the cluster that pre-pulls images](self-hosted/helm-configuration.mdx#prepullimages ) onto nodes. - -### Improvements {#improvements-1.36} - -- Installer now retries transient connection issues -- [Okteto CLI 3.11.0](https://github.com/okteto/okteto/releases/tag/3.11.0): Added support for overriding the [`readOnlyRootFilesystem`](reference/okteto-manifest.mdx#securitycontext-object-optional) property in the `securityContext` of dev containers defined in the Okteto Manifest - -### Bug Fixes {#bug-fixes-1.36} - -- Fixed previews layout issue that could hide logs when breadcrumb is visible -- [Okteto CLI 3.11.0](https://github.com/okteto/okteto/releases/tag/3.11.0): Fixed a panic when deploying an Okteto manifest with Divert using `okteto up` or `okteto test` -- [Okteto CLI 3.11.0](https://github.com/okteto/okteto/releases/tag/3.11.0): Fixed an issue with the `--wait` flag in `okteto deploy` when deploying a subset of services from a Compose file. The command no longer hangs until timeout - -## 1.35.2 - -29 August 2025 - -This version is compatible with Kubernetes versions 1.31 to 1.33 \ -Okteto Chart release 1.35 is designed to work with [Okteto CLI 3.10.x](https://github.com/okteto/okteto/releases/tag/3.10.0) - -### Bug Fixes -- Downgrade BuildKit dependency to version `0.22.0` to avoid a bug that was causing a huge consumption in CPU, provoking poor performance and stuck builds. - -## 1.35.1 - -12 August 2025 - -This version is compatible with Kubernetes versions 1.31 to 1.33 \ -Okteto Chart release 1.35 is designed to work with [Okteto CLI 3.10.x](https://github.com/okteto/okteto/releases/tag/3.10.0) - -### Bug Fixes -- Fixed an issue in the daemonset which was causing the component to fail when the Okteto instance was not using self-signed certificates nor private CAs. - -## 1.35.0 - -1 August 2025 - -This version is compatible with Kubernetes versions 1.31 to 1.33 \ -Okteto Chart release 1.35 is designed to work with [Okteto CLI 3.10.x](https://github.com/okteto/okteto/releases/tag/3.10.0) - -### New Features {#new-features-1.35} -- Added support for [Kubernetes 1.33](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.33.md) (support for 1.30 has been removed) and [Amazon Linux 2023](https://github.com/amazonlinux/amazon-linux-2023). [Please follow our upgrade guide](self-hosted/manage/upgrade.mdx#upgrading-to-okteto-135x--kubernetes-133-support-and-amazon-linux-2023-al2023compatibility) when moving to Amazon Linux 2023 -- CIDR-based traffic filtering is now supported for BYOC (Bring Your Own Cluster) environments. Use this to improve security by restricting access to Okteto services to specific IP ranges. -- Namespace deletion now properly applies the timeout value to dev environments that use a `destroy` section in their manifest. Previously, if a dev environment took longer than 5 minutes to destroy gracefully, the overall namespace deletion would fail, even if a longer timeout was specified. -- Added support for `loadBalancerSourceRanges` in the BuildKit service configuration to better control external access -- [Okteto CLI 3.10.0](https://github.com/okteto/okteto/releases/tag/3.10.0): Okteto now supports inheriting Kubernetes `nodeSelector` and resource settings in Development Environments. When omitted from the `okteto.yaml` manifest, these values can be pulled from the base Kubernetes resources using the `OKTETO_INHERIT_KUBERNETES_RESOURCES` and `OKTETO_INHERIT_KUBERNETES_NODESELECTOR` feature flags. - -### Improvements {#improvements-1.35} -- [Okteto CLI 3.10.0](https://github.com/okteto/okteto/releases/tag/3.10.0): Improved the `okteto deploy` command to avoid rebuilding all images when deploying a compose and only a subset of services are being deployed. -- [Okteto CLI 3.10.0](https://github.com/okteto/okteto/releases/tag/3.10.0): Updated the `okteto preview destroy` command to correctly propagate the `--timeout` flag to the backend, ensuring longer destroy operations don’t fail prematurely. ⚠️ This requires both CLI 3.10.0 and Chart 1.35. -- [Okteto CLI 3.10.0](https://github.com/okteto/okteto/releases/tag/3.10.0): Enhanced `okteto context use` to better handle invalid or expired local tokens. The CLI will now prompt for login rather than failing with a non-actionable error. - -### Bug Fixes {#bug-fixes-1.35} -- Fixed an issue that prevented some development environments from waking up as expected when there were dependency cycles between dev environments -- Improved AWS IAM Role regex handling for tighter validation on Private Registry Credentials and Cloud Credentials - -### Removal Notice {#removal-notice-1.35} -- Support for Kubernetes [1.30](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.30.md) has been removed in this release. - - -## 1.34 - -3 July 2025 - -This version is compatible with Kubernetes versions 1.30 to 1.32 \ -Okteto Chart release 1.34 is designed to work with [Okteto CLI 3.9.x](https://github.com/okteto/okteto/releases/tag/3.9.0) - -### Improvements {#improvements-1.34} -- [Okteto CLI 3.9.0](https://github.com/okteto/okteto/releases/tag/3.9.0): Added a [feature flag](reference/feature-flags.mdx) to return services in development to their "running" state (`okteto down`) when exiting the terminal session -- [Okteto CLI 3.9.0](https://github.com/okteto/okteto/releases/tag/3.9.0): Included a [feature flag](reference/feature-flags.mdx) to make `dev..services` wait for file synchronization to finish before running their commands during `okteto up` execution - -### Bug Fixes {#bug-fixes-1.34} - -- Fixed the "Retry Destroy" action so it now performs a graceful deletion instead of triggering a force destroy. Previously, both "Retry Destroy" and "Force Destroy" were triggering a force deletion -- Fixed breadcrumb layout regressions across several updates -- Prevented UI overflow of the redeploy button in the resources sidebar -- Fixed an error when running `okteto test` with defined artifacts but no output files; the `/okteto/artifacts` directory is now created by default to prevent execution failures - - -## 1.33.1 - -19 June 2025 - -This version is compatible with Kubernetes versions 1.30 to 1.32 \ -Okteto Chart release 1.33 is designed to work with [Okteto CLI 3.8.x](https://github.com/okteto/okteto/releases/tag/3.8.0) - -### Bug Fixes - -- Fixed a glitch in the breadcrumb within the preview detail view when the monitor used has a big resolution - -## 1.33.0 - -13 June 2025 - -This version is compatible with Kubernetes versions 1.30 to 1.32 \ -Okteto Chart release 1.33 is designed to work with [Okteto CLI 3.8.x](https://github.com/okteto/okteto/releases/tag/3.8.0) - -### New Features {#new-features-1.33} - -- Introduced support for dependency-aware redeploy and destroy operations in multi-service environments - - [Okteto CLI 3.8.0](https://github.com/okteto/okteto/releases/tag/3.8.0): New `--dependencies` flag for `okteto pipeline deploy`, `okteto preview deploy`, and `okteto pipeline destroy` commands to include direct dependencies (defaults follow admin-level configuration) - - New environment variable format `OKTETO_DEPENDENCY_${DEPENDENCY_NAME}_BUILD_${BUILD_SVC}_${BUILD_ENVVAR}` for accessing dependency-specific build variables - - ⚠️ Note: The `--dependencies` flag only applies to direct dependencies and does not recurse further to avoid impacting cyclic relationships -- New [**Deployments** admin panel](admin/dashboard.mdx#deployments) allowing configuration of default behavior for: - - Redeploying all direct dependencies by default - - Destroying all direct dependencies by default -- Added a checkbox option in both the redeploy and destroy dialogs to optionally include direct dependencies when present - -### Improvements {#improvements-1.33} - -- Enforced GitHub App ID type as int64 for configmap rendering consistency to avoid fatal errors in the API components when the field was specified without quotes in the helm values -- Added breadcrumbs to the Preview Environment details page to make navigation easier -- [Okteto CLI 3.8.0](https://github.com/okteto/okteto/releases/tag/3.8.0): `okteto namespace list` now supports an `output` option to specify `json` or `yaml` formats as `okteto preview list` - -### Bug Fixes {#bug-fixes-1.33} - -- Fixed text overflow issue in Resource Manager UI for small screens -- Hid sidebar redeploy button on smaller screens to avoid UI clutter -- Fixed "back to catalog" link navigation -- Fixed ellipsis rendering issues in previews - - -## 1.32.0 - -8 May 2025 - -This version is compatible with Kubernetes versions 1.30 to 1.32 \ -Okteto Chart release 1.32 is designed to work with [Okteto CLI 3.7.x](https://github.com/okteto/okteto/releases/tag/3.7.0) - -### New Features {#new-features-1.32} - -- Added support for waking up development environments without dependencies in parallel. This behavior is disabled by default and can be enabled via the [feature flag](reference/feature-flags.mdx) `OKTETO_PARALLEL_WAKE_UPS_FOR_DEVENVS`. When dependencies exist, their defined startup order is still respected - -### Improvements {#improvements-1.32} - -- Refreshed the Okteto Dashboard UI to improve the visual design and lay the groundwork for features coming later this year. The changes are purely visual; everything is still in the same place -- Included changes to prevent an empty stage `Deploy <>` log entries in the UI when deployments are triggered via `okteto deploy` from the CLI -- Upgraded our BuildKit client to [0.21.1](https://github.com/moby/buildkit/releases/tag/v0.21.1) for improved performance and stability -- Enhanced privacy and security by removing sensitive repository information when Development Environments are deployed using the GitHub App integration -- All pods deployed within a diverted Namespace now have 2 environment variables automatically injected that can be used at runtime. `OKTETO_SHARED_ENVIRONMENT` contains the name of the shared Namespace where all the services are deployed, and `OKTETO_DIVERTED_ENVIRONMENT` contains the routing key used to route the traffic to the proper version of the service (its value is the name of the Namespace where diverted services are deployed) -- Endpoints in namespaces that include diverted services are now correctly displayed in the UI when using the `nginx` driver - -### Bug Fixes {#bug-fixes-1.32} - -- [Okteto CLI 3.7.0](https://github.com/okteto/okteto/releases/tag/3.7.0): Fixed a bug in the [Smart Builds](core/build-service.mdx#smart-builds) hash calculation process that caused indefinite hangs when hundreds of untracked files existed in the local Git repository -- Unified the HTTP header used in [Divert](reference/okteto-manifest.mdx#divert) to propagate the routing key for both drivers `nginx` and `istio`. `istio` driver was using `baggage` header with the key `okteto-divert`, but `nginx` driver was using the header `baggage.okteto-divert`. Now, both drivers use the same standard [`baggage`](https://www.w3.org/TR/baggage/) header as `baggage: okteto-divert=`. For the `nginx` driver, the header `baggage.okteto-divert` is still being injected automatically for backward compatibility, but **it will be removed in the future** -- Fixed an issue when using both [Divert](reference/okteto-manifest.mdx#divert) and [`endpoints`](/docs/reference/okteto-manifest#endpoints-object-required) to deploy a Development Environment. Endpoints for the diverted namespaces were not working as expected, as the HTTP header with the routing key was not being injected into the request - -## 1.31.0 - -4 April 2025 - -This version is compatible with Kubernetes versions 1.30 to 1.32 \ -Okteto Chart release 1.31 is designed to work with [Okteto CLI 3.6.x](https://github.com/okteto/okteto/releases/tag/3.6.0) - -### Deprecation Notice {#deprecation-notice-1.31} - -- ⚠️ Important: **Support for Docker Image Manifest Schema 1 images is removed in this** (1.31) due to upstream dependency changes. If you are using older images, they may fail to pull or deploy.\ -[Learn how to check and update your images →](self-hosted/manage/upgrade.mdx#upgrading-to-okteto-131x--schema-1-image-deprecation) - -### New Features {#new-features-1.31} - -- Added a new [Okteto API endpoint](admin/okteto-api.mdx) to list users -- Added support for waking up resources within Development Environments respecting the dependencies defined through `depends_on` field in Docker Compose. By default this behavior is disabled, but it can be enabled [with the feature flag](reference/feature-flags.mdx) `OKTETO_COMPOSE_WAIT_FOR_DEPENDENCIES` (requires redeploying the application with [Okteto CLI 3.6.0](https://github.com/okteto/okteto/releases/tag/3.6.0)). -- Added support for Kubernetes [1.32](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.32.md) (previous support for 1.29 was removed) - -### Improvements {#improvements-1.31} - -- Improved error messages when ssh-keyscan error fails for deploys triggered from the UI, `okteto pipeline deploy` or `okteto preview deploy` -- Patched IngressNightmare CVE-2025-1974 to enhance platform security -- Upgraded our BuildKit client to [0.20.2](https://github.com/moby/buildkit/releases/tag/v0.20.2) - -### Bug Fixes {#bug-fixes-1.31} - -- The `baggage.divert` header is now properly propagated to downstream services when using the `nginx` divert driver, allowing services to detect diverted requests -- Fixed an issue where logs appeared out of order on initial load -- Support bundles now include Ingress NGINX logs and Helm values for installations managed via ArgoCD -- Fixed UI overflow in the deploy dialog when rendering long lists - -### Removal Notice {#removal-notice-1.31} - -- Support for Kubernetes [1.29](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.29.md) has been removed in this release. - - - -## 1.30.1 - -26 March 2025 - -This version is compatible with Kubernetes versions 1.29 to 1.31 \ -Okteto Chart release 1.30 is designed to work with [Okteto CLI 3.5.x](https://github.com/okteto/okteto/releases/tag/3.5.0) - -### Improvements - -- Updated ingress-nginx dependency as a preventive measure for a [critical vulnerability](https://thehackernews.com/2025/03/critical-ingress-nginx-controller.html). Note: The affected **admission webhook** component is **not enabled by default in our deployments**, but it could be enabled through helm settings - -### Bug Fixes - -- `baggage.okteto-divert` HTTP header is now included on every request going through the ingress-controller when using `nginx` driver for [Divert](reference/okteto-manifest.mdx#divert) -- [Okteto CLI 3.5.1](https://github.com/okteto/okteto/releases/tag/3.5.1): Fixed Smart Builds cache calculation when the git repository has a high number of files in the build context - -## 1.30.0 - -7 March 2025 - -This version is compatible with Kubernetes versions 1.29 to 1.31 \ -Okteto Chart release 1.30 is designed to work with [Okteto CLI 3.5.x](https://github.com/okteto/okteto/releases/tag/3.5.0) - -### Deprecation Notice {#deprecation-notice-1.30} - -- ⚠️ Important: **Support for Docker Image Manifest Schema 1 images will be removed in next release** (1.31) due to upstream dependency changes. If you are using older images, they may fail to pull or deploy.\ -[Learn how to check and update your images →](self-hosted/manage/upgrade.mdx#upgrading-to-okteto-131x--schema-1-image-deprecation) - -### New Features {#new-features-1.30} - -- Okta User De-provisioning: Okta users can now be [automatically de-provisioned in Okteto](admin/integrations/okta-user-deprovisioning.mdx) when removed from Okta -- Okteto Test Insights: You can now view average success time metrics for your Okteto Test runs in [Okteto Insights](core/okteto-insights-dashboards.mdx#test-dashboard) - -### Improvements {#improvements-1.30} - -- Automatic Cleanup of Orphaned Namespaces: Namespaces with no owner will now be automatically garbage collected to free up resources -- The ingress-nginx package has been upgraded to 4.12.0 -- Improved the interaction between helm and Horizontal Pod Autoscaler(HPA) to avoid longer upgrade periods and unnecessary BuildKit restarts when the number of replicas specified in helm values differs from the ones HPA enforces -- If a deployment via UI, `okteto pipeline deploy`, or `okteto preview deploy` can’t be scheduled, it will be marked as failed after 5 minutes. -- [Okteto CLI 3.5.0](https://github.com/okteto/okteto/releases/tag/3.5.0): Files listed in .dockerignore can now be excluded from the smart build context calculation by [setting the Admin Variable](reference/feature-flags.mdx) `OKTETO_SMART_BUILDS_IGNORE_FILES_ENABLED` to `true` -- [Okteto CLI 3.5.0](https://github.com/okteto/okteto/releases/tag/3.5.0): We've optimized remote executions of Deploy and Destroy operations when buildkit execution is not needed - -### Bug Fixes {#bug-fixes-1.30} - -- Init container logs now appear before container logs in history -- [Okteto CLI 3.5.0](https://github.com/okteto/okteto/releases/tag/3.5.0): The CLI now waits if Buildkit is not available -- [Okteto CLI 3.5.0](https://github.com/okteto/okteto/releases/tag/3.5.0): The `OKTETO_AUTODEPLOY` [feature flag](reference/feature-flags.mdx) now works as intended when set -- [Okteto CLI 3.5.0](https://github.com/okteto/okteto/releases/tag/3.5.0): Fixed re-deploy logic for compose files with `depends_on` between services. If a dependency failed in a previous operation, a redeploy sometimes was being considered failed as it was taking into account the previous state - -### Removal Notice {#removal-notice-1.30} - -- Support for Kubernetes [1.28](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.28.md) has been removed in this release. - - -## 1.29.0 - -7 February 2025 - -This version is compatible with Kubernetes versions 1.28 to 1.31 \ -Okteto Chart release 1.29 is designed to work with [Okteto CLI 3.4.x](https://github.com/okteto/okteto/releases/tag/3.4.0) - - -### New Features {#new-features-1.29} - -- Added support for [Kubernetes 1.31](https://kubernetes.io/blog/2024/08/13/kubernetes-v1-31-release/) -- Personal Namespaces can now be [included in your Garbage Collection Policy](admin/cleanup.mdx#applying-garbage-collection-to-personal-namespaces) - - Personal Namespaces themselves will not be deleted, but their unused resources (e.g., Pods, Services, ConfigMaps) will be removed following the Sleep and Delete Period settings - - To leave developer workflows untouched, Persistent Volume Claims (PVCs) within Personal Namespaces will not be deleted as part of this process -- Introducing the [Okteto API (Beta)](admin/okteto-api.mdx)! 🎉 Now you can get programmatic information on namespaces and applications with authenticated API requests. Access the full API documentation via the Okteto Dashboard under **Admin → Admin Access Tokens** - -### Improvements {#improvements-1.29} - -- [Okteto CLI 3.4.0](https://github.com/okteto/okteto/releases/tag/3.4.0): Optimized image building in `okteto up`: Now, only the necessary images required for the process are built, instead of building all images. This reduces build times, speeds up environment startup, and minimizes unnecessary resource usage -- [Okteto CLI 3.4.0](https://github.com/okteto/okteto/releases/tag/3.4.0): Improve warnings when a CLI user has a different version than within the accepted range set by the Okteto Admin -- Added a warning for users on older browsers that may have compatibility issues - - -### Bug Fixes {#bug-fixes-1.29} - -- Fixed an issue where [Divert](reference/okteto-manifest.mdx#divert) would not work with Docker Compose as intended -- Buildkit in rootless mode when running in Kubernetes 1.30 no longer adds a deprecated annotation -- Fixed an issue where Okteto failed to inject the ingress-nginx controller’s private IP in Okteto components when the service name was too long - -### Removal Notice {#removal-notice-1.29} - -- Support for Kubernetes [1.27](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.27.md) has been removed in this release. - - -## 1.28.2 - -14 January 2025 - -This version is compatible with Kubernetes versions 1.27 to 1.30 \ -Okteto Chart release 1.28 is designed to work with [Okteto CLI 3.3.x](https://github.com/okteto/okteto/releases/tag/3.3.1) - -### Bug Fixes - -- [Okteto CLI 3.3.1](https://github.com/okteto/okteto/releases/tag/3.3.1): Fixed an issue when deploying with divert through a docker compose file - -## 1.28.1 - -10 January 2025 - -This version is compatible with Kubernetes versions 1.27 to 1.30 \ -Okteto Chart release 1.28 is designed to work with [Okteto CLI 3.3.x](https://github.com/okteto/okteto/releases/tag/3.3.0) - -### Bug Fixes - -- [Okteto CLI 3.3.0](https://github.com/okteto/okteto/releases/tag/3.3.0): Fixed an issue where deployments of Compose files would always time out after 5 minutes -- [Okteto CLI 3.3.0](https://github.com/okteto/okteto/releases/tag/3.3.0): Resolved a permission issue when deploying Compose files with volumes that were being initialized - - -## 1.28.0 - -10 January 2025 - -This version is compatible with Kubernetes versions 1.27 to 1.30 \ -Okteto Chart release 1.28 is designed to work with [Okteto CLI 3.3.x](https://github.com/okteto/okteto/releases/tag/3.3.0) - -### New Features - -- [Okteto CLI 3.3.0](https://github.com/okteto/okteto/releases/tag/3.3.0): Introducing [Okteto Validate](reference/okteto-cli.mdx#validate), a CLI command allowing you to run validation on your Okteto Manifest -- All [external dependencies](self-hosted/manage/air-gapped.mdx) now use images hosted under our [Docker Hub organization okteto/](https://registry.hub.docker.com/u/okteto) (e.g., ingress-nginx, reloader, redis) - -### Improvements - -- Enabled hourly intervals for [Garbage Collection delete schedules](admin/cleanup.mdx#configuring-the-sleep-and-delete-periods) -- Add new `unschedulable` status for when a pod has the reason Unschedulable for more than 3 minutes -- [Okteto CLI 3.3.0](https://github.com/okteto/okteto/releases/tag/3.3.0): Upgraded our BuildKit client to [0.18.2](https://github.com/moby/buildkit/releases/tag/v0.18.2) - -### Bug Fixes - -- Addressed inconsistent states in the logs filters within the UI to improve reliability -- Fixed an issue where the okteto deploy command did not correctly receive variables specified in the commands section of an Okteto Manifest - - -## 1.27.2 - -10 January 2025 - -This version is compatible with Kubernetes versions 1.27 to 1.30 \ -Okteto Chart release 1.27 is designed to work with [Okteto CLI 3.2.x](https://github.com/okteto/okteto/releases/tag/3.2.3) - -### Bug Fixes - -- [Okteto CLI 3.2.3](https://github.com/okteto/okteto/releases/tag/3.2.3): Fixed an issue that was provoking that deployment of compose file were timing out always after 5 minutes -- [Okteto CLI 3.2.3](https://github.com/okteto/okteto/releases/tag/3.2.3): Fixed a permission issue when deploying compose files with volumes, and the volume was being initialized - - -## 1.27.1 - -17 December 2024 - -This version is compatible with Kubernetes versions 1.27 to 1.30 \ -Okteto Chart release 1.27 is designed to work with [Okteto CLI 3.2.x](https://github.com/okteto/okteto/releases/tag/3.2.1) - -### Bug Fixes - -- Recovered `kustomize` binary as part of our default runner image. - -## 1.27.0 - -12 December 2024 - -This version is compatible with Kubernetes versions 1.27 to 1.30 \ -Okteto Chart release 1.27 is designed to work with [Okteto CLI 3.2.x](https://github.com/okteto/okteto/releases/tag/3.2.1) - -### Breaking Changes - -- Remove code for our deprecated Quickstarts feature -- Helm chart now separates registry and repository fields for overwriting container images. -Update configurations for `backend.image`, `frontend.image`, `buildkit.image`, `buildkit.rootless.image`, `registry.image` following [this guide](self-hosted/manage/air-gapped.mdx#step-2-set-up-a-private-registry-for-required-images) if you have previously overwritten these. -- `cue`, `helmfile`, `kustomize`, `yq` and `docker-credential-ecr-login` binaries were removed from the Okteto's default pipeline runner image. If you need some of those binaries in your pipelines, you can build [your own runner image](admin/custom-installer-image.mdx). - -### New Features - -- We now allow the ability for admins of Okteto to [set the minimum accepted CLI version for their team](admin/dashboard.mdx#command-line-cli). This will apply for all users who are using CLI 3.2.0 and above -- We've published the [Okteto Manifest JSON Schema for inline suggestions and validation for creating and editing Okteto manifests within your code editor](reference/okteto-manifest.mdx#validating-and-autocompleting-the-okteto-manifest-in-your-ide) -- Added support for [overwriting CLI images at the Helm chart level](self-hosted/helm-configuration.mdx#cli) -- Shipped additional support for the installation of [Okteto in Air-Gapped Environments](self-hosted/manage/air-gapped.mdx) -- Configured buildkit probes to only accept requests when buildkit is healthy -- Added support for configuring the [Okteto control plane jobs TTL at the helm level](self-hosted/helm-configuration.mdx#jobs) - -### Improvements - -- We've reorganized the [Admin Dashboard menu items](admin/dashboard.mdx) into groups for easier navigation -- For [Catalog](admin/catalog.mdx) and [Cloud Credentials](admin/cloud-credentials/index.mdx) items that were created via CRDs, we've added "read-only" tags in the Dashboard to avoid confusion on which items can be edited in the UI -- Updated buildkit cacheRatio default value to `0.5` -- The Okteto installer image is no longer needed, binaries for the installer jobs are now installed from `okteto/backend` -- [Okteto CLI 3.2.1](https://github.com/okteto/okteto/releases/tag/3.2.1): We merged `okteto/bin` and `okteto/busybox` images into the `okteto/okteto` image to reduce the number of images used in the CLI workflow -- [Okteto CLI 3.2.1](https://github.com/okteto/okteto/releases/tag/3.2.1): You can now define the Admin Variable `OKTETO_DEV_PERSISTENT_VOLUME_SIZE` to configure the default volume size for Development Containers - -### Bug Fixes - -- Added `globals.priorityClassName` to sleep/wake jobs and the `events-exporter` component -- Added new logic to filter out terminated containers from Resource Manager calculations -- Redacted service accounts from our diagnostics package -- [Okteto CLI 3.2.1](https://github.com/okteto/okteto/releases/tag/3.2.1): Fixed a problem when deploying a compose with failed health checks. We were not taking into account the timeout operation, so the deploy operation was stuck forever - - -## 1.26.1 - -12 November 2024 - -This version is compatible with Kubernetes versions 1.27 to 1.30 - -### Bug Fixes - -- Fixed the calculation of the total requested CPU/memory in Resource Manager Admin View by excluding completed pods. -- Fixed an issue when Resource Manager was enabled in Manual mode and `quotas.limitranges.requests.limitRequestRatio` was also set. - -## 1.26.0 - -9 November 2024 - -This version is compatible with Kubernetes versions 1.27 to 1.30 - -### Breaking Changes {#breaking-changes-1.26} -Please read the following changes before upgrading to 1.26 - -- **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](https://www.okteto.com/docs/1.26/self-hosted/helm-configuration/#manual-migration-steps-when-renaming-the-defaultbackend-service). -- **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 - -### New Features - -- **[Introducing the Okteto Resource Manager](admin/resource-manager.mdx)**: a new feature that automatically optimizes CPU and memory requests for your environments. By analyzing real-time resource utilization, the Resource Manager dynamically adjusts resource requests to ensure efficient usage, prevent node overload, and improve overall cluster performance. This feature simplifies resource management, reduces manual adjustments, and enhances application stability, especially in larger clusters. The default installation provides recommendations but doesn't apply them automatically. [See our docs for details on how to apply these automatically](admin/resource-manager.mdx) -- Added Okteto [Garbage Collector settings to the Admin Dashboard](admin/cleanup.mdx): Admins can now manage sleep and delete periods from the Dashboard, with the ability to set different configurations for Namespaces and Preview Environments -- [Remote Execution can now be set as the default](core/remote-execution.mdx) in the Okteto Admin Dashboard, allowing admins to enforce consistent remote deploys. Remote deploys also include improvements for feature parity with local deploys, such as the ability to specify the context synchronization folder and private Git repository cloning during deploy commands using SSH keys -- Added additional feature and documentation for [running Buildkit at scale](self-hosted/manage/buildkit-high-performance.mdx) - -### Improvements - -- Okteto will now automatically create a Docker secret if one doesn't already exist in the Controller Manager. This prevents a misleading warning that was being displayed in some scenarios when deploying from the UI -- [Buildkit cache size is now automatically configured](self-hosted/helm-configuration.mdx#buildkit) based on its PVC volume size -- Removed Buildkit persistency as an installation step now that it defaults to true -- The Okteto frontend now runs rootless by default, while Buildkit operates without privileges when rootless mode is enabled -- We've [released Okteto CLI 3.1.0 with many new improvements](https://github.com/okteto/okteto/releases/tag/3.1.0) -- [Okteto CLI 3.1.0](https://github.com/okteto/okteto/releases/tag/3.1.0): Added support for a `context` field in the Okteto Manifest, allowing you to specify the working directory for commands in the `deploy` and `destroy` sections -- [Okteto CLI 3.1.0](https://github.com/okteto/okteto/releases/tag/3.1.0): [Added automatic retry for build operations](reference/feature-flags.mdx) when BuildKit is unavailable due to transient errors. The behavior can be controlled using the environment variables `OKTETO_BUILDKIT_MAX_RETRIES_FOR_TRANSIENT_ERRORS`, `OKTETO_BUILDKIT_WAIT_TIMEOUT`, and `OKTETO_BUILDKIT_RETRY_INTERVAL`. - -### Bug Fixes - -- Fixed an issue that was preventing Development Environments to be destroyed when the specified manifest doesn't exist -- Fixed a patch operation in the Okteto Insights cronjob that was causing the loss of node labels when there were concurrent operations from external processes -- Resolved an issue where build logs were not displayed in the UI when deploying dev or preview environments, causing the UI to appear frozen. Build logs now display correctly during deployments - - -## 1.25.0 - -7 October 2024 - -This version is compatible with Kubernetes versions 1.27 to 1.30 - -### New Features - -- [Announcing Okteto CLI 3.0](https://www.okteto.com/blog/cli-three-release/) - upgrading to chart release 1.25 requires a CLI upgrade to 3.0 -- Announcing [Cloud Credentials](admin/cloud-credentials/index.mdx), a central location to manage your cloud provider credentials for `deploy`, `destroy`, and `test` remote operations -- Added official [support for Red Hat OpenShift](get-started/install/openshift.mdx) -- Added support and a new Namespace UI for [resource quotas at the individual Namespace level](core/namespaces.mdx#configure-namespace-quotas). This allows administrators to set the maximum resources that can be used per Namespace -- Enabling [Okteto Insights Dashboards](core/okteto-insights-dashboards.mdx) for all SaaS and BYOC users of Okteto -- Added support to allow override of [installer security context](self-hosted/helm-configuration.mdx#installer) - -### Improvements - -- Support for [`priorityClassName`](reference/okteto-manifest.mdx#priorityclassname-string-optional) and [`accessMode`](reference/okteto-manifest.mdx#persistentvolume-object-optional) for volumes created by `okteto up` -- Show more actionable feedback upon "failed to deploy okteto pipeline" error -- You can now list your Github App installations under Settings → Integrations -- Implemented a number of UI updates to ensure your Okteto experience stays smooth -- Made a number of improvements to the [Okteto Insights Dashboards](core/okteto-insights-dashboards.mdx) to display historical build and deploy data, and provide a better experience loading large datasets - -### Bug Fixes - -- [Okteto CLI 3.0](https://github.com/okteto/okteto/releases/tag/3.0.0): Fix in Smart Builds logic to properly calculate when to build a new image if the build context points to a parent folder -- Fixed wrong data parsing error from unknown git urls -- Fixed issue where interactive but hidden elements, such as links in closed deploy log stage, were wrongly accessible via keyboard navigation and screen readers -- Fixed issue preventing password managers from filling in the login token -- Reconfigured GitHub installation to error when trying to be installed by a non-admin -- Fixed external resources not being selectable on Preview Environments -- Fixed sleep namespaces job when statefulset within it is in dev mode -- Fix for Buildkit PVC cleanups in the "okteto" Namespace -- Fix keyboard navigation on Admin → Users actions dropdown menu -- Removed support for "Volumes" on the Admin Nodes view and Autoscaler \ No newline at end of file diff --git a/versioned_docs/version-1.37/saas-vs-self-hosted.mdx b/versioned_docs/version-1.37/saas-vs-self-hosted.mdx deleted file mode 100644 index 079dbcc05..000000000 --- a/versioned_docs/version-1.37/saas-vs-self-hosted.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: SaaS vs. Self-Hosted -description: The difference between Okteto's product offerings in SaaS and Self-Hosted -sidebar_label: SaaS vs. Self-Hosted -id: saas-vs-self-hosted ---- - -Okteto consists of two products: our [CLI](get-started/install-okteto-cli.mdx) and the Okteto Platform. We provide the Okteto Platform in two forms: SaaS (fully managed by Okteto) and Self-Hosted (installed using our Helm chart and fully managed by you). The SaaS and Self-Hosted offerings exist primarily to deliver the Okteto Platform experience and features. - -# The Okteto Platform - -In addition to Okteto's [CLI](get-started/install-okteto-cli.mdx) we optionally provide the Okteto Platform. This is the other half of our product experience that provides the fully managed infrastructure for your development environments. It's what interprets the [Okteto Manifest](reference/okteto-manifest.mdx) to spin up a development environment and automates your workflows. One of the biggest advantages of the Okteto Platform is that we scale the underlying cluster infrastructure so you never have to worry about your development environments having insufficient resources to run even your most complex applications. - -Additionally, you can use the Okteto CLI without using the Okteto Platform, but there are important considerations with that use case. - -Some examples of what the Okteto Platform manages are: [configuring variables](core/okteto-variables.mdx), adding [external resources](/docs/tutorials/external-resources) into your development environment, and build and push container images to the [Okteto Registry](core/container-registry.mdx). For a more comprehensive list of features, check out our [docs](self-hosted/index.mdx). - -# Important things to know - -| SaaS | Self-Hosted | -| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | -| Fully managed by Okteto and great for small teams with simpler applications and infrastructure requirements. | Great for larger teams with bigger with more complex applications and a large number of microservices. | -| Limited access to cluster admin features. | Full access to the kubernetes cluster and fully integrates with the rest of your kubernetes infrastructure. | -| Pricing includes Okteto license + infrastructure. | Pricing includes only the Okteto license. | diff --git a/versioned_docs/version-1.37/self-hosted/install/certificates/cert-manager.mdx b/versioned_docs/version-1.37/self-hosted/install/certificates/cert-manager.mdx deleted file mode 100644 index ff12cb65f..000000000 --- a/versioned_docs/version-1.37/self-hosted/install/certificates/cert-manager.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Setting up certificates with -description: Setting up certificates with cert-manager and Let’s Encrypt -sidebar_label: Let’s Encrypt -id: cert-manager ---- - -# Setting up Certificates with cert-manager and Let’s Encrypt - -Let’s Encrypt is a free, automated, and open Certificate Authority. Certificates can be automatically requested using various tools. A very popular way of requesting certificate from Let's Encrypt is [by using cert-manager](https://github.com/cert-manager/cert-manager). - -When using [cert-manager](https://cert-manager.io/), you need to use a [DNS01](https://cert-manager.io/docs/configuration/acme/dns01/#delegated-domains-for-dns01) auth method in your [Issuer](https://cert-manager.io/docs/concepts/issuer/), since Okteto requires a wildcart certificate. -Check the list of supported providers [here](https://cert-manager.io/docs/configuration/acme/dns01/) for more information. - -Our community maintains guides on how to use cert-manager together with different Cloud Providers to generate certificates for Okteto: - -- [Amazon Route53](https://community.okteto.com/t/how-do-i-configure-okteto-with-cert-manager-and-aws-route53/273/2) -- [Google Cloud DNS](https://community.okteto.com/t/how-do-i-configure-okteto-with-cert-manager-and-google-cloud-dns/274/2) -- [Azure Cloud DNS](https://community.okteto.com/t/how-do-i-configure-okteto-with-cert-manager-and-azure-cloud-dns/275/2) - -You can also check out our video tutorial on how to configure certificates for your Okteto installation using cert-manager and Let's Encrypt: - -
- -
diff --git a/versioned_docs/version-1.37/self-hosted/manage/okteto-license.mdx b/versioned_docs/version-1.37/self-hosted/manage/okteto-license.mdx deleted file mode 100644 index 23352011b..000000000 --- a/versioned_docs/version-1.37/self-hosted/manage/okteto-license.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Okteto License -description: This page provides information about how Okteto's license works for the products we provide. -sidebar_label: Okteto License -id: okteto-license ---- - -Okteto requires a license key to use any of our paid products. We offer two paid products: [SaaS and Self-Hosted](saas-vs-self-hosted.mdx). If you use Okteto SaaS then no action is required of you to obtain a license as this is fully managed by Okteto. If you use Okteto Self-Hosted, then you will need to obtain a license and include that in your `config.yaml` when installing Okteto. - -:::note -You can also optionally include your Okteto license using [Cloud Secrets](self-hosted/helm-configuration.mdx#secret). -::: - -## Why a license is required - -We require you obtain a license to use Okteto because the product is highly customizable and we want to ensure you have a great experience getting it installed and configured. Obtaining a license from us kicks off specific customer success workflows to help us provide you with the right guidance and support. - -Don't worry. We don't require you speak with someone from our Sales team to try Okteto or deal with more friction than is necessary. There's also no requirement to provide us with credit card information. We want you to experience Okteto in the ways we believe will inform your decisions and requiring a license is the first step on that journey. - -This requirement also helps us know who's using our product for typical product development and marketing initiatives that enable us to continue building more and better features. - -## How to obtain a license - -There are two ways to obtain a license from Okteto. - -1. Fill out the self-hosted [Free Tier form](https://www.okteto.com/free-trial/) on our website -1. [Contact us](https://www.okteto.com/get-demo/) to schedule a demo - -When you fill out the self-hosted Free Tier form you will automatically receive an email containing a license key for your Free Tier access. This option does not require any interaction with Okteto or our teams and gives you the control and independence to try Okteto self-hosted on your schedule and at your own pace. This process and license key only works and provides access to the self-hosted version of Okteto. - -The alternative option of contacting us for a demo will get you in touch with someone from our team to guide you through a personalized demo and gives you the opportunity to ask questions and explore our product side-by-side with our knowledgeable team. This process can result in Free Tier access to Okteto SaaS or Self-Hosted, which provides you with additional flexibility to use Okteto in the way that best suits your needs. - -## How to use the license - -If you have opted to use Okteto SaaS then there is no action required of you. We will handle the generation, assignment, and configuration of the license for your SaaS instance. - -If you have opted to use Okteto Self-Hosted then you will need to add your license key to your `config.yaml`. If you do not yet have a license, please choose one of the methods [above](#how-to-obtain-a-license). - -Once you have your license, you can add it to your `config.yaml` using the `license:` key. For example: - -```yaml -license: ABC123...XYZ456 -``` - -After that, you'll need to [upgrade](upgrade.mdx) your Okteto instance for the new license to be applied. diff --git a/versioned_docs/version-1.37/self-hosted/manage/troubleshooting.mdx b/versioned_docs/version-1.37/self-hosted/manage/troubleshooting.mdx deleted file mode 100644 index 971acc4a6..000000000 --- a/versioned_docs/version-1.37/self-hosted/manage/troubleshooting.mdx +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Troubleshoot your Okteto instance -description: Questions and answers to common issues when installing or upgrading your Okteto instance -sidebar_label: Troubleshooting -id: troubleshooting ---- - - -Welcome to the Okteto troubleshooting guide. This page provides answers to some common issues encountered while using Okteto. -Please also review our [FAQ Guide](reference/faqs.mdx) for additional help. - -## How to extract logs from Okteto when asking for help - -### For Developers: -When reaching out to Okteto for support or when asking the [Okteto Community](http://community.okteto.com), run [`okteto doctor` to generate a doctor file](reference/okteto-cli.mdx#doctor) with the okteto logs for a given development container. - -### For Administrators of Okteto: -Please use our [Okteto Diagnostics tool](self-hosted/manage/diagnostics.mdx) to create a support bundle with cluster information, logs for okteto components, and other relevant information. - -## UPGRADE FAILED: “okteto” has no deployed releases - -This error will occur on your second install/upgrade if your initial install failed. If the first instal failed, delete the existing install before trying again: - -``` -helm uninstall okteto -``` - -## Registry pods keep restarting - -This can happen when the pods can't read/write from your cloud storage bucket. Double check that the cloud IAM you created has read/write access to the specified bucket. - -## Deployment pipelines stay in "progressing" forever - -This can happen for several reasons, among others, the installer job couldn't be started due to an error in Kubernetes API, or due to an overload in the cluster. -In order to find out what the problem is, there's a way to list all the jobs and pods for a specific pipeline. - -You need the pipeline name (it is the name displayed on Okteto UI) and the namespace where it is deployed. With that information, you can get jobs and pods running these commands: - -```console -kubectl get jobs -l=dev.okteto.com/pipeline-name=movies -l=dev.okteto.com/pipeline-namespace=cindy --namespace=okteto -``` - -```console -kubectl get pods -l=dev.okteto.com/pipeline-name=movies -l=dev.okteto.com/pipeline-namespace=cindy --namespace=okteto -``` - -## Using a Custom CNI - -If you're using a custom CNI on your cluster then there may be some additional configuration needed for webhooks. -In certain cases the CNI used on the worker nodes is not the same as the CNI used by the control plane and host networking will need to be used for webhooks. -In addition, the ports may need to be changed to avoid collisions. - -The Okteto Webhook is configured by setting`webhook.hostNetwork` to `true`. The ports are set with `webhook.port`. -More information on the Okteto Webhook configuration can be found [here](self-hosted/helm-configuration.mdx#webhook). - -## Docker Hub credentials misconfiguration - -As you can [configure your own Docker Hub account](admin/dashboard.mdx#registry-credentials) in Okteto, it could happen that the credentials are not properly set. If that is the case, kubelet won't be able to pull public images from Docker Hub, which can be an important issue in the cluster. - -If this ever happens in your cluster, there is a way to fix it: -- [Update the container image used by the daemonset pods](self-hosted/helm-configuration.mdx#daemonset). **Important note**, use a container registry different than Docker Hub to pull the image without credential problems. For example, you can use `ghcr.io/okteto/busybox`. -- Change or remove the credentials for the Docker Hub registry. -- [Upgrade your cluster](self-hosted/manage/upgrade.mdx) with the new configuration. - -After this, the Okteto daemonset will be able to configure the right credentials for Docker Hub. Once you verify everything is working, you can restore the original base image for the Okteto daemonset. - -## We are here to help - -[Reach out to us](https://community.okteto.com/), we're always happy to help! \ No newline at end of file diff --git a/versioned_docs/version-1.37/variables.json b/versioned_docs/version-1.37/variables.json deleted file mode 100644 index b9fccb8bc..000000000 --- a/versioned_docs/version-1.37/variables.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "kubernetesMinVersion": "1.31", - "kubernetesMaxVersion": "1.33", - "cliVersion": "3.12.0", - "chartVersion": "1.37.0", - "syncthingVersion": "2.0.10" -} \ No newline at end of file diff --git a/versioned_docs/version-1.49/admin/billing.mdx b/versioned_docs/version-1.49/admin/billing.mdx new file mode 100644 index 000000000..1f08b68ef --- /dev/null +++ b/versioned_docs/version-1.49/admin/billing.mdx @@ -0,0 +1,169 @@ +--- +title: Billing +description: Okteto bills per seat on an annual contract. Run as many environments and agents as your infrastructure supports. For Enterprise, your license covers all your Okteto clusters and we count unique seats across the fleet. +sidebar_label: Billing +id: billing +--- + +import Head from '@docusaurus/Head'; + + + + + +# Billing + +Okteto bills per seat on an annual contract. We do not charge per environment or per agent: a developer with one seat can run as many development environments and agents as your infrastructure supports. + +## Summary + +- **Pricing is per seat**, billed annually. +- **No charge per agent or per environment.** Run as many development environments and agents per developer as your infrastructure supports. +- **Enterprise license covers your entire fleet.** A single license entitles you to deploy as many Okteto clusters as you need; we only charge for unique seats across all of them. +- **No hard cap.** New user accounts can keep being created without service interruption. Overages are settled with a true-up. +- **Self-service visibility.** See your user seat count in the [Admin Dashboard](admin/dashboard.mdx) or via the [Okteto API](admin/okteto-api.mdx) at any time. + +## Seats + +A seat is one user account in your Okteto instance, identified by an email address. When a user logs in for the first time, an account is automatically created. + +Okteto does **not** count: + +- The number of development environments a developer creates. +- The number of agents (Okteto, AI, or otherwise) that operate on behalf of that developer. +- Service accounts and bots that the platform itself uses. + +If you bought 50 seats, you can have 50 accounts in your system. Each one can run as many environments and agents as your cluster supports. + +:::note +Your contract refers to "Users" and "User Allowance". This page uses "seat"; the terms are equivalent. +::: + +## Enterprise: Multi-Cluster Licensing + +For Enterprise customers, your Okteto license covers your entire fleet. You can deploy Okteto on as many clusters as you need (production, staging, regional, per-team) at no extra cost. + +Billing counts **unique seats across the fleet**. A user with the same email in two clusters counts once. This means you can split workloads, isolate environments, or run regional clusters without paying twice for the same developer. + +## Managing Your Seat Count + +- **Delete user accounts you no longer need.** Once a user account is deleted, it disappears from the count immediately. Accounts cannot be reassigned to new users; when a different person logs in with their email, a new account is created automatically. +- **Use Okta to deprovision automatically.** If your team uses Okta, configure [Okta User Deprovisioning](admin/integrations/okta-user-deprovisioning.mdx) to delete accounts automatically when users are removed from your identity provider. +- **Use the Okteto API.** The [Okteto API](admin/okteto-api.mdx) supports listing and deleting users by ID, so you can wire account cleanup into your own offboarding scripts or integrations. + +For permanent team growth, contact your Okteto account team to purchase additional seats in advance. Add-on seats are typically cheaper than waiting for a true-up. + +## Seat Usage + +Your current account count is visible in the [Admin Dashboard](admin/dashboard.mdx) and via the [Okteto API](admin/okteto-api.mdx). + +Okteto checks user account counts monthly. If your count exceeds your allowance, your Okteto account team will reach out. + +## Seat Overages + +Okteto does not block new account creation when you exceed your seat allowance. + +When the count of user accounts exceeds your purchased seat allowance: + +1. **Okteto notifies you before invoicing.** Unless you have explicitly requested otherwise, Okteto reaches out before invoicing any true-up. Add-on seats purchased proactively are typically cheaper than waiting for the true-up. +2. **True-up at your contracted rate.** The additional user seats are billed at the per-seat price on your Order Form, pro-rated over the remaining months of your current annual term, and invoiced immediately. +3. **Renewal updated.** At the start of your next annual period, your subscription is updated to reflect the new seat count. + +## Frequently Asked Questions + +### Do I get charged when a developer runs an extra environment? + +No. Okteto charges for seats, not environments. A developer with one seat can run as many environments as your cluster supports. + +### What about AI agents or build agents that use Okteto on a developer's behalf? + +Not counted. A seat is a human, identified by email. + +### Can I reassign a seat from a former employee to their replacement? + +Accounts are not reassigned. Delete the former employee's account; when their replacement logs in with their own email, a new account is automatically created. + +### Our team grew permanently. We have 10 extra accounts in the system. What happens? + +This is a true-up scenario. The 10 additional seats are billed at your contracted rate, pro-rated over the remaining months of your annual term, and your renewal reflects the new seat count. + +### A developer left. Do I deactivate the account or delete it? + +Delete it. Deactivation does not remove the account from the count. + +### Is there a hard cap? + +No. Okteto does not block additional accounts from being created. The platform stays fully usable, and the true-up settles the difference at invoicing. + +### If we run multiple Okteto clusters, do we pay for each cluster? + +No. For Enterprise, a single license covers your entire fleet. We count unique seats across all your clusters: a developer with the same email in two clusters counts once. + +## Next Steps + +View your current seat count in the [Admin Dashboard](admin/dashboard.mdx) or query it via the [Okteto API](admin/okteto-api.mdx). To remove accounts automatically when users leave your identity provider, configure [Okta User Deprovisioning](admin/integrations/okta-user-deprovisioning.mdx). For Self-Hosted license installation, see [Okteto License](self-hosted/manage/okteto-license.mdx). diff --git a/versioned_docs/version-1.49/admin/build-service.mdx b/versioned_docs/version-1.49/admin/build-service.mdx new file mode 100644 index 000000000..f449eac5b --- /dev/null +++ b/versioned_docs/version-1.49/admin/build-service.mdx @@ -0,0 +1,114 @@ +--- +title: Build Service Management +description: Monitor and manage BuildKit performance and resource utilization +sidebar_label: Build Service +id: build-service +--- + +import Image from "@theme/Image"; + +# Build Service Management + +The Build Service admin view provides comprehensive monitoring for your BuildKit infrastructure. +This interface allows administrators to track real-time performance metrics, configure resource thresholds, and ensure optimal build performance across your Okteto instance. + +## Overview + +The Build Service uses BuildKit, a high-performance image builder, to power fast image builds and [remote executions](core/remote-execution.mdx). +The admin dashboard provides visibility into BuildKit pod health, resource utilization, and active build workloads. + +For more information about optimizing BuildKit performance, see the [BuildKit High Performance guide](self-hosted/manage/buildkit-high-performance.mdx). + +## Build queue + +The build queue routes builds to the least-loaded server and holds requests when all servers are at capacity. This prevents overload during peak usage and delivers more predictable build performance. + +The build queue is enabled by default. To disable it, set the `OKTETO_BUILD_QUEUE_ENABLED` [feature flag](reference/feature-flags.mdx) to `false`. + +## Accessing the Build Service Dashboard + +Navigate to **Admin → Build Service** in the Okteto UI to access the Build Service management interface. + +

+ Build Service Admin Dashboard +

+ +## Metrics + +The Build Service dashboard displays key metrics for each BuildKit pod: + +- **CPU Pressure**: indicates how much any process is waiting for CPU in the last 10s. A value greater than 50% is a potential signal of build performance degradation. +- **Memory Usage**: a percentage out of 100%. A value close to 70% increases your chances to face Out-Of-Memory kill events. +- **IO Pressure**: indicates how much any process is waiting for IO in the last 10s. A value greater than 30% is a potential signal of build performance degradation. +- **Active Builds**: number of concurrent builds. + +### Configurable Thresholds + +You can configure the following thresholds from the admin UI: + +#### CPU Pressure Threshold +- **Default**: 50% +- **Description**: Maximum CPU pressure allowed before a BuildKit pod is marked as busy. CPU pressure is measured in 10-second intervals and indicates how much the pod is CPU-constrained. +- **When to adjust**: Increase if builds are being queued unnecessarily when CPU usage is acceptable. Decrease if you notice build performance degradation at current levels. + +#### Memory Pressure Threshold +- **Default**: 70% +- **Description**: Maximum memory usage allowed before a BuildKit pod is marked as busy. Memory usage is reported as a percentage out of 100%. +- **When to adjust**: Increase if you have sufficient memory headroom and want to maximize pod utilization. Decrease if memory pressure is causing OOM issues. + +#### IOPS Pressure Threshold +- **Default**: 30% +- **Description**: Maximum I/O pressure allowed before a BuildKit pod is marked as busy. I/O pressure is measured in 10-second intervals and indicates disk I/O contention. +- **When to adjust**: Increase if using high-performance SSDs with greater I/O capacity. Decrease if experiencing I/O-related build slowdowns. + +### Understanding Pod Status + +Each BuildKit pod displays one of the following statuses: + +- **Ready**: The pod is healthy and below all recommended thresholds. +- **Busy**: One or more metrics exceed the recommended thresholds. +- **Starting**: The pod is initializing and not yet ready to accept builds. +- **Stopping**: The pod is gracefully terminating, allowing active builds to complete. +- **Error**: The pod has encountered an error. + +### Restarting a BuildKit Pod + +Administrators can restart individual BuildKit pods directly from the dashboard. This terminates the existing pod and creates a new one. + +#### When to Restart + +- **Stuck builds**: A build appears hung with no progress +- **Repeated failures**: Builds are failing consistently on a specific pod +- **Pod errors**: The pod shows an error status that hasn't self-resolved +- **Performance degradation**: A pod is underperforming compared to others + +#### What Happens When You Restart + +- **Active builds are retried**: Builds running on that pod are automatically retried on another available pod, or on this pod once it's recreated +- **Queued builds reroute**: If the build queue is enabled, waiting builds are routed to other available pods +- **Cache is preserved**: The build cache is stored on a persistent volume and survives the restart +- **Typical recovery time**: 30-60 seconds for the new pod to become ready + +#### How to Restart + +1. Locate the pod you want to restart in the Build Service dashboard +2. Click the **Restart** button +3. Review the confirmation dialog and click **Delete and recreate** to confirm + +## Best Practices + +### Threshold Configuration + +- **Start with defaults**: The default thresholds (50% CPU, 70% memory, 30% IOPS) work well for most workloads +- **Monitor and adjust**: Watch the metrics over time and adjust thresholds based on actual performance patterns +- **Balance utilization and performance**: Higher thresholds maximize resource utilization but may impact build performance + +## Related Documentation + +- [Build Service Overview](core/build-service.mdx) - Learn about how the Okteto Build service works +- [BuildKit High Performance](self-hosted/manage/buildkit-high-performance.mdx) - Detailed guide on optimizing BuildKit performance at high scale +- [BuildKit Helm Configuration](self-hosted/helm-configuration.mdx#buildkit) - Configure BuildKit settings in your Helm chart diff --git a/versioned_docs/version-1.37/admin/catalog.mdx b/versioned_docs/version-1.49/admin/catalog.mdx similarity index 97% rename from versioned_docs/version-1.37/admin/catalog.mdx rename to versioned_docs/version-1.49/admin/catalog.mdx index db1b9245e..7ce080b6a 100644 --- a/versioned_docs/version-1.37/admin/catalog.mdx +++ b/versioned_docs/version-1.49/admin/catalog.mdx @@ -40,7 +40,7 @@ _Only accounts with the administrator role can use this feature._ ::: ### Create and Manage Catalog Items via the Dashboard -Within the Okteto Dashboard, navigate to **Admin -> Catalog** under the Cluster Management section. On this page, click the `Add Repository` button to open the `Add Repository` form. +Within the Okteto Dashboard, navigate to **Admin -> Catalog** under the Cluster Management section. On this page, click the **Add Item** button to open the **Add Catalog Item** form. #### Add an application to the Catalog diff --git a/versioned_docs/version-1.37/admin/cleanup.mdx b/versioned_docs/version-1.49/admin/cleanup.mdx similarity index 90% rename from versioned_docs/version-1.37/admin/cleanup.mdx rename to versioned_docs/version-1.49/admin/cleanup.mdx index 2bd4c34af..363337a97 100644 --- a/versioned_docs/version-1.37/admin/cleanup.mdx +++ b/versioned_docs/version-1.49/admin/cleanup.mdx @@ -58,13 +58,13 @@ Here's how the timing works in practice: 1. Navigate to **Admin → Garbage Collector** in your Okteto dashboard 2. In the **Settings for Namespaces** section: - - Toggle **Sleep Period** on/off + - Select the **Sleep Period** from the dropdown (or select "Disabled" to turn it off) - Set sleep duration in hours (e.g., "3" for 3 hours) - Set delete period in days (e.g., "14" for 14 days) -3. In the **Settings for Preview Environments** section: +3. In the **Settings for Previews** section: - Configure similarly to Namespaces - Consider shorter periods for temporary environments -4. Click **Save** to apply changes +4. Changes apply automatically when you adjust each setting :::tip Start with conservative settings and adjust based on your team's usage patterns. Monitor the effects for a few weeks before making the settings more aggressive. @@ -99,7 +99,7 @@ Additionally, Namespaces can be manually scaled to zero by following these steps 1. Navigate to **Admin → Namespaces** under the Cluster Management section 2. Find the Namespace you want to sleep in the list 3. Click the **three dots (⋯)** on the right side of the Namespace row -4. Select **Sleep** from the dropdown menu +4. Select **Put To Sleep** from the dropdown menu 5. Confirm the action when prompted :::warning @@ -107,7 +107,7 @@ Manually sleeping a Namespace will immediately scale down all deployments and st :::

sleep option in the namespace actions dropdown menu @@ -151,7 +151,7 @@ When the delete period is reached, the Garbage Collector will: - Users must recreate environments from source :::danger -Deletion is permanent and irreversible. Ensure critical data is backed up or mark important Namespaces as persistent. +Deletion is permanent and irreversible. Ensure critical data is backed up or [mark important Namespaces as persistent](#persistent-resources). ::: ## What Counts as Activity? @@ -172,6 +172,18 @@ Additionally, if you are using the Okteto Nginx Ingress Controller, incoming req However, note that these incoming requests do not count as activity to reset the inactivity counter and keep the Namespace awake. The auto-wake behavior for incoming requests can also be disabled by [configuring the `autowake` field](self-hosted/helm-configuration.mdx#autowake). +### Custom Error Pages + +When users access endpoints that encounter errors (such as accessing a sleeping namespace before it wakes up, or when a service is unavailable), Okteto displays custom error pages with helpful hints on how to resolve the issue. + +These error pages are served by the [defaultBackend](self-hosted/helm-configuration.mdx#defaultbackend) component and provide clear explanations of what went wrong. + +Common scenarios where custom error pages appear: +- Accessing a sleeping namespace (the error page will explain the namespace is waking up) +- Service temporarily unavailable + +This feature works automatically and requires no additional configuration, providing a better user experience than generic error messages. + ### Manually Wake Sleeping Resources Okteto's UI will notify you when there are sleeping applications in your Namespace. @@ -185,7 +197,7 @@ Okteto's UI will notify you when there are sleeping applications in your Namespa **To wake specific resources:** 1. Go to **Admin → Namespaces** 2. Find the sleeping Namespace -3. Click the three dots (⋯) and select **Wake** +3. Click the three dots (⋯) and select **Wake Up** 4. Resources will begin starting automatically

@@ -210,6 +222,14 @@ This only affects [Non-Personal Namespaces](core/namespaces.mdx), Personal Names In case you are interested in the Garbage Collector but you want to skip a specific Namespace, you can mark it as `persistent`. To do so, you can add the label `dev.okteto.com/persistent` to it or [use the Admin Dashboard](admin/dashboard.mdx#namespaces). +

+ mark a namespace as persistent +

+ In case you want more granularity and only want to persist specific deployments or statefulsets within a Namespace, you can include the label `dev.okteto.com/persistent` on those resources. In that case, the Garbage Collector will ignore only those specific resources while sleeping the rest of the Namespace. @@ -247,7 +267,7 @@ If you are using Okteto Self-Hosted, you can also [configure this in the Helm Ch *Symptoms:* Personal Namespace contents are being deleted *Solutions:* -1. **Check Settings**: Verify **Personal Namespaces GC** toggle in Admin → Garbage Collector +1. **Check Settings**: Verify the **Include Personal Namespaces** toggle in Admin → Garbage Collector 2. **Understand Scope**: Remember that Personal Namespaces contents are cleaned, not the Namespaces themselves 3. **PVC Protection**: Confirm PVCs are preserved as expected diff --git a/versioned_docs/version-1.37/admin/cloud-credentials/aws.mdx b/versioned_docs/version-1.49/admin/cloud-credentials/aws.mdx similarity index 92% rename from versioned_docs/version-1.37/admin/cloud-credentials/aws.mdx rename to versioned_docs/version-1.49/admin/cloud-credentials/aws.mdx index f59959715..d679b9d77 100644 --- a/versioned_docs/version-1.37/admin/cloud-credentials/aws.mdx +++ b/versioned_docs/version-1.49/admin/cloud-credentials/aws.mdx @@ -1,12 +1,16 @@ --- title: Configure access to your AWS account using IAM Roles -description: Configure AWS credentials +description: Configure AWS IAM credentials for your Okteto instance using OIDC federation to grant development environments access to AWS resources. sidebar_label: Amazon Web Services id: aws-cloud-credentials --- import Image from "@theme/Image"; -This guide walks you through configuring AWS credentials for your Okteto instance to enable the commands in your Okteto Manifests to interact with your AWS account. +This guide walks you through configuring AWS credentials for your Okteto instance so the `deploy`, `destroy`, and `test` commands in your Okteto Manifest can interact with your AWS account. + +:::info +Cloud Credentials are injected only into the `deploy`, `destroy`, and `test` commands that Okteto runs on the cluster. They are not available inside a Development Container started with `okteto up`, nor during image builds. +::: We will focus on requesting access to an S3 bucket. However, you can extend this approach to grant access to other AWS resources by specifying a role with the necessary permissions. @@ -204,9 +208,9 @@ Please note that if you add credentials using CRDs they will be displayed in the - **Role ARN**: The Role ARN `ROLE_ARN` you created in Step 2. - **Region**: The AWS Region for the AWS STS Regional Endpoint. You can find more information about regional endpoints [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html) and [here](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sts-regionalized-endpoints.html) -- **Audience**: The Audience `AUDIENCE` that we defined in Step 1. +- **Audience JWT Claim**: The Audience `AUDIENCE` that we defined in Step 1. -Once this configuration is in place, your Okteto Manifests commands will have access to your AWS account. +Once this configuration is in place, the `deploy`, `destroy`, and `test` commands in your Okteto Manifest have access to your AWS account. ## Example Okteto Manifest diff --git a/versioned_docs/version-1.37/admin/cloud-credentials/gcp.mdx b/versioned_docs/version-1.49/admin/cloud-credentials/gcp.mdx similarity index 95% rename from versioned_docs/version-1.37/admin/cloud-credentials/gcp.mdx rename to versioned_docs/version-1.49/admin/cloud-credentials/gcp.mdx index 98610803d..8543919ec 100644 --- a/versioned_docs/version-1.37/admin/cloud-credentials/gcp.mdx +++ b/versioned_docs/version-1.49/admin/cloud-credentials/gcp.mdx @@ -1,6 +1,6 @@ --- title: Configure access to your GCP account using Workload ID -description: Configure GCP credentials +description: Configure Google Cloud credentials for your Okteto instance using Workload Identity Federation to grant development environments access to GCP resources. sidebar_label: Google Cloud id: gcp-cloud-credentials --- @@ -37,7 +37,7 @@ gcloud iam workload-identity-pools create ${POOL_ID} --location=global --display ## Step 2: Register the OIDC Identity Provider Within the newly created Workload Identity Pool, register your Kubernetes cluster as an OIDC Identity Provider in GCP. -To do this, Okteto provides the OIDC endpoint of your cluster, which can be found under the Integrations -> Cloud Credentials section of your Okteto Admin Dashboard. +To do this, Okteto provides the OIDC endpoint of your cluster, which you can find under the Integrations -> General section of your Okteto Admin Dashboard.

- {`FROM okteto/pipeline-runner:${variables.chartVersion} + {`FROM ghcr.io/okteto/pipeline-runner:${variables.chartVersion} RUN apt-get upgrade && apt-get install wget`} @@ -34,7 +34,7 @@ RUN apt-get upgrade && apt-get install wget`} Once the image has been defined, build it and push it to your container registry. ```bash -docker build -t REGISTRY/REPOSITORY:TAG +docker build -t REGISTRY/REPOSITORY:TAG . docker push REGISTRY/REPOSITORY:TAG ``` @@ -44,7 +44,7 @@ docker push REGISTRY/REPOSITORY:TAG defaultValue="self-hosted" values={[ { label: 'Self-Hosted', value: 'self-hosted', }, - { label: 'SaaS', value: 'saas', }, + { label: 'BYOC', value: 'byoc', }, ]} > @@ -61,7 +61,7 @@ installer: - + If your instance is hosted by Okteto, contact support to configure your custom image in your Okteto Instance. @@ -71,5 +71,5 @@ If your instance is hosted by Okteto, contact support to configure your custom i ## Using the Custom Image Once the configuration has been applied, all the Development Environments will be deployed using your custom image. -In order to help you troubleshoot any issues, the name of the image used during deployment is included in the pipeline logs. You can consult this in the Okteto UI. +To help troubleshoot any issues, the name of the image used during deployment is included in the pipeline logs. You can view this in the Okteto UI. diff --git a/versioned_docs/version-1.37/admin/dashboard.mdx b/versioned_docs/version-1.49/admin/dashboard.mdx similarity index 80% rename from versioned_docs/version-1.37/admin/dashboard.mdx rename to versioned_docs/version-1.49/admin/dashboard.mdx index 1a5d2d782..1606cdc36 100644 --- a/versioned_docs/version-1.37/admin/dashboard.mdx +++ b/versioned_docs/version-1.49/admin/dashboard.mdx @@ -1,6 +1,6 @@ --- title: Admin dashboard -description: Admin dashboard +description: The Admin Dashboard provides a centralized interface to manage users, Namespaces, integrations, and settings for your Okteto instance. sidebar_label: Admin dashboard id: dashboard --- @@ -14,13 +14,13 @@ The Admin Dashboard provides a web UI to see various details of your Okteto inst ## Accessing the dashboard -You can access the Admin Dashboard by clicking on the `Admin` icon on the left sidebar. Only accounts with the administrator role will be able to access the Admin Dashboard. The first user signing into your Okteto instance will automatically become the initial administrator. +You can access the Admin Dashboard by clicking **Admin** in the left sidebar. Only accounts with the administrator role will be able to access the Admin Dashboard. The first user signing into your Okteto instance will automatically become the initial administrator. You can promote other accounts to the administrator role in the `Users` section of the Admin Dashboard or by adding the `dev.okteto.com/super: "true"` label to the corresponding `serviceAccount` in Kubernetes.

Admin dashboard tabs @@ -33,6 +33,7 @@ Cluster Management - [Installation](#installation) - [Catalog](#catalog) - [Users](#users) +- [Build Service](#build-service) - [Nodes](#nodes) - [Namespaces](#namespaces) - [Previews](#previews) @@ -44,7 +45,6 @@ Settings - [Admin Variables](#admin-variables) - [Garbage Collector](#garbage-collector) - [Resource Manager](#resource-manager) -- [Okteto AI](#okteto-ai) Integrations - [General Integrations](#general-integrations) @@ -68,6 +68,10 @@ The overview section of the Admin Dashboard is designed to give you a high level - Number of Namespaces in your Okteto instance - Number of Preview Environments currently active +:::tip +The Okteto Helm chart version is also available to all users from the **Help** menu in the main navigation. This is useful when reporting issues or verifying your installation without Admin access. +::: + ## Installation Okteto is a flexible platform that streamlines your developer operations to make developers faster and more efficient. The initial installation has a few steps and we've built a guided experience to help get you setup even faster than before. @@ -108,8 +112,8 @@ On this page an administrator will be able to: - View the total number of users on the Okteto instance (The `Total` value in the top right of the table) - View each user's name, email, and avatar - View when a user was `Last Seen` (any user who recently sent any API request to Okteto, e.g. from the browser, CLI, GitHub actions) -- Change each user's role (Select `Dev` or `Admin` from the dropdown menu in the `Role` column) -- Remove users (Click the `(X) Remote` button on the far right) +- Change each user's role (Select `Developer` or `Admin` from the dropdown menu in the `Role` column) +- Remove users (Click **Remove** from the overflow menu on the far right) :::caution @@ -117,6 +121,33 @@ Removing the user will automatically remove all the namespaces owned by the dele ::: +## Build Service + +The Build Service section provides real-time Okteto Build infrastructure performance metrics. +From this dashboard, you can view comprehensive monitoring of your BuildKit infrastructure, configure resource thresholds, and ensure optimal build performance across your Okteto instance. + +

+ Build Service Dashboard +

+ +From this section, administrators can: + +- **Configure Resource Thresholds**: Set thresholds that determine when a BuildKit pod is considered "Ready" to accept new build requests: + - CPU Pressure Threshold (default: 50%) + - Memory Pressure Threshold (default: 70%) + - IOPS Pressure Threshold (default: 30%) +- **Monitor BuildKit Performance**: View real-time metrics for each BuildKit pod including CPU pressure, memory usage, IOPS, and active builds +- **View Pod Status**: See the current status of each BuildKit pod (Ready, Busy, Starting, Stopping, Error) + +The Build Service uses these thresholds to route build requests through the [build queue system](core/build-service.mdx#build-queue-system), ensuring consistent performance and fair resource distribution across your development teams. + +For detailed information about configuring and optimizing the Build Service, see the [Build Service Management Guide →](admin/build-service.mdx) + + ## Nodes In this section of the Admin Dashboard, you can find the following system information about your Kubernetes cluster, separated by node: @@ -133,9 +164,9 @@ This view enables you to manage all of the Namespaces within your Okteto instanc For each Namespace, an administrator can: - View the name, owner, status (`active` or `sleeping`), and when it was last active -- Get `read-only` access to any Namespace managed by Okteto (using the `View` option) -- Manually wake the Namespace (using the `Wake Namespace` option) -- Mark the Namespace as `persistent` using the `Keep Awake` option to prevent it from being deleted and exempt it from the [garbage collection](self-hosted/helm-configuration.mdx#gc) process +- Get read-only access to any Namespace managed by Okteto by clicking the Namespace name +- Manually wake the Namespace (using the **Wake Up** option) +- Mark the Namespace as `persistent` using the `Persistent` option to prevent it from sleeping, being deleted, and exempt it from the [garbage collection](self-hosted/helm-configuration.mdx#gc) process - [Transfer a Namespace](core/namespaces.mdx#transfer-namespace-ownership) to a new owner - View the "Last Seen" time referring to the most recent activity detected within the Namespace, [such as deploying resources or running okteto up](admin/cleanup.mdx#what-counts-as-activity). @@ -143,15 +174,9 @@ For each Namespace, an administrator can: Similar to the [Namespaces section](#namespaces), the `Previews` section shows you a list of all [Preview Environments](previews/index.mdx) that exist in your Okteto instance. -From this page, an administrator can view the default settings for the [garbage collection](self-hosted/helm-configuration.mdx#gc) configuration and view any of the listed Preview Environments. +From this page, an administrator can configure and manage any of the listed Preview Environments, including filtering, searching, and performing actions like wake, sleep, and delete. -This table provides a consolidated view about Preview Environments, including: - -- Preview Environment name -- Owner -- Scope (`Personal` or `Global`) -- Status (`Active` or `Sleeping`) -- Last seen +[See the full Preview Environments management guide →](admin/previews.mdx) ## Command Line (CLI) @@ -190,7 +215,6 @@ From this panel, you can enable the following options: These settings help ensure more predictable and consistent behavior when working with multi-service development environments. - ## SSH Known Hosts Use SSH Known Hosts to centrally manage trusted host keys for SSH-based Git operations (including submodules) across your organization. This improves security and avoids host verification prompts for remote deploys. @@ -247,30 +271,6 @@ This feature simplifies resource management, reduces manual adjustments, and enh [See our Resource Manager documentation for a full guide on how to automatically optimize your environments →](admin/resource-manager.mdx) -## Okteto AI - -The Okteto AI section allows you to enable and configure AI-powered development agents for your organization. These agents, powered by Claude Code from Anthropic, can help developers scale AI-powered workflows by running agents in fully isolated, production-like development environments without local setup or risk. - -

- Okteto AI configuration -

- -From this section, administrators can: - -- **Enable Okteto AI**: Toggle the feature on or off for your organization -- **Configure Access Control**: Choose between enabling for all users or selected users only -- **Select LLM Provider**: Configure either Anthropic (direct) or Amazon Bedrock as your provider -- **Set up Git Integration**: Configure Git tokens to enable agents to have access to the repositories that you wish - -The currently supported LLM model is **Claude Sonnet 4**, optimized for software development tasks. Support for additional models will be added in future releases. - -For detailed configuration instructions, see the [Okteto AI Administrator Configuration Guide →](okteto-ai/okteto-ai-admin-config.mdx) - - ## General Integrations This section allows you to configure Okteto integrations with other tools. diff --git a/versioned_docs/version-1.37/admin/index.mdx b/versioned_docs/version-1.49/admin/index.mdx similarity index 79% rename from versioned_docs/version-1.37/admin/index.mdx rename to versioned_docs/version-1.49/admin/index.mdx index 2d9869df4..b2208a4f1 100644 --- a/versioned_docs/version-1.37/admin/index.mdx +++ b/versioned_docs/version-1.49/admin/index.mdx @@ -17,10 +17,14 @@ A web UI for your Okteto instance. Manage users, monitor activity, and oversee e [Learn more about the Admin Dashboard →](admin/dashboard.mdx) -### Okteto AI -Accelerate development with AI-powered agents that can write, test, and debug code in isolated Okteto environments. Enable your teams to scale development workflows with Claude Code-powered assistants that work alongside developers. +### Agent Skills Rollout +Pre-install the Okteto agent skills for every developer in your organization. Adding the marketplace to Claude Code's managed settings keeps the plugin current without anyone running install commands, so agents have the Okteto CLI knowledge from their first session. The [managed settings configuration](agentic/index.mdx#updating-the-plugin) covers the setup. -[Configure Okteto AI for your organization →](okteto-ai/okteto-ai-admin-config.mdx) +### Build Service +Monitor Okteto Build performance and resource utilization. View real-time metrics for CPU pressure, memory usage, IO pressure, and active builds across your BuildKit pods. +Configure thresholds to optimize build performance and ensure consistent build times for your development teams. + +[Learn more about the Build Service →](admin/build-service.mdx) ### Okteto Catalog Discover and deploy applications from the Okteto Catalog. Simplify the setup of tools and services for your development teams with pre-configured environment templates. @@ -60,7 +64,7 @@ Pull images from a private registry in addition to [Okteto's Container Registry] ### Cloud Credentials Dynamically configure Okteto's connection to AWS and GCP, eliminating the need for developers to manage static credentials. -[Lean More about Cloud Credentials →](admin/cloud-credentials/index.mdx) +[Learn More about Cloud Credentials →](admin/cloud-credentials/index.mdx) ### Custom Installer Image for Your Pipelines Tailor Okteto to fit your unique deployment needs with Custom Installer Images, allowing your tools, frameworks, or custom configurations. diff --git a/versioned_docs/version-1.37/admin/integrations/okta-user-deprovisioning.mdx b/versioned_docs/version-1.49/admin/integrations/okta-user-deprovisioning.mdx similarity index 100% rename from versioned_docs/version-1.37/admin/integrations/okta-user-deprovisioning.mdx rename to versioned_docs/version-1.49/admin/integrations/okta-user-deprovisioning.mdx diff --git a/versioned_docs/version-1.37/admin/okteto-api.mdx b/versioned_docs/version-1.49/admin/okteto-api.mdx similarity index 97% rename from versioned_docs/version-1.37/admin/okteto-api.mdx rename to versioned_docs/version-1.49/admin/okteto-api.mdx index 8d2e754d3..3194ae78f 100644 --- a/versioned_docs/version-1.37/admin/okteto-api.mdx +++ b/versioned_docs/version-1.49/admin/okteto-api.mdx @@ -23,7 +23,7 @@ The Okteto API `BETA` is accessible with an [Admin Access Token](admin/dashboard To access the full Swagger API documentation, follow these steps: 1. Navigate to **Admin → Admin Access Tokens** in the Okteto Dashboard - 2. Click on the link to the **Public API Reference** + 2. Click on the link to the **public API reference** The Swagger documentation provides details on all available endpoints, request formats, and response structures. You can even run live tests to example responses for your query. diff --git a/versioned_docs/version-1.37/admin/okteto-insights.mdx b/versioned_docs/version-1.49/admin/okteto-insights.mdx similarity index 89% rename from versioned_docs/version-1.37/admin/okteto-insights.mdx rename to versioned_docs/version-1.49/admin/okteto-insights.mdx index b58440a33..71523991c 100644 --- a/versioned_docs/version-1.37/admin/okteto-insights.mdx +++ b/versioned_docs/version-1.49/admin/okteto-insights.mdx @@ -7,19 +7,19 @@ id: okteto-insights import Image from "@theme/Image"; -This page explains how to scrape the Okteto Insights endpoint and provides an overview of the data available in Okteto Insights +Okteto Insights exposes a metrics endpoint you can scrape to collect analytics on resource usage, builds, and deployments. :::info -For SaaS or Bring Your Own Cloud (BYOC) customers, Okteto Insights comes pre-configured with Grafana dashboards. -Please refer to our [Okteto Insights Dashboard Documentation](core/okteto-insights-dashboards.mdx) for instructions on accessing and understanding the available metrics. -Follow this guide only if you wish to enable another tool to consume Insights data. +For Bring Your Own Cloud (BYOC) customers, Okteto Insights comes pre-configured with Grafana dashboards. +See the [Okteto Insights Dashboard documentation](core/okteto-insights-dashboards.mdx) for instructions on accessing and understanding the available metrics. +Use this guide only if you want to enable another tool to consume Insights data. ::: -## Introduction +## Overview -Okteto inherently generates a lot of data from developers using the platform. This includes product usage and behavior data such as developer usage, as well as infrastructure utilization and performance data like infrastructure and platform activities. +Okteto generates data from developer activity on the platform, including product usage, infrastructure utilization, and performance metrics. -Analyzing this data can be helpful for understanding the performance of your Okteto cluster, including overall health, trends in build and deploy times, and the activity of users on the platform. +You can use this data to monitor the health of your Okteto cluster, track trends in build and deploy times, and measure user activity.

-## How to consume Okteto Insights data +## Consuming Okteto Insights data -Okteto Insights data is available via API endpoints that can be scraped using tools like Prometheus. This provides a way for Okteto Administrators to obtain and consume this data programmatically. For a quick setup, follow the below steps to turn on Insights and get your bearer token. Then, deploy our [open-source Insights Dashboards](https://github.com/okteto/insights-dashboards) to get started visualizing your Okteto data. +Okteto Insights data is available via API endpoints that can be scraped using tools like Prometheus. This allows Admins to consume this data programmatically. To get started, enable Insights, retrieve your bearer token, and deploy the [open-source Insights Dashboards](https://github.com/okteto/insights-dashboards) to visualize your Okteto data. ### Enable the Helm Setting -This feature is `disabled` by default for Self Hosted instances. To `enable` it you will need to set the helm setting [`insights.enabled`](self-hosted/helm-configuration.mdx#insights) to `true` and upgrade your Okteto instance. +This feature is `disabled` by default for Self-Hosted instances. To `enable` it you will need to set the helm setting [`insights.enabled`](self-hosted/helm-configuration.mdx#insights) to `true` and upgrade your Okteto instance. Once you enable the feature, Okteto will create a new endpoint accessible through `https://okteto.SUBDOMAIN/metrics` where data will be available in Prometheus format. This new endpoint is protected with a bearer token which is auto-generated by Okteto. Alternatively, you can specify your own token using the secret defined in this [helm setting](self-hosted/helm-configuration.mdx#insights). @@ -51,7 +51,7 @@ If you'd like to configure this yourself, you'll need to configure a scraper to scrape_interval: 5m scrape_timeout: 30s - scheme: http + scheme: https static_configs: - targets: ["okteto.:443"] # replace with your Okteto subdomain authorization: @@ -71,7 +71,7 @@ The [Open Source Dashboard Repository](https://github.com/okteto/insights-dashbo Okteto provides [open source Grafana dashboards](https://github.com/okteto/insights-dashboards) based on the Insights [data made available](#what-data-is-available). These dashboards should enable to you quickly get started using Okteto Insights and serve as a base to build more customized metrics for your organization. -Please refer to our [Okteto Insights Dashboard Documentation](core/okteto-insights-dashboards.mdx) for instructions on understanding the available metrics. +Refer to the [Okteto Insights Dashboard documentation](core/okteto-insights-dashboards.mdx) for instructions on understanding the available metrics.

+ +The Previews section of the Admin Dashboard provides administrators with a centralized view to manage all [Preview Environments](../previews/index.mdx) in your Okteto instance. + + +## Preview Scope + +Preview Environments can have one of two scopes: + +- **Global Scope** (default): The Preview Environment is accessible to all members of your organization. These previews are visible to the entire team and can be managed by users with appropriate permissions. +- **Personal Scope**: The Preview Environment is only accessible to the owner and anyone they explicitly share it with. These previews are indicated with a user icon next to the preview name in the preview list. + +Preview Environments use global scope by default. The scope determines who can view and interact with the Preview Environment within your organization. For more details on user permissions and what actions each role can perform, see [Preview Environment Permissions](../core/user-roles-and-permissions.mdx#operations-within-previews). + +:::note +The Previews dashboard doesn't include a Scope column. It marks only personal-scope previews with a user icon next to the preview name. A preview with no icon has global scope, which is the default. +::: + +## Filtering and Searching Previews + +The Preview Environments list provides several filtering options to help you find specific previews: + +- **Search** - Search for previews by name using the search box +- **Repository** - Filter by one or more repositories (searchable dropdown) +- **Status** - Filter by preview status such as active, sleeping, or error states +- **Owner** - Filter by the user who created the preview (searchable dropdown) +- **Updated** - Filter by when the preview was last updated: + - Last Hour + - Last 24 Hours + - Last 7 Days + - Last 30 Days + - Last 90 Days + +You can combine multiple filters to narrow down your search results. + +## Preview Table Columns + +The Preview Environments table displays the following information for each preview: + +- **Name** - The Preview Environment name with a user icon indicator for personal scope previews. Click the name to view details. +- **Repository** - The repository hosting the code, with a link to view it in your source control provider +- **PR** - A link to the associated pull request +- **Owner** - The user who created the Preview Environment +- **Status** - The current status of the preview (e.g., active, sleeping, deploying) +- **Last Updated** - When the preview was last modified +- **Actions** - Available actions for managing the preview + +## Managing Preview Environments + +Each preview has an actions menu with the following options: + +- **Delete** - Remove the Preview Environment. This option is only available if you have the necessary permissions. +- **Wake Up** - Wake up a sleeping Preview Environment to make it active again +- **Put To Sleep** - Put an active Preview Environment to sleep to save resources. This option is disabled for previews marked as "Persistent" +- **Persistent** - Toggle to mark a Preview Environment as persistent, preventing it from deletion and automatically sleeping due to inactivity. Because the preview remains active, it also prevents automatic deletion by the garbage collector. + +:::tip +Marking a Preview Environment as persistent with "Persistent" prevents automatic sleeping and deletion. The preview will remain available at all times until manually deleted. This is useful for long-running demos or environments that need to be always accessible. +::: diff --git a/versioned_docs/version-1.37/admin/private-repositories/github.mdx b/versioned_docs/version-1.49/admin/private-repositories/github.mdx similarity index 97% rename from versioned_docs/version-1.37/admin/private-repositories/github.mdx rename to versioned_docs/version-1.49/admin/private-repositories/github.mdx index 7b633777a..3ecd2b05b 100644 --- a/versioned_docs/version-1.37/admin/private-repositories/github.mdx +++ b/versioned_docs/version-1.49/admin/private-repositories/github.mdx @@ -24,7 +24,7 @@ There are several reasons for considering this approach including: defaultValue="self-hosted" values={[ { label: 'Self-Hosted', value: 'self-hosted', }, - { label: 'SaaS', value: 'saas', }, + { label: 'BYOC', value: 'byoc', }, ]} > @@ -33,7 +33,7 @@ Follow the guide to [configure the GitHub integration](self-hosted/install/githu - + If your instance is hosted by Okteto, the GitHub integration is enabled by default. diff --git a/versioned_docs/version-1.37/admin/private-repositories/ssh-key.mdx b/versioned_docs/version-1.49/admin/private-repositories/ssh-key.mdx similarity index 91% rename from versioned_docs/version-1.37/admin/private-repositories/ssh-key.mdx rename to versioned_docs/version-1.49/admin/private-repositories/ssh-key.mdx index df27fb9b6..309b59745 100644 --- a/versioned_docs/version-1.37/admin/private-repositories/ssh-key.mdx +++ b/versioned_docs/version-1.49/admin/private-repositories/ssh-key.mdx @@ -21,7 +21,7 @@ The public SSH is available by navigating to **Admin -> General** underneath the src={ require("@site/static/img/private-repository-ssh-key-sidebar+1.32.png").default } - alt="show SSH key" + alt="Admin General Integrations page showing the Git SSH key, Insights token, and OpenID Connect sections" width="800" />

@@ -41,7 +41,7 @@ To deploy a private repository, use the `SSH` url of your git repository. This a

add a private repository

diff --git a/versioned_docs/version-1.37/admin/registry-credentials/amazon-ecr.mdx b/versioned_docs/version-1.49/admin/registry-credentials/amazon-ecr.mdx similarity index 97% rename from versioned_docs/version-1.37/admin/registry-credentials/amazon-ecr.mdx rename to versioned_docs/version-1.49/admin/registry-credentials/amazon-ecr.mdx index 257028147..e4cce8e4b 100644 --- a/versioned_docs/version-1.37/admin/registry-credentials/amazon-ecr.mdx +++ b/versioned_docs/version-1.49/admin/registry-credentials/amazon-ecr.mdx @@ -67,8 +67,8 @@ Add the following registry credentials to the [Admin Registry Credentials view]( - **Type**: `AWS IAM User` - **Hostname**: the default registry endpoint is `https://{AWS_ACCOUNT_ID}.dkr.ecr.{REGION}.amazonaws.com` -- **Username**: `AccessKeyId` from the previous step -- **Password**: `SecretAccessKey` from the previous step +- **Access Key**: `AccessKeyId` from the previous step +- **Secret Access Key**: `SecretAccessKey` from the previous step ## Using IAM Roles via OpenID Connect (OIDC) Federation @@ -209,7 +209,7 @@ Click "Add Credential" and use the following settings: - **Type**: `AWS IAM Role` - **Hostname**: The ECR registry endpoint is `https://{AWS_ACCOUNT_ID}.dkr.ecr.{REGION}.amazonaws.com` - **Role ARN**: The Role ARN `ROLE_ARN` you created in Step 1 -- **Audience**: The Audience `AUDIENCE` you specified during the Identity Provider setup +- **Audience JWT Claim**: The Audience `AUDIENCE` you specified during the Identity Provider setup :::tip You can also configure these credentials via [Kubernetes CRDs](self-hosted/manage/crds.mdx#private-registries). This is useful when you want to automate the configuration of your Okteto instance (e.g. IaaC as Terraform or GitOps with ArgoCD). diff --git a/versioned_docs/version-1.37/admin/registry-credentials/azure-acr.mdx b/versioned_docs/version-1.49/admin/registry-credentials/azure-acr.mdx similarity index 100% rename from versioned_docs/version-1.37/admin/registry-credentials/azure-acr.mdx rename to versioned_docs/version-1.49/admin/registry-credentials/azure-acr.mdx diff --git a/versioned_docs/version-1.37/admin/registry-credentials/dockerhub.mdx b/versioned_docs/version-1.49/admin/registry-credentials/dockerhub.mdx similarity index 100% rename from versioned_docs/version-1.37/admin/registry-credentials/dockerhub.mdx rename to versioned_docs/version-1.49/admin/registry-credentials/dockerhub.mdx diff --git a/versioned_docs/version-1.37/admin/registry-credentials/google-artifact-registry.mdx b/versioned_docs/version-1.49/admin/registry-credentials/google-artifact-registry.mdx similarity index 94% rename from versioned_docs/version-1.37/admin/registry-credentials/google-artifact-registry.mdx rename to versioned_docs/version-1.49/admin/registry-credentials/google-artifact-registry.mdx index dacd9ffba..4ffded090 100644 --- a/versioned_docs/version-1.37/admin/registry-credentials/google-artifact-registry.mdx +++ b/versioned_docs/version-1.49/admin/registry-credentials/google-artifact-registry.mdx @@ -47,7 +47,7 @@ gcloud iam service-accounts keys create SA_KEY_FILE.json \ --iam-account=SA_NAME@PROJECT_ID.iam.gserviceaccount.com ``` -The command will create a file `SA_KEY_FILE.json` with rhe required credentials. You will use this file in the next step. +The command will create a file `SA_KEY_FILE.json` with the required credentials. You will use this file in the next step. ## Step 3: Configure the credentials in Okteto @@ -59,10 +59,10 @@ Click "Add Credential" and use the following settings: - **Type**: `Static` - **Hostname**: your private Google Artifact Registry endpoint, for example `europe-west1-docker.pkg.dev` - **Username**: `_json_key` -- **Password**: the content of the file `SA_KEY_FILE.json`` +- **Password**: the content of the file `SA_KEY_FILE.json` You can also use `_json_key_base64` as `username` and encode your `SA_KEY_FILE.json` as the value of the `password`: ```bash cat SA_KEY_FILE.json | base64 -``` \ No newline at end of file +``` diff --git a/versioned_docs/version-1.37/admin/registry-credentials/index.mdx b/versioned_docs/version-1.49/admin/registry-credentials/index.mdx similarity index 67% rename from versioned_docs/version-1.37/admin/registry-credentials/index.mdx rename to versioned_docs/version-1.49/admin/registry-credentials/index.mdx index 3c9d56088..8423ee638 100644 --- a/versioned_docs/version-1.37/admin/registry-credentials/index.mdx +++ b/versioned_docs/version-1.49/admin/registry-credentials/index.mdx @@ -9,6 +9,31 @@ import Image from "@theme/Image"; In the Admin Dashboard, you can set up private registry credentials for your Okteto instance. These credentials are automatically used by Okteto for various developer operations like building and deploying, so developers don't need direct credential access. Once set, all developers can access the registries through Okteto without additional steps. Additionally, you have the option to manage these credentials via [Kubernetes CRDs provided by Okteto](self-hosted/manage/crds.mdx#private-registries). +## Why configure registry credentials? + +Some container registries, most notably Docker Hub, enforce pull rate limits for unauthenticated requests. Without registry credentials configured, image pulls can fail with errors like: + +``` +toomanyrequests: You have reached your unauthenticated pull rate limit. +``` + +This can affect two flows in Okteto: + +- **Image builds** — when Dockerfiles pull base images from public registries during dev environment builds +- **Pod deployments** — when Kubelet pulls images for pods running in Okteto-managed namespaces + +Authenticated requests have significantly higher (or unlimited) rate limits, so configuring credentials avoids these failures across both flows. + +### Registries that enforce rate limits + +**Docker Hub** is the most common source of rate limit issues. Unauthenticated pulls are limited to 100 pulls per 6 hours (per IP), while authenticated users get 200 pulls per 6 hours, with higher limits on paid plans. Since many Dockerfiles use Docker Hub base images (e.g., `python:3`, `node:18`, `ruby:3-slim`), teams can hit this limit quickly. + +Other registries like **GitHub Container Registry (ghcr.io)** don't currently enforce pull rate limits for public images, but do throttle API requests (2,000/minute). Configuring credentials is still recommended where supported, as registry policies can change. + +:::tip +Even if you only use public images, configuring Docker Hub credentials is recommended to avoid hitting rate limits as your team scales. +::: +

Registry credentials add

@@ -41,7 +66,7 @@ There are three types of registries that can be configured in Okteto: - **Static** - credentials use a username and password, ideal for platforms like DockerHub. - **AWS IAM User** - Provides credentials for Amazon Elastic Container Registry (ECR) using an Access Key and a Secret Key. Okteto will exchange an ECR temporary token with AWS using these credentials. -- **AWS IAM Role** - Provides credentials for Amazon Elastic Container Registry (ECR) using a predefined AWS IAM Role. Okteto will exchange an ECR temporary token with AWS using [OIDC federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html) +- **AWS IAM Role (via OIDC)** - Provides credentials for Amazon Elastic Container Registry (ECR) using a predefined AWS IAM Role. Okteto exchanges an ECR temporary token with AWS using [OIDC federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html) Follow our guides below to learn how to retrieve your registry credentials: @@ -62,7 +87,7 @@ For sensitive data you will only see the last few characters as a hint to verify

Registry credentials detail

@@ -77,7 +102,7 @@ Click on the **Remove** button on the right of every registry credential. A conf

Registry credentials detail

@@ -92,6 +117,17 @@ This is useful, for example, if you have your own mechanism to provision credent To make sure Okteto is able to access your private registries, you can check if they are available from the [Admin dashboard](admin/dashboard.mdx#registry-credentials). If you add credentials using CRDs they will be displayed in the UI, but they can't be modified from the UI. If you want to manage them from the UI, they must be created from there. +## Self-hosted: Node-level credentials + +If you are running Okteto in a self-hosted environment, you may already have registry credentials configured at the node level (e.g., through instance profiles, credential helpers, or pre-pulled secrets on each node). This is a valid alternative to configuring credentials through the Okteto UI. + +Keep in mind that node-level credentials are not visible to Okteto. This means: + +- The Okteto [Build Service](core/build-service.mdx) won't use them — node-level credentials only apply to Kubelet image pulls, not to image builds +- Any installation task prompting you to configure registry credentials can be safely dismissed if your nodes already handle authentication + +If your builds also need authenticated access to private registries, configure credentials through the Okteto UI or [CRDs](self-hosted/manage/crds.mdx#private-registries) in addition to your node-level setup. + ## How it works Okteto runs a dedicated Kubernetes Controller to manage Registry Credentials. As part of this process, the Controller creates and manages a [Docker Config JSON](https://kubernetes.io/docs/concepts/configuration/secret/#docker-config-secrets) secret in the Okteto namespace. diff --git a/versioned_docs/version-1.37/admin/resource-manager.mdx b/versioned_docs/version-1.49/admin/resource-manager.mdx similarity index 91% rename from versioned_docs/version-1.37/admin/resource-manager.mdx rename to versioned_docs/version-1.49/admin/resource-manager.mdx index 983ef3786..f638a6e1f 100644 --- a/versioned_docs/version-1.37/admin/resource-manager.mdx +++ b/versioned_docs/version-1.49/admin/resource-manager.mdx @@ -46,16 +46,16 @@ Resource Manager is available in Okteto chart version 1.26 and above. Refer to o 1. Log in to the Okteto Admin Dashboard 1. Navigate to **Admin -> Resource Manager** under the Settings section -1. If the Resource Manager is enabled, you will see an "Manual/Automatic" toggle switch -1. Toggle the switch to "Automatic", this will activate the Resource Manager's automated resource management +1. If the Resource Manager is enabled, you see "Manual" and "Automatic" radio buttons (the default value for this setting is `Automatic`) +1. Select "Automatic" to activate the Resource Manager's automated resource management share a namespace -Once activated, the Resource Manager will immediately begin adjusting resource requests based on average utilization. +In "Automatic" mode, the Resource Manager adjusts resource requests based on average utilization. ### Customizing Resource Manager Settings You can customize the Resource Manager by adjusting the following settings in your Helm configuration: @@ -112,8 +112,8 @@ Note: Docker Compose labels are translated to Kubernetes annotations. ## Disabling the Resource Manager If you need to disable the Resource Manager temporarily, you can do so by: -- Using the toggle switch in the Admin Dashboard to disable the Resource Managers automatic adjustments - +- Selecting "Manual" in the Admin Dashboard to disable the Resource Managers automatic adjustments +{/* - To uninstall Resource Manager, you can set the `resourceManager` helm setting to `enabled: false` */} ## Troubleshooting and Support ### Metric Server Availability @@ -138,4 +138,4 @@ spec: metadata: labels: dev.okteto.com/component-name: "hello-world" -``` \ No newline at end of file +``` diff --git a/versioned_docs/version-1.37/admin/ssh-known-hosts.mdx b/versioned_docs/version-1.49/admin/ssh-known-hosts.mdx similarity index 97% rename from versioned_docs/version-1.37/admin/ssh-known-hosts.mdx rename to versioned_docs/version-1.49/admin/ssh-known-hosts.mdx index 53e5cb0f1..a9ba35de4 100644 --- a/versioned_docs/version-1.37/admin/ssh-known-hosts.mdx +++ b/versioned_docs/version-1.49/admin/ssh-known-hosts.mdx @@ -38,7 +38,7 @@ When a Git clone operation fails using one protocol, Okteto automatically attemp This fallback ensures public repositories remain accessible and doesn't compromise security, as HTTPS clones are secured through certificate authorities (CA) rather than known hosts. **Important:** For private repositories, authentication is required through at least one protocol. Configure either: -- **SSH authentication:** Add known hosts entries and configure the [Okteto-generated SSH key](https://www.okteto.com/docs/admin/private-repositories/ssh-key/) in your Git provider +- **SSH authentication:** Add known hosts entries and configure the [Okteto-generated SSH key](admin/private-repositories/ssh-key.mdx) in your Git provider - **HTTPS authentication:** Use our [GitHub App integration](admin/private-repositories/github.mdx) The fallback mechanism ensures deployment succeeds if either protocol is properly configured. diff --git a/versioned_docs/version-1.49/agentic/autonomous-workflows.mdx b/versioned_docs/version-1.49/agentic/autonomous-workflows.mdx new file mode 100644 index 000000000..a4978bdce --- /dev/null +++ b/versioned_docs/version-1.49/agentic/autonomous-workflows.mdx @@ -0,0 +1,119 @@ +--- +title: Autonomous Workflows +description: How AI agents handle the full development lifecycle from ticket to pull request using Okteto +sidebar_label: Autonomous Workflows +--- + +In autonomous mode, an agent handles the full development lifecycle without a developer in the loop: deploying an Okteto environment, writing code, running tests against live services, and opening a pull request when everything passes. This is the basis of a Software Factory, where agents pick up work from tickets or CI triggers, execute against real infrastructure, and deliver tested pull requests. The developer reviews the output, not the process. + +## How it works + +```mermaid +flowchart LR + A[Read ticket] --> B[okteto deploy] + B --> C[Write code] + C --> D[okteto deploy] + D --> E[okteto test] + E -->|pass| F[Open PR] + E -->|fail| C +``` + +1. Agent reads the ticket or issue for requirements and acceptance criteria +2. `okteto deploy --wait` to spin up the full environment +3. `okteto endpoints` to capture live URLs +4. Agent makes code changes based on requirements +5. `okteto deploy --wait` to rebuild and redeploy with updated code +6. `okteto test ` to run test containers +7. Smoke-test live endpoints (e.g., `curl` against the URLs from step 3) +8. `okteto logs --since 5m` to check for runtime errors +9. If anything fails: fix the code, redeploy, re-test +10. Commit changes and open a pull request + +:::warning +`okteto up` is never part of autonomous workflows. It's interactive and requires a human terminal. See [Command rules](agentic/best-practices.mdx#command-rules). +::: + +## Agent authentication + +For autonomous workflows triggered by CI or webhooks, the agent needs to authenticate with Okteto without a human logging in interactively. Use a [Personal Access Token](core/credentials/personal-access-tokens.mdx) and set the Okteto context before running any commands: + +```bash +okteto context use https://okteto.example.com --token $OKTETO_TOKEN +``` + +Store the token as a secret in your CI system (e.g., a GitHub Actions secret or GitLab CI variable). The agent then has the same CLI access as the token's owner. + +## Repository instructions + +The [plugin](agentic/index.mdx#installing-the-plugin) teaches the agent how to run this workflow, but the agent still decides when to reach for it by matching skill descriptions against the prompt (see [Skill activation](agentic/index.mdx#skill-activation)). A ticket that says "add a `/health` endpoint" carries no signal that the project deploys to Okteto, so the agent may implement the change and validate it locally without deploying anything. + +Add the expectation to the repository's agent instructions file (`CLAUDE.md` for Claude Code, `AGENTS.md` for most other agents), and the agent runs the deploy-test loop on every task: + +```markdown +## Verifying changes + +This project deploys to Okteto. After implementing any change, verify it in an +Okteto environment: deploy with `okteto deploy --wait` and run the test +containers defined in `okteto.yaml` with `okteto test`. +``` + +For one-off runs, the prompt works too: "implement PROJ-123 and test the change in Okteto" activates the skill directly. The instructions file is what removes the need to say it every time. + +## Workflow example: ticket to PR + +A CI pipeline or webhook triggers the agent with a ticket: + +> Add a `/health` endpoint to the API service that returns database connectivity status and uptime. + +The agent deploys the environment, captures the live URLs, then starts coding: + +```bash +okteto deploy --wait +okteto endpoints +``` + +After making the code changes, the agent redeploys and validates: + +```bash +# Rebuild and redeploy with the updated code +okteto deploy --wait + +# Run tests +okteto test integration + +# Smoke-test the new endpoint +curl -s https://api-myns.okteto.example.com/health + +# Check logs for errors +okteto logs api --since 5m +``` + +If the tests or smoke tests fail, the agent reads the error, fixes the code, redeploys, and re-tests. Once everything passes: + +```bash +git add src/api/health.ts src/api/routes.ts && git commit -m "Add /health endpoint with db status" +gh pr create --title "Add health endpoint" --body "..." +``` + +## The deploy-test loop + +The core pattern in autonomous mode: + +1. `okteto deploy --wait` builds any changed images and rolls out the updated services +2. `okteto test ` runs validation against the live environment + +The agent repeats this loop until all tests pass. Each iteration gives real feedback from a running environment, which is what lets the agent self-correct without human intervention. + +If you need to rebuild a single service without redeploying the whole environment, `okteto build ` does that. But for most workflows, `okteto deploy --wait` handles both building and deploying in one step. + +The full list of commands agents may and may not run is in [Command rules](agentic/best-practices.mdx#command-rules). For flag details on any command, see the [CLI Reference](reference/okteto-cli.mdx). + +## Isolating parallel runs + +Autonomous agents often run several tickets at once, each on its own branch in a separate git worktree. Runs that share a Namespace overwrite each other's environments. Give each run its own Namespace with `okteto namespace create` and pass `-n ` on every command, so parallel branches never collide. See [Worktree isolation](agentic/best-practices.mdx#worktree-isolation). + +## Next steps + +- [Ticket to pull request with an autonomous agent](/docs/tutorials/agent-ticket-to-pr/) — build this workflow as a GitHub Actions pipeline, step by step +- [Collaborative Workflows](agentic/collaborative-workflows.mdx) — stay in the loop and iterate with the agent +- [Best Practices](agentic/best-practices.mdx) — command rules and common pitfalls diff --git a/versioned_docs/version-1.49/agentic/best-practices.mdx b/versioned_docs/version-1.49/agentic/best-practices.mdx new file mode 100644 index 000000000..e247b3af9 --- /dev/null +++ b/versioned_docs/version-1.49/agentic/best-practices.mdx @@ -0,0 +1,173 @@ +--- +title: Best Practices and Troubleshooting +description: Common pitfalls when using AI agents with Okteto and how to avoid them +sidebar_label: Best Practices +--- + +Agents work best with Okteto when they follow the same patterns human developers use: deploy through the CLI, build with the Okteto Build Service, read `okteto.yaml` for service discovery. Most issues come from agents bypassing these patterns. + +## Command rules + +This is the full list of which commands agents may run. The collaborative and autonomous workflow pages link here. + +| Command | Agent may run? | Notes | +|---------|----------------|-------| +| `okteto deploy --wait` | Yes | Builds images and deploys all services. Always pass `--wait`. | +| `okteto build ` | Yes | Builds a single image through the Okteto Build Service. | +| `okteto test ` | Yes | Runs a test container defined in `okteto.yaml`. | +| `okteto validate` | Yes | Checks `okteto.yaml` for syntax and schema errors. | +| `okteto logs ` | Yes | Views container logs. | +| `okteto endpoints` | Yes | Lists public URLs for the environment. | +| `okteto doctor` | Yes | Generates a diagnostic bundle for troubleshooting. | +| `okteto exec -- ` | Collaborative only | Runs a command in the active Development Container. | +| `okteto status` | Collaborative only | Checks file sync progress during a dev session. | +| `okteto down` | Yes | Exits dev mode for a service. Restores the deployment without destroying the environment. | +| `okteto up ` | Never | Interactive, hangs if an agent runs it. The human runs it in collaborative mode. | +| `okteto namespace create ` | Yes | Creates an isolated Namespace for a worktree. See [Worktree isolation](#worktree-isolation). | +| `okteto namespace delete ` | Only one it created | Deletes a Namespace. Safe only for one the agent created for a worktree, never a shared or pre-existing Namespace. | +| `okteto destroy` | Only with authorization | Tears down all resources. Needs explicit policy or human approval. See [Cleanup and teardown](#cleanup-and-teardown). | +| `kubectl` / `helm` directly | No | Bypasses Okteto's resource tracking. Use `okteto deploy` instead. | + +Every command that targets an environment accepts a `-n ` flag to run against a specific Namespace without changing the active context. Agents use it to isolate git worktrees. See [Worktree isolation](#worktree-isolation). + +The sections below explain the reasoning behind the rules that matter most. + +## Best practices + +### Read `okteto.yaml` for service discovery + +Agents should read the `okteto.yaml` manifest to discover services, build targets, and test definitions. Don't hardcode service names or assume a fixed project structure. + +```bash +# Good: agent reads okteto.yaml to find services +# The plugin teaches agents to do this automatically + +# Bad: agent hardcodes "api", "frontend", "worker" +okteto build api # What if the service is called "backend"? +``` + +Reading the manifest makes the agent portable across projects. + +### Use `okteto build`, not local Docker builds + +Agents should use `okteto build` to build container images. This uses the [Okteto Build Service](core/build-service.mdx), which pushes images directly to the Okteto Registry where they're accessible to the environment. + +```bash +# Good +okteto build api + +# Bad — image won't be in the registry +docker build -t api . +``` + +### Use `okteto deploy`, not raw `kubectl` or `helm` + +`okteto deploy` handles building images, deploying services, and cleaning up resources when the environment is torn down. If an agent uses `kubectl` or `helm` directly, those resources won't show up in the Dashboard, won't get cleaned up automatically, and can leak across environments. + +```bash +# Good — builds, deploys, and tracks everything +okteto deploy --wait + +# Bad — resources get orphaned when the environment is destroyed +helm install my-release ./charts +kubectl apply -f manifests/ +``` + +### Never run `okteto up` from an agent + +`okteto up` starts an interactive development session with a terminal and file sync. It requires human interaction and will hang if an agent runs it. + +- In [collaborative mode](agentic/collaborative-workflows.mdx): the human runs `okteto up`, the agent uses `okteto exec` +- In [autonomous mode](agentic/autonomous-workflows.mdx): use `okteto deploy` + `okteto build` instead + +### Never run `okteto destroy` without authorization + +`okteto destroy` tears down all resources in the environment. An agent should never run this without explicit policy or human approval, since it could destroy shared resources or in-progress work. + +### Use `--wait` with `okteto deploy` + +Always pass `--wait` when deploying so the agent waits for services to be ready before moving on. Without it, the agent might try to test services that haven't finished starting. + +```bash +# Good — waits for all pods to be ready +okteto deploy --wait + +# Risky — services might not be ready yet +okteto deploy +``` + +## Worktree isolation + +A Namespace is the unit of isolation for everything `okteto deploy` creates. The active Namespace comes from the Okteto context, which is global to the machine, not per-directory. That matters the moment an agent works in more than one checkout at once. + +A single primary checkout can use its context's default Namespace with no extra flags. Reach for a dedicated Namespace when parallel checkouts or git worktrees would otherwise collide. Two worktrees deploying into the same Namespace overwrite each other's environments, return the wrong data from `okteto endpoints` and `okteto logs`, and an `okteto destroy` in one tears down the other. + +Give each worktree its own Namespace. The agent creates it once: + +```bash +okteto namespace create +``` + +Then it passes `-n ` on every command for the rest of the session: + +```bash +okteto deploy --wait -n +okteto build -n +okteto endpoints -n +okteto test -n +``` + +Agents derive the Namespace name from the branch or worktree directory. Okteto Namespace names are lowercase alphanumeric plus `-`, and start and end with an alphanumeric character. + +Agents use the per-command `-n ` flag, not `okteto namespace use `. The `use` command switches the active Namespace in the shared global context, which races with any other worktree or agent on the same machine. The `-n` flag is per-invocation and never mutates shared state, so it's safe under concurrency. + +## Cleanup and teardown + +Tearing an environment down matters as much as standing one up. Pick the right command, and get the authorization right. + +| Command | What it does | When to use | +|---------|--------------|-------------| +| `okteto down` | Exits dev mode for one service and restores the original deployment. Does not destroy the environment. | The developer has finished iterating on a service but wants the environment running. | +| `okteto destroy` | Tears down every resource `okteto deploy` created in the Namespace. Destructive. | The environment is no longer needed and teardown is authorized. | +| `okteto namespace delete ` | Deletes an entire Namespace and everything in it. Very destructive. | Only for a Namespace the agent created for an isolated worktree, or with explicit user instruction. | + +Reaching for `okteto destroy` when the developer only wanted to exit dev mode is a common mistake. When in doubt, `okteto down` is the safe choice. + +In [collaborative mode](agentic/collaborative-workflows.mdx), the agent surfaces `okteto destroy` as a suggestion and lets the developer run it. In [autonomous mode](agentic/autonomous-workflows.mdx), the agent runs `okteto destroy` only when the task authorizes cleanup, a cleanup policy is documented in the repo's `CLAUDE.md` or the ticket, or the environment is ephemeral and owned by the pipeline. Otherwise it leaves the environment running and reports the command the caller would use to tear it down. + +A Namespace the agent created itself for an isolated worktree is the one case where it may run `okteto namespace delete` without a separate instruction, since it owns that Namespace's teardown: + +```bash +okteto destroy -n # remove the deployed resources +okteto namespace delete # then remove the now-empty Namespace +``` + +## Troubleshooting + +### Agent hangs and becomes unresponsive + +The most common cause is the agent running `okteto up`, which is interactive and sits waiting for terminal input. Stop the agent. In collaborative mode, you keep an `okteto up` session running in your own terminal and the agent works against it with `okteto exec`. In autonomous mode, the agent uses `okteto deploy` + `okteto build` instead. The [Okteto plugin for Claude Code](agentic/index.mdx#installing-the-plugin) teaches agents to avoid this automatically. + +### Build fails + +Check the build logs from `okteto build `. Common causes include missing dependencies in the Dockerfile, a build context that doesn't include required files, or registry authentication issues. + +If the agent is trying to use `docker build` locally, switch to `okteto build` to use the Okteto Build Service. + +### Tests fail after deployment + +First, make sure you're using `okteto deploy --wait` so all pods are running before tests execute. Then check `okteto logs --since 5m` for startup errors or crash loops. Also review the `test` section of `okteto.yaml` to make sure the test container has the right image, commands, and dependencies. + +### Agent uses wrong service names + +The agent is probably not reading `okteto.yaml`. Make sure the [Okteto plugin for Claude Code](agentic/index.mdx#installing-the-plugin) is installed, which teaches the agent to auto-discover services from the manifest. + +### Environment endpoints not accessible + +Run `okteto endpoints` to get the current URLs. If nothing shows up, check that services are deployed with `okteto logs `, verify that your `okteto.yaml` or Helm chart exposes the correct ports, and confirm that `okteto deploy --wait` completed successfully. + +### Agent creates resources Okteto can't track + +This happens when the agent uses `kubectl`, `helm`, or other tools directly instead of `okteto deploy`. Resources created outside of Okteto's deploy pipeline won't appear in the Dashboard and won't be cleaned up automatically. + +Make sure all deployments go through `okteto deploy`. If you need custom commands, add them to the `deploy` section of `okteto.yaml`. diff --git a/versioned_docs/version-1.49/agentic/collaborative-workflows.mdx b/versioned_docs/version-1.49/agentic/collaborative-workflows.mdx new file mode 100644 index 000000000..5e63f00ba --- /dev/null +++ b/versioned_docs/version-1.49/agentic/collaborative-workflows.mdx @@ -0,0 +1,61 @@ +--- +title: Collaborative Workflows +description: How developers and AI agents work together using okteto up and okteto exec +sidebar_label: Collaborative Workflows +--- + +In collaborative mode, you stay in control of the development session while the agent runs commands, tests, and debugs issues inside your live Okteto environment. You manage the dev session with `okteto up`. The agent runs commands in the active Development Container using `okteto exec`. Code changes sync automatically, so when the agent edits a file, it's running in the container within seconds. No rebuilds between iterations. + +## How it works + +1. The agent runs `okteto deploy --wait` to set up the environment (or you do this yourself) +2. You run `okteto up ` in your terminal to start the dev session +3. The agent uses `okteto exec -- ` to run commands in the dev container +4. Code changes sync to the container automatically via [file sync](development/containers/file-sync/index.mdx) +5. The agent checks results with `okteto exec` and `okteto test` +6. You iterate together until the task is complete + +:::warning +`okteto up` is interactive and hangs if an agent runs it. You always start the dev session yourself. See [Command rules](agentic/best-practices.mdx#command-rules). +::: + +## Workflow example: fixing a bug + +You start the dev environment: +```bash +okteto up api +``` + +You ask the agent: +``` +The /api/orders endpoint returns a 500 error when the cart is empty. +Can you investigate and fix it? +``` + +The agent investigates: +```bash +# Reproduce the failure by running the test that covers it +okteto exec -- npm test -- --grep "empty cart" + +# After reading the code and making a fix... + +# Run the tests again to verify +okteto exec -- npm test +``` + +Because `api` is in dev mode, its live output appears in the `okteto up api` terminal you control, not in `okteto logs`. The agent reproduces and verifies the fix by running commands in the dev container with `okteto exec`. + +Since file sync is active, the agent's code changes are immediately available in the running container. No rebuild needed. + +The agent's day-to-day commands in this mode are `okteto exec` and `okteto test`. Output from the service in dev mode appears in your `okteto up` terminal, not in `okteto logs`; the agent uses `okteto logs ` for the other services in the environment. The full list of commands agents may and may not run is in [Command rules](agentic/best-practices.mdx#command-rules). For flag details on any command, see the [CLI Reference](reference/okteto-cli.mdx). + +## File sync + +When `okteto up` is running, Okteto syncs file changes between your local machine and the dev container. The agent edits files locally, changes appear in the container within seconds, and the running application picks them up immediately (assuming hot-reload or similar). There's no need to run `okteto build` or `okteto deploy` for code changes during development. + +The agent makes a change, runs a test with `okteto exec`, sees the result, and iterates. No waiting on builds. + +## Next steps + +- [Autonomous Workflows](agentic/autonomous-workflows.mdx) — let the agent handle the full lifecycle without human input +- [Best Practices](agentic/best-practices.mdx) — command rules and common pitfalls diff --git a/versioned_docs/version-1.49/agentic/index.mdx b/versioned_docs/version-1.49/agentic/index.mdx new file mode 100644 index 000000000..ea696f8d9 --- /dev/null +++ b/versioned_docs/version-1.49/agentic/index.mdx @@ -0,0 +1,123 @@ +--- +title: Agentic Workflows +description: Install the Okteto plugin for Claude Code to give AI agents the knowledge to deploy, test, and debug code in Okteto environments +--- + +AI agents are most effective when they can deploy code, run tests, and get feedback from real environments, not just read and write files locally. Okteto gives agents isolated, live environments driven by the same Okteto CLI and `okteto.yaml` that human developers use. The [Okteto plugin for Claude Code](https://github.com/okteto/okteto-agent-skills) packages that knowledge as agent skills: install it once, and in any project your agent knows which commands to run, which to never run, and how to discover your services. + +## Installing the plugin + +Run these commands in Claude Code: + +```bash +/plugin marketplace add okteto/okteto-agent-skills +/plugin install okteto +``` + +The plugin needs the [Okteto CLI installed and configured](get-started/install-okteto-cli.mdx) with your Okteto instance. Your project doesn't need an `okteto.yaml` yet. If it's missing, the onboarding skill creates one. + +## Updating the plugin + +Claude Code doesn't update third-party plugins automatically by default. To get the latest version of the plugin, run: + +```bash +/plugin marketplace update okteto-plugins +``` + +To apply updates automatically at startup instead, run `/plugin`, go to the **Marketplaces** tab, select `okteto-plugins`, and choose **Enable auto-update**. + +Platform teams can enable updates for an entire organization by adding the marketplace to Claude Code's [managed settings](https://code.claude.com/docs/en/settings#extraknownmarketplaces) with auto-update turned on: + +```json +{ + "extraKnownMarketplaces": { + "okteto-plugins": { + "source": { + "source": "github", + "repo": "okteto/okteto-agent-skills" + }, + "autoUpdate": true + } + }, + "enabledPlugins": { + "okteto@okteto-plugins": true + } +} +``` + +This pre-installs the marketplace and the plugin for every developer and keeps both current without anyone running update commands. + +## Installing in other agents + +The skills use the open [Agent Skills](https://agentskills.io) format, so the same `okteto`, `okteto-onboarding`, `okteto-debugging`, and `okteto-preview` skills run in Cursor, OpenAI Codex, GitHub Copilot, Gemini CLI, and other compatible agents. Install them with the [`skills` CLI](https://github.com/vercel-labs/skills), which detects your agent and installs into it: + +```bash +npx skills add okteto/okteto-agent-skills +``` + +Agents that read a plain instruction file can use the tool-neutral `AGENTS.md` (or, for GitHub Copilot, `.github/copilot-instructions.md`) from the [plugin repository](https://github.com/okteto/okteto-agent-skills) instead. These load the full guidance on every turn rather than on demand. + +The `/dev-setup` and `/debug-env` commands ship only with the Claude Code plugin. Every other method carries the four skills. + +## Skills and commands + +The plugin installs four skills and two slash commands: + +| | What it does | When it activates | +|---|---|---| +| `okteto` skill | Teaches the agent the Okteto CLI: deploying with `okteto deploy`, building with `okteto build`, running tests with `okteto test`, reading services from `okteto.yaml`, and the commands it must never run (like `okteto up`). | The project has an `okteto.yaml`, or you mention Okteto. | +| `okteto-onboarding` skill | Discovers your services from Docker Compose files, Helm charts, Kubernetes manifests, or Dockerfiles; drafts an `okteto.yaml`; and validates it with `okteto validate`, `okteto build`, and `okteto deploy`. | The project has no `okteto.yaml` and you ask to set it up for Okteto. | +| `okteto-debugging` skill | Triages a broken environment with a playbook per failure mode: `CrashLoopBackOff`, `OOMKilled`, `ImagePullBackOff`, `Pending`, runtime errors, deploy failures, and file sync issues. Diagnostics are read-only. | You describe an unhealthy service, or paste output showing one. | +| `okteto-preview` skill | Deploys a Preview Environment for a branch or pull request with `okteto preview deploy`, captures its endpoints, and posts the URL back. Also covers wiring previews into GitHub Actions or GitLab CI/CD. | You ask for a shareable environment or URL for a branch or pull request. | +| `/dev-setup` command | Validates the manifest, runs `okteto deploy --wait`, prints the environment URLs, and guides you into a dev session on the service you pick. | You run it. | +| `/debug-env` command | Runs a read-only health sweep of the environment and reports a root cause and fix for each unhealthy service. Pass a service name to scope it to one. | You run it. | + +## Skill activation + +Skills load on demand: the agent matches each skill's description against your prompt and against what it has already seen of the project. A prompt that mentions Okteto, or a session where the agent has already read `okteto.yaml`, activates the `okteto` skill. A generic prompt like "implement this feature" gives the agent no signal to look for Okteto, so it may write the code and validate it locally without ever deploying. + +To make Okteto verification part of every task instead of only Okteto-specific ones, add the expectation to your repository's agent instructions file — `CLAUDE.md` for Claude Code, `AGENTS.md` for most other agents: + +```markdown +## Verifying changes + +This project deploys to Okteto. After implementing any change, verify it in an +Okteto environment: deploy with `okteto deploy --wait` and run the test +containers defined in `okteto.yaml` with `okteto test`. Use the okteto skill +for all environment work. +``` + +The instructions file loads on every session, so the agent treats Okteto verification as part of the definition of done even when the prompt never mentions Okteto. + +## Example prompts + +What you say to the agent determines what happens: + +| Prompt | What the agent does | +|---|---| +| "Set this repo up for Okteto." | Creates and validates an `okteto.yaml` (onboarding skill) | +| "I have `okteto up` running for the api service. Check the logs for errors and run the test suite." | Works inside your dev session with `okteto exec` (collaborative) | +| "The `/api/orders` endpoint returns a 500 on an empty cart. Investigate and fix it." | Debugs against your live environment (collaborative) | +| "Deploy the environment, add a `/health` endpoint to the api service, run the tests, and open a PR." | Handles deploy, code, test, and PR end to end (autonomous) | +| "Pick up PROJ-123, implement it against a live environment, and open a PR when the tests pass." | Handles the full ticket lifecycle (autonomous) | + +## Collaborative and autonomous modes + +Agents work in one of two modes. Pick based on whether you want to stay in the loop. + +| | [Collaborative](agentic/collaborative-workflows.mdx) | [Autonomous](agentic/autonomous-workflows.mdx) | +|---|---|---| +| **Who drives** | You and the agent, together | The agent, end to end | +| **Triggered by** | You, in your IDE or terminal | A ticket, webhook, or CI pipeline | +| **Environment** | You run `okteto up`; the agent runs `okteto exec` inside it | The agent runs `okteto deploy` + `okteto build` directly | +| **Feedback loop** | File sync and hot-reload, instant | Deploy, test, and fix until tests pass | +| **Best for** | Pair-programming, interactive debugging | Ticket-to-PR automation, batch tasks | + +In both modes the agent follows the same [command rules](agentic/best-practices.mdx#command-rules). The one to know up front: `okteto up` is interactive and hangs if an agent runs it, so agents never run it. In collaborative mode you start it yourself, and in autonomous mode it isn't part of the workflow. + +## Next steps + +- [Getting started with Agentic Workflows](/docs/tutorials/agentic-workflows) — a hands-on walkthrough on the Movies sample application +- [Collaborative Workflows](agentic/collaborative-workflows.mdx) — work alongside your agent +- [Autonomous Workflows](agentic/autonomous-workflows.mdx) — let the agent handle it end to end +- [Best Practices](agentic/best-practices.mdx) — command rules, common pitfalls, and troubleshooting diff --git a/versioned_docs/version-1.37/archived-release-notes.mdx b/versioned_docs/version-1.49/archived-release-notes.mdx similarity index 64% rename from versioned_docs/version-1.37/archived-release-notes.mdx rename to versioned_docs/version-1.49/archived-release-notes.mdx index b1a8f7c5b..acff9a089 100644 --- a/versioned_docs/version-1.37/archived-release-notes.mdx +++ b/versioned_docs/version-1.49/archived-release-notes.mdx @@ -1,12 +1,534 @@ --- title: Archived Release Notes -description: Archived Release Notes +description: Release notes from archived Okteto versions that are no longer actively maintained, covering features and changes from older releases. sidebar_label: Archived Release notes id: archived-release-notes --- Here you can find the release notes for archived versions of Okteto. +## 1.36.2 + +12 September 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.36 is designed to work with [Okteto CLI 3.11.x](https://github.com/okteto/okteto/releases/tag/3.11.0) + +### Improvements + +- Improve Okteto UI UX by showing "Pulling" status when encountering transient pull QPS exceeded errors + +### Bug Fixes + +- Fixed an issue with Kubernetes credential configuration in the delete agent job +- Fixed a UI issue where the list of endpoints in the agent view was not scrollable + +## 1.36.1 + +9 September 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.36 is designed to work with [Okteto CLI 3.11.x](https://github.com/okteto/okteto/releases/tag/3.11.0) + +### Bug Fixes +- Fixed an issue with streaming Okteto Agent installation logs that was preventing the agent chat from loading + +## 1.36.0 + +5 September 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.36 is designed to work with [Okteto CLI 3.11.x](https://github.com/okteto/okteto/releases/tag/3.11.0) + +### Okteto AI Now Available (Beta) +Okteto AI brings the power of AI directly into your development workflow, powered by Claude Code from Anthropic. Each agent operates independently in its own Kubernetes namespace with full isolation, giving you the safety and control you need for AI-assisted development. + +#### Key Capabilities + +- **Intelligent Repository Onboarding**: Agents can quickly understand and work with existing codebases, analyzing project structure, dependencies, and patterns to get up to speed faster than ever +- **Application Scaffolding**: Generate new services, APIs, and applications from natural language descriptions, complete with best practices and proper project structure +- **Task Automation**: Automate common development tasks like adding endpoints, refactoring code, updating dependencies, or implementing new features +- **Real Containerized Environments**: All agents run in production-like Kubernetes environments with access to the same runtime, secrets, and configurations as your actual development setup +- **Parallel Execution**: Launch multiple agents simultaneously to work on different features or experiments independently + +#### For Administrators +Organization administrators have full control over Okteto AI deployment: +- Enable the feature for your organization through the Admin Dashboard under Admin > Okteto AI +- Toggle access per user to control who can launch AI agents in your organization +- Configure LLM keys - Provide your own Anthropic API key (directly from Anthropic or via Amazon Bedrock) + +We're continuously improving Okteto AI based on your feedback. Try it today and let us know how it transforms your development workflow! + +### New Features {#new-features-1.36} + +- Added a [new Public API endpoint to delete users](admin/okteto-api.mdx) +- Added support for [configuring custom init containers](self-hosted/helm-configuration.mdx#installer) in the installer job +- Pre-pull Okteto images used by jobs to accelerate job start times. This deploys a new [DaemonSet in the cluster that pre-pulls images](self-hosted/helm-configuration.mdx#prepullimages ) onto nodes. + +### Improvements {#improvements-1.36} + +- Installer now retries transient connection issues +- [Okteto CLI 3.11.0](https://github.com/okteto/okteto/releases/tag/3.11.0): Added support for overriding the [`readOnlyRootFilesystem`](reference/okteto-manifest.mdx#securitycontext-object-optional) property in the `securityContext` of dev containers defined in the Okteto Manifest + +### Bug Fixes {#bug-fixes-1.36} + +- Fixed previews layout issue that could hide logs when breadcrumb is visible +- [Okteto CLI 3.11.0](https://github.com/okteto/okteto/releases/tag/3.11.0): Fixed a panic when deploying an Okteto manifest with Divert using `okteto up` or `okteto test` +- [Okteto CLI 3.11.0](https://github.com/okteto/okteto/releases/tag/3.11.0): Fixed an issue with the `--wait` flag in `okteto deploy` when deploying a subset of services from a Compose file. The command no longer hangs until timeout + +## 1.35.2 + +29 August 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.35 is designed to work with [Okteto CLI 3.10.x](https://github.com/okteto/okteto/releases/tag/3.10.0) + +### Bug Fixes +- Downgrade BuildKit dependency to version `0.22.0` to avoid a bug that was causing a huge consumption in CPU, provoking poor performance and stuck builds. + +## 1.35.1 + +12 August 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.35 is designed to work with [Okteto CLI 3.10.x](https://github.com/okteto/okteto/releases/tag/3.10.0) + +### Bug Fixes +- Fixed an issue in the daemonset which was causing the component to fail when the Okteto instance was not using self-signed certificates nor private CAs. + +## 1.35.0 + +1 August 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.35 is designed to work with [Okteto CLI 3.10.x](https://github.com/okteto/okteto/releases/tag/3.10.0) + +### New Features {#new-features-1.35} +- Added support for [Kubernetes 1.33](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.33.md) (support for 1.30 has been removed) and [Amazon Linux 2023](https://github.com/amazonlinux/amazon-linux-2023). [Please follow our upgrade guide](self-hosted/manage/upgrade.mdx#upgrading-to-okteto-135x--kubernetes-133-support-and-amazon-linux-2023-al2023compatibility) when moving to Amazon Linux 2023 +- CIDR-based traffic filtering is now supported for BYOC (Bring Your Own Cluster) environments. Use this to improve security by restricting access to Okteto services to specific IP ranges. +- Namespace deletion now properly applies the timeout value to dev environments that use a `destroy` section in their manifest. Previously, if a dev environment took longer than 5 minutes to destroy gracefully, the overall namespace deletion would fail, even if a longer timeout was specified. +- Added support for `loadBalancerSourceRanges` in the BuildKit service configuration to better control external access +- [Okteto CLI 3.10.0](https://github.com/okteto/okteto/releases/tag/3.10.0): Okteto now supports inheriting Kubernetes `nodeSelector` and resource settings in Development Environments. When omitted from the `okteto.yaml` manifest, these values can be pulled from the base Kubernetes resources using the `OKTETO_INHERIT_KUBERNETES_RESOURCES` and `OKTETO_INHERIT_KUBERNETES_NODESELECTOR` feature flags. + +### Improvements {#improvements-1.35} +- [Okteto CLI 3.10.0](https://github.com/okteto/okteto/releases/tag/3.10.0): Improved the `okteto deploy` command to avoid rebuilding all images when deploying a compose and only a subset of services are being deployed. +- [Okteto CLI 3.10.0](https://github.com/okteto/okteto/releases/tag/3.10.0): Updated the `okteto preview destroy` command to correctly propagate the `--timeout` flag to the backend, ensuring longer destroy operations don’t fail prematurely. ⚠️ This requires both CLI 3.10.0 and Chart 1.35. +- [Okteto CLI 3.10.0](https://github.com/okteto/okteto/releases/tag/3.10.0): Enhanced `okteto context use` to better handle invalid or expired local tokens. The CLI will now prompt for login rather than failing with a non-actionable error. + +### Bug Fixes {#bug-fixes-1.35} +- Fixed an issue that prevented some development environments from waking up as expected when there were dependency cycles between dev environments +- Improved AWS IAM Role regex handling for tighter validation on Private Registry Credentials and Cloud Credentials + +### Removal Notice {#removal-notice-1.35} +- Support for Kubernetes [1.30](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.30.md) has been removed in this release. + +## 1.34 + +3 July 2025 + +This version is compatible with Kubernetes versions 1.30 to 1.32 \ +Okteto Chart release 1.34 is designed to work with [Okteto CLI 3.9.x](https://github.com/okteto/okteto/releases/tag/3.9.0) + +### Improvements {#improvements-1.34} +- [Okteto CLI 3.9.0](https://github.com/okteto/okteto/releases/tag/3.9.0): Added a [feature flag](reference/feature-flags.mdx) to return services in development to their "running" state (`okteto down`) when exiting the terminal session +- [Okteto CLI 3.9.0](https://github.com/okteto/okteto/releases/tag/3.9.0): Included a [feature flag](reference/feature-flags.mdx) to make `dev..services` wait for file synchronization to finish before running their commands during `okteto up` execution + +### Bug Fixes {#bug-fixes-1.34} + +- Fixed the "Retry Destroy" action so it now performs a graceful deletion instead of triggering a force destroy. Previously, both "Retry Destroy" and "Force Destroy" were triggering a force deletion +- Fixed breadcrumb layout regressions across several updates +- Prevented UI overflow of the redeploy button in the resources sidebar +- Fixed an error when running `okteto test` with defined artifacts but no output files; the `/okteto/artifacts` directory is now created by default to prevent execution failures + +## 1.33.1 + +19 June 2025 + +This version is compatible with Kubernetes versions 1.30 to 1.32 \ +Okteto Chart release 1.33 is designed to work with [Okteto CLI 3.8.x](https://github.com/okteto/okteto/releases/tag/3.8.0) + +### Bug Fixes + +- Fixed a glitch in the breadcrumb within the preview detail view when the monitor used has a big resolution + +## 1.33.0 + +13 June 2025 + +This version is compatible with Kubernetes versions 1.30 to 1.32 \ +Okteto Chart release 1.33 is designed to work with [Okteto CLI 3.8.x](https://github.com/okteto/okteto/releases/tag/3.8.0) + +### New Features {#new-features-1.33} + +- Introduced support for dependency-aware redeploy and destroy operations in multi-service environments + - [Okteto CLI 3.8.0](https://github.com/okteto/okteto/releases/tag/3.8.0): New `--dependencies` flag for `okteto pipeline deploy`, `okteto preview deploy`, and `okteto pipeline destroy` commands to include direct dependencies (defaults follow admin-level configuration) + - New environment variable format `OKTETO_DEPENDENCY_${DEPENDENCY_NAME}_BUILD_${BUILD_SVC}_${BUILD_ENVVAR}` for accessing dependency-specific build variables + - ⚠️ Note: The `--dependencies` flag only applies to direct dependencies and does not recurse further to avoid impacting cyclic relationships +- New [**Deployments** admin panel](admin/dashboard.mdx#deployments) allowing configuration of default behavior for: + - Redeploying all direct dependencies by default + - Destroying all direct dependencies by default +- Added a checkbox option in both the redeploy and destroy dialogs to optionally include direct dependencies when present + +### Improvements {#improvements-1.33} + +- Enforced GitHub App ID type as int64 for configmap rendering consistency to avoid fatal errors in the API components when the field was specified without quotes in the helm values +- Added breadcrumbs to the Preview Environment details page to make navigation easier +- [Okteto CLI 3.8.0](https://github.com/okteto/okteto/releases/tag/3.8.0): `okteto namespace list` now supports an `output` option to specify `json` or `yaml` formats as `okteto preview list` + +### Bug Fixes {#bug-fixes-1.33} + +- Fixed text overflow issue in Resource Manager UI for small screens +- Hid sidebar redeploy button on smaller screens to avoid UI clutter +- Fixed "back to catalog" link navigation +- Fixed ellipsis rendering issues in previews + +## 1.32.0 + +8 May 2025 + +This version is compatible with Kubernetes versions 1.30 to 1.32 \ +Okteto Chart release 1.32 is designed to work with [Okteto CLI 3.7.x](https://github.com/okteto/okteto/releases/tag/3.7.0) + +### New Features {#new-features-1.32} + +- Added support for waking up development environments without dependencies in parallel. This behavior is disabled by default and can be enabled via the [feature flag](reference/feature-flags.mdx) `OKTETO_PARALLEL_WAKE_UPS_FOR_DEVENVS`. When dependencies exist, their defined startup order is still respected + +### Improvements {#improvements-1.32} + +- Refreshed the Okteto Dashboard UI to improve the visual design and lay the groundwork for features coming later this year. The changes are purely visual; everything is still in the same place +- Included changes to prevent an empty stage `Deploy <>` log entries in the UI when deployments are triggered via `okteto deploy` from the CLI +- Upgraded our BuildKit client to [0.21.1](https://github.com/moby/buildkit/releases/tag/v0.21.1) for improved performance and stability +- Enhanced privacy and security by removing sensitive repository information when Development Environments are deployed using the GitHub App integration +- All pods deployed within a diverted Namespace now have 2 environment variables automatically injected that can be used at runtime. `OKTETO_SHARED_ENVIRONMENT` contains the name of the shared Namespace where all the services are deployed, and `OKTETO_DIVERTED_ENVIRONMENT` contains the routing key used to route the traffic to the proper version of the service (its value is the name of the Namespace where diverted services are deployed) +- Endpoints in namespaces that include diverted services are now correctly displayed in the UI when using the `nginx` driver + +### Bug Fixes {#bug-fixes-1.32} + +- [Okteto CLI 3.7.0](https://github.com/okteto/okteto/releases/tag/3.7.0): Fixed a bug in the [Smart Builds](core/build-service.mdx#smart-builds) hash calculation process that caused indefinite hangs when hundreds of untracked files existed in the local Git repository +- Unified the HTTP header used in [Divert](reference/okteto-manifest.mdx#divert) to propagate the routing key for both drivers `nginx` and `istio`. `istio` driver was using `baggage` header with the key `okteto-divert`, but `nginx` driver was using the header `baggage.okteto-divert`. Now, both drivers use the same standard [`baggage`](https://www.w3.org/TR/baggage/) header as `baggage: okteto-divert=`. For the `nginx` driver, the header `baggage.okteto-divert` is still being injected automatically for backward compatibility, but **it will be removed in the future** +- Fixed an issue when using both [Divert](reference/okteto-manifest.mdx#divert) and [`endpoints`](/docs/reference/okteto-manifest#endpoints-object-required) to deploy a Development Environment. Endpoints for the diverted namespaces were not working as expected, as the HTTP header with the routing key was not being injected into the request + +## 1.31.0 + +4 April 2025 + +This version is compatible with Kubernetes versions 1.30 to 1.32 \ +Okteto Chart release 1.31 is designed to work with [Okteto CLI 3.6.x](https://github.com/okteto/okteto/releases/tag/3.6.0) + +### Deprecation Notice {#deprecation-notice-1.31} + +- ⚠️ Important: **Support for Docker Image Manifest Schema 1 images is removed in this** (1.31) due to upstream dependency changes. If you are using older images, they may fail to pull or deploy.\ +[Learn how to check and update your images →](self-hosted/manage/upgrade.mdx#upgrading-to-okteto-131x--schema-1-image-deprecation) + +### New Features {#new-features-1.31} + +- Added a new [Okteto API endpoint](admin/okteto-api.mdx) to list users +- Added support for waking up resources within Development Environments respecting the dependencies defined through `depends_on` field in Docker Compose. By default this behavior is disabled, but it can be enabled [with the feature flag](reference/feature-flags.mdx) `OKTETO_COMPOSE_WAIT_FOR_DEPENDENCIES` (requires redeploying the application with [Okteto CLI 3.6.0](https://github.com/okteto/okteto/releases/tag/3.6.0)). +- Added support for Kubernetes [1.32](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.32.md) (previous support for 1.29 was removed) + +### Improvements {#improvements-1.31} + +- Improved error messages when ssh-keyscan error fails for deploys triggered from the UI, `okteto pipeline deploy` or `okteto preview deploy` +- Patched IngressNightmare CVE-2025-1974 to enhance platform security +- Upgraded our BuildKit client to [0.20.2](https://github.com/moby/buildkit/releases/tag/v0.20.2) + +### Bug Fixes {#bug-fixes-1.31} + +- The `baggage.divert` header is now properly propagated to downstream services when using the `nginx` divert driver, allowing services to detect diverted requests +- Fixed an issue where logs appeared out of order on initial load +- Support bundles now include Ingress NGINX logs and Helm values for installations managed via ArgoCD +- Fixed UI overflow in the deploy dialog when rendering long lists + +### Removal Notice {#removal-notice-1.31} + +- Support for Kubernetes [1.29](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.29.md) has been removed in this release. + +## 1.30.1 + +26 March 2025 + +This version is compatible with Kubernetes versions 1.29 to 1.31 \ +Okteto Chart release 1.30 is designed to work with [Okteto CLI 3.5.x](https://github.com/okteto/okteto/releases/tag/3.5.0) + +### Improvements + +- Updated ingress-nginx dependency as a preventive measure for a [critical vulnerability](https://thehackernews.com/2025/03/critical-ingress-nginx-controller.html). Note: The affected **admission webhook** component is **not enabled by default in our deployments**, but it could be enabled through helm settings + +### Bug Fixes + +- `baggage.okteto-divert` HTTP header is now included on every request going through the ingress-controller when using `nginx` driver for [Divert](reference/okteto-manifest.mdx#divert) +- [Okteto CLI 3.5.1](https://github.com/okteto/okteto/releases/tag/3.5.1): Fixed Smart Builds cache calculation when the git repository has a high number of files in the build context + +## 1.30.0 + +7 March 2025 + +This version is compatible with Kubernetes versions 1.29 to 1.31 \ +Okteto Chart release 1.30 is designed to work with [Okteto CLI 3.5.x](https://github.com/okteto/okteto/releases/tag/3.5.0) + +### Deprecation Notice {#deprecation-notice-1.30} + +- ⚠️ Important: **Support for Docker Image Manifest Schema 1 images will be removed in next release** (1.31) due to upstream dependency changes. If you are using older images, they may fail to pull or deploy.\ +[Learn how to check and update your images →](self-hosted/manage/upgrade.mdx#upgrading-to-okteto-131x--schema-1-image-deprecation) + +### New Features {#new-features-1.30} + +- Okta User De-provisioning: Okta users can now be [automatically de-provisioned in Okteto](admin/integrations/okta-user-deprovisioning.mdx) when removed from Okta +- Okteto Test Insights: You can now view average success time metrics for your Okteto Test runs in [Okteto Insights](core/okteto-insights-dashboards.mdx#test-dashboard) + +### Improvements {#improvements-1.30} + +- Automatic Cleanup of Orphaned Namespaces: Namespaces with no owner will now be automatically garbage collected to free up resources +- The ingress-nginx package has been upgraded to 4.12.0 +- Improved the interaction between helm and Horizontal Pod Autoscaler(HPA) to avoid longer upgrade periods and unnecessary BuildKit restarts when the number of replicas specified in helm values differs from the ones HPA enforces +- If a deployment via UI, `okteto pipeline deploy`, or `okteto preview deploy` can't be scheduled, it will be marked as failed after 5 minutes. +- [Okteto CLI 3.5.0](https://github.com/okteto/okteto/releases/tag/3.5.0): Files listed in .dockerignore can now be excluded from the smart build context calculation by [setting the Admin Variable](reference/feature-flags.mdx) `OKTETO_SMART_BUILDS_IGNORE_FILES_ENABLED` to `true` +- [Okteto CLI 3.5.0](https://github.com/okteto/okteto/releases/tag/3.5.0): We've optimized remote executions of Deploy and Destroy operations when buildkit execution is not needed + +### Bug Fixes {#bug-fixes-1.30} + +- Init container logs now appear before container logs in history +- [Okteto CLI 3.5.0](https://github.com/okteto/okteto/releases/tag/3.5.0): The CLI now waits if Buildkit is not available +- [Okteto CLI 3.5.0](https://github.com/okteto/okteto/releases/tag/3.5.0): The `OKTETO_AUTODEPLOY` [feature flag](reference/feature-flags.mdx) now works as intended when set +- [Okteto CLI 3.5.0](https://github.com/okteto/okteto/releases/tag/3.5.0): Fixed re-deploy logic for compose files with `depends_on` between services. If a dependency failed in a previous operation, a redeploy sometimes was being considered failed as it was taking into account the previous state + +### Removal Notice {#removal-notice-1.30} + +- Support for Kubernetes [1.28](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.28.md) has been removed in this release. + +## 1.29.0 + +7 February 2025 + +This version is compatible with Kubernetes versions 1.28 to 1.31 \ +Okteto Chart release 1.29 is designed to work with [Okteto CLI 3.4.x](https://github.com/okteto/okteto/releases/tag/3.4.0) + + +### New Features {#new-features-1.29} + +- Added support for [Kubernetes 1.31](https://kubernetes.io/blog/2024/08/13/kubernetes-v1-31-release/) +- Personal Namespaces can now be [included in your Garbage Collection Policy](admin/cleanup.mdx#applying-garbage-collection-to-personal-namespaces) + - Personal Namespaces themselves will not be deleted, but their unused resources (e.g., Pods, Services, ConfigMaps) will be removed following the Sleep and Delete Period settings + - To leave developer workflows untouched, Persistent Volume Claims (PVCs) within Personal Namespaces will not be deleted as part of this process +- Introducing the [Okteto API (Beta)](admin/okteto-api.mdx)! 🎉 Now you can get programmatic information on namespaces and applications with authenticated API requests. Access the full API documentation via the Okteto Dashboard under **Admin → Admin Access Tokens** + +### Improvements {#improvements-1.29} + +- [Okteto CLI 3.4.0](https://github.com/okteto/okteto/releases/tag/3.4.0): Optimized image building in `okteto up`: Now, only the necessary images required for the process are built, instead of building all images. This reduces build times, speeds up environment startup, and minimizes unnecessary resource usage +- [Okteto CLI 3.4.0](https://github.com/okteto/okteto/releases/tag/3.4.0): Improve warnings when a CLI user has a different version than within the accepted range set by the Okteto Admin +- Added a warning for users on older browsers that may have compatibility issues + + +### Bug Fixes {#bug-fixes-1.29} + +- Fixed an issue where [Divert](reference/okteto-manifest.mdx#divert) would not work with Docker Compose as intended +- Buildkit in rootless mode when running in Kubernetes 1.30 no longer adds a deprecated annotation +- Fixed an issue where Okteto failed to inject the ingress-nginx controller’s private IP in Okteto components when the service name was too long + +### Removal Notice {#removal-notice-1.29} + +- Support for Kubernetes [1.27](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.27.md) has been removed in this release. + + +## 1.28.2 + +14 January 2025 + +This version is compatible with Kubernetes versions 1.27 to 1.30 \ +Okteto Chart release 1.28 is designed to work with [Okteto CLI 3.3.x](https://github.com/okteto/okteto/releases/tag/3.3.1) + +### Bug Fixes + +- [Okteto CLI 3.3.1](https://github.com/okteto/okteto/releases/tag/3.3.1): Fixed an issue when deploying with divert through a docker compose file + +## 1.28.1 + +10 January 2025 + +This version is compatible with Kubernetes versions 1.27 to 1.30 \ +Okteto Chart release 1.28 is designed to work with [Okteto CLI 3.3.x](https://github.com/okteto/okteto/releases/tag/3.3.0) + +### Bug Fixes + +- [Okteto CLI 3.3.0](https://github.com/okteto/okteto/releases/tag/3.3.0): Fixed an issue where deployments of Compose files would always time out after 5 minutes +- [Okteto CLI 3.3.0](https://github.com/okteto/okteto/releases/tag/3.3.0): Resolved a permission issue when deploying Compose files with volumes that were being initialized + + +## 1.28.0 + +10 January 2025 + +This version is compatible with Kubernetes versions 1.27 to 1.30 \ +Okteto Chart release 1.28 is designed to work with [Okteto CLI 3.3.x](https://github.com/okteto/okteto/releases/tag/3.3.0) + +### New Features + +- [Okteto CLI 3.3.0](https://github.com/okteto/okteto/releases/tag/3.3.0): Introducing [Okteto Validate](reference/okteto-cli.mdx#validate), a CLI command allowing you to run validation on your Okteto Manifest +- All [external dependencies](self-hosted/manage/air-gapped.mdx) now use images hosted under our [Docker Hub organization okteto/](https://registry.hub.docker.com/u/okteto) (e.g., ingress-nginx, reloader, redis) + +### Improvements + +- Enabled hourly intervals for [Garbage Collection delete schedules](admin/cleanup.mdx#configuring-the-sleep-and-delete-periods) +- Add new `unschedulable` status for when a pod has the reason Unschedulable for more than 3 minutes +- [Okteto CLI 3.3.0](https://github.com/okteto/okteto/releases/tag/3.3.0): Upgraded our BuildKit client to [0.18.2](https://github.com/moby/buildkit/releases/tag/v0.18.2) + +### Bug Fixes + +- Addressed inconsistent states in the logs filters within the UI to improve reliability +- Fixed an issue where the okteto deploy command did not correctly receive variables specified in the commands section of an Okteto Manifest + + + +## 1.27.2 + +10 January 2025 + +This version is compatible with Kubernetes versions 1.27 to 1.30 \ +Okteto Chart release 1.27 is designed to work with [Okteto CLI 3.2.x](https://github.com/okteto/okteto/releases/tag/3.2.3) + +### Bug Fixes + +- [Okteto CLI 3.2.3](https://github.com/okteto/okteto/releases/tag/3.2.3): Fixed an issue that was provoking that deployment of compose file were timing out always after 5 minutes +- [Okteto CLI 3.2.3](https://github.com/okteto/okteto/releases/tag/3.2.3): Fixed a permission issue when deploying compose files with volumes, and the volume was being initialized + + +## 1.27.1 + +17 December 2024 + +This version is compatible with Kubernetes versions 1.27 to 1.30 \ +Okteto Chart release 1.27 is designed to work with [Okteto CLI 3.2.x](https://github.com/okteto/okteto/releases/tag/3.2.1) + +### Bug Fixes + +- Recovered `kustomize` binary as part of our default runner image. + +## 1.27.0 + +12 December 2024 + +This version is compatible with Kubernetes versions 1.27 to 1.30 \ +Okteto Chart release 1.27 is designed to work with [Okteto CLI 3.2.x](https://github.com/okteto/okteto/releases/tag/3.2.1) + +### Breaking Changes + +- Remove code for our deprecated Quickstarts feature +- Helm chart now separates registry and repository fields for overwriting container images. +Update configurations for `backend.image`, `frontend.image`, `buildkit.image`, `buildkit.rootless.image`, `registry.image` following [this guide](self-hosted/manage/air-gapped.mdx#step-2-set-up-a-private-registry-for-required-images) if you have previously overwritten these. +- `cue`, `helmfile`, `kustomize`, `yq` and `docker-credential-ecr-login` binaries were removed from the Okteto's default pipeline runner image. If you need some of those binaries in your pipelines, you can build [your own runner image](admin/custom-installer-image.mdx). + +### New Features + +- We now allow the ability for admins of Okteto to [set the minimum accepted CLI version for their team](admin/dashboard.mdx#command-line-cli). This will apply for all users who are using CLI 3.2.0 and above +- We've published the [Okteto Manifest JSON Schema for inline suggestions and validation for creating and editing Okteto manifests within your code editor](reference/okteto-manifest.mdx#validating-and-autocompleting-the-okteto-manifest-in-your-ide) +- Added support for [overwriting CLI images at the Helm chart level](self-hosted/helm-configuration.mdx#cli) +- Shipped additional support for the installation of [Okteto in Air-Gapped Environments](self-hosted/manage/air-gapped.mdx) +- Configured buildkit probes to only accept requests when buildkit is healthy +- Added support for configuring the [Okteto control plane jobs TTL at the helm level](self-hosted/helm-configuration.mdx#jobs) + +### Improvements + +- We've reorganized the [Admin Dashboard menu items](admin/dashboard.mdx) into groups for easier navigation +- For [Catalog](admin/catalog.mdx) and [Cloud Credentials](admin/cloud-credentials/index.mdx) items that were created via CRDs, we've added "read-only" tags in the Dashboard to avoid confusion on which items can be edited in the UI +- Updated buildkit cacheRatio default value to `0.5` +- The Okteto installer image is no longer needed, binaries for the installer jobs are now installed from `okteto/backend` +- [Okteto CLI 3.2.1](https://github.com/okteto/okteto/releases/tag/3.2.1): We merged `okteto/bin` and `okteto/busybox` images into the `okteto/okteto` image to reduce the number of images used in the CLI workflow +- [Okteto CLI 3.2.1](https://github.com/okteto/okteto/releases/tag/3.2.1): You can now define the Admin Variable `OKTETO_DEV_PERSISTENT_VOLUME_SIZE` to configure the default volume size for Development Containers + +### Bug Fixes + +- Added `globals.priorityClassName` to sleep/wake jobs and the `events-exporter` component +- Added new logic to filter out terminated containers from Resource Manager calculations +- Redacted service accounts from our diagnostics package +- [Okteto CLI 3.2.1](https://github.com/okteto/okteto/releases/tag/3.2.1): Fixed a problem when deploying a compose with failed health checks. We were not taking into account the timeout operation, so the deploy operation was stuck forever + +## 1.26.1 + +12 November 2024 + +This version is compatible with Kubernetes versions 1.27 to 1.30 + +### Bug Fixes + +- Fixed the calculation of the total requested CPU/memory in Resource Manager Admin View by excluding completed pods. +- Fixed an issue when Resource Manager was enabled in Manual mode and `quotas.limitranges.requests.limitRequestRatio` was also set. + +## 1.26.0 + +9 November 2024 + +This version is compatible with Kubernetes versions 1.27 to 1.30 + +### Breaking Changes {#breaking-changes-1.26} +Please read the following changes before upgrading to 1.26 + +- **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](https://www.okteto.com/docs/1.26/self-hosted/helm-configuration/#manual-migration-steps-when-renaming-the-defaultbackend-service). +- **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 + +### New Features + +- **[Introducing the Okteto Resource Manager](admin/resource-manager.mdx)**: a new feature that automatically optimizes CPU and memory requests for your environments. By analyzing real-time resource utilization, the Resource Manager dynamically adjusts resource requests to ensure efficient usage, prevent node overload, and improve overall cluster performance. This feature simplifies resource management, reduces manual adjustments, and enhances application stability, especially in larger clusters. The default installation provides recommendations but doesn't apply them automatically. [See our docs for details on how to apply these automatically](admin/resource-manager.mdx) +- Added Okteto [Garbage Collector settings to the Admin Dashboard](admin/cleanup.mdx): Admins can now manage sleep and delete periods from the Dashboard, with the ability to set different configurations for Namespaces and Preview Environments +- [Remote Execution can now be set as the default](core/remote-execution.mdx) in the Okteto Admin Dashboard, allowing admins to enforce consistent remote deploys. Remote deploys also include improvements for feature parity with local deploys, such as the ability to specify the context synchronization folder and private Git repository cloning during deploy commands using SSH keys +- Added additional feature and documentation for [running Buildkit at scale](self-hosted/manage/buildkit-high-performance.mdx) + +### Improvements + +- Okteto will now automatically create a Docker secret if one doesn't already exist in the Controller Manager. This prevents a misleading warning that was being displayed in some scenarios when deploying from the UI +- [Buildkit cache size is now automatically configured](self-hosted/helm-configuration.mdx#buildkit) based on its PVC volume size +- Removed Buildkit persistency as an installation step now that it defaults to true +- The Okteto frontend now runs rootless by default, while Buildkit operates without privileges when rootless mode is enabled +- We've [released Okteto CLI 3.1.0 with many new improvements](https://github.com/okteto/okteto/releases/tag/3.1.0) +- [Okteto CLI 3.1.0](https://github.com/okteto/okteto/releases/tag/3.1.0): Added support for a `context` field in the Okteto Manifest, allowing you to specify the working directory for commands in the `deploy` and `destroy` sections +- [Okteto CLI 3.1.0](https://github.com/okteto/okteto/releases/tag/3.1.0): [Added automatic retry for build operations](reference/feature-flags.mdx) when BuildKit is unavailable due to transient errors. The behavior can be controlled using the environment variables `OKTETO_BUILDKIT_MAX_RETRIES_FOR_TRANSIENT_ERRORS`, `OKTETO_BUILDKIT_WAIT_TIMEOUT`, and `OKTETO_BUILDKIT_RETRY_INTERVAL`. + +### Bug Fixes + +- Fixed an issue that was preventing Development Environments to be destroyed when the specified manifest doesn't exist +- Fixed a patch operation in the Okteto Insights cronjob that was causing the loss of node labels when there were concurrent operations from external processes +- Resolved an issue where build logs were not displayed in the UI when deploying dev or preview environments, causing the UI to appear frozen. Build logs now display correctly during deployments + +## 1.25.0 + +7 October 2024 + +This version is compatible with Kubernetes versions 1.27 to 1.30 + +### New Features + +- [Announcing Okteto CLI 3.0](https://www.okteto.com/blog/cli-three-release/) - upgrading to chart release 1.25 requires a CLI upgrade to 3.0 +- Announcing [Cloud Credentials](admin/cloud-credentials/index.mdx), a central location to manage your cloud provider credentials for `deploy`, `destroy`, and `test` remote operations +- Added official [support for Red Hat OpenShift](get-started/install/openshift.mdx) +- Added support and a new Namespace UI for [resource quotas at the individual Namespace level](core/namespaces.mdx#configure-namespace-quotas). This allows administrators to set the maximum resources that can be used per Namespace +- Enabling [Okteto Insights Dashboards](core/okteto-insights-dashboards.mdx) for all SaaS and BYOC users of Okteto +- Added support to allow override of [installer security context](self-hosted/helm-configuration.mdx#installer) + +### Improvements + +- Support for [`priorityClassName`](reference/okteto-manifest.mdx#priorityclassname-string-optional) and [`accessMode`](reference/okteto-manifest.mdx#persistentvolume-object-optional) for volumes created by `okteto up` +- Show more actionable feedback upon "failed to deploy okteto pipeline" error +- You can now list your Github App installations under Settings → Integrations +- Implemented a number of UI updates to ensure your Okteto experience stays smooth +- Made a number of improvements to the [Okteto Insights Dashboards](core/okteto-insights-dashboards.mdx) to display historical build and deploy data, and provide a better experience loading large datasets + +### Bug Fixes + +- [Okteto CLI 3.0](https://github.com/okteto/okteto/releases/tag/3.0.0): Fix in Smart Builds logic to properly calculate when to build a new image if the build context points to a parent folder +- Fixed wrong data parsing error from unknown git urls +- Fixed issue where interactive but hidden elements, such as links in closed deploy log stage, were wrongly accessible via keyboard navigation and screen readers +- Fixed issue preventing password managers from filling in the login token +- Reconfigured GitHub installation to error when trying to be installed by a non-admin +- Fixed external resources not being selectable on Preview Environments +- Fixed sleep namespaces job when statefulset within it is in dev mode +- Fix for Buildkit PVC cleanups in the "okteto" Namespace +- Fix keyboard navigation on Admin → Users actions dropdown menu +- Removed support for "Volumes" on the Admin Nodes view and Autoscaler + ## 1.24.2 9 September 2024 @@ -387,7 +909,7 @@ This version is compatible with Kubernetes versions 1.25 to 1.29 - Allow `okteto-bot` to use GitHub integration when deploying repositories - Fix a wrong redirect when a preview doesn't exist - Make docker config static a pull secret -- Translate compose annotations into Kubernetes labels. We had been translating compose labels into k8s annotations but not viceversa +- Translate compose annotations into Kubernetes labels. We had been translating compose labels into k8s annotations but not vice versa ## 1.18.2 @@ -997,7 +1519,7 @@ In some cases, there is a race condition recreating the controller pods in which ### Bugfixes -- When injecting host alises to go through internal network to buildkit, registry and api, don't duplicate entries for same IP. Instead, pass the list of hostnames for the IP +- When injecting host aliases to go through internal network to buildkit, registry and api, don't duplicate entries for same IP. Instead, pass the list of hostnames for the IP - Remove non-existent External Resources status that caused Deployments to show as "Deployed" with a red error badge - "Get Started" button is not active while running a "destroy all" job - Fix namespace wake up when endpoint requests is sent to paths other than root. @@ -1280,7 +1802,7 @@ May 19, 2022 - Decouple computing overloaded nodes from the autoscaler - Allow users to type in custom branch name for Github repository in the deploy modal - Add delete button to preview list -- Fix inaccesible modal elements on small screens +- Fix inaccessible modal elements on small screens - Upgrade to Okteto CLI 2.2.2 - Upgrade ingress-nginx helm chart to 4.1.0 @@ -1324,4 +1846,4 @@ April 7, 2022 ### Bugfixes - Automatically reload mutation webhook when internal certificates expire -- Fix service resource creating with NodePort defined \ No newline at end of file +- Fix service resource creating with NodePort defined diff --git a/versioned_docs/version-1.49/byoc-vs-self-hosted.mdx b/versioned_docs/version-1.49/byoc-vs-self-hosted.mdx new file mode 100644 index 000000000..83e5b6711 --- /dev/null +++ b/versioned_docs/version-1.49/byoc-vs-self-hosted.mdx @@ -0,0 +1,24 @@ +--- +title: BYOC vs. Self-Hosted +description: The difference between Okteto's Bring Your Own Cloud (BYOC) and Self-Hosted product offerings +sidebar_label: BYOC vs. Self-Hosted +id: byoc-vs-self-hosted +--- + +Okteto consists of two products: our [Okteto CLI](get-started/install-okteto-cli.mdx) and the Okteto Platform. We provide the Okteto Platform in two forms: Bring Your Own Cloud (BYOC), where Okteto runs and manages the platform in your own cloud account, and Self-Hosted, where you install and manage it in your own Kubernetes cluster using our Helm chart. Both offerings deliver the same Okteto Platform experience and features. + +# The Okteto Platform + +In addition to Okteto's [CLI](get-started/install-okteto-cli.mdx) we optionally provide the Okteto Platform. This is the other half of our product experience that provides the fully managed infrastructure for your development environments. It's what interprets the [Okteto Manifest](reference/okteto-manifest.mdx) to spin up a development environment and automates your workflows. One of the biggest advantages of the Okteto Platform is that we scale the underlying cluster infrastructure so you never have to worry about your development environments having insufficient resources to run even your most complex applications. + +Additionally, you can use the Okteto CLI without using the Okteto Platform, but there are important considerations with that use case. + +Some examples of what the Okteto Platform manages are: [configuring variables](core/okteto-variables.mdx), adding [external resources](/docs/tutorials/external-resources) into your development environment, and build and push container images to the [Okteto Registry](core/container-registry.mdx). For the full list of features, see the [Self-Hosted documentation](self-hosted/index.mdx). + +# Important things to know + +| BYOC | Self-Hosted | +| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| Okteto runs and manages the Okteto Platform in your own cloud account, handling upgrades, patching, and monitoring. | You install, upgrade, and operate the Okteto Platform in your own Kubernetes cluster. | +| You retain ownership of the cloud account and data with none of the operational overhead. | Full access to the Kubernetes cluster and fully integrates with the rest of your Kubernetes infrastructure. | +| Great for teams that want full control over their data and infrastructure without managing the platform themselves. | Great for air-gapped, highly regulated, or on-premise environments, or teams with Kubernetes expertise. | diff --git a/versioned_docs/version-1.37/byoc/aws/index.mdx b/versioned_docs/version-1.49/byoc/aws/index.mdx similarity index 80% rename from versioned_docs/version-1.37/byoc/aws/index.mdx rename to versioned_docs/version-1.49/byoc/aws/index.mdx index caf707cb4..e1230bd8e 100644 --- a/versioned_docs/version-1.37/byoc/aws/index.mdx +++ b/versioned_docs/version-1.49/byoc/aws/index.mdx @@ -23,7 +23,7 @@ Before you start, ensure the following: AWS Account Requirements: - Use a **dedicated AWS account** exclusively for Okteto. No other workloads should run in this account. - Flexible Service Control Policies (SCPs): Okteto requires elevated permissions to provision and for our SRE team to operate infrastructure. -- Disable VPC Block Public Access. Okteto uses internet-facing load balancers to expose applications. CIDR-based access controls will be available in a future release. +- Disable VPC Block Public Access. Okteto uses internet-facing load balancers to expose applications. Okteto can restrict the load balancer that exposes your applications to a list of allowed IP ranges (CIDR blocks); the Okteto control plane remains reachable over the internet. Contact your Okteto representative to set this up or to update the list. ::: ## Step 1: Get the AWS IAM Role Assumption External ID @@ -155,6 +155,19 @@ Our team will: - Install Okteto into your AWS environment - Ensure the platform is configured and ready for your team to use -You’ll be notified once installation is complete and receive onboarding support to help your team start developing with Okteto. +You'll be notified once installation is complete and receive onboarding support to help your team start developing with Okteto. -> Welcome to Okteto BYOC — we’re excited to have you on board! +## ⚠️ Cluster Management Guidelines + +Once Okteto is installed, **do not manually modify the EKS cluster or related infrastructure** through the AWS Console, AWS CLI, or Terraform. + +This includes: +- EKS cluster configuration (node groups, instance types, scaling configurations) +- Kubernetes resources in Okteto-managed namespaces +- Networking, load balancers, or storage resources created by Okteto + +Manual modifications can cause service degradation, state inconsistencies, and break our SLA commitments. If you need infrastructure changes, please contact your Okteto representative. + +For more details, see the [Cluster Management Restrictions](../#important-cluster-management-restrictions) section in the main BYOC documentation. + +> Welcome to Okteto BYOC — we're excited to have you on board! diff --git a/versioned_docs/version-1.37/byoc/gcp/index.mdx b/versioned_docs/version-1.49/byoc/gcp/index.mdx similarity index 51% rename from versioned_docs/version-1.37/byoc/gcp/index.mdx rename to versioned_docs/version-1.49/byoc/gcp/index.mdx index ff8880ae3..7789ffc1a 100644 --- a/versioned_docs/version-1.37/byoc/gcp/index.mdx +++ b/versioned_docs/version-1.49/byoc/gcp/index.mdx @@ -23,22 +23,21 @@ Getting started with Okteto BYOC on GCP is simple. You’ll just need to: Once the project is created, contact your Okteto representative and share the following: - The name and ID of your GCP project -- The email address of the Okteto service account (provided by your sales contact) to which permissions should be granted ## Step 2: Grant Access -Your sales rep will provide a service account that Okteto uses to access your project. Grant that service account the **Admin** role in the project you just created: +Your Okteto representative will provide the email address of the Okteto service account. Grant that service account the **Admin** role in the project you just created: ```bash gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ - --member="serviceAccount:okteto-infra@yourdomain.iam.gserviceaccount.com" \ + --member="serviceAccount:OKTETO_SERVICE_ACCOUNT_EMAIL" \ --role="roles/admin" ``` -Replace YOUR_PROJECT_ID and the service account as instructed by your technical contact. The service account will look like an email address, similar to the above example. +Replace `YOUR_PROJECT_ID` with your GCP project ID and `OKTETO_SERVICE_ACCOUNT_EMAIL` with the service account email provided by your Okteto representative. ## ✅ What Happens Next -Once you’ve granted access, we’ll take it from here. +Once you've granted access, we'll take it from here. Our team will: - Set up and configure a GKE cluster in your GCP project @@ -46,4 +45,17 @@ Our team will: - Keep it updated securely based on our GitOps practices - Ensure the platform is fully operational and ready for use -You’ll be notified once installation is complete and receive onboarding support to help your team start building with Okteto. +You'll be notified once installation is complete and receive onboarding support to help your team start building with Okteto. + +## ⚠️ Cluster Management Guidelines + +Once Okteto is installed, **do not manually modify the GKE cluster or related infrastructure** through the GCP Console, `gcloud` CLI, or Terraform. + +This includes: +- GKE cluster configuration (node pools, machine types, disk configurations) +- Kubernetes resources in Okteto-managed namespaces +- Networking, load balancers, or storage resources created by Okteto + +Manual modifications can cause service degradation, state inconsistencies, and break our SLA commitments. If you need infrastructure changes, please contact your Okteto representative. + +For more details, see the [Cluster Management Restrictions](../#important-cluster-management-restrictions) section in the main BYOC documentation. diff --git a/versioned_docs/version-1.49/byoc/index.mdx b/versioned_docs/version-1.49/byoc/index.mdx new file mode 100644 index 000000000..f046eecf9 --- /dev/null +++ b/versioned_docs/version-1.49/byoc/index.mdx @@ -0,0 +1,74 @@ +--- +title: Okteto Bring Your Own Cloud (BYOC) +description: Introduction to Okteto Bring Your Own Cloud (BYOC) +--- + +Okteto’s Bring Your Own Cloud (BYOC) offering allows you to run Okteto on your own cloud infrastructure while still enjoying the benefits of a fully managed experience. + +This is ideal for teams who need to meet strict security or compliance requirements, operate at high-scale, require custom infrastructure configurations, or simply want to maintain full control over their environments. + +We currently support BYOC on: + +- [**Amazon Web Services (AWS)**](byoc/aws/index.mdx) +- [**Google Cloud Platform (GCP)**](byoc/gcp/index.mdx) + +## How the BYOC Model Works + +With BYOC, you bring the cloud provider account; we bring the platform and operational expertise. + +- You provision and secure the cloud account +- Okteto creates the all the necessary cloud infrastructure and software components +- Our team manages and maintains Okteto on your cloud, including upgrades, monitoring, and incident response +- You retain full ownership of your cloud environment and data + +## 🤝 What You Can Expect from Okteto + +When you connect your cloud to Okteto: + +- Okteto installs and manages its components in your cloud +- Our team handles upgrades, patching, and observability of Okteto services +- You retain full control of your cluster and data, Okteto only interacts with workloads required for our platform to function +- Continuous monitoring and observability of Okteto services +- Support and guidance is provided by our team throughout your journey + +## ⚠️ Important: Cluster Management Restrictions {#important-cluster-management-restrictions} + +**Do not manually modify cluster infrastructure directly in your cloud provider console or CLI**, even though you have the necessary permissions. + +### What You Should Not Modify + +- Kubernetes cluster configuration (node pools, machine types, disk sizes, etc.) +- Resources in Okteto-managed namespaces (including `okteto`, `default`, and system namespaces) +- Infrastructure managed by Okteto's configuration management +- Load balancers, networking, or storage resources created by Okteto + +### Why This Is Critical + +Manual modifications to cluster infrastructure create several serious problems: + +1. **Infrastructure State Conflicts**: Okteto manages your cluster infrastructure with automated daily reconciliation. Manual changes create state inconsistencies that can cause: + - Automatic reversion of your changes during the next reconciliation + - Configuration management failures that prevent critical updates + - Unintended resource deletions or recreations + +2. **SLA and Support Impact**: When you modify infrastructure directly, Okteto cannot guarantee our SLA commitments. The remediation for issues may be entirely on your side, outside of our control. + +3. **Missing Context**: Okteto's infrastructure is configured based on specific architectural decisions and requirements. Manual changes without this context can cause unexpected side effects or service degradation. + +4. **Monitoring and Alerting**: Direct modifications can trigger false alerts for our SRE team and mask real issues that need attention. + +### What To Do Instead + +If you need infrastructure changes or want to install additional tools: +- **Contact Okteto first** - reach out to your Okteto representative or support team +- We'll coordinate the change through proper channels to ensure it's compatible with our managed infrastructure +- For approved changes, we'll implement them through our infrastructure management tooling to maintain consistency + +**If you manage infrastructure yourself, the BYOC model is not the right fit.** BYOC means Okteto manages the cluster while you retain ownership of the cloud account and data. + +## Getting Started + +Ready to get started? Head to the BYOC Onboarding Guide for your cloud provider: + +- [**Amazon Web Services (AWS)**](byoc/aws/index.mdx) +- [**Google Cloud Platform (GCP)**](byoc/gcp/index.mdx) \ No newline at end of file diff --git a/versioned_docs/version-1.37/core/build-service.mdx b/versioned_docs/version-1.49/core/build-service.mdx similarity index 64% rename from versioned_docs/version-1.37/core/build-service.mdx rename to versioned_docs/version-1.49/core/build-service.mdx index 539d07c0f..75f41d849 100644 --- a/versioned_docs/version-1.37/core/build-service.mdx +++ b/versioned_docs/version-1.49/core/build-service.mdx @@ -1,7 +1,7 @@ --- -title: Okteto Build service -description: The Okteto Build service allows you to build your container images remotely -sidebar_label: Okteto Build service +title: Okteto Build Service +description: The Okteto Build Service allows you to build your container images remotely +sidebar_label: Okteto Build Service id: build-service --- @@ -15,13 +15,15 @@ The following image illustrates this process:

Buildkit architecture

The Okteto Build service addresses common issues that often slow down image builds such as limited local resources, inefficient emulation, and the lack of reusing images and cache layers already computed by other team members. +On Self-Hosted installations, Admins can run the BuildKit server in [rootless mode](self-hosted/helm-configuration.mdx#rootless) so that builds do not run in a privileged container. + ## How to build your images The Okteto CLI is automatically configured to interact with the Okteto Build service (follow our docs to [install and configure the Okteto CLI](get-started/install-okteto-cli.mdx)). @@ -51,6 +53,40 @@ okteto build Read our documentation about the [`build` section](reference/okteto-manifest.mdx#build-object-optional) and the [`okteto build` command](reference/okteto-cli.mdx#build) for more information. +## Dockerfile Compatibility + +Okteto Build is compatible with Dockerfile syntax. We leverage BuildKit's full capabilities, so any valid Dockerfile will work seamlessly with the Okteto Build service. + +### Mount Cache ID Management + +The only difference in Okteto Build compared to standard Docker behavior is how we manage the default ID for [mount caches](https://docs.docker.com/build/cache/optimize/#use-your-package-manager-wisely). + +**Docker's default behavior:** +- The default cache ID is based solely on the target path +- Example: `RUN --mount=type=cache,target=/go/pkg/mod` uses `/go/pkg/mod` as the cache ID + +**Okteto's default behavior:** +- The default cache ID is based on the target path **and** the current git repository name +- Example: For repository `myapp`, the same mount would use `myapp-/go/pkg/mod` as the cache ID + +This difference ensures that different repositories using the same target folder don't accidentally share the same cache, which could lead to unexpected behavior or conflicts. + +### Sharing Caches Between Repositories + +If you want to explicitly share caches between different repositories, you can manually set the cache ID: + +```dockerfile +# Explicitly set a cache ID to share between repositories +RUN --mount=type=cache,target=/go/pkg/mod,id=shared-go-cache \ + go mod download + +# Or share npm cache across multiple projects +RUN --mount=type=cache,target=/root/.npm,id=shared-npm-cache \ + npm ci +``` + +For more information about mount caches and cache optimization, see the [official Docker documentation on build cache](https://docs.docker.com/build/cache/optimize/#use-your-package-manager-wisely). + ## Smart Builds Buildkit comes with a local cache to reuse cache layers between image builds. @@ -91,7 +127,7 @@ As you can see in the following image, the image is pushed to `okteto/api:09f8e`

Smart builds

@@ -103,7 +139,7 @@ The following image illustrates this process:

Smart builds

@@ -125,7 +161,7 @@ Instead, the image `david/api:okteto` is re-tagged to `okteto/api:09f8e` to reme

Smart builds

@@ -185,6 +221,21 @@ You can also disable Smart Builds by setting the environment variable `OKTETO_SM If you define `OKTETO_SMART_BUILDS_ENABLED=false` as an [Admin Variable](admin/dashboard.mdx#admin-variables), Smart Builds is disabled for all the image builds for all developers in your organization. Admin variables are equivalent to defining that variable on every developer's machine. +## Build Queue System + +Okteto implements a build queue system to ensure consistent build performance and fair resource distribution across your development teams. When you execute a build command, Okteto automatically routes your build to the Okteto Build pod with the lowest resource utilization based on real-time metrics (CPU pressure, memory usage, and IOPS). + +If all Okteto Build pods are busy (exceeding configured resource thresholds), your build request enters a queue and waits until a build pod becomes ready. +This happens when builds finish and resources are freed, or when new build pods are created through the Okteto Build [Horizontal Pod Autoscaler](self-hosted/manage/buildkit-high-performance.mdx#4-enable-hpa-to-optimize-performance-and-costs). + +The Build Queue System ensures that builds have consistent performance by preventing Okteto Build pods from being overloaded during high-demand periods. +Administrators can monitor Okteto Build performance, configure resource thresholds, and fine-tune the build queue behavior through the [Build Service admin dashboard](admin/build-service.mdx). + +### Queue Wait Experience + +When all Okteto Build pods are busy, the Okteto CLI will wait for an available build pod before starting your build. During this time, you'll see clear messages indicating your position in the queue and the waiting status. The CLI automatically retries with exponential backoff to minimize unnecessary requests while ensuring your build starts as soon as resources become available. + +If the wait time exceeds the configured timeout (default 10 minutes), the build will fail with an error message suggesting you contact your Okteto administrators to increase the number of Okteto Build instances or adjust the resource threshold configuration. You can configure this timeout by setting the `OKTETO_BUILDKIT_QUEUE_WAIT_TIMEOUT` environment variable (e.g., `OKTETO_BUILDKIT_QUEUE_WAIT_TIMEOUT=15m`). ## Advanced timeouts configuration diff --git a/versioned_docs/version-1.37/core/container-registry.mdx b/versioned_docs/version-1.49/core/container-registry.mdx similarity index 100% rename from versioned_docs/version-1.37/core/container-registry.mdx rename to versioned_docs/version-1.49/core/container-registry.mdx diff --git a/versioned_docs/version-1.37/core/credentials/environment-variables.mdx b/versioned_docs/version-1.49/core/credentials/environment-variables.mdx similarity index 100% rename from versioned_docs/version-1.37/core/credentials/environment-variables.mdx rename to versioned_docs/version-1.49/core/credentials/environment-variables.mdx diff --git a/versioned_docs/version-1.37/core/credentials/kubernetes-credentials.mdx b/versioned_docs/version-1.49/core/credentials/kubernetes-credentials.mdx similarity index 92% rename from versioned_docs/version-1.37/core/credentials/kubernetes-credentials.mdx rename to versioned_docs/version-1.49/core/credentials/kubernetes-credentials.mdx index 241405f01..29b62856b 100644 --- a/versioned_docs/version-1.37/core/credentials/kubernetes-credentials.mdx +++ b/versioned_docs/version-1.49/core/credentials/kubernetes-credentials.mdx @@ -18,8 +18,8 @@ If this is your first time using the Okteto CLI, install it following [this guid The next thing you need to do is to configure your Okteto context to point to your Okteto instance. To do this, run the `okteto context` command: -```console -$ okteto context use https://okteto.example.com +```bash +okteto context use https://okteto.example.com ``` ```console @@ -39,8 +39,8 @@ Now that you have installed Okteto CLI and it is connected to your Okteto instan Having your Okteto context configured to access Okteto, run the following command: -```console -$ okteto kubeconfig +```bash +okteto kubeconfig ``` ```console @@ -65,16 +65,16 @@ Once downloaded, point your `KUBECONFIG` environment variable to the credentials > -```console -$ export KUBECONFIG=$HOME/Downloads/okteto-kube.config:${KUBECONFIG:-$HOME/.kube/config} +```bash +export KUBECONFIG=$HOME/Downloads/okteto-kube.config:${KUBECONFIG:-$HOME/.kube/config} ``` -```console -> $Env:KUBECONFIG=("$HOME\Downloads\okteto-kube.config;$Env:KUBECONFIG;$HOME\.kube\config") +```powershell +$Env:KUBECONFIG=("$HOME\Downloads\okteto-kube.config;$Env:KUBECONFIG;$HOME\.kube\config") ``` @@ -83,9 +83,10 @@ $ export KUBECONFIG=$HOME/Downloads/okteto-kube.config:${KUBECONFIG:-$HOME/.kube To see that the new configuration is working, enter this command: -```console -$ kubectl get all +```bash +kubectl get all ``` + ```console No resources found. ``` diff --git a/versioned_docs/version-1.37/core/credentials/personal-access-tokens.mdx b/versioned_docs/version-1.49/core/credentials/personal-access-tokens.mdx similarity index 86% rename from versioned_docs/version-1.37/core/credentials/personal-access-tokens.mdx rename to versioned_docs/version-1.49/core/credentials/personal-access-tokens.mdx index 261b683e8..9b04b1443 100644 --- a/versioned_docs/version-1.37/core/credentials/personal-access-tokens.mdx +++ b/versioned_docs/version-1.49/core/credentials/personal-access-tokens.mdx @@ -15,11 +15,12 @@ You can use Personal Access Tokens instead of OAuth to authenticate with Okteto. 1. Navigate to the Okteto Dashboard 1. Click on the **Settings** icon on the navigation bar at the left. +1. Click on the **Personal Access Tokens** sidebar item. 1. Click on the **New Token** button.

new token

@@ -27,7 +28,7 @@ You can use Personal Access Tokens instead of OAuth to authenticate with Okteto.

token name

@@ -35,7 +36,7 @@ You can use Personal Access Tokens instead of OAuth to authenticate with Okteto.

copy token to clipboard

@@ -76,15 +77,15 @@ The state and expiration date of every token will be displayed in the UI. Once you have a token, you can use it to authenticate with the [Okteto CLI](reference/okteto-cli.mdx) instead of using your browser, as shown below: -```console -$ okteto context use https://okteto.example.com --token $YOUR_TOKEN +```bash +okteto context use https://okteto.example.com --token $YOUR_TOKEN ``` Personal Access Tokens can also be used when setting the `OKTETO_TOKEN` environment variable. -```console -$ export OKTETO_TOKEN=xxxxxxx -$ okteto namespace create test-cindy +```bash +export OKTETO_TOKEN=xxxxxxx +okteto namespace create test-cindy ``` ### Revoking a Personal Access Token @@ -96,7 +97,7 @@ $ okteto namespace create test-cindy

delete a token

diff --git a/versioned_docs/version-1.49/core/divert.mdx b/versioned_docs/version-1.49/core/divert.mdx new file mode 100644 index 000000000..3a54463a2 --- /dev/null +++ b/versioned_docs/version-1.49/core/divert.mdx @@ -0,0 +1,238 @@ +--- +title: Divert +description: Intelligent traffic routing for efficient microservice development +sidebar_label: Divert +id: divert +--- + +import Image from "@theme/Image"; + +Divert is Okteto's intelligent traffic routing system that enables developers to work efficiently with subsets of microservice applications. Instead of spinning up complete copies of your entire application stack for each developer, Divert allows you to deploy only the services you're actively modifying while seamlessly connecting to stable, shared versions of everything else. + +## What is Divert? + +Divert transforms how teams develop microservices by making selective service deployment both practical and transparent to your application code. With Divert, you can: + +- **Deploy only what you change**: Work on 1-2 services instead of managing 20+ +- **Get shareable preview URLs**: Receive real URLs others can access to test your work-in-progress +- **Start developing in seconds**: Skip waiting for databases, message queues, and third-party services to initialize +- **Collaborate without conflicts**: Multiple developers work on different services simultaneously +- **Reduce infrastructure costs**: Share expensive resources like databases and message queues across your team +- **Test against real services**: No more mocks or stubs for services you're not modifying + +## How Divert Works + +Divert creates lightweight development environments containing only your modified services, then intelligently routes traffic between your services and shared infrastructure based on HTTP headers. + +### The Divert Flow + +1. A shared environment runs the complete application stack (e.g., in a `staging` namespace) +2. You create a personal Development Environment deploying only the service(s) you're modifying +3. Divert automatically routes traffic: + - Requests with your namespace header → Your version of the service + - Requests to services you haven't deployed → Shared versions in the staging namespace + - Database, queue, and external service calls → Shared infrastructure +4. Your application works normally, unaware it's communicating with services across namespaces + +### Shared environment requirements + +The shared environment must run in an Okteto-managed Namespace — a Namespace that Okteto deployed, such as with [`okteto deploy`](../get-started/deploy-your-app/deploy.mdx) or a [Preview Environment](../previews/index.mdx). Divert routes traffic to the services in the shared Namespace and, depending on the driver, reads or modifies their ingresses or Istio VirtualServices. Okteto performs these operations with your Okteto credentials, so it needs to manage that Namespace. + +Pointing Divert at a Namespace that Okteto did not deploy — for example, an existing `core` namespace you manage yourself — is not officially supported. If your shared services run in a Namespace outside Okteto, redeploy or duplicate them into an Okteto-managed Namespace and set `divert.namespace` to that Namespace. + +### Traffic Routing Mechanism + +Divert uses the W3C Trace Context standard `baggage` header for routing decisions: + +``` +baggage: okteto-divert=alice-feature +``` + +This header: + +- Routes traffic to your diverted services when they exist +- Falls back to shared services automatically +- Propagates through your entire application call chain when properly instrumented + +### Architecture Example + +Consider a Movies application with multiple microservices. Alice is working on the frontend and only needs to deploy that service: + +```mermaid +graph TB + User[User Request] + Frontend["Frontend (React)
Alice's personal version"] + Catalog[Catalog Service] + API[API Gateway] + Rent[Rent Service] + MongoDB[(MongoDB)] + PostgreSQL[(PostgreSQL)] + Kafka[(Kafka)] + + User --> Frontend + Frontend --> Catalog + Frontend --> API + Frontend --> Rent + Catalog --> MongoDB + API --> PostgreSQL + Rent --> Kafka + + classDef personal fill:#00d1ca,stroke:#00a89c,color:#000 + classDef shared fill:#e8e8e8,stroke:#999,color:#000 + classDef infrastructure fill:#f5f5f5,stroke:#ccc,color:#000 + + class Frontend personal + class Catalog,API,Rent shared + class MongoDB,PostgreSQL,Kafka infrastructure +``` + +**Key Points:** +- **Alice's services** (teal): Only the Frontend is deployed in her namespace +- **Shared services** (gray): Catalog, API Gateway, and Rent Service run in staging +- **Shared infrastructure** (gray): Databases and message queues run in staging + +Alice doesn't need to deploy or manage the catalog service, rent service, API gateway, MongoDB, PostgreSQL, or Kafka. Divert handles all the routing transparently. + +## Divert Drivers + +Okteto supports two implementations of Divert to accommodate different infrastructure setups: + +| Driver | Use Case | Requirements | +|--------|----------|--------------| +| **nginx** (default) | Standard Okteto installations | Uses Okteto's built-in nginx ingress with optional Linkerd for service mesh | +| **istio** | Environments with existing Istio service mesh | Requires Istio installation (non-default Okteto configuration) | + +Both drivers provide the same developer experience and use the same `okteto.yaml` configuration. The difference is in the underlying routing technology. + +:::info +Both drivers now use the same baggage header format: `baggage: okteto-divert=`. This was unified in Okteto 1.31+ for consistency. +::: + +### Driver Selection Guide + +**Choose nginx driver (default) when:** +- Using standard Okteto installation +- You want the simplest setup +- Optional: You can add Linkerd for advanced service mesh features + +**Choose istio driver when:** +- Your cluster already has Istio installed +- You prefer Istio's VirtualService-based routing +- Your team is familiar with Istio configuration + +:::tip +**Istio vs Linkerd**: These serve different purposes. **Istio is a divert driver** (alternative to nginx), while **Linkerd enhances the nginx driver** (optional add-on). You cannot use both Istio driver and Linkerd together. See the [admin configuration guide](self-hosted/install/divert/index.mdx) for details. +::: + +## What Services Should Be Shared? + +Divert works best when you share stable, resource-intensive services that developers rarely modify directly. + +### Commonly Shared Services + +| Service Type | Why Share It | Examples | +|--------------|--------------|----------| +| **Databases** | Expensive, slow to initialize, stable schemas | PostgreSQL, MongoDB, Redis, MySQL | +| **Message Queues** | Complex setup, shared infrastructure | Kafka, RabbitMQ, SQS, Redis Pub/Sub | +| **Third-party APIs** | External dependencies, no local version | Payment gateways, auth providers, email services | +| **Legacy Services** | Rarely modified, complex to run | Mainframe connectors, monoliths | +| **ML/AI Models** | Resource-intensive, stable interfaces | Recommendation engines, NLP services | +| **Object Storage** | Shared test data, binary assets | S3, MinIO, Azure Blob Storage | + +## Real Team Scenario + +Consider a team working on the Movies application: + +| Developer | Task | Diverted Services | Shared Services | +|-----------|------|-------------------|-----------------| +| **Alice** | New UI for movie cards | frontend | catalog, api, rent, worker, all databases | +| **Bob** | Add discount logic | rent, worker | frontend, catalog, api, all databases | +| **Carla** | Rental history API | api | frontend, catalog, rent, worker, all databases | +| **David** | Performance testing | catalog | frontend, api, rent, worker, all databases | + +All four developers work simultaneously without conflicts: + +- They share expensive infrastructure (databases, Kafka) +- Each has isolated versions of services they're modifying +- Changes don't affect other developers +- Testing happens against real services, not mocks + +## Resource Comparison + +### Without Divert (per developer) + +- 5+ application services +- 3+ databases/queues +- ~4GB RAM and 2 CPU cores minimum +- 5-10 minutes to spin up everything +- Full infrastructure cost per person + +### With Divert (per developer) + +- 1-2 services they're actually modifying +- ~500MB RAM and 0.5 CPU cores +- 10-30 seconds to start developing +- Access to real shared data and services +- **~80% reduction in infrastructure costs** + +## Header Propagation Requirement + +For Divert to work across service boundaries, your services must propagate the `baggage` header to downstream calls. This ensures that when Service A calls Service B, the routing header travels with the request. + +### Propagation Pattern + +``` +User Request (with baggage header) + │ + ▼ +Frontend (reads header, includes in API calls) + │ + ▼ +API Service (reads header, includes in database/queue calls) + │ + ▼ +Backend Services (reads header, includes in further calls) +``` + +### Example Implementations + +**JavaScript/Node.js:** +```javascript +// Extract from incoming request +const baggage = req.headers['baggage']; + +// Include in outgoing requests +fetch('http://catalog-service/api/movies', { + headers: { 'baggage': baggage } +}); +``` + +**Go:** +```go +// Extract from incoming request +baggage := r.Header.Get("baggage") + +// Include in outgoing requests +req, _ := http.NewRequest("GET", "http://catalog-service/api/movies", nil) +req.Header.Set("baggage", baggage) +``` + +**Java/Spring:** +```java +// Using Spring's WebClient +webClient.get() + .uri("http://catalog-service/api/movies") + .header("baggage", baggage) + .retrieve(); +``` + +:::tip +Beyond HTTP routing, the baggage header can also be used to route messages to different queues/topics, redirect requests to services in other namespaces, and dynamically select database instances. See the [implementation guide](../development/using-divert.mdx) for detailed patterns. +::: + +## Next Steps + +- **[Using Divert](../development/using-divert.mdx)** - Implementation details, manifest configuration, and code patterns +- **[Divert Tutorial](/docs/tutorials/divert)** - Step-by-step getting started guide +- **[Manifest Reference](../reference/okteto-manifest.mdx#divert)** - Complete configuration options +- **[Self-Hosted Configuration](../self-hosted/install/divert/index.mdx)** - Admin setup for Divert drivers diff --git a/versioned_docs/version-1.37/core/endpoints/automatic-ssl.mdx b/versioned_docs/version-1.49/core/endpoints/automatic-ssl.mdx similarity index 100% rename from versioned_docs/version-1.37/core/endpoints/automatic-ssl.mdx rename to versioned_docs/version-1.49/core/endpoints/automatic-ssl.mdx diff --git a/versioned_docs/version-1.37/core/endpoints/private-endpoints.mdx b/versioned_docs/version-1.49/core/endpoints/private-endpoints.mdx similarity index 98% rename from versioned_docs/version-1.37/core/endpoints/private-endpoints.mdx rename to versioned_docs/version-1.49/core/endpoints/private-endpoints.mdx index c36d56351..80bdcdb89 100644 --- a/versioned_docs/version-1.37/core/endpoints/private-endpoints.mdx +++ b/versioned_docs/version-1.49/core/endpoints/private-endpoints.mdx @@ -98,7 +98,8 @@ spec: backend: service: name: hello-world - port: 8080 + port: + number: 8080 ``` If you only want to protect certain endpoints of you application (e.g the admin portal, or your metrics endpoint), we recommend that you create two ingresses: diff --git a/versioned_docs/version-1.49/core/index.mdx b/versioned_docs/version-1.49/core/index.mdx new file mode 100644 index 000000000..ccb65e923 --- /dev/null +++ b/versioned_docs/version-1.49/core/index.mdx @@ -0,0 +1,69 @@ +--- +title: Core Concepts +description: Okteto organizes development around Namespaces, credentials, networking, builds, and a central manifest. +--- + +Okteto organizes development around isolated Namespaces, built-in networking, a remote Build Service, and a central manifest that ties everything together. These concepts apply whether you are deploying a single service or managing a multi-team platform. + +## Environment and access + +### Namespaces + +[Namespaces](core/namespaces.mdx) are isolated workspaces where Development Environments run. Each developer gets a personal Namespace, and you can create shared Namespaces for team collaboration. + +### Credentials + +Okteto supports three types of credentials to access your environments: + +- [Kubernetes credentials](core/credentials/kubernetes-credentials.mdx) — connect `kubectl` and other tools to your Okteto Namespace +- [Personal Access Tokens](core/credentials/personal-access-tokens.mdx) — authenticate CLI and API access +- [Environment variables](core/credentials/environment-variables.mdx) — manage secrets and configuration + +### User roles and permissions + +Okteto uses [role-based access control (RBAC)](core/user-roles-and-permissions.mdx) with two roles: Admin and Developer. + +## Networking + +### Endpoints + +Okteto automatically generates HTTPS endpoints for your deployed services, with SSL certificates managed for you. + +- [Automatic SSL](core/endpoints/automatic-ssl.mdx) — auto-generated HTTPS endpoints for your services +- [Private endpoints](core/endpoints/private-endpoints.mdx) — restrict access to internal services + +### Divert + +[Divert](core/divert.mdx) routes traffic across microservice environments so you only deploy the services you are modifying, connecting to shared versions of everything else. + +## Build and configuration + +### Okteto Manifest + +The [Okteto Manifest](core/okteto-manifest.mdx) (`okteto.yaml`) is the central configuration for building, deploying, testing, and developing your application in Okteto. It defines everything from build targets to Development Container settings. + +### Okteto Variables + +[Okteto Variables](core/okteto-variables.mdx) let you save configuration values and inject them automatically at deployment time. Variables can be scoped to a Namespace, user, or Admin level. + +### Build Service + +The [Okteto Build Service](core/build-service.mdx) builds container images remotely and pushes them automatically to Okteto Registry. + +### Container registry + +Each Okteto Namespace has its own space in [Okteto Registry](core/container-registry.mdx) to store and pull images. + +### Remote Execution + +[Remote Execution](core/remote-execution.mdx) runs your deploy, test, and destroy commands in the cluster rather than on your local machine, ensuring consistent, reproducible operations. + +## Data and observability + +### Insights dashboards + +[Okteto Insights](core/okteto-insights-dashboards.mdx) tracks build times, deploy frequency, resource usage, and user activity across your cluster. + +### Volume Snapshots + +[Volume Snapshots](core/use-volume-snapshots.mdx) let you initialize a persistent volume from a previous snapshot, so you can seed Development Environments with realistic data. diff --git a/versioned_docs/version-1.37/core/namespaces.mdx b/versioned_docs/version-1.49/core/namespaces.mdx similarity index 94% rename from versioned_docs/version-1.37/core/namespaces.mdx rename to versioned_docs/version-1.49/core/namespaces.mdx index b9b73b250..730bdfbc2 100644 --- a/versioned_docs/version-1.37/core/namespaces.mdx +++ b/versioned_docs/version-1.49/core/namespaces.mdx @@ -83,7 +83,7 @@ If the Resource Manager is not enabled, the Metrics tab will display basic Stora share a Namespace @@ -118,7 +118,7 @@ To transfer a Namespace to a new owner, go to the **Okteto Dashboard -> Admin ->

transfer a Namespace @@ -141,11 +141,11 @@ User specific variables will not transfer along with a Namespace. If the Namespa New user specific variables can be added to a transferred Namespace if desired to avoid future failures. Details on [adding variables can be found here](core/okteto-variables.mdx). ::: -### Keep Awake to Prevent a Namespace from Sleeping +### Mark a Namespace as Persistent to Prevent it from Sleeping and Deletion -Administrators can mark a Namespace as `persistent` using the `Keep Awake` option to prevent it from being deleted and exempt it from the [garbage collection](self-hosted/helm-configuration.mdx#gc) process. +Administrators can mark a Namespace as `persistent` using the `Persistent` option to prevent it from sleeping, being deleted, and exempt it from the [garbage collection](self-hosted/helm-configuration.mdx#gc) process. -To do so, navigate to the **Okteto Dashboard -> Admin -> Namespaces** under the Cluster Management section. Then locate the Namespace that you would like to Keep Awake. Click on the three dots `...` to display the Namespace menu. From the Namespace menu select `Keep Awake`. +To do so, navigate to the **Okteto Dashboard -> Admin -> Namespaces** under the Cluster Management section. Then locate the Namespace that you would like to mark as persistent. Click on the three dots `...` to display the Namespace menu. From the Namespace menu select `Persistent`. ### Garbage collection settings diff --git a/versioned_docs/version-1.37/core/okteto-insights-dashboards.mdx b/versioned_docs/version-1.49/core/okteto-insights-dashboards.mdx similarity index 84% rename from versioned_docs/version-1.37/core/okteto-insights-dashboards.mdx rename to versioned_docs/version-1.49/core/okteto-insights-dashboards.mdx index ecb0b1a05..82d8a344b 100644 --- a/versioned_docs/version-1.37/core/okteto-insights-dashboards.mdx +++ b/versioned_docs/version-1.49/core/okteto-insights-dashboards.mdx @@ -27,8 +27,9 @@ Okteto provides the following dashboards out of the box: - [Dashboards Available](#dashboards-available) - [Activity Dashboard](#activity-dashboard) - - [Builds Dashboard](#builds-dashboard) + - [Build Service Dashboard](#build-service-dashboard) - [Cluster Nodes Dashboard](#cluster-nodes-dashboard) + - [Images Dashboard](#images-dashboard) - [Deploy Dashboard](#deploy-dashboard) - [Namespace Dashboard](#namespace-dashboard) - [Nodes Dashboard](#nodes-dashboard) @@ -55,21 +56,36 @@ The Activity dashboard provides metrics to help you track platform adoption and --- -### Builds Dashboard +### Build Service Dashboard -Analyzes build efficiency, duration, and error rates. +Analyzes the [Okteto Build Service](build-service.mdx) performance and resource utilization. + +**Why Use This Dashboard?** +- Identify resource bottlenecks in the build service +- Monitor build concurrency and distribution across BuildKit pods +- Optimize BuildKit pod resource allocation +- Troubleshoot build performance degradation **Key Metrics:** -- Build duration trends -- Build success/failure rates +- Total number of replicas for BuildKit pods +- Total active builds across all BuildKit pods -**Filter Options:** -- **Development Environment** – Select specific Okteto environments to display data for -- **Image** – Filter by container image +Okteto Build Service Insights Dashboard + +**Key Metrics per BuildKit pod:** +- Active builds per BuildKit pod +- BuildKit pod CPU and memory consumption trends +- CPU pressure and throttling indicators +- Number of disk read/write operations and I/O pressure metrics +- Available inodes to prevent build failures Okteto Build Insights Dashboard @@ -95,6 +111,26 @@ Pods under-utilizing their CPU/memory requests leads to wasted infrastructure, w --- +### Images Dashboard + +Analyzes build efficiency, duration, and error rates. + +**Key Metrics:** +- Build duration trends +- Build success/failure rates + +**Filter Options:** +- **Development Environment** – Select specific Okteto environments to display data for +- **Image** – Filter by container image + +Okteto Images Insights Dashboard + +--- + ### Deploy Dashboard The Deploy dashboard helps you analyze the evolution of application deployments, focusing on both duration and error rates. @@ -133,7 +169,7 @@ The Pods section displays the number of Pods active in the namespace over time, Okteto Pods Insights Dashboard @@ -192,7 +228,7 @@ The Test dashboard helps you analyze the evolution of Okteto Test runs, focusing Okteto Deploy Insights Dashboard diff --git a/versioned_docs/version-1.37/core/okteto-manifest.mdx b/versioned_docs/version-1.49/core/okteto-manifest.mdx similarity index 96% rename from versioned_docs/version-1.37/core/okteto-manifest.mdx rename to versioned_docs/version-1.49/core/okteto-manifest.mdx index bb9dda186..eddcfe1ca 100644 --- a/versioned_docs/version-1.37/core/okteto-manifest.mdx +++ b/versioned_docs/version-1.49/core/okteto-manifest.mdx @@ -41,7 +41,7 @@ build: npmrc: .npmrc ``` -This configuration defines images to be built for three services: `api`, and `frontend`. It also defines a `context` for each image, which tells Okteto which folder/subfolder to use for building each container image. +This configuration defines images to be built for two services: `api` and `frontend`. It also defines a `context` for each image, which tells Okteto which folder/subfolder to use for building each container image. In this case, Okteto is using the `api` subfolder for the `api` image, and the `frontend` subfolder for the `frontend` image. For the `frontend` image, it's also defining the `dockerfile` path and a build secret. Refer to our documentation to learn more about [the `build` section](reference/okteto-manifest.mdx#build-object-optional) and how [Okteto Build works](core/build-service.mdx). @@ -102,7 +102,7 @@ Your `destroy` section might look like this: ```yaml destroy: - image: okteto/pipeline-runner:1.0.0-sam + image: ghcr.io/okteto/pipeline-runner:1.0.0-sam commands: - name: destroy worker service command: | @@ -181,7 +181,7 @@ Your `test` section might look like this: ```yaml test: unit: - image: okteto/golang:1 + image: ghcr.io/okteto/golang:1 artifacts: - coverage.out caches: @@ -193,7 +193,7 @@ test: integration: depends_on: - unit - image: okteto/golang:1 + image: ghcr.io/okteto/golang:1 context: integration commands: - make tests diff --git a/versioned_docs/version-1.37/core/okteto-variables.mdx b/versioned_docs/version-1.49/core/okteto-variables.mdx similarity index 88% rename from versioned_docs/version-1.37/core/okteto-variables.mdx rename to versioned_docs/version-1.49/core/okteto-variables.mdx index bbb4df721..a8852c62e 100644 --- a/versioned_docs/version-1.37/core/okteto-variables.mdx +++ b/versioned_docs/version-1.49/core/okteto-variables.mdx @@ -107,7 +107,7 @@ Okteto automatically shares variables passed with the `--var` flag during the `d For example: -```console +```bash okteto deploy --var MY_VAR=hello ``` @@ -198,14 +198,14 @@ External Resources are defined in the Okteto manifest and have a name and a URL. deploy: - name: Create AWS infrastructure command: | - # Example: some infrastructure has been provisioned - - terraform init -backend-config=./config/${ENV}/backend.hcl - - terraform plan -var-file=./config/${ENV}/terraform.tfvars -out tfplan - - terraform apply tfplan - - terraform output -json > tfout.json + # Example: some infrastructure has been provisioned + terraform init -backend-config=./config/${ENV}/backend.hcl + terraform plan -var-file=./config/${ENV}/terraform.tfvars -out tfplan + terraform apply tfplan + terraform output -json > tfout.json - # I configure the external resource URL - - echo OKTETO_EXTERNAL_SQS_ENDPOINTS_QUEUE_URL=$(cat tfout.json | jq -r '.queue_url') >> $OKTETO_ENV + # I configure the external resource URL + echo OKTETO_EXTERNAL_SQS_ENDPOINTS_QUEUE_URL=$(cat tfout.json | jq -r '.queue_url') >> $OKTETO_ENV external: sqs: @@ -217,12 +217,23 @@ external: ## Built-in by Okteto -### Default Environment Variables +### Runtime Environment Variables (Injected into Pods) -The following environment variables are automatically injected by Okteto. You can use them in the manifest and `deploy`, `destroy` and `test` sections, including your scripts and tools (e.g. `Makefile`). +Okteto automatically injects the following environment variables into every pod managed by Okteto at runtime. These variables are available within your application containers: - **`OKTETO_DOMAIN`**: The domain where Okteto exposes your application endpoints. - **`OKTETO_NAMESPACE`**: The namespace where your application is installed. +- **`OKTETO_MANAGED_POD`**: Set to `true` for all pods managed by Okteto. Useful for identifying and filtering Okteto-managed pods. + +### Deployment Environment Variables + +The following environment variables are automatically injected by Okteto during deployment operations. You can use them in the manifest and `deploy`, `destroy` and `test` sections, including your scripts and tools (e.g. `Makefile`). + +:::note +`OKTETO_DOMAIN` and `OKTETO_NAMESPACE` are available both at runtime in pods and during deployment operations. +::: + +- **`OKTETO_NAME`**: The name of the Development Environment. It is also injected into the Development Container at runtime. - **`OKTETO_USERNAME`**: Your username in Okteto. - **`OKTETO_REGISTRY_URL`**: The URL of the Okteto Registry. - **`OKTETO_GIT_BRANCH`**: The name of the Git branch being deployed. @@ -288,7 +299,7 @@ Variables defined at deployment time are those set with the `--var` flag. They a Example: -```console +```bash okteto deploy --var PORT=4000 ``` @@ -310,7 +321,7 @@ Similar to the `--var` flag, local environment variables are useful when you nee Example: -```console +```bash PORT=4000 okteto deploy ``` @@ -323,8 +334,7 @@ The `.env` should be placed in the same folder of the Okteto Manifest. The Oktet For example: -```console -# .env +```bash title=".env" PORT=4000 ``` @@ -341,8 +351,7 @@ The `.env` integration also supports parameter expansion to set default values a Example: -```console -# .env +```bash title=".env" PORT=${PORT:-4000} ``` @@ -360,7 +369,7 @@ To create or delete User Variables go to the `Variables` section in the `Setting

Variables in settings

@@ -370,17 +379,17 @@ To create a new variable, click on the **Add Variable** button, and provide a na

add a variable

-To delete an existing variable, click on the **Delete** button on the right. You'll have to confirm your choice before the variable is deleted. Deleted variables can't be recovered, so be careful when doing this. +To delete an existing variable, click on the **Remove** button on the right. You'll have to confirm your choice before the variable is deleted. Deleted variables can't be recovered, so be careful when doing this.

delete a variable

@@ -394,7 +403,7 @@ To create or delete Admin Variables navigate to the **Admin -> Admin Variables**

Variables in settings

@@ -404,17 +413,17 @@ To create a new variable, click on the **Add Variable** button, and provide a na

add a variable

-To delete an existing variable, click on the **Delete** button on the right. You'll have to confirm your choice before the variable is deleted. Deleted variables can't be recovered, so be careful when doing this. +To delete an existing variable, click on the **Remove** button on the right. You'll have to confirm your choice before the variable is deleted. Deleted variables can't be recovered, so be careful when doing this.

delete a variable

diff --git a/versioned_docs/version-1.37/core/remote-execution.mdx b/versioned_docs/version-1.49/core/remote-execution.mdx similarity index 94% rename from versioned_docs/version-1.37/core/remote-execution.mdx rename to versioned_docs/version-1.49/core/remote-execution.mdx index 18f5a846c..96f3acac5 100644 --- a/versioned_docs/version-1.37/core/remote-execution.mdx +++ b/versioned_docs/version-1.49/core/remote-execution.mdx @@ -16,9 +16,9 @@ You can enable remote execution by default for all applications or on a per appl ### Enable Remote Execution by Default -Remote Execution can also be made the default by configuring it in the Admin Dashboard. The default value for this setting is `local`. +Remote Execution can also be made the default by configuring it in the Admin Dashboard. The default value for this setting is `remote`. -Navigate to **Admin -> Command Line(CLI)** under the Settings section to enable it. +Navigate to **Admin -> Command Line (CLI)** under the Settings section to enable it. Buildkit architecture

diff --git a/versioned_docs/version-1.37/core/use-volume-snapshots.mdx b/versioned_docs/version-1.49/core/use-volume-snapshots.mdx similarity index 67% rename from versioned_docs/version-1.37/core/use-volume-snapshots.mdx rename to versioned_docs/version-1.49/core/use-volume-snapshots.mdx index fe1a39a74..41684aa6b 100644 --- a/versioned_docs/version-1.37/core/use-volume-snapshots.mdx +++ b/versioned_docs/version-1.49/core/use-volume-snapshots.mdx @@ -1,6 +1,6 @@ --- -title: Volume Snapshots -description: Use Volume Snapshots in your Development Environments +title: Volume Snapshots in Development Environments +description: Okteto Volume Snapshots let you initialize persistent volumes from previous snapshots to populate Development Environments with production or staging data. sidebar_label: Volume Snapshots id: use-volume-snapshots --- @@ -9,14 +9,14 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; Okteto Volume Snapshots allow you to initialize Persistent Volume Claims (PVCs) with data from a previously created snapshot. -This is useful when working with large datasets or when you need to create Development Environments with realistic data from production or staging. +This lets you work with large datasets or create Development Environments with realistic data from production or staging. Common use cases: - Restoring a database (PostgreSQL, MySQL, etc.) with real data for development and testing - Quickly populating a Development Environment with staging or production data - Cloning datasets for machine learning models, logs, or images -## How Volume Snapshots Work +## How Volume Snapshots work 1. Your application uses a Persistent Volume Claim (PVC) to store data (e.g., a PostgreSQL or MySQL database) 1. You create a snapshot of this volume, capturing the data at that moment 1. When deploying a new Development Environment, you can restore the PVC from the snapshot, ensuring your app starts with the same dataset @@ -29,21 +29,22 @@ This allows you to spin up new environments with fresh, realistic data every tim defaultValue="self-hosted" values={[ { label: 'Self-Hosted', value: 'self-hosted', }, - { label: 'SaaS', value: 'saas', }, + { label: 'BYOC', value: 'byoc', }, ]} > -Follow [this guide](self-hosted/install/volume-snapshots.mdx) to enable Volume Snapshots in your cluster. +On Self-Hosted instances, Volume Snapshots support depends on your cluster configuration. Okteto requires a StorageClass backed by a [CSI driver that supports volume snapshots](https://kubernetes-csi.github.io/docs/snapshot-restore-feature.html), and a `VolumeSnapshotClass` that references that driver. Use this StorageClass for the source persistent volume of your volume snapshots. -Make sure your storage class supports snapshots by using a **CSI driver** that [supports volume snapshots](https://kubernetes-csi.github.io/docs/snapshot-restore-feature.html) for the source persistent volume of your volume snapshots. +Follow [this guide](self-hosted/install/volume-snapshots.mdx) to install a compatible CSI driver, create the `VolumeSnapshotClass`, and enable Volume Snapshots in your cluster. - -If your instance is managed by Okteto, Volume Snapshots are enabled by default. + -**Important**: you need to use the `csi-okteto` storage classes for the source persistent volume of your volume snapshots. +On Bring Your Own Cloud (BYOC) instances, Volume Snapshots are enabled by default. + +The default StorageClass on BYOC instances does not support Volume Snapshots. To snapshot a volume, set its StorageClass to `csi-okteto`, which supports Volume Snapshots. Use `csi-okteto` for the source persistent volume of your volume snapshots. @@ -51,19 +52,19 @@ If your instance is managed by Okteto, Volume Snapshots are enabled by default. ## Using Volume Snapshots in your Development Environment Okteto enables developers to initialize persistent volume claims with the contents of a pre-existing volume snapshot. -The volume snapshot is created from a persistent volume claim and it can contain database backups, big files, images, a copy of your staging data, etc. +The Volume Snapshot is created from a persistent volume claim and can contain database backups, large files, images, or a copy of your staging data. -In order to use Volume Snapshots with your Development Environment you need to follow these steps: +To use Volume Snapshots with your Development Environment, follow these steps: - [1. Create the source persistent volume](core/use-volume-snapshots.mdx#1-create-the-source-persistent-volume-pvc) - [2. Create a volume snapshot of the source persistent volume](core/use-volume-snapshots.mdx#2-create-a-snapshot-of-the-pvc) - [3. Consume the volume snapshot in a new persistent volume](core/use-volume-snapshots.mdx#3-restore-a-pvc-from-a-snapshot) -### 1. Create the Source Persistent Volume (PVC) +### 1. Create the source persistent volume (PVC) The first step is to ensure your database or application is storing data in a Persistent Volume Claim (PVC). This is the data that you want to be able to clone into your Development Environment. -In the example below we use a database, but this could be anything that uses a volume for storage: databases, ML models, images, etc... +In the example below we use a database, but this could be anything that uses a volume for storage, such as databases, ML models, or images. > If the default storage class of your cluster doesn't support volume snapshots, make sure you set the storage class to one that is compatible when creating your persistent volume. Check the [requirements](core/use-volume-snapshots.mdx#requirements) section to learn more about the available storage classes in Okteto. @@ -127,11 +128,11 @@ volumes: :::note -Before generating a snapshot of the source volume above, ensure that the PersistentVolumeClaim is bounded (i.e. with Status `Bound`), and that the data you want to snapshot is already written to the volume. +Before generating a snapshot of the source volume above, ensure that the PersistentVolumeClaim is bound (i.e. with Status `Bound`), and that the data you want to snapshot is already written to the volume. On the Kubernetes and Compose implementations of the sample volume shown above, the defined PersistentVolumeClaim will be bound by a Pod that runs a MySQL database, but it could be any other application that writes data to your source volume. ::: -### 2. Create a Snapshot of the PVC +### 2. Create a snapshot of the PVC After creating the source persistent volume, the next step is to create the Volume Snapshot. Volume snapshots are created with the content of the persistent volume at the time of creating the volume snapshot. Further updates on the persistent volume aren't reflected in the volume snapshot content. @@ -150,7 +151,7 @@ spec: persistentVolumeClaimName: mysql-pvc ``` -### 3. Restore a PVC from a Snapshot +### 3. Restore a PVC from a snapshot Finally, you can use the Volume Snapshot created in the previous step to populate a new persistent volume. Use the `dev.okteto.com/from-snapshot-name` and `dev.okteto.com/from-snapshot-namespace` annotations on any persistent volume claim to tell Okteto to initialize your persistent volume claim from an existing volume snapshot, as shown below: @@ -199,11 +200,13 @@ volumes: -✅ If the annotation `dev.okteto.com/from-snapshot-namespace` is **not defined**, Okteto will default to the Namespace of the new persistent volume claim. +:::note +If the annotation `dev.okteto.com/from-snapshot-namespace` is **not defined**, Okteto defaults to the Namespace of the new persistent volume claim. +::: -✅ Use the annotation `dev.okteto.com/skip-snapshot-if-same-namespace: "true"` to skip the data cloning operation if the source snapshot and the new persistent volume claim are in the same namespace. +Use the annotation `dev.okteto.com/skip-snapshot-if-same-namespace: "true"` to skip the data cloning operation if the source snapshot and the new persistent volume claim are in the same Namespace. -## Automating Snapshot Creation in Deployments +## Automating snapshot creation in deployments You can integrate snapshot creation into your Okteto Manifest so every deployment includes an updated snapshot: ```yaml @@ -212,9 +215,9 @@ deploy: - deploy app ``` - \ No newline at end of file +- [How to Create a Development Environment with Realistic Data in Okteto](https://www.okteto.com/blog/how-to-create-and-use-data-clones-in-okteto-cloud/) blog post +- [How to Create and Use Data Clones in Okteto](https://www.okteto.com/blog/how-to-create-and-use-data-clones-in-okteto-video/) video tutorial +*/} \ No newline at end of file diff --git a/versioned_docs/version-1.37/core/user-roles-and-permissions.mdx b/versioned_docs/version-1.49/core/user-roles-and-permissions.mdx similarity index 66% rename from versioned_docs/version-1.37/core/user-roles-and-permissions.mdx rename to versioned_docs/version-1.49/core/user-roles-and-permissions.mdx index 781018321..49aa2b0a8 100644 --- a/versioned_docs/version-1.37/core/user-roles-and-permissions.mdx +++ b/versioned_docs/version-1.49/core/user-roles-and-permissions.mdx @@ -72,8 +72,8 @@ Developers have read access to Global Preview Environments, enabling them to tro | Wake | ✅ | ✅ | ✅ | ❌ | | Sleep | ✅ | ✅ | ✅ | ❌ | | Transfer Ownership | ✅ | ❌ | ❌ | ❌ | -| Keep awake/make persistent | ✅ | ❌ | ❌ | ❌ | -| Undo keep awake | ✅ | ❌ | ❌ | ❌ | +| Make Persistent | ✅ | ❌ | ❌ | ❌ | +| Undo Make Persistent | ✅ | ❌ | ❌ | ❌ | | Start Development over sub-resource | ✅ | ✅ | ✅ | ❌ | | Restart sub-resource | ✅ | ✅ | ✅ | ❌ | | Destroy sub-resource | ✅ | ✅ | ✅ | ❌ | @@ -100,8 +100,8 @@ Developers have read access to Global Preview Environments, enabling them to tro | Wake | ✅ | ✅ | ✅ | ❌ | | Sleep | ✅ | ✅ | ✅ | ❌ | | Transfer Ownership | - | - | - | - | -| Keep awake/make persistent | ✅ | ❌ | ❌ | ❌ | -| Undo keep awake | ✅ | ❌ | ❌ | ❌ | +| Make Persistent | ✅ | ❌ | ❌ | ❌ | +| Undo Make Persistent | ✅ | ❌ | ❌ | ❌ | | Start Development over sub-resource | - | - | - | - | | Restart sub-resource | - | - | - | - | | Destroy sub-resource | - | - | - | - | @@ -126,8 +126,8 @@ Developers have read access to Global Preview Environments, enabling them to tro | Wake | ✅ | ✅ | - | ❌ | | Sleep | ✅ | ✅ | - | ❌ | | Transfer Ownership | - | - | - | - | -| Keep awake/make persistent | ✅ | ❌ | - | ❌ | -| Undo keep awake | ✅ | ❌ | - | ❌ | +| Make Persistent | ✅ | ❌ | - | ❌ | +| Undo Make Persistent | ✅ | ❌ | - | ❌ | | Start Development over sub-resource | - | - | - | - | | Restart sub-resource | - | - | - | - | | Destroy sub-resource | - | - | - | - | @@ -135,4 +135,38 @@ Developers have read access to Global Preview Environments, enabling them to tro | Access private endpoints | ✅ | ✅ | - | ✅ | - ✅ The role has permission to perform this action - ❌ The role does not have permission to perform this action -- **-** This action is not applicable to the role or context \ No newline at end of file +- **-** This action is not applicable to the role or context + +## Kubernetes RBAC Model + +In addition to the Okteto platform roles described above, Okteto configures Kubernetes RBAC resources in each namespace it manages. This section explains how those permissions work at the Kubernetes level. + +### Namespace-scoped RoleBindings + +Okteto creates a **RoleBinding** in each developer namespace that grants the `cluster-admin` [ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) to every admin, owner, and member of that namespace. Although the ClusterRole is named `cluster-admin`, the RoleBinding is **namespace-scoped** — it only grants permissions within that specific namespace, not across the entire cluster. + +You can think of this as: **every developer is an admin of their own namespaces**. Users cannot access or modify resources outside the namespaces they own or have been granted access to. + +### Default ServiceAccount binding + +By default, Okteto also binds the `default` ServiceAccount in each namespace to the same ClusterRole through a separate namespace-scoped RoleBinding. This is controlled by the [`namespace.autoRoleBinding.enabled`](self-hosted/helm-configuration.mdx#namespace) setting (defaults to `true`). + +This means pods that don't specify a custom ServiceAccount will have Kubernetes API access scoped to their own namespace. If your security policy requires restricting pod-level API access, you can disable this by setting `namespace.autoRoleBinding.enabled` to `false` in your [Helm configuration](self-hosted/helm-configuration.mdx#namespace). + +### Okteto control plane ServiceAccount + +The ServiceAccount in the `okteto` namespace is used by the Okteto control plane itself. This account has cluster-wide permissions because the control plane needs to create and manage namespaces, service accounts, role bindings, and other cluster-level resources on behalf of users. This is separate from the namespace-scoped permissions granted to developer namespaces. + +### Customizing namespace roles + +You can change the ClusterRole assigned in developer namespaces through the [`serviceAccounts.roleBindings.namespaces`](self-hosted/helm-configuration.mdx#serviceaccounts) Helm configuration value. For example, to use a more restrictive role: + +```yaml +serviceAccounts: + roleBindings: + namespaces: my-custom-role +``` + +The ClusterRole you specify must already exist in the cluster — Okteto does not create it. If you need to combine multiple ClusterRoles, use [ClusterRole aggregation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles). + +For global preview environments, the role is configured separately via [`serviceAccounts.roleBindings.previews`](self-hosted/helm-configuration.mdx#serviceaccounts) (defaults to `view`). \ No newline at end of file diff --git a/versioned_docs/version-1.37/development/containers/file-sync/aspnetcore.mdx b/versioned_docs/version-1.49/development/containers/file-sync/aspnetcore.mdx similarity index 98% rename from versioned_docs/version-1.37/development/containers/file-sync/aspnetcore.mdx rename to versioned_docs/version-1.49/development/containers/file-sync/aspnetcore.mdx index 6bd3df838..81289325d 100644 --- a/versioned_docs/version-1.37/development/containers/file-sync/aspnetcore.mdx +++ b/versioned_docs/version-1.49/development/containers/file-sync/aspnetcore.mdx @@ -51,7 +51,7 @@ Open your browser and go to the URL of the application. You can get the URL by l Okteto UI ASP.NET Did you notice that you're accessing your application through an HTTPs endpoint? This is because Okteto will [automatically create them](core/endpoints/automatic-ssl.mdx) for you when you deploy your application. Cool no 😎? @@ -63,7 +63,7 @@ The [dev](reference/okteto-manifest.mdx#dev-object-optional) section defines how ```yaml title="okteto.yml" dev: hello-world: - image: okteto/aspnetcore-getting-started:dev + image: ghcr.io/okteto/aspnetcore-getting-started:dev command: bash environment: - ASPNETCORE_ENVIRONMENT=Development diff --git a/versioned_docs/version-1.37/development/containers/file-sync/golang.mdx b/versioned_docs/version-1.49/development/containers/file-sync/golang.mdx similarity index 97% rename from versioned_docs/version-1.37/development/containers/file-sync/golang.mdx rename to versioned_docs/version-1.49/development/containers/file-sync/golang.mdx index 64c2f85dd..c26f558d6 100644 --- a/versioned_docs/version-1.37/development/containers/file-sync/golang.mdx +++ b/versioned_docs/version-1.49/development/containers/file-sync/golang.mdx @@ -51,7 +51,7 @@ Log into your Okteto instance and click on the URL of the application: Okteto UI golang Did you notice that you're accessing your application through an HTTPs endpoint? This is because Okteto will [automatically create them](core/endpoints/automatic-ssl.mdx) for you when you deploy your application. Cool no 😎? @@ -63,7 +63,7 @@ The [dev](reference/okteto-manifest.mdx#dev-object-optional) section defines how ```yaml title="okteto.yml" dev: hello-world: - image: okteto/golang:1 + image: ghcr.io/okteto/golang:1 command: bash sync: - .:/usr/src/app @@ -198,7 +198,7 @@ The execution will halt at your breakpoint. You can then inspect the request, th debugging in Okteto with golang diff --git a/versioned_docs/version-1.37/development/containers/file-sync/index.mdx b/versioned_docs/version-1.49/development/containers/file-sync/index.mdx similarity index 100% rename from versioned_docs/version-1.37/development/containers/file-sync/index.mdx rename to versioned_docs/version-1.49/development/containers/file-sync/index.mdx diff --git a/versioned_docs/version-1.37/development/containers/file-sync/java.mdx b/versioned_docs/version-1.49/development/containers/file-sync/java.mdx similarity index 98% rename from versioned_docs/version-1.37/development/containers/file-sync/java.mdx rename to versioned_docs/version-1.49/development/containers/file-sync/java.mdx index daaa51fd0..5e362b6a0 100644 --- a/versioned_docs/version-1.37/development/containers/file-sync/java.mdx +++ b/versioned_docs/version-1.49/development/containers/file-sync/java.mdx @@ -85,7 +85,7 @@ Log into your Okteto instance and click on the endpoint URL for the application: Okteto UI Java Notice that you're accessing your application through an HTTPS endpoint? This is because Okteto will [automatically create them](core/endpoints/automatic-ssl.mdx) for you when you deploy your application. Cool, no 😎? @@ -99,7 +99,7 @@ The [dev](reference/okteto-manifest.mdx#dev-object-optional) section defines how ```yaml title="okteto.yml" dev: hello-world: - image: okteto/maven:3 + image: ghcr.io/okteto/maven:3 command: bash sync: - .:/usr/src/app @@ -114,7 +114,7 @@ dev: ```yaml title="okteto.yml" dev: hello-world: - image: okteto/gradle:6.5 + image: ghcr.io/okteto/gradle:6.5 command: bash sync: - .:/usr/src/app diff --git a/versioned_docs/version-1.37/development/containers/file-sync/node.mdx b/versioned_docs/version-1.49/development/containers/file-sync/node.mdx similarity index 98% rename from versioned_docs/version-1.37/development/containers/file-sync/node.mdx rename to versioned_docs/version-1.49/development/containers/file-sync/node.mdx index 3a590d276..0076f9213 100644 --- a/versioned_docs/version-1.37/development/containers/file-sync/node.mdx +++ b/versioned_docs/version-1.49/development/containers/file-sync/node.mdx @@ -51,7 +51,7 @@ Log into your Okteto instance and click on the URL of the application: Okteto UI Node.js Did you notice that you're accessing your application through an HTTPs endpoint? This is because Okteto will [automatically create them](core/endpoints/automatic-ssl.mdx) for you when you deploy your application. Cool no 😎? diff --git a/versioned_docs/version-1.37/development/containers/file-sync/php.mdx b/versioned_docs/version-1.49/development/containers/file-sync/php.mdx similarity index 97% rename from versioned_docs/version-1.37/development/containers/file-sync/php.mdx rename to versioned_docs/version-1.49/development/containers/file-sync/php.mdx index 23c9f1a22..267468789 100644 --- a/versioned_docs/version-1.37/development/containers/file-sync/php.mdx +++ b/versioned_docs/version-1.49/development/containers/file-sync/php.mdx @@ -51,7 +51,7 @@ Open your browser and go to the URL of the application. You can get the URL by l Okteto UI PHP Did you notice that you're accessing your application through an HTTPS endpoint? This is because Okteto will [automatically create them](core/endpoints/automatic-ssl.mdx) for you when you deploy your application. Cool no 😎? @@ -63,7 +63,7 @@ The [dev](reference/okteto-manifest.mdx#dev-object-optional) section defines how ```yaml title="okteto.yml" dev: hello-world: - image: okteto/php-getting-started:dev + image: ghcr.io/okteto/php-getting-started:dev command: bash sync: - .:/app diff --git a/versioned_docs/version-1.37/development/containers/file-sync/python.mdx b/versioned_docs/version-1.49/development/containers/file-sync/python.mdx similarity index 96% rename from versioned_docs/version-1.37/development/containers/file-sync/python.mdx rename to versioned_docs/version-1.49/development/containers/file-sync/python.mdx index ddc62e0a9..ecd668611 100644 --- a/versioned_docs/version-1.37/development/containers/file-sync/python.mdx +++ b/versioned_docs/version-1.49/development/containers/file-sync/python.mdx @@ -51,7 +51,7 @@ Log into your Okteto instance and click on the URL of the application: Okteto UI Python Did you notice that you're accessing your application through an HTTPs endpoint? This is because Okteto will [automatically create them](core/endpoints/automatic-ssl.mdx) for you when you deploy your application. Cool no 😎? @@ -128,7 +128,6 @@ Save your changes. @app.route('/') def hello_world(): return 'Hello World from Okteto!' -} ``` Okteto will synchronize your changes to your development container. @@ -185,7 +184,7 @@ Press the `resume` button to let the execution continue. debugging with Python @@ -195,7 +194,7 @@ The execution will halt at your breakpoint. You can then inspect the request, th breakpoint in Python diff --git a/versioned_docs/version-1.37/development/containers/file-sync/ruby.mdx b/versioned_docs/version-1.49/development/containers/file-sync/ruby.mdx similarity index 98% rename from versioned_docs/version-1.37/development/containers/file-sync/ruby.mdx rename to versioned_docs/version-1.49/development/containers/file-sync/ruby.mdx index 6eff6fccb..e318d11f0 100644 --- a/versioned_docs/version-1.37/development/containers/file-sync/ruby.mdx +++ b/versioned_docs/version-1.49/development/containers/file-sync/ruby.mdx @@ -24,7 +24,7 @@ $ git clone https://github.com/okteto/ruby-getting-started $ cd ruby-getting-started ``` -At the root of the directory, you'll find the `okteto.yml` file. This file describes how to [deploy](reference/okteto-manifest.mdx#deploy-string-optional) the Python Sample App. +At the root of the directory, you'll find the `okteto.yml` file. This file describes how to [deploy](reference/okteto-manifest.mdx#deploy-string-optional) the Ruby Sample App. ```yaml title="okteto.yml" deploy: @@ -51,7 +51,7 @@ Log into your Okteto instance and click on the URL of the application: Okteto UI Ruby Did you notice that you're accessing your application through an HTTPs endpoint? This is because Okteto will [automatically create them](core/endpoints/automatic-ssl.mdx) for you when you deploy your application. Cool no 😎? diff --git a/versioned_docs/version-1.37/development/containers/hybrid/frontend.mdx b/versioned_docs/version-1.49/development/containers/hybrid/frontend.mdx similarity index 100% rename from versioned_docs/version-1.37/development/containers/hybrid/frontend.mdx rename to versioned_docs/version-1.49/development/containers/hybrid/frontend.mdx diff --git a/versioned_docs/version-1.37/development/containers/hybrid/index.mdx b/versioned_docs/version-1.49/development/containers/hybrid/index.mdx similarity index 100% rename from versioned_docs/version-1.37/development/containers/hybrid/index.mdx rename to versioned_docs/version-1.49/development/containers/hybrid/index.mdx diff --git a/versioned_docs/version-1.37/development/containers/hybrid/java.mdx b/versioned_docs/version-1.49/development/containers/hybrid/java.mdx similarity index 99% rename from versioned_docs/version-1.37/development/containers/hybrid/java.mdx rename to versioned_docs/version-1.49/development/containers/hybrid/java.mdx index 4e145a45b..a7f873e5f 100644 --- a/versioned_docs/version-1.37/development/containers/hybrid/java.mdx +++ b/versioned_docs/version-1.49/development/containers/hybrid/java.mdx @@ -85,7 +85,7 @@ dev: reverse: - 8080:8080 forward: - 9092:kafka:9092 + - 9092:kafka:9092 ``` The `vote` key matches the name of the **hello world** Deployment. The definition of the rest of fields are: diff --git a/versioned_docs/version-1.37/development/containers/index.mdx b/versioned_docs/version-1.49/development/containers/index.mdx similarity index 100% rename from versioned_docs/version-1.37/development/containers/index.mdx rename to versioned_docs/version-1.49/development/containers/index.mdx diff --git a/versioned_docs/version-1.37/development/deploy/deploy-from-catalog.mdx b/versioned_docs/version-1.49/development/deploy/deploy-from-catalog.mdx similarity index 80% rename from versioned_docs/version-1.37/development/deploy/deploy-from-catalog.mdx rename to versioned_docs/version-1.49/development/deploy/deploy-from-catalog.mdx index dd2868bda..dea7ac09f 100644 --- a/versioned_docs/version-1.37/development/deploy/deploy-from-catalog.mdx +++ b/versioned_docs/version-1.49/development/deploy/deploy-from-catalog.mdx @@ -23,22 +23,14 @@ In order to deploy a pre-configured application using the Catalog, navigate to ` In this tab you should see all the applications that your team has added. Once you are the Catalog dialog, select the application you want to deploy, optionally update the pre-configured values, and click `Deploy`.

- Deploy a development environment from the Catalog +

-

- view a Catalog repo's environment variables -

-When you deploy an application using the Catalog, Okteto will automatically build and deploy the repository, manifest path, and variables defined by your team. This is the equivalent of running `okteto deploy --build --path $PATH.yaml --variables=XXXXX` from your command line. +When you deploy an application using the Catalog, Okteto automatically builds and deploys the repository, manifest path, and variables defined by your team. This is the equivalent of running `okteto deploy --file $PATH.yaml --var KEY=value` from your command line. In the example above, Okteto will deploy the "Scheduling Application", from the "main" branch, and passing the "SCHEDULE_URL", "SLACK_CHANNEL", and "ANOTHER_VAR" variables. @@ -63,7 +55,7 @@ A dialog will open where you can modify the branch, variables, and path to the O

Redeploy from the catalog @@ -79,7 +71,7 @@ A confirmation dialog will pop up. Click the `Destroy` button to delete your env

Destroy application diff --git a/versioned_docs/version-1.37/development/deploy/deploy-from-git.mdx b/versioned_docs/version-1.49/development/deploy/deploy-from-git.mdx similarity index 91% rename from versioned_docs/version-1.37/development/deploy/deploy-from-git.mdx rename to versioned_docs/version-1.49/development/deploy/deploy-from-git.mdx index 1493f277d..c3bfbdca9 100644 --- a/versioned_docs/version-1.37/development/deploy/deploy-from-git.mdx +++ b/versioned_docs/version-1.49/development/deploy/deploy-from-git.mdx @@ -19,13 +19,13 @@ Type the URL for the Movies App repo (https://github.com/okteto/movies), pick a

deploy from git

-When you deploy a dev environment using a Git repository, Okteto will analyze your repo and automatically deploy it running `okteto deploy --build`. +When you deploy a dev environment using a Git repository, Okteto analyzes your repo and automatically deploys it by running `okteto deploy`. In the example above, Okteto will install a Helm chart with the Movies App demo. :::tip @@ -40,7 +40,7 @@ Your development environment will be ready to go once it reaches the `Success` s

UI of the movies app

@@ -53,7 +53,7 @@ A dialog will open where you can modify the branch to redeploy and configure adv

Redeploy from git with dependencies @@ -74,7 +74,7 @@ If your application has dependencies, you’ll also see an option to destroy its

Destroy application @@ -148,5 +148,5 @@ You can parametrize your development environment deployment using the following - `repository`: The repository to be deployed. If it's not present, Okteto will automatically infer it using the referrer header, if available. - `branch`: The repository branch to be deployed. If not included, it will use the default branch of the repository. -- `vars`: It allows you to specify a list of variables that will be available as environment variables during the deployment. It is optional. .e.g `vars=[{"name":"THEME","value":"dark"},{"name":"LANG","value":"en"}]`. This would generate 2 environment variables avaible on your deployment: `THEME=dark` and `LANG=en`. It has to be URL encoded. +- `vars`: It allows you to specify a list of variables that will be available as environment variables during the deployment. It is optional. .e.g `vars=[{"name":"THEME","value":"dark"},{"name":"LANG","value":"en"}]`. This would generate 2 environment variables available on your deployment: `THEME=dark` and `LANG=en`. It has to be URL encoded. - `filename`: The location of the [Okteto Manifest](reference/okteto-manifest.mdx) relative to the root of the repository. diff --git a/versioned_docs/version-1.37/development/deploy/develop-on-okteto-button.mdx b/versioned_docs/version-1.49/development/deploy/develop-on-okteto-button.mdx similarity index 100% rename from versioned_docs/version-1.37/development/deploy/develop-on-okteto-button.mdx rename to versioned_docs/version-1.49/development/deploy/develop-on-okteto-button.mdx diff --git a/versioned_docs/version-1.37/development/deploy/from-private-repositories.mdx b/versioned_docs/version-1.49/development/deploy/from-private-repositories.mdx similarity index 61% rename from versioned_docs/version-1.37/development/deploy/from-private-repositories.mdx rename to versioned_docs/version-1.49/development/deploy/from-private-repositories.mdx index 4904b62ce..13b735adf 100644 --- a/versioned_docs/version-1.37/development/deploy/from-private-repositories.mdx +++ b/versioned_docs/version-1.49/development/deploy/from-private-repositories.mdx @@ -9,30 +9,25 @@ import Image from "@theme/Image"; ## GitHub Private Repositories -Okteto integrates with GitHub and allows you to easily deploy any repository from any account or organization you grant permissions to. You can connect both personal repositories and those belonging to an organization in the same Okteto account. +Okteto integrates with GitHub and allows you to deploy any repository from any account or organization you grant permissions to. You can connect both personal repositories and those belonging to an organization in the same Okteto account. -### Grant permissions +:::note +Before you can connect your GitHub account, your Okteto administrator must enable the GitHub integration for your instance. If you don't see a deploy from **GitHub** option in the Deploy dialog, ask your admin to [set up the GitHub integration](admin/private-repositories/github.mdx). +::: + +### Connect your GitHub account -You'll need to perform the following steps the first time you grant GitHub permissions to Okteto: +This is a one-time setup. Once complete, Okteto will remember your GitHub permissions across sessions. 1. Log into your Okteto instance 1. Click on the "**Deploy Dev Environment**" button on the top 1. Make sure "**GitHub**" is the selected source - -

- Deploy private repository from git -

- -1. Click on the **Configure GitHub** button, to open the authorization dialog from GitHub. GitHub will ask you to install the Okteto app in the accounts and organizations you select. Follow the instructions to grant permissions to your repositories. +1. Click **Configure GitHub** or **Add repositories** to open the authorization dialog from GitHub. GitHub asks you to install the Okteto app in the accounts and organizations you select. Follow the instructions to grant permissions to your repositories.

install Okteto

@@ -52,7 +47,7 @@ Once you or your administrator grants permission, Okteto will automatically list

list of private repositories @@ -60,7 +55,7 @@ Once you or your administrator grants permission, Okteto will automatically list ### Deploy from a Private GitHub Repository -After giving Okteto access to any of your public or private repositories, you'll be able to deploy from a GitHub repository [using an Okteto Manifest](reference/okteto-cli.mdx#deploy). +After connecting your GitHub account, you'll be able to deploy from any of your public or private repositories [using an Okteto Manifest](reference/okteto-cli.mdx#deploy). ## Other Private Repositories @@ -68,8 +63,8 @@ You can also use `SSH` authentication to deploy a private repository. To do this

add a private repository

diff --git a/versioned_docs/version-1.37/development/deploy/index.mdx b/versioned_docs/version-1.49/development/deploy/index.mdx similarity index 100% rename from versioned_docs/version-1.37/development/deploy/index.mdx rename to versioned_docs/version-1.49/development/deploy/index.mdx diff --git a/versioned_docs/version-1.37/development/images.mdx b/versioned_docs/version-1.49/development/images.mdx similarity index 100% rename from versioned_docs/version-1.37/development/images.mdx rename to versioned_docs/version-1.49/development/images.mdx diff --git a/versioned_docs/version-1.49/development/index.mdx b/versioned_docs/version-1.49/development/index.mdx new file mode 100644 index 000000000..0fcd50a54 --- /dev/null +++ b/versioned_docs/version-1.49/development/index.mdx @@ -0,0 +1,17 @@ +--- +title: Development Environments on Kubernetes +description: Okteto Development Environments let you code locally while your application runs on Kubernetes, with real-time file sync and hot reload. +--- + +Development Environments enable developers to develop applications on Kubernetes with a joyful development experience. +Developers write code locally on their machine with the tools they love, and Okteto transparently updates their application on Kubernetes **in real-time as they code**! + +Developers don't have to spend time configuring and deploying their applications. +Everything is pre-configured in the [Okteto Manifest](core/okteto-manifest.mdx). +This way developers spend less time troubleshooting your development environment and more time coding cool features for their users 😎 + +- [Okteto CLI](development/using-okteto-cli.mdx) usage and commands +- [Divert](development/using-divert.mdx) for lightweight Development Environments with shared services +- [Development Containers](development/containers/index.mdx) for hot reload and debugging on Okteto +- [Development images](development/images.mdx) for customizing your container setup +- [Deploying](development/deploy/index.mdx) Development Environments diff --git a/versioned_docs/version-1.49/development/using-divert.mdx b/versioned_docs/version-1.49/development/using-divert.mdx new file mode 100644 index 000000000..2e8f48f1a --- /dev/null +++ b/versioned_docs/version-1.49/development/using-divert.mdx @@ -0,0 +1,416 @@ +--- +title: Using Divert +description: Practical guide for implementing Divert in your development workflow +sidebar_label: Using Divert +id: using-divert +--- + +This guide covers the practical implementation of Divert in your Okteto development environments, including manifest configuration, header propagation, and common patterns for databases and message queues. + +## Okteto Manifest Configuration + +The `divert` section goes under `deploy` in your `okteto.yaml` to configure traffic routing between your development environment and a shared namespace. + +### Basic Divert Configuration (nginx driver) + +```yaml +deploy: + commands: + - helm upgrade --install myservice chart --set image=${OKTETO_BUILD_IMAGE} + divert: + driver: nginx # Optional, nginx is the default + namespace: staging +``` + +| Field | Description | +|-------|-------------| +| `driver` | The backend for divert routing. Options: `nginx` (default) or `istio` | +| `namespace` | The shared namespace containing the full application stack. Must be an Okteto-managed Namespace. | + +:::note +The shared namespace must be an Okteto-managed Namespace — one that Okteto deployed with [`okteto deploy`](../get-started/deploy-your-app/deploy.mdx) or a [Preview Environment](../previews/index.mdx). Okteto reads and routes to resources in this Namespace using your Okteto credentials, so a Namespace that Okteto did not deploy is not officially supported. To use existing shared services that run outside Okteto, redeploy or duplicate them into an Okteto-managed Namespace. +::: + +When you run `okteto deploy`, Okteto automatically: + +1. Deploys only the services defined in your manifest +2. Configures routing to redirect requests for missing services to the shared namespace +3. Injects the `baggage: okteto-divert=` header into requests through your endpoints + +### Istio Driver Configuration + +If your cluster uses Istio for service mesh, use the `istio` driver: + +```yaml +deploy: + commands: + - helm upgrade --install myservice chart --set image=${OKTETO_BUILD_IMAGE} + divert: + driver: istio + virtualServices: + - name: frontend-vs + namespace: staging + routes: + - route-to-frontend + hosts: + - virtualService: frontend + namespace: staging +``` + +The Istio driver has two key configuration fields: + +- **`virtualServices`**: Lists the Istio VirtualService resources in the shared namespace where traffic should be diverted. Okteto modifies these virtual services to add header-based routing logic so that requests containing the baggage header are sent to the corresponding service in your development namespace. You can target all routes defined in the virtual service or specify a subset using the `routes` field. + +- **`hosts`** (optional): Creates a dedicated copy of the listed virtual services in your development namespace, each with its own host (e.g., `https://service-a-.`). Requests reaching this host automatically have the baggage header injected. Internally, the copied virtual service still points to the original virtual service in the shared namespace, ensuring the rest of the request flow goes through the shared environment with the divert header applied. This is useful for services you are **not** deploying as part of your development environment — it gives you a dedicated URL to reach your version of the app without having to manually use the staging endpoint with the baggage header. Services you deploy in your own namespace already have their own endpoints. + +For complete configuration details, see the [manifest reference](../reference/okteto-manifest.mdx#divert). + +## Project Structure Patterns + +### Single Service Development + +For working on a single service, create a dedicated manifest: + +```yaml +# okteto.frontend.yaml +build: + frontend: + context: frontend + +deploy: + commands: + - helm upgrade --install frontend chart/frontend --set image=${OKTETO_BUILD_FRONTEND_IMAGE} + divert: + namespace: ${OKTETO_SHARED_NAMESPACE:-staging} +``` + +### Multi-Service Development + +When working on related services together: + +```yaml +# okteto.rentals.yaml +build: + rent: + context: rentals + worker: + context: worker + +deploy: + commands: + - helm upgrade --install rent chart/rent --set image=${OKTETO_BUILD_RENT_IMAGE} + - helm upgrade --install worker chart/worker --set image=${OKTETO_BUILD_WORKER_IMAGE} + - helm upgrade --install kafka chart/kafka + - helm upgrade --install postgresql chart/postgresql + divert: + namespace: ${OKTETO_SHARED_NAMESPACE:-staging} +``` + +### Using Environment Variables + +Reference the shared namespace via environment variable for flexibility: + +```bash +export OKTETO_SHARED_NAMESPACE="movies-shared" +okteto deploy -f okteto.frontend.yaml +``` + +## Header Propagation + +For Divert to work across your service mesh, implement header propagation in your services. The `baggage` header must be extracted from incoming requests and included in all outgoing requests. + +### JavaScript/Node.js (Express) + +```javascript +const express = require('express'); +const axios = require('axios'); + +const app = express(); + +// Middleware to capture baggage header +app.use((req, res, next) => { + req.baggage = req.headers['baggage'] || ''; + next(); +}); + +// Propagate in outgoing requests +app.get('/api/movies', async (req, res) => { + const response = await axios.get('http://catalog:8080/movies', { + headers: { 'baggage': req.baggage } + }); + res.json(response.data); +}); +``` + +### Go + +```go +package main + +import ( + "net/http" +) + +func handler(w http.ResponseWriter, r *http.Request) { + baggage := r.Header.Get("baggage") + + // Create downstream request + req, _ := http.NewRequest("GET", "http://catalog:8080/movies", nil) + req.Header.Set("baggage", baggage) + + client := &http.Client{} + resp, _ := client.Do(req) + // Handle response... +} +``` + +### Java/Spring Boot + +```java +@RestController +public class ApiController { + + private final WebClient webClient; + + @GetMapping("/api/movies") + public Mono getMovies(@RequestHeader(value = "baggage", required = false) String baggage) { + return webClient.get() + .uri("http://catalog:8080/movies") + .header("baggage", baggage != null ? baggage : "") + .retrieve() + .bodyToMono(Movies.class); + } +} +``` + +### Python (FastAPI) + +```python +from fastapi import FastAPI, Request +import httpx + +app = FastAPI() + +@app.get("/api/movies") +async def get_movies(request: Request): + baggage = request.headers.get("baggage", "") + + async with httpx.AsyncClient() as client: + response = await client.get( + "http://catalog:8080/movies", + headers={"baggage": baggage} + ) + return response.json() +``` + +## Database Isolation Patterns + +When using Divert, you can choose between shared or isolated databases depending on your needs. + +### Shared Database (Default) + +Services connect to the database in the shared namespace. This is the simplest approach and works well when you don't need to modify the database schema or data: + +```yaml +# Your diverted service uses the shared database +env: + - name: DATABASE_URL + value: postgresql://postgres:5432/movies # Resolves to shared namespace +``` + +### Isolated Database per Developer + +Deploy your own database instance when you need isolation for schema changes or test data: + +```yaml +deploy: + commands: + - helm upgrade --install mongodb chart/mongodb # Local database + - helm upgrade --install catalog chart/catalog --set image=${OKTETO_BUILD_IMAGE} + divert: + namespace: staging +``` + +Your service then connects to the local database: + +```yaml +env: + - name: MONGODB_URL + value: mongodb://mongodb:27017/catalog # Local instance +``` + +## Message Queue Routing Patterns + +For queue-based systems, you can route messages based on the baggage header to ensure proper service isolation. + +### SQS Queue Routing + +When publishing messages, include the namespace in the message attributes: + +```javascript +// Producer: Include routing info in message +const baggage = req.headers['baggage'] || ''; +const namespace = extractNamespace(baggage); // Extract from "okteto-divert=namespace" + +await sqs.sendMessage({ + QueueUrl: QUEUE_URL, + MessageBody: JSON.stringify(orderData), + MessageAttributes: { + 'okteto-namespace': { + DataType: 'String', + StringValue: namespace || 'shared' + } + } +}); +``` + +Consumer filters messages by namespace: + +```javascript +// Consumer: Filter messages by namespace +const messages = await sqs.receiveMessage({ + QueueUrl: QUEUE_URL, + MessageAttributeNames: ['okteto-namespace'] +}); + +for (const message of messages.Messages) { + const targetNamespace = message.MessageAttributes?.['okteto-namespace']?.StringValue; + + if (targetNamespace === CURRENT_NAMESPACE || targetNamespace === 'shared') { + // Process this message + await processOrder(JSON.parse(message.Body)); + } +} +``` + +### Kafka Topic Routing + +Use message headers for Kafka routing: + +```javascript +// Producer +await producer.send({ + topic: 'orders', + messages: [{ + value: JSON.stringify(order), + headers: { + 'okteto-namespace': namespace + } + }] +}); + +// Consumer +await consumer.run({ + eachMessage: async ({ message }) => { + const targetNamespace = message.headers['okteto-namespace']?.toString(); + + if (targetNamespace === CURRENT_NAMESPACE || !targetNamespace) { + await processOrder(JSON.parse(message.value)); + } + } +}); +``` + +## Testing Your Diverted Environment + +### Using curl + +Test routing with the baggage header: + +```bash +# Without header - uses shared services +curl https://movies-staging.okteto.example.com/api/catalog/healthz +# Response: {"status": "ok", "namespace": "staging"} + +# With header - routes to your namespace +curl -H "baggage: okteto-divert=alice" \ + https://movies-staging.okteto.example.com/api/catalog/healthz +# Response: {"status": "ok", "namespace": "alice"} +``` + +### Using Browser Extensions + +Install a header modification extension (like [ModHeader](https://modheader.com/)) and add: + +- **Header Name**: `baggage` +- **Header Value**: `okteto-divert=` + +### Automated Testing + +Include header propagation in your test setup: + +```javascript +// Jest/Mocha test setup +const request = require('supertest'); + +describe('Catalog API', () => { + it('should return movies', async () => { + const response = await request(app) + .get('/api/movies') + .set('baggage', `okteto-divert=${process.env.OKTETO_NAMESPACE}`) + .expect(200); + + expect(response.body.namespace).toBe(process.env.OKTETO_NAMESPACE); + }); +}); +``` + +## Multi-Developer Collaboration + +### Accessing Another Developer's Environment + +To test a colleague's changes, use their namespace in the baggage header: + +```bash +curl -H "baggage: okteto-divert=bob-feature" \ + https://movies-staging.okteto.example.com/api/movies +``` + +### Sharing Your Work + +Others can access your diverted environment using: + +1. Your personal endpoint: `https://movies-alice.okteto.example.com` +2. Or the shared endpoint with your header: `baggage: okteto-divert=alice` + +## Troubleshooting + +### Traffic Not Being Diverted + +1. **Check header format**: Ensure you're using `baggage: okteto-divert=` (not `baggage.okteto-divert`) +2. **Verify header propagation**: All services in the call chain must forward the baggage header +3. **Check namespace name**: The namespace in the header must match your Okteto namespace exactly + +### Services Not Discovered + +1. **Verify shared namespace**: Ensure the shared namespace is running and healthy +2. **Check service names**: Service discovery uses Kubernetes DNS (`..svc.cluster.local`) +3. **Review divert config**: Ensure `divert.namespace` points to the correct shared environment + +### Database Connection Issues + +1. **Check connection strings**: Ensure they resolve to the correct database (shared vs. local) +2. **Verify network policies**: Ensure cross-namespace communication is allowed +3. **Test connectivity**: Use `kubectl exec` to test database connectivity from your pod + +## Best Practices + +1. **Name namespaces descriptively**: Use patterns like `-` for clarity +2. **Clean up when done**: Delete personal namespaces after completing work +3. **Keep shared environment updated**: Regularly deploy updates to the shared staging environment +4. **Document header propagation**: Ensure all team members understand which headers to propagate +5. **Use environment variables**: Reference shared namespace via variables for flexibility +6. **Monitor resource usage**: Track namespace quotas and clean up unused resources + +## Next Steps + +- **[Divert Core Concepts](core/divert.mdx)** - Understanding Divert architecture +- **[Divert Tutorial](/docs/tutorials/divert)** - Step-by-step getting started guide +- **[Manifest Reference](reference/okteto-manifest.mdx#divert)** - Complete configuration options +- **[Example Repositories](#example-repositories)** - Working code samples + +## Example Repositories + +- [Movies with Divert](https://github.com/okteto-community/movies-with-divert) - Multi-service example +- [TacoShop with Divert Queues](https://github.com/okteto-community/tacoshop-with-divert-queues) - Queue routing patterns +- [Divert with Istio Sample](https://github.com/okteto-community/getting-started-with-divert-istio) - Istio driver configuration diff --git a/versioned_docs/version-1.37/development/using-okteto-cli.mdx b/versioned_docs/version-1.49/development/using-okteto-cli.mdx similarity index 96% rename from versioned_docs/version-1.37/development/using-okteto-cli.mdx rename to versioned_docs/version-1.49/development/using-okteto-cli.mdx index 17fe79ce8..13dfb5c88 100644 --- a/versioned_docs/version-1.37/development/using-okteto-cli.mdx +++ b/versioned_docs/version-1.49/development/using-okteto-cli.mdx @@ -9,7 +9,7 @@ import Image from "@theme/Image"; import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; -The Okteto CLI is our [open-source](https://github.com/okteto/okteto) tool that let's you develop your applications on Okteto. +The Okteto CLI is our [open-source](https://github.com/okteto/okteto) tool that lets you develop your applications on Okteto. If you haven't done so yet, install and configure the Okteto CLI following [this guide](get-started/install-okteto-cli.mdx). diff --git a/versioned_docs/version-1.37/get-started/advanced-commands-and-concepts.mdx b/versioned_docs/version-1.49/get-started/advanced-commands-and-concepts.mdx similarity index 97% rename from versioned_docs/version-1.37/get-started/advanced-commands-and-concepts.mdx rename to versioned_docs/version-1.49/get-started/advanced-commands-and-concepts.mdx index 4a7486e73..1de1b96de 100644 --- a/versioned_docs/version-1.37/get-started/advanced-commands-and-concepts.mdx +++ b/versioned_docs/version-1.49/get-started/advanced-commands-and-concepts.mdx @@ -27,7 +27,7 @@ A list of all available CLI commands is in our full [CLI reference guide here -> - **`okteto deploy --no-build`**: Skips the re-build of the images in your okteto manifest - **`okteto build --no-cache`**: Do not use a cache when building an image - **`okteto destroy --volumes`**: Destroy the persistent volumes created by the development environment. Persistent volumes are a storage resource that persists beyond the lifecycle of the Development Environment. This allows data to survive and be accessible by new Development Applications that may be created later. This could be useful for data for databases or application state while developing. -- **`okteto destroy --all`**: Destroy all Development Environments, including resources annotated with `dev.okteto.com/policy: keep` +- **`okteto destroy --all`**: Destroy all Development Environments, excluding resources annotated with `dev.okteto.com/policy: keep` ## Concepts to Understand @@ -100,4 +100,4 @@ Okteto's Preview Environments automatically generate a unique, shareable version - Follow this [tutorial to write your first Okteto Manifest](/get-started/deploy-your-app/index.mdx) - Join the [Okteto Community](https://community.okteto.com/) for additional help and updates -- Check out our [Release Notes](https://www.okteto.com/docs/release-notes/) for monthly updates to Okteto +- Check out our [Release Notes](release-notes.mdx) for monthly updates to Okteto diff --git a/versioned_docs/version-1.37/get-started/deploy-your-app/build.mdx b/versioned_docs/version-1.49/get-started/deploy-your-app/build.mdx similarity index 100% rename from versioned_docs/version-1.37/get-started/deploy-your-app/build.mdx rename to versioned_docs/version-1.49/get-started/deploy-your-app/build.mdx diff --git a/versioned_docs/version-1.37/get-started/deploy-your-app/dependencies.mdx b/versioned_docs/version-1.49/get-started/deploy-your-app/dependencies.mdx similarity index 96% rename from versioned_docs/version-1.37/get-started/deploy-your-app/dependencies.mdx rename to versioned_docs/version-1.49/get-started/deploy-your-app/dependencies.mdx index 580aeea42..ac657f2a4 100644 --- a/versioned_docs/version-1.37/get-started/deploy-your-app/dependencies.mdx +++ b/versioned_docs/version-1.49/get-started/deploy-your-app/dependencies.mdx @@ -28,7 +28,7 @@ The `wait` flag instructs Okteto to wait until MongoDB is ready before running t The `variables` field can be used to customize the deployment of the dependency, in this case to set the MongoDB password. :::note -Learn more about the diffent ways to define [Okteto Variables here](core/okteto-variables.mdx) 😎 +Learn more about the different ways to define [Okteto Variables here](core/okteto-variables.mdx) 😎 ::: Deploy the Movies app to apply the changes: diff --git a/versioned_docs/version-1.37/get-started/deploy-your-app/deploy.mdx b/versioned_docs/version-1.49/get-started/deploy-your-app/deploy.mdx similarity index 100% rename from versioned_docs/version-1.37/get-started/deploy-your-app/deploy.mdx rename to versioned_docs/version-1.49/get-started/deploy-your-app/deploy.mdx diff --git a/versioned_docs/version-1.37/get-started/deploy-your-app/endpoints.mdx b/versioned_docs/version-1.49/get-started/deploy-your-app/endpoints.mdx similarity index 100% rename from versioned_docs/version-1.37/get-started/deploy-your-app/endpoints.mdx rename to versioned_docs/version-1.49/get-started/deploy-your-app/endpoints.mdx diff --git a/versioned_docs/version-1.37/get-started/deploy-your-app/index.mdx b/versioned_docs/version-1.49/get-started/deploy-your-app/index.mdx similarity index 100% rename from versioned_docs/version-1.37/get-started/deploy-your-app/index.mdx rename to versioned_docs/version-1.49/get-started/deploy-your-app/index.mdx diff --git a/versioned_docs/version-1.37/get-started/dev-quickstart.mdx b/versioned_docs/version-1.49/get-started/dev-quickstart.mdx similarity index 98% rename from versioned_docs/version-1.37/get-started/dev-quickstart.mdx rename to versioned_docs/version-1.49/get-started/dev-quickstart.mdx index 4a6557703..62f7ecdbb 100644 --- a/versioned_docs/version-1.37/get-started/dev-quickstart.mdx +++ b/versioned_docs/version-1.49/get-started/dev-quickstart.mdx @@ -44,7 +44,7 @@ Welcome to the Okteto Quick Start Guide! This guide will help you, as a develope ## Step 4: Install the Okteto CLI -The Okteto CLI is our [open-source](https://github.com/okteto/okteto) tool that let's you develop your applications on Okteto. +The Okteto CLI is our [open-source](https://github.com/okteto/okteto) tool that lets you develop your applications on Okteto. Follow [the Okteto CLI installation steps](get-started/install-okteto-cli.mdx) before continuing this guide. diff --git a/versioned_docs/version-1.37/get-started/install-okteto-cli.mdx b/versioned_docs/version-1.49/get-started/install-okteto-cli.mdx similarity index 96% rename from versioned_docs/version-1.37/get-started/install-okteto-cli.mdx rename to versioned_docs/version-1.49/get-started/install-okteto-cli.mdx index 48836632b..2b4734656 100644 --- a/versioned_docs/version-1.37/get-started/install-okteto-cli.mdx +++ b/versioned_docs/version-1.49/get-started/install-okteto-cli.mdx @@ -8,7 +8,7 @@ id: install-okteto-cli import variables from '../variables.json'; import CodeBlock from '@theme/CodeBlock'; -The Okteto CLI is our [open-source](https://github.com/okteto/okteto) tool that let's you develop your applications on Okteto. +The Okteto CLI is our [open-source](https://github.com/okteto/okteto) tool that lets you develop your applications on Okteto. This doc explains how to install and configure the Okteto CLI. diff --git a/versioned_docs/version-1.37/get-started/install/amazon-eks.mdx b/versioned_docs/version-1.49/get-started/install/amazon-eks.mdx similarity index 92% rename from versioned_docs/version-1.37/get-started/install/amazon-eks.mdx rename to versioned_docs/version-1.49/get-started/install/amazon-eks.mdx index e17201381..1e969b325 100644 --- a/versioned_docs/version-1.37/get-started/install/amazon-eks.mdx +++ b/versioned_docs/version-1.49/get-started/install/amazon-eks.mdx @@ -32,6 +32,8 @@ You'll also need the following: **Important**: As of Okteto 1.35, Okteto supports Amazon Linux 2 (AL2) and introduces support for Amazon Linux 2023 (AL2023) as the AMI for cluster nodes. We recommend upgrading Okteto to version 1.35 before upgrading your EKS cluster to Kubernetes 1.33 or changing to AL2023. In mixed clusters, make sure both the control plane and development workloads run on nodes with Amazon Linux 2 or Amazon Linux 2023 using [taints](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) and [tolerations](self-hosted/helm-configuration.mdx#tolerations). +**Bottlerocket OS is not supported.** Okteto requires write access to `/etc/hosts` on cluster nodes, which is not possible on Bottlerocket's read-only root filesystem. If you are using Bottlerocket, you must switch to AL2023. See [Troubleshooting](self-hosted/manage/troubleshooting.mdx#daemon-fails-with-open-etchosts-permission-denied) for more details. + ::: ## Getting your Okteto License @@ -98,17 +100,34 @@ export AWS_PAGER="" For initial evaluation, we recommend a Kubernetes cluster with a pool of 3 `m5.xlarge` nodes with 250 GB each: +:::note ARM Clusters (Beta) +If you want to install Okteto on an ARM-based cluster using AWS Graviton instances, use `m7g.xlarge` instead of `m5.xlarge`. ARM support on EKS is currently in **Beta**. See the [ARM Support guide](self-hosted/manage/arm-support.mdx) for full details and requirements. +::: + ```bash -eksctl create cluster \ - --region="${AWS_REGION}" \ - --name="${CLUSTER_NAME}" \ - --with-oidc \ - --version="${K8S_VERSION}" \ - --nodes=3 \ - --node-type="m5.xlarge" \ - --node-volume-size="250" \ - --node-volume-type="gp3" \ - --node-ami-family="AmazonLinux2023" +eksctl create cluster -f - <= {variables.cliVersion} ([okteto installation guides](get-started/install-okteto-cli.mdx)) +- `nkp` >= 2.17 ([NKP CLI installation guide](https://portal.nutanix.com/page/documents/details?targetId=Nutanix-Kubernetes-Platform-v2_17:Nutanix-Kubernetes-Platform-v2_17)) +- `kubectl` >= 1.28 ([kubectl installation guides](https://kubernetes.io/docs/tasks/tools/#kubectl)) +- `helm` >= 3.14 ([helm installation guides](https://helm.sh/docs/intro/install/)) + +You'll also need the following: + +- An Okteto License +- A Domain and the ability to create wildcard DNS records for it +- An NKP management cluster, and a workload cluster managed by it + +## Getting your Okteto License + +A license is mandatory to use Okteto. You'll receive a license key as part of your subscription to Okteto. If you haven't received it, [please open a support ticket](https://okteto.com/support). + +If you are interested in evaluating Okteto, [sign up for our Free Tier (5 seats, 1 year)](https://www.okteto.com/free-trial/). No credit card required. + +## A Domain and the ability to create wildcard DNS records for it + +You'll need sufficient access to a [subdomain](self-hosted/helm-configuration.mdx#subdomain) to add a wildcard DNS record, such as `dev.example.com`. +By default, all endpoints created by Okteto for your development environments will be exposed on the wildcard subdomain you choose. + +NKP doesn't create this record for you, so make sure you can add it in your DNS provider. + +## Prepare your NKP workload cluster + +Our installation guides assume Okteto will be running in a new dedicated workload cluster. + +:::note +If you plan on installing Okteto in an existing workload cluster with other workloads, read this section to make sure your cluster satisfies the requirements to install Okteto. +::: + +### Create the workload cluster + +Create a workload cluster from your NKP management cluster using the NKP Dashboard or the `nkp create cluster` command for your infrastructure provider. +Follow the [NKP documentation](https://portal.nutanix.com/page/documents/details?targetId=Nutanix-Kubernetes-Platform-v2_17:Nutanix-Kubernetes-Platform-v2_17) for the provider-specific options. + +For initial evaluation, we recommend a node pool of 3 worker nodes with 4 vCPUs, 16 GB of memory, and 250 GB of disk each (for example, `m5.xlarge` on AWS). + +:::note +Okteto supports Kubernetes versions {variables.kubernetesMinVersion} through {variables.kubernetesMaxVersion}. +Check the [supported Kubernetes versions](release-notes.mdx) for the Okteto Helm chart version you plan to install, and choose an NKP release that ships a compatible Kubernetes version. +::: + +For example, to create a workload cluster on Amazon EKS from your management cluster: + +```bash +export CLUSTER_NAME="okteto" +export WORKSPACE_NAMESPACE="" + +nkp create cluster eks \ + --cluster-name=${CLUSTER_NAME} \ + --namespace=${WORKSPACE_NAMESPACE} \ + --region= \ + --worker-instance-type=m5.xlarge \ + --worker-replicas=3 \ + --kubeconfig= +``` + +Clusters created from the management cluster are attached to its workspace automatically, so they show up in the NKP Dashboard and receive the workspace platform applications. + +### Get the workload cluster kubeconfig + +Retrieve the kubeconfig of the workload cluster from the management cluster: + +```bash +nkp get kubeconfig \ + --cluster-name=${CLUSTER_NAME} \ + --namespace=${WORKSPACE_NAMESPACE} \ + --kubeconfig= > ${CLUSTER_NAME}.conf + +export KUBECONFIG=$(pwd)/${CLUSTER_NAME}.conf +kubectl get nodes +``` + +All the commands below run against the workload cluster. + +:::tip +On Amazon EKS, the kubeconfig returned by `nkp get kubeconfig` authenticates with `aws-iam-authenticator`. If you don't have it installed, generate the kubeconfig with `aws eks update-kubeconfig --name --region ` instead. +::: + +### Verify the default storage class + +Okteto uses persistent volumes to persist the cache of the [Okteto Build](core/build-service.mdx) service (BuildKit). +The default installation also uses persistent volumes to store your container images in the [Okteto Registry](core/container-registry.mdx). + +NKP deploys a CSI driver and a default storage class on every cluster. Confirm there is one marked as `(default)`: + +```bash +kubectl get storageclass +``` + +The name depends on your infrastructure provider: + +| Infrastructure provider | Default storage class | +|---|---| +| Nutanix AHV | `nutanix-volume` | +| AWS / Amazon EKS | `ebs-sc` | +| Azure / AKS | `azuredisk-sc` | +| GCP | `csi-gce-pd` | +| vSphere | `vsphere-raw-block-sc` | + +:::warning +On pre-provisioned clusters, NKP uses the `localvolumeprovisioner` storage class, which Nutanix doesn't recommend for production. Configure a production-grade CSI driver as the default storage class before installing Okteto. +::: + +### Verify load balancer support + +Okteto exposes its ingress controller using a Kubernetes `LoadBalancer` service. Make sure your workload cluster can allocate an external address for it: + +- **Nutanix AHV, vSphere, and pre-provisioned clusters**: NKP uses [MetalLB](https://metallb.io/). NKP's own Traefik ingress already takes one address from the MetalLB range, so make sure the range has **at least one more free IP address** for Okteto. +- **Cloud providers (AWS, EKS, Azure, AKS, GCP)**: the cloud provider allocates a load balancer automatically. + +NKP clusters use [Cilium](https://cilium.io/) as the CNI, with kube-proxy replacement enabled. +We recommend setting `externalTrafficPolicy: Local` on the Okteto ingress controller service so the load balancer only sends traffic to nodes that run an ingress controller pod. The configuration below already includes it. + +## Installing Okteto + +:::note +If you already use Argo CD, or you want a GitOps-based installation, you can install Okteto with Argo CD instead of running Helm directly. Argo CD deploys the same Helm chart declaratively. See [Configure Argo CD](self-hosted/manage/argocd.mdx) for the `Application` manifest, sync policy, and the `ignoreDifferences` Okteto requires. +It replaces [Add the Okteto Helm repository](#add-the-okteto-helm-repository) and [Installing the Okteto Helm chart](#installing-the-okteto-helm-chart). Every other step on this page still applies, including the DNS record, sign-in, and CLI context. +::: + +Okteto is installed using a Helm chart. Let's start the process: + +### Add the Okteto Helm repository + +You'll need to add the Okteto Helm repository to be able to install Okteto: + +```bash +helm repo add okteto https://charts.okteto.com +helm repo update +``` + +### Create the Helm configuration file + +In order to install Okteto you need to first create a `config.yaml` for the installation process. +Replace `license` and `subdomain` with your own values, and pick the configuration for your infrastructure provider: + + + + +```yaml title="config.yaml" +// highlight-next-line +license: "REPLACE ME WITH YOUR OKTETO LICENSE" +// highlight-next-line +subdomain: "REPLACE ME WITH YOUR OKTETO DOMAIN" + +ingress-nginx: + controller: + service: + externalTrafficPolicy: Local + +registry: + storage: + filesystem: + persistence: + enabled: true +``` + +MetalLB assigns the next free address in its range to the Okteto ingress controller. To request a specific address, add the `metallb.universe.tf/loadBalancerIPs: ` annotation under `ingress-nginx.controller.service.annotations`. + + + + +```yaml title="config.yaml" +// highlight-next-line +license: "REPLACE ME WITH YOUR OKTETO LICENSE" +// highlight-next-line +subdomain: "REPLACE ME WITH YOUR OKTETO DOMAIN" + +ingress-nginx: + controller: + service: + externalTrafficPolicy: Local + annotations: + service.beta.kubernetes.io/aws-load-balancer-type: nlb + service.beta.kubernetes.io/aws-load-balancer-scheme: "internet-facing" + +registry: + storage: + filesystem: + persistence: + enabled: true +``` + +The annotations tell AWS to create an internet-facing [Network Load Balancer (NLB)](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html). NLBs on NKP-managed clusters are internal by default, so the `internet-facing` scheme is required to reach Okteto from outside your VPC. + + + + +```yaml title="config.yaml" +// highlight-next-line +license: "REPLACE ME WITH YOUR OKTETO LICENSE" +// highlight-next-line +subdomain: "REPLACE ME WITH YOUR OKTETO DOMAIN" + +ingress-nginx: + controller: + service: + externalTrafficPolicy: Local + +registry: + storage: + filesystem: + persistence: + enabled: true +``` + +Azure allocates a public load balancer for the Okteto ingress controller automatically, so no additional annotations are required. + + + + +```yaml title="config.yaml" +// highlight-next-line +license: "REPLACE ME WITH YOUR OKTETO LICENSE" +// highlight-next-line +subdomain: "REPLACE ME WITH YOUR OKTETO DOMAIN" + +ingress-nginx: + controller: + service: + externalTrafficPolicy: Local + +registry: + storage: + filesystem: + persistence: + enabled: true +``` + +Google Cloud allocates a public load balancer for the Okteto ingress controller automatically, so no additional annotations are required. + + + + +_Note: This is the minimum configuration. Check our [Helm configuration](self-hosted/helm-configuration.mdx) docs to learn more_ + +Okteto installs its own NGINX ingress controller, which runs alongside the Traefik ingress that NKP deploys on every cluster. The two don't conflict: Okteto only manages ingresses for the endpoints of your development environments. + +### Installing the Okteto Helm chart + +Install the latest version of Okteto by running: + + + {`helm upgrade --install okteto okteto/okteto -f config.yaml --namespace=okteto --create-namespace --version=${variables.chartVersion}`} + + +After a few seconds, all the resources will be created. The output will look something like this: + +```bash +Release "okteto" has been installed. Happy Helming! +NAME: okteto +LAST DEPLOYED: Thu Mar 26 18:07:55 2020 +NAMESPACE: okteto +STATUS: deployed +``` + +### Retrieve the Ingress Controller address + +Use `kubectl` to fetch the address allocated to the NGINX Ingress Controller installed as a part of Okteto: + +```bash +kubectl get service -l=app.kubernetes.io/name=ingress-nginx,app.kubernetes.io/component=controller --namespace=okteto +``` + +The output will look something like this: + +``` +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +okteto-ingress-nginx-controller LoadBalancer 10.0.7.73 10.38.12.151 80:30795/TCP,443:32481/TCP,1234:30885/TCP 5m +``` + +Take the `EXTERNAL-IP` value and add a wildcard DNS record for the domain you have chosen to use: + +- If it's an IP address (MetalLB), create an `A` record with the name `*` pointing to it. +- If it's a hostname (for example, an AWS NLB), create a `CNAME` record with the name `*` pointing to it, or an alias record if your DNS provider supports it. + +### Sign in to your Okteto instance + +:::warning + +**Important**: The default installation is not recommended for production use. We highly advise configuring a [wildcard certificate](self-hosted/install/certificates/index.mdx) and [Okteto Registry storage](self-hosted/install/okteto-registry-storage/index.mdx) after finishing your evaluation and giving your team access to your Okteto instance. + +NKP deploys cert-manager on workload clusters by default, so you can follow the [cert-manager and Let's Encrypt guide](self-hosted/install/certificates/cert-manager.mdx) without installing cert-manager yourself. Only create the DNS01 `Issuer` and the wildcard `Certificate`. + +::: + +After a successful installation, you can access your Okteto instance at `https://okteto.SUBDOMAIN`. Your account will be automatically created as part of the login process. The first user to successfully login into the instance will be automatically assigned the `administrator` role. + +### Configure the Okteto CLI + +[Install the Okteto CLI](get-started/install-okteto-cli.mdx) if you haven't done it yet and set the Okteto CLI context with your Okteto instance. +To do this, run the command below replacing `SUBDOMAIN`: + +```bash +okteto context use https://okteto.SUBDOMAIN +``` + +Once your Okteto instance is up and running and your Okteto CLI properly configured, you are going to [deploy your first app](get-started/deploy-your-app/index.mdx) to Okteto 😎 + +## Support for joint Okteto and Nutanix customers + +Okteto and Nutanix work together to support joint customers. +If you run into an issue installing or operating Okteto on NKP, [open a support ticket](https://okteto.com/support) with Okteto. When an issue involves the NKP layer, we'll coordinate with Nutanix to resolve it. diff --git a/versioned_docs/version-1.37/get-started/install/openshift.mdx b/versioned_docs/version-1.49/get-started/install/openshift.mdx similarity index 97% rename from versioned_docs/version-1.37/get-started/install/openshift.mdx rename to versioned_docs/version-1.49/get-started/install/openshift.mdx index f119ff052..3644d4d00 100644 --- a/versioned_docs/version-1.37/get-started/install/openshift.mdx +++ b/versioned_docs/version-1.49/get-started/install/openshift.mdx @@ -82,7 +82,7 @@ This command grants the `privileged` SCC to the `okteto-buildkit` service accoun ### Grant access to the host to the Okteto Daemon service account By default, access to the host is restricted by default in Red Hat OpenShift. -This restriction impacts the he [Okteto Daemon](self-hosted/helm-configuration.mdx#daemonset) service. +This restriction impacts the [Okteto Daemon](self-hosted/helm-configuration.mdx#daemonset) service. To grant the necessary permissions to the Okteto Daemon, run: ```bash @@ -176,7 +176,7 @@ user: - system:openshift:scc:anyuid ``` -The `extraRoleBindings` section allows your developers to use use images that require `root` privileges in their development environments. +The `extraRoleBindings` section allows your developers to use images that require `root` privileges in their development environments. :::tip This is the minimum configuration. Check our [Helm configuration documentation](self-hosted/helm-configuration.mdx) to learn more diff --git a/versioned_docs/version-1.37/get-started/using-okteto-cli-and-dashboard.mdx b/versioned_docs/version-1.49/get-started/using-okteto-cli-and-dashboard.mdx similarity index 80% rename from versioned_docs/version-1.37/get-started/using-okteto-cli-and-dashboard.mdx rename to versioned_docs/version-1.49/get-started/using-okteto-cli-and-dashboard.mdx index 83c12ae0a..d86e6c40b 100644 --- a/versioned_docs/version-1.37/get-started/using-okteto-cli-and-dashboard.mdx +++ b/versioned_docs/version-1.49/get-started/using-okteto-cli-and-dashboard.mdx @@ -21,7 +21,7 @@ For a deeper dive into how the Okteto Manifest works, check out our [Okteto Mani ## Essential Okteto CLI Commands -The Okteto CLI is our [open-source](https://github.com/okteto/okteto) tool that let's you develop your applications on Okteto. +The Okteto CLI is our [open-source](https://github.com/okteto/okteto) tool that lets you develop your applications on Okteto. If you haven't done so yet, install and configure the Okteto CLI following [this guide](get-started/install-okteto-cli.mdx). Most developers interact with okteto via the Command Line Interface (CLI). Here we’ll explain common CLI commands and a typical workflow for using them. @@ -53,22 +53,34 @@ You can find a list of all available CLI commands in our full [CLI reference gui ### 2. **Using the Catalog to Deploy a Development Environment** - The most common way to deploy a Development Environment on Okteto is through the Catalog. The Catalog is a list of your applications, configured by a platform engineer on your team, with everything the application needs to run included. You can find the Catalog by clicking on the “Deploy a Dev Environment” button. + The most common way to deploy a Development Environment on Okteto is through the Catalog. The Catalog is a list of your applications, configured by a platform engineer on your team, with everything the application needs to run included. You can find the Catalog by clicking on the “Deploy Dev Environment” button.

Okteto Namespace Landing Page

You can also deploy a Development Environment with the following methods: - - **Git Repository:** Deploy from a repository in a connected GitHub account - - **URL**: Deploy from a specific Git URL + - **GitHub:** Deploy from a repository in a connected GitHub account + - **Git URL**: Deploy from a specific Git URL + +### 3. **Monitoring Your Environment** -### 3. **Creating a New Namespace** + The Namespace view shows you all the resources that Okteto manages for your environment, and for each resource you can inspect its YAML and stream its live logs. Clicking on the element that represents the environment shows all the build and deploy steps defined in your manifest, along with the logs for each event. Logs and status update live for all resources, making this a great way to monitor and troubleshoot the state of your environment. + +

+ monitoring resources and streaming live logs for an environment in the Okteto dashboard +

+ +### 4. **Creating a New Namespace** To create a Namespace, go to the Okteto dashboard, click on your Namespace on the left, and at the bottom of the namespace list select (+) New Namespace.

@@ -84,7 +96,7 @@ You can find a list of all available CLI commands in our full [CLI reference gui - **Non-Personal Namespaces** are additional Namespaces created by users or through automation, facilitating broader project collaboration and management. They may be deleted or transferred to other users. - As a common practice, you might name your Namespace based on a feature number, ticket number, or a similar identifier. Development environments within these Namespaces are created from Git branches. This allows you to run multiple Namespaces simultaneously, each corresponding to a different branch or feature. -### 4. **Sharing a Namespace** +### 5. **Sharing a Namespace** - Collaborate on several applications at once by sharing your namespace - To share a Namespace go to the Okteto dashboard, select the namespace you want to share and press the `Share` button in the namespace menu (you'll find it in the main bar at the top). @@ -92,19 +104,19 @@ You can find a list of all available CLI commands in our full [CLI reference gui

Okteto Namespace Landing Page

Read more about [sharing a Namespace here](core/namespaces.mdx#sharing-and-collaboration-with-namespaces) -### 5. **Environment States** +### 6. **Environment States** - **Sleep**: Suspend your environment to save resources, the Okteto Garbage collector configured by your Okteto admin will set the sleep periods after a certain amount of inactivity - **Destroy All**: Remove all resources in a Namespace - - **Keep Awake**: Admins can choose to prevent Namespaces from sleeping so that they are always accessible + - **Persistent**: Admins can choose to prevent Namespaces from deletion and automatically sleeping so that they are always accessible -### 6. **Preview Environments** +### 7. **Preview Environments** - Temporary environments for testing features before merging into the main branch. These are a great way to share your changes with a QA Team or Product Manager - Okteto Admins can configure Previews to work with your source control and CI/CD provider so that a Preview links are automatically added to submitted pull requests @@ -112,13 +124,17 @@ You can find a list of all available CLI commands in our full [CLI reference gui

Okteto Namespace Landing Page

Read more about [Preview Environments here](previews/index.mdx) +### 8. **Help menu** + + Click the **Help** item at the bottom of the main menu to access quick links to documentation, community resources, and support. The Help panel also displays the installed Okteto version at the bottom, which is useful when reporting issues or verifying your environment. + ## Next Steps Now that you know more about how to use Okteto, lets introduce some [Advanced Commands & Concepts](get-started/advanced-commands-and-concepts.mdx) 😎 diff --git a/versioned_docs/version-1.37/index.md b/versioned_docs/version-1.49/index.md similarity index 52% rename from versioned_docs/version-1.37/index.md rename to versioned_docs/version-1.49/index.md index d4da1642f..4bd2f5cbc 100644 --- a/versioned_docs/version-1.37/index.md +++ b/versioned_docs/version-1.49/index.md @@ -1,10 +1,13 @@ --- -title: Welcome to Okteto! -description: An overview of Okteto and how it helps teams build, test, and deploy faster. +title: "Okteto: the environment platform for agentic development" +description: Okteto gives every AI agent task and developer an isolated, production-like environment on your own infrastructure to build, test, and verify against real services and data. --- -## Build modern development experiences with Okteto -Okteto transforms the way developers code, test, and deploy applications by offering a seamless, cloud-native development experience. Say goodbye to the complexities of setting up local environments and the discrepancies between development and production. With Okteto, you get **ephemeral cloud-based environments**, **instant code sync**, **remote debugging**, and **built-in automations** all designed to improve developer productivity and platform team efficiency. +## The environment platform for agentic development + +Okteto gives every task, whether it's run by an AI agent or a developer, an isolated, production-like environment on your own infrastructure. Agents and developers build, run, and test their changes against real services and data, so the work is verified before a human reviews it. Platform teams stay in control with resource limits, governance, and observability across every environment. + +These docs explain how to install Okteto, run agent and development environments, add Preview Environments to your pull requests, test inside those environments, and operate the platform on BYOC or Self-Hosted infrastructure. [Start with our Free Tier (5 seats, 1 year)](https://www.okteto.com/free-trial/) @@ -13,20 +16,23 @@ Okteto transforms the way developers code, test, and deploy applications by offe ### Control, Governance, and Self-service access Enable your developers to easily access secure and reproducible ephemeral environments. Okteto abstracts the complexity of Kubernetes, providing developers with a straightforward path from code to deployment, all within the cloud. This means no more wrestling with local setup or inconsistencies between environments. -![Platform team using Okteto diagram](../../static/img/platform-team-diagram.jpg) +![Diagram showing developers reaching self-service ephemeral environments in Okteto, while the platform team retains control over the underlying Kubernetes infrastructure](../../static/img/platform-team-diagram.jpg) -### Create a seamless development experience -With Okteto, your development environment is a one-click experience for everyone on the team. Featuring instantaneous Code Sync and Live Updates, experience the magic of seeing your code changes reflected instantly in your cloud environment. This allows for rapid testing and iteration without the need for rebuilds or redeployments, ensuring that your applications run just as smoothly in development as they do in production. +### Real environments for agents and developers +With Okteto, every development environment is a one-click experience for everyone on the team, human or agent. Code Sync and Live Updates reflect your code changes in your cloud environment as soon as you save, so you test and iterate without rebuilds or redeployments. Agents get the same isolated, production-like environments through the Okteto CLI, so what runs for an agent runs the same for a developer and in production. ![Developing with Okteto Example](../../static/img/dev-environment-example.jpg) ### Okteto Manifest simplifies environment automation -Utilize the [Okteto Manifest](core/okteto-manifest.mdx) to define and configure your development environments declaratively. This powerful feature ensures consistent and reproducible environments across your team, tailored to your projects' needs. Use the [Okteto Catalog](development/deploy/deploy-from-catalog.mdx) to create a collection of ready-to-use development environments for your development team. +Utilize the [Okteto Manifest](core/okteto-manifest.mdx) to define and configure your development environments declaratively. This ensures consistent, reproducible environments across your team, tailored to your projects' needs. Use the [Okteto Catalog](development/deploy/deploy-from-catalog.mdx) to create a collection of ready-to-use development environments for your development team. -![Platform team using Okteto diagram](../../static/img/manifest.jpg) +![Diagram showing the Okteto Manifest's build, deploy, dev, and test sections generating ephemeral environments for the Dev, Preview, Test, and QA stages](../../static/img/manifest.jpg) ## Key features +### AI Agent Environments +Okteto works with the agents you already use, such as Claude Code, Cursor, Codex, and Copilot. Install the Okteto plugin in one command and your agent gets an isolated, production-like environment, driven by the same Okteto CLI and `okteto.yaml` your developers use. Now the agent can deploy code, run tests, and verify its changes against real services and data instead of only reading and writing files locally, so its work is proven before you review it. [Agentic Workflows](agentic/index.mdx) covers the setup and example prompts. + ### Development Environments Okteto's [Development Environments](development/index.mdx) enable you to deploy and develop applications directly in the cloud with a single [CLI command](development/using-okteto-cli.mdx) or click of a button. Write code locally on your machine and view your changes live, deployed in the cloud **as soon as you hit save**! You don't have to spend time configuring anything to do this. @@ -56,10 +62,12 @@ Okteto is flexible enough to meet your deployment and compliance needs. --- -## Get Started Today +## Getting started -- 🚀 [Follow the installation guide](get-started/install/index.mdx) +- 🤖 [Set up environments for AI agents](agentic/index.mdx) — install the Okteto plugin so your coding agent can deploy, test, and debug against real services. +- 👩‍💻 [Deploy your first Development Environment](get-started/dev-quickstart.mdx) — start here if your platform team already runs Okteto. +- 🚀 [Follow the installation guide](get-started/install/index.mdx) — install the Okteto Platform in your own Kubernetes cluster. - 🗓️ [Book a demo with our team](https://okteto.com/schedule/) - 🎁 [Sign up for our Free Tier (5 seats, 1 year)](https://www.okteto.com/free-trial/) -Need help deciding which deployment model or feature fits best? [Contact us](https://okteto.com/schedule/) and we’ll walk you through it. \ No newline at end of file +Need help deciding which deployment model or feature fits best? [Contact us](https://okteto.com/schedule/) and we'll walk you through it. diff --git a/versioned_docs/version-1.49/previews/index.mdx b/versioned_docs/version-1.49/previews/index.mdx new file mode 100644 index 000000000..83480309c --- /dev/null +++ b/versioned_docs/version-1.49/previews/index.mdx @@ -0,0 +1,127 @@ +--- +title: Preview Environments +description: Create a preview environment for your application using Okteto +--- + +import Image from "@theme/Image"; + +Preview Environments automatically create a live, production-like instance of your application for every pull request. This means faster feedback loops, reduced deployment risks, and the ability to test changes in a real environment before merging to main—no more "works on my machine" surprises. + +

+ Previews list in the Okteto UI showing active and sleeping Preview Environments with repository, branch, and status columns +

+ +Okteto's Preview Environments are powered by Kubernetes and seamlessly integrate with your existing CI/CD workflows. Share live previews with designers, product managers, QA engineers, and stakeholders—anyone can test and provide feedback without needing to set up a development environment. + +## Why Preview Environments? + +Preview Environments transform how teams collaborate on code changes by providing instant, shareable environments for every pull request. + +**Accelerate Review Cycles** +- Share a live URL instead of screenshots or videos +- Stakeholders can click through actual functionality +- Get feedback from non-technical team members without complex setup +- Reduce back-and-forth in PR comments + +**Catch Issues Early** +- Test integration with dependent services in production-like conditions +- Identify configuration issues before they reach production +- Run automated tests against real infrastructure +- Validate database migrations and schema changes safely + +**Reduce Deployment Risk** +- Preview exactly what will be deployed to production +- Test with production-like data and scale +- Validate infrastructure changes alongside code changes +- Ensure all services work together before merging + +**Improve Team Productivity** +- No more waiting for shared staging environments +- Parallel development without conflicts +- Automatic cleanup saves infrastructure costs +- Focus on building features, not managing environments + +## How It Works + +Preview Environments in Okteto follow a simple, automated workflow: + +1. **Open a Pull Request** - When you create or update a PR in GitHub or GitLab, your CI/CD workflow triggers an Okteto Preview Environment automatically +2. **Automatic Deployment** - Okteto deploys your application using your [Okteto manifest](core/okteto-manifest.mdx), creating an isolated environment in response to the CI/CD trigger +3. **Share and Collaborate** - Get a unique URL to share with your team for testing and feedback +4. **Automatic Updates** - Push new commits, and your CI/CD workflow redeploys the Preview Environment with the latest changes +5. **Automatic Cleanup** - When you close or merge the PR, your CI/CD workflow destroys the Preview Environment + +:::tip +Preview Environments can run [integration tests](reference/okteto-cli.mdx#test) automatically, ensuring your changes work correctly before merging. +::: + +## Getting Started + +Ready to add Preview Environments to your workflow? Choose your CI/CD platform: + +- [GitHub Actions](previews/using-github-actions.mdx) - Set up Preview Environments with GitHub +- [GitLab CI/CD](previews/using-gitlab-cicd.mdx) - Integrate with GitLab pipelines +- Bitbucket Pipelines (coming soon!) +- Azure DevOps (coming soon!) + +### Prerequisites + +Preview Environments deploy the code in a pull request to [Okteto](index.md). You can configure the way your code gets deployed using the [Okteto manifest](core/okteto-manifest.mdx)'s `deploy` section. + +### Detecting Preview Environments in Your Code + +When your application runs in a Preview Environment, Okteto automatically sets the `OKTETO_IS_PREVIEW_ENVIRONMENT` environment variable to `true`. You can use this in your application to: + +- Enable preview-specific features or configurations +- Show preview banners or badges in your UI +- Adjust logging or monitoring behavior +- Connect to preview-specific resources + +For a complete list of available environment variables, see [Okteto Variables](core/okteto-variables.mdx). + +## Understanding Preview Scope + +Preview Environments can be configured with different visibility levels to match your team's workflow: + +- **Global Scope** (default): The Preview Environment is accessible to all members of your namespace. These previews are visible to the entire team and can be managed by users with appropriate permissions. Ideal for team collaboration and stakeholder reviews. + +- **Personal Scope**: The Preview Environment is only accessible to you and anyone you explicitly share it with. These previews are indicated with a user icon next to the preview name in the preview list. Perfect for testing experimental changes before sharing with the broader team. + +:::info +Preview Environments use global scope by default. You can set the scope to personal when creating the Preview Environment if you need private access. The dashboard doesn't include a Scope column: only personal-scope previews are marked, with a user icon next to the preview name. A preview with no icon has global scope. +::: + +## Working with Preview Environments + +### Viewing Your Previews + +All Preview Environments are listed in the Okteto dashboard, where you can see their status, owner, and associated pull request. Click any preview name to view its details and access the live environment. + +### Filtering and Searching + +The Preview Environments list provides several filtering options to help you find specific previews: + +- **Search** - Search for previews by name using the search box +- **Repository** - Filter by one or more repositories (searchable dropdown) +- **Status** - Filter by preview status such as active, sleeping, or error states +- **Owner** - Filter by the user who created the preview (searchable dropdown) +- **Updated** - Filter by when the preview was last updated (last hour, 24 hours, 7 days, 30 days, or 90 days) + +You can combine multiple filters to narrow down your search results. + +### Preview Information + +Each Preview Environment displays the following information: + +1. **Name** - The Preview Environment name. Click the name to view details. Previews with personal scope show a user icon next to the name. +2. **Repository** - The repository hosting the code, with a link to view it in your source control provider +3. **Branch** - The Git branch being deployed in this preview +4. **PR** - A link to the associated pull request +5. **Owner** - The user who created the Preview Environment +6. **Status** - The current status of the preview (e.g., active, sleeping, deploying) +7. **Last Updated** - When the preview was last modified + +For detailed information on managing previews as an administrator (delete, wake, sleep, persist), see the [Managing Preview Environments guide](admin/previews.mdx). diff --git a/versioned_docs/version-1.37/previews/using-github-actions.mdx b/versioned_docs/version-1.49/previews/using-github-actions.mdx similarity index 99% rename from versioned_docs/version-1.37/previews/using-github-actions.mdx rename to versioned_docs/version-1.49/previews/using-github-actions.mdx index a1c5b00db..5d5a8086b 100644 --- a/versioned_docs/version-1.37/previews/using-github-actions.mdx +++ b/versioned_docs/version-1.49/previews/using-github-actions.mdx @@ -41,7 +41,7 @@ concurrency: # more info here: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#concurrency group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: false - + jobs: preview: runs-on: ubuntu-latest diff --git a/versioned_docs/version-1.37/previews/using-gitlab-cicd.mdx b/versioned_docs/version-1.49/previews/using-gitlab-cicd.mdx similarity index 50% rename from versioned_docs/version-1.37/previews/using-gitlab-cicd.mdx rename to versioned_docs/version-1.49/previews/using-gitlab-cicd.mdx index eec46b308..56de22c6e 100644 --- a/versioned_docs/version-1.37/previews/using-gitlab-cicd.mdx +++ b/versioned_docs/version-1.49/previews/using-gitlab-cicd.mdx @@ -1,24 +1,24 @@ --- title: Preview environments using GitLab CI/CD -description: Create a preview environment for your application using Okteto and GitLab +description: Configure GitLab CI/CD to automatically create Preview Environments for your application using Okteto. sidebar_label: Using GitLab CI/CD id: using-gitlab-cicd --- import Image from "@theme/Image"; -This section will show you how to automatically create a preview environment for your applications using Okteto and GitLab's review apps. +Okteto integrates with GitLab review apps to automatically create a Preview Environment for your applications on every merge request. -## Pre-Requisites +## Prerequisites - An Okteto account -- A [GitLab Account](https://gitlab.com) +- A [GitLab account](https://gitlab.com) -For this tutorial, we'll be using our sample [movies rental application](https://gitlab.com/okteto/preview-environments). If you're using your own application to follow along, please ensure you have your [Okteto Manifest](reference/okteto-manifest.mdx) configured. +This tutorial uses the sample [movies rental application](https://gitlab.com/okteto/preview-environments). If you are using your own application, make sure your [Okteto Manifest](reference/okteto-manifest.mdx) is configured. -## Step 1: Configure your Okteto API Token +## Step 1: Configure your Okteto API token -To deploy a preview environment with Okteto, you need to define the following environment variables: +To deploy a Preview Environment with Okteto, you need to define the following environment variables: 1. `OKTETO_TOKEN`: an Okteto [access token](admin/dashboard.mdx#admin-access-tokens) 1. `OKTETO_CONTEXT`: specify the URL of your Okteto instance (e.g., https://okteto.example.com) @@ -38,7 +38,7 @@ To add the environment variables: The "Protect variable" flag is checked by default, meaning only protected branches can access the variable's value. Uncheck this flag if you want to use the variable across all branches. ::: -1. Add _OKTETO_TOKEN_ as the key, and your access token as the value, and press the **Add Variable** button: +1. Add `OKTETO_TOKEN` as the key and your access token as the value, then click the **Add Variable** button:

-1. Repeat the same process to add the _OKTETO_CONTEXT_ variables (optional) +1. Repeat the same process to add the `OKTETO_CONTEXT` variable (optional):

-## Step 2: Configure the Preview Environment on the Repository +## Step 2: Configure the Preview Environment on the repository -To tell GitLab how to deploy our preview environment, you need to create a file named [`.gitlab-ci.yml`](https://docs.gitlab.com/ee/ci/yaml/gitlab_ci_yaml.html) file at the root of the repository. +To configure GitLab to deploy your Preview Environment, create a [`.gitlab-ci.yml`](https://docs.gitlab.com/ee/ci/yaml/gitlab_ci_yaml.html) file at the root of the repository. -In this file, we'll define two jobs. The `review` creates a preview environment for every branch and a `stop-review` job to destroy it when merging or deleting the branch. +This file defines two jobs: `review` creates a Preview Environment for every branch, and `stop-review` destroys it when merging or deleting the branch. -The flow to create a preview environment looks like this: +The flow to create a Preview Environment looks like this: -1. Create a dedicated namespace for the Preview Environment +1. Create a dedicated Namespace for the Preview Environment 1. Build and deploy the application using the [Okteto preview](previews/index.mdx) defined in the repository. 1. Add the URL of the Preview Environment to the Merge Request. -The flow to delete a preview environment looks like this: +The flow to delete a Preview Environment looks like this: -1. Destroy the application deployed with the [Okteto preview](previews/index.mdx) +1. Destroy the application deployed with [Okteto preview](previews/index.mdx) The `.gitlab-ci.yml` looks like this: ```yaml -# file: .gitlab.ci.yml -image: okteto/okteto:latest +# file: .gitlab-ci.yml +image: ghcr.io/okteto/okteto:latest stages: - review @@ -118,31 +118,31 @@ stop-review: - master ``` -A few recommendations when creating your preview environment: +A few recommendations when creating your Preview Environment: -- Create a preview environment per branch/merge request to keep things isolated. We use a preview and `$CI_COMMIT_REF_SLUG` in the name to ensure the namespace is unique and that we only create one per branch. -- Pass the URL of your preview environment using the `environment.url` key. That way, the reviewers can directly go to the preview environment from GitLab. -- Delete both the preview environment, and the namespace when the branch is deleted to cut down on manual deletion. +- Create one Preview Environment per branch or merge request to keep things isolated. The example uses `$CI_COMMIT_REF_SLUG` in the name to ensure the Namespace is unique and that only one Preview Environment exists per branch. +- Pass the URL of your Preview Environment using the `environment.url` key so reviewers can go directly to the Preview Environment from GitLab. +- Delete both the Preview Environment and the Namespace when the branch is deleted to avoid manual cleanup. :::tip -Learn more about [the okteto CLI here](reference/okteto-cli.mdx). +See the [Okteto CLI reference](reference/okteto-cli.mdx) for the full list of available commands and flags. ::: -## Step 3: Create a Merge Request +## Step 3: Create a merge request Once your changes are in your repository, make a small code change and create a new merge request. -After a few seconds, the workflow will update the pull request with the URL of your preview environment. Click on the _View App_ button, access it, and see your changes running. +After a few seconds, the workflow updates the merge request with the URL of your Preview Environment. Click the **View App** button to access it and see your changes running.

GitLab merge request

## Step 4: Cleanup -Merging the merge request or deleting the branch automatically triggers the `stop-review` job we defined in the `.gitlab-ci.yml` file. The `stop-review` job will destroy the preview environment automatically for you. +Merging the merge request or deleting the branch automatically triggers the `stop-review` job defined in the `.gitlab-ci.yml` file. The `stop-review` job destroys the Preview Environment automatically. diff --git a/versioned_docs/version-1.37/reference/docker-compose.mdx b/versioned_docs/version-1.49/reference/docker-compose.mdx similarity index 61% rename from versioned_docs/version-1.37/reference/docker-compose.mdx rename to versioned_docs/version-1.49/reference/docker-compose.mdx index dea90de0f..900760bc6 100644 --- a/versioned_docs/version-1.37/reference/docker-compose.mdx +++ b/versioned_docs/version-1.49/reference/docker-compose.mdx @@ -63,7 +63,7 @@ We summarize the most relevant ones below: #### build ([string|object], optional) -Indicate how to build the image of this service when running `okteto build` or `okteto deploy --build`. +Indicate how to build the image of this service when running `okteto build` or `okteto deploy`. The value is the path to the build context: ```yaml @@ -76,6 +76,7 @@ It can also be an object with these fields: - `dockerfile`: the path to the Dockerfile. It is a relative path to the build context (default: `Dockerfile`) - `target`: build the specified stage as defined inside the Dockerfile. See the multi-stage build [Docker official docs](https://docs.docker.com/develop/develop-images/multistage-build/) for details. - `args`: add build arguments, which are environment variables accessible only during the build process. Build arguments with a value containing a `$` sign are resolved to the environment variable value on the machine okteto is running on, which can be helpful for secret or machine-specific values. +- `secrets`: a list of [top-level secrets](#secrets-object-optional) to expose during the build. Only the short form (secret name) is supported. ```yaml build: @@ -85,6 +86,8 @@ build: args: - ENV1=prod - ENV2=$VALUE + secrets: + - npm_token ``` `okteto deploy` builds a new docker image, pushes it to the registry and redeploys your containers. @@ -149,10 +152,74 @@ depends_on: - initialization-svc ``` +Okteto checks these conditions every second while `okteto deploy` runs, and it doesn't create the dependent service until all of them are met. The wait is bounded by the deploy timeout, which defaults to 5 minutes. You can change it with the `--timeout` flag of [`okteto deploy`](reference/okteto-cli.mdx#deploy) or the `OKTETO_TIMEOUT` environment variable. This wait applies even if you don't pass `--wait`. + +:::info +If a dependency never meets its condition, the deploy fails instead of waiting forever: + +- **Timeout**: when the timeout expires, `okteto deploy` exits with `compose '' didn't finish after 5m0s`. +- **Failed job**: if a `service_completed_successfully` dependency runs out of retries and its Job is marked as failed, the deploy fails immediately with `service '' dependency '' failed`. +- **Failed healthcheck**: if a `service_healthy` dependency fails a liveness probe (`x-okteto-liveness: true`), the deploy fails immediately with `service '' cannot be deployed because dependent service '' is failing its healthcheck probes`. A failing readiness probe only prints a warning, and Okteto keeps waiting until the timeout. +- **Crash loop**: if a dependency's container restarts 3 times during the deploy (or the number set in `deploy.restart_policy.max_attempts`), the deploy fails with `service '' has been restarted N times within this deploy`. +::: + :::info -💡 To enforce `depends_on` ordering during environment wake-up, enable the [`OKTETO_COMPOSE_DEPENDS_ON_ENABLED` feature flag](reference/feature-flags.mdx). +💡 To enforce `depends_on` ordering during environment wake-up, enable the [`OKTETO_COMPOSE_WAIT_FOR_DEPENDENCIES` feature flag](reference/feature-flags.mdx). +::: + +#### deploy (object, optional) + +The `deploy` key configures how Okteto translates a Compose service into Kubernetes. Supported subkeys: + +- `deploy.resources` — CPU and memory requests and limits. See [resources](#resources-object-optional). +- `deploy.restart_policy` — restart behavior and retry limits (see below). +- `deploy.replicas` — number of container replicas (alias for [`scale`](#scale-int-optional)). +- `deploy.endpoint_mode` — endpoint mode for the service. See [endpoint_mode](#endpoint_mode-string-optional). + +##### `restart_policy` + +`deploy.restart_policy` controls restart behavior for a service and determines whether Okteto creates a Kubernetes Job. When both [`restart`](#restart-string-optional) and `deploy.restart_policy.condition` are set, `deploy.restart_policy.condition` takes precedence. + +| Field | Type | Description | +|-------|------|-------------| +| `condition` | string | Restart condition. Accepts the same values as [`restart`](#restart-string-optional): `none`, `never`, `no`, `always`, `unless-stopped`, `any`, `on-failure`. | +| `max_attempts` | int | Maximum retry attempts before the Job is marked as failed. Maps to the Kubernetes Job `backoffLimit`. | + +:::note +`deploy.restart_policy.delay` and `deploy.restart_policy.window` are recognized but unsupported. Okteto displays a warning if either is set. ::: +```yaml +services: + init: + image: okteto/movies-with-compose:api + command: yarn load + deploy: + restart_policy: + condition: on-failure + max_attempts: 5 + depends_on: + mongodb: + condition: service_healthy +``` + +This configuration creates a Kubernetes Job that retries up to five times if the container exits with a non-zero code. Okteto maps `max_attempts` to the Kubernetes Job `backoffLimit` field. + +##### Kubernetes object mapping + +The combination of restart condition, `max_attempts`, and volume mounts determines the Kubernetes object type: + +| Restart condition | `max_attempts` | Resulting Kubernetes object | +|-------------------|----------------|---------------------------| +| `always` / `unless-stopped` / `any` (default) | — | Deployment (StatefulSet if the service defines a named volume) | +| `on-failure` | 0 or unset | Deployment (StatefulSet if the service defines a named volume) | +| `on-failure` | > 0 | Job | +| `none` / `never` / `no` | — | Job | + +A service that resolves to a Deployment becomes a StatefulSet when it defines a named volume. Services that resolve to a Job are unaffected. + +Use `deploy.restart_policy` with `condition: on-failure` and a `max_attempts` value greater than zero for one-shot tasks (such as database migrations or seed scripts) that should retry on transient failures. + #### endpoint_mode (string, optional) Specify the endpoint mode for the service. @@ -228,7 +295,7 @@ service are "healthy". either a string or a list. If it's a list, the first item must be either `NONE`, `CMD` or `CMD-SHELL`. If it's a string, it's equivalent to specifying `CMD-SHELL` followed by that string. - `http` (object): Defines the path and port that has to be tested on the container to set - the healthcheck as successful + the healthcheck as successful. This key is an Okteto extension not part of the standard Compose spec. - `x-okteto-readiness` (bool): Defines if the probe should be a readiness probe (default: `true`). - `x-okteto-liveness` (bool): Defines if the probe should be a liveness probe (default: `false`). @@ -259,7 +326,7 @@ healthcheck: The container image of each service. ```yaml -image: okteto/vote:compose +image: ghcr.io/okteto/vote:compose ``` If [`build`](reference/docker-compose.mdx#build-stringobject-optional) is defined, `image` is optional. Otherwise, it's required. @@ -352,7 +419,7 @@ If you need make these ports public, you can use [endpoints](reference/docker-co #### resources (object, optional) -Configure resource [requests and limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits). +Configure resource [requests and limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits). This top-level key is an Okteto extension — the standard Compose spec places resources under `deploy.resources`. ```yaml resources: @@ -379,20 +446,21 @@ deploy: #### restart (string, optional) -Defines the policy that the platform will apply on container termination. +Defines the policy that the platform applies on container termination. -- `always/unless-stopped/any`: The default restart policy. The policy always restarts the container until its removal. -- `none/never/no`: The policy does not restart a container under any circumstances. -- `on-failure`: The policy restarts a container if the exit code indicates an error. +- `always` / `unless-stopped` / `any`: The default. The container always restarts until removal. Okteto creates a Deployment (or StatefulSet if the service mounts volumes). +- `none` / `never` / `no`: The container does not restart. Okteto creates a Job. +- `on-failure`: The container restarts only when the exit code indicates an error. Okteto creates a Job if [`deploy.restart_policy.max_attempts`](#deploy-object-optional) is greater than zero; otherwise it creates a Deployment or StatefulSet. ```yaml -deploy: - restart_policy: - condition: on-failure - max_attempts: 3 +restart: on-failure ``` -If the restart policy is other than always, the service will be translated to a Kubernetes Job. +:::note +`never` is an Okteto-specific alias for `none` / `no`. Standard Docker Compose does not accept `never` as a restart value. +::: + +If both `restart` and [`deploy.restart_policy.condition`](#deploy-object-optional) are set, `deploy.restart_policy.condition` takes precedence. See [Kubernetes object mapping](#kubernetes-object-mapping) for the full translation rules. #### scale (int, optional) @@ -463,6 +531,83 @@ x-node-selector: More information about Kubernetes node selectors is [available here](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector). +#### x-enable-service-links (boolean, optional) + +Controls whether Kubernetes injects [service link environment variables](https://kubernetes.io/docs/concepts/services-networking/connect-applications-service/#environment-variables) into the service containers. By default, Kubernetes adds variables such as `_SERVICE_HOST`, `_SERVICE_PORT`, and `_PORT` for every service in the namespace, with port values formatted as URIs (for example, `tcp://10.0.0.1:8125`). Set this field to `false` to stop the injection for a service whose application reads those variable names for its own configuration. + +```yaml +x-enable-service-links: false +``` + +When unset, Okteto preserves the default Kubernetes behavior and injects the variables. This field is opt-in and only affects the service that declares it. + +#### x-okteto-identity-token (object, optional) + +Project an audience-scoped Kubernetes ServiceAccount token into the service container, so the application can authenticate to cloud providers through OIDC or AWS STS web-identity federation without static credentials. Okteto creates a [projected `serviceAccountToken` volume](https://kubernetes.io/docs/concepts/storage/projected-volumes/#serviceaccounttoken) and mounts it read-only at the configured path. The kubelet refreshes the token before it expires. + +```yaml +x-okteto-identity-token: + audience: sts.amazonaws.com + mount_path: /var/run/secrets/tokens/aws + expiration_seconds: 3600 +``` + +The directive accepts the following fields: + +- `audience` (string, required): Intended audience of the token. Set it to the identity provider you federate with, such as `sts.amazonaws.com` for AWS. +- `mount_path` (string, required): Absolute path where the token is mounted. Okteto writes the token to a file named `token` inside this directory (for example, `/var/run/secrets/tokens/aws/token`). +- `expiration_seconds` (int, optional): Requested token lifetime in seconds. Must be at least `600`, the kubelet minimum. Defaults to `3600` when unset. + +Okteto injects no environment variables for this directive. Set the variables your provider expects yourself, and point them at the `token` file inside `mount_path`. Services that don't declare `x-okteto-identity-token` are unaffected. + +:::note +Federation also requires your cloud provider to trust the cluster's OIDC issuer for the configured `audience`. That trust setup is configured on the provider, outside the Okteto Manifest. + +Compose services run under each namespace's `default` ServiceAccount, so the projected token's subject is `system:serviceaccount::default`. Because the `default` ServiceAccount exists in every Namespace, scope the provider's trust to that subject across all Namespaces with a wildcard: `system:serviceaccount:*:default`. +::: + +For AWS, set the AWS environment variables on the service and point `AWS_WEB_IDENTITY_TOKEN_FILE` at the `token` file inside `mount_path`: + +```yaml +services: + api: + image: my-api:latest + environment: + - AWS_ROLE_ARN=arn:aws:iam:::role/api + - AWS_REGION=us-east-1 + - AWS_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/tokens/aws/token + x-okteto-identity-token: + audience: sts.amazonaws.com + mount_path: /var/run/secrets/tokens/aws +``` + +The IAM role referenced by `AWS_ROLE_ARN` needs a trust policy that allows `sts:AssumeRoleWithWebIdentity` for the cluster's OIDC issuer, scoped to the configured `audience` and the `default` ServiceAccount. The `sub` claim uses a wildcard to match the `default` ServiceAccount in any Namespace, so it must go under `StringLike` rather than `StringEquals`: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Federated": "arn:aws:iam:::oidc-provider/" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringEquals": { + ":aud": "sts.amazonaws.com" + }, + "StringLike": { + ":sub": "system:serviceaccount:*:default" + } + } + } + ] +} +``` + +Replace `` with the cluster's issuer URL without the `https://` prefix and `` with your AWS account ID. Keep the `aud` value in sync with the `audience` field in the directive. To restrict the role to a single Namespace, replace the wildcard with `system:serviceaccount::default` and move that condition under `StringEquals`. + ### volumes ([object], optional) List of volumes created by the Docker Compose file. @@ -504,6 +649,44 @@ labels: app: redis ``` +### secrets ([object], optional) + +Define secrets that can be referenced by `build.secrets` in your services. Each secret provides a value to the build through either a file or an environment variable. + +```yaml +secrets: + npm_token: + environment: NPM_TOKEN + server_cert: + file: ./certs/server.cert + +services: + api: + build: + context: . + secrets: + - npm_token + - server_cert +``` + +Each secret has one of the following fields (mutually exclusive): + +- `file`: path to a file containing the secret value. Relative paths are resolved from the location of the Docker Compose file. +- `environment`: name of an environment variable containing the secret value. + +To consume a secret during the build, use the `--mount=type=secret` flag in your Dockerfile: + +```dockerfile +RUN --mount=type=secret,id=npm_token \ + cat /run/secrets/npm_token +``` + +The `id` in the Dockerfile mount must match the secret name defined in the `secrets` section. + +:::note +Only build secrets are supported. Runtime secrets (`services..secrets` for mounting secrets into running containers) remain unsupported. +::: + ## Environment variables There are multiple parts of Docker Compose files that deal with environment variables in one sense or another. @@ -528,13 +711,11 @@ The `.env` file is placed at the same folder than the Docker Compose file. For example: -```console -$ cat .env +```bash title=".env" TAG=v1.5 ``` -```console -$ cat docker-compose.yml +```yaml title="docker-compose.yml" services: web: image: "app:${TAG}" @@ -679,23 +860,24 @@ Okteto supports a large subset of the Docker Compose specification and introduce | volumes | yes | ✅ | | | networks | yes | ⚠️ | Warning shown to the user | | configs | yes | ⚠️ | Warning shown to the user | -| secrets | yes | ⚠️ | Warning shown to the user | +| secrets | yes | ✅ | Supported for build secrets (`file` and `environment`). Runtime secrets remain unsupported | | version *(obsolete)* | yes | ✅ | Kept for back-compatibility | | profiles | yes | ⛔️ | Ignored | | x-* extension keys | yes | ⛔️ | Ignored but we ignore them consciously | -| endpoints | — | 🆕 | Okteto-specific syntax | +| endpoints | — | 🆕 | Okteto extension for defining HTTPS routes | ### Service Spec #### ✅ Supported ```yaml annotations -build.context / dockerfile / args +build.context / dockerfile / args / secrets cap_add / cap_drop command depends_on deploy.replicas deploy.resources.{limits|reservations} +deploy.restart_policy.condition deploy.restart_policy.max_attempts deploy.endpoint_mode entrypoint @@ -731,6 +913,8 @@ cpu_rt_runtime cpu_shares cpuset credential_spec +deploy.restart_policy.delay +deploy.restart_policy.window device_cgroup_rules devices dns @@ -763,7 +947,6 @@ profiles pull_policy read_only runtime -secrets security_opt shm_size stdin_open @@ -798,10 +981,14 @@ uts | **Key** | **Purpose** | | --- | --- | +| endpoints | Define HTTPS routes for services | | public: true | Auto-generate a Kubernetes Ingress | | x-node-selector | Pod scheduling hint | -| resources | Set CPU / Memory | -| scale | Compose-style replica shorthand (alias for deploy.replicas) | +| x-enable-service-links | Toggle Kubernetes service link environment variable injection per service | +| x-okteto-identity-token | Project a ServiceAccount token for keyless cloud federation | +| resources | Top-level CPU / memory requests and limits (shorthand for `deploy.resources`) | +| healthcheck.http | HTTP path and port healthcheck probe | +| scale | Compose-style replica shorthand (alias for `deploy.replicas`) | --- @@ -815,6 +1002,10 @@ uts --- -### Networks, Configs & Secrets Blocks +### Networks & Configs Blocks + +Both blocks are **parsed only to raise a warning**; every sub-field therefore falls under ⚠️. + +### Secrets Block -All three blocks are **parsed only to raise a warning**; every sub-field therefore falls under ⚠️. \ No newline at end of file +Top-level `secrets` definitions with `file` or `environment` fields are ✅ supported for use with `build.secrets`. Runtime secrets (`services..secrets`) remain ⚠️ unsupported. \ No newline at end of file diff --git a/versioned_docs/version-1.49/reference/faqs.mdx b/versioned_docs/version-1.49/reference/faqs.mdx new file mode 100644 index 000000000..e1d0f5b98 --- /dev/null +++ b/versioned_docs/version-1.49/reference/faqs.mdx @@ -0,0 +1,268 @@ +--- +title: Frequently Asked Questions (FAQs) +description: Frequently asked questions about Okteto +sidebar_label: FAQs +id: faqs +--- + +import Head from '@docusaurus/Head'; + + + + + +## Can I use Okteto CLI with Minikube? + +Yes. Okteto CLI accelerates your development workflow regardless of where your Kubernetes cluster is running. + +If you can run `kubectl apply`, you can benefit from Okteto CLI. + +For Minikube, k3s, or similar local Kubernetes distributions, you can directly use our [open source project](https://github.com/okteto/okteto). For shared remote clusters, we recommend you take a look at [Okteto](https://okteto.com/) to handle credential management, namespace isolation, integration with GitHub among other things. + +## Why is Okteto better than traditional development? + +Among the many advantages, Okteto allows developers to: + +- Reduce local setup and eliminate integration issues by developing the same way your application runs in production +- Test your application as fast as you type code, without needing to use `docker` or `kubectl` in your inner loop cycle +- No more CPU cycles wasted in your machine. Hardware and network just limited by the power of the cloud +- Your development endpoints are always available. No need to expose your local machine to the internet through remote tunnels + +## How is Okteto different from other tools like Skaffold? + +Skaffold automates the workflow for building, pushing, and deploying your application. You iterate on your application source code locally and then deploy to local or remote Kubernetes clusters. + +Okteto's philosophy is to move development entirely to Kubernetes. The Skaffold pipeline, even though automated, is still slow. With Okteto, you code locally in your favorite IDE and Okteto automatically synchronizes your changes to your remote development environment. No commit, build, push, or deploy required. + +The main differences from tools like Skaffold are: + +- Okteto decouples deployment from development. You can deploy your application with `kubectl`, `Helm`, a serverless framework or even a CI job and use Okteto later to develop any component of your application +- Use any docker image as your remote development environment, with your favorite tools. Okteto doesn't require you to change the way you build, debug, or deploy your applications. Since builds are executed in your remote development environment, you benefit from fast incremental builds, hot reloaders, or the dependency caching offered by your programming language. Native builds are always faster than building images and redeploying containers +- You can integrate Okteto with your local IDE remote plugins, making it possible to execute your favorite IDE extensions and debuggers as you develop your application directly in Kubernetes +- Okteto provides bidirectional synchronization. For example, you can execute package managers like `npm` or `pip` in your remote development environment and the changes are synchronized back to your local file system + +## Is Okteto compatible with Flux/ArgoCD? + +Okteto decouples deployment from development, making it possible to use it with tools like Flux or ArgoCD. + +We recommend you to stop the Flux/ArgoCD reconciliation loop while running `okteto up`. For example, add this field to your Okteto Manifest to stop the Flux reconciliation loop: + +```yaml +annotations: + fluxcd.io/ignore: "true" +``` + +:::tip +Please see our [ArgoCD Configuration Guide](self-hosted/manage/argocd.mdx) for our full recommendation on deploying Okteto with ArgoCD +::: + + +## How to use private images? + +In order to use your private registry credentials, use the Okteto's built-in [Registry Credentials](/admin/registry-credentials/index.mdx) feature. + +## Why are my [Endpoints](core/endpoints/automatic-ssl.mdx) not present in the CLI or UI? + +Endpoint links are not present within Okteto if there are no services actively running. If your endpoints are missing, consider the following states and their implications: + +#### Progressing: +* Description: Your deployment is in the process of being rolled out +* Possible Causes: + * Your service is still being started + * Okteto is waiting for all healthchecks to pass + * There are pending updates or new deployments +* Actions: + * Wait for the deployment to complete + * Look at the events of the deployment for any issues + +#### Pulling: +* Description: The image for your deployment is in the process of being pulled +* Possible Causes: + * Your service is still being started +* Actions: + * Wait for the deployment to complete + * Look at the events of the deployment for any issues + +#### Booting: +* Description: Starting the containers for your deployment +* Possible Causes: + * All containers for your service are not yet ready +* Actions: + * Wait for all containers to finish starting and enter their ready state + * Look at the events of the deployment for any issues + +#### Running: +* Description: Your deployment is active, and the service should be running correctly +* Possible Causes: + * Network policies or firewall rules could be blocking the endpoint +* Actions: + * Verify the service annotations in your manifest to ensure `dev.okteto.com/auto-ingress: "true"` is present + * Verify your [Docker Compose endpoints](reference/docker-compose.mdx#endpoints-object-optional) are configured correctly + +#### Unschedulable: +* Description: At least one of the pods of your service cannot be scheduled. +* Possible Causes: + * You cluster doesn't have enough resources to allocate the pods + * Some of the pod tolerations are preventing the pods from being scheduled +* Actions: + * Check the events for the pods that belong to your service: `kubectl events --for pod/my-pod-1234 -n my-ns` + * Contact your cluster administrator and check if your cluster is at capacity + +#### Error: +* Description: There is an issue with your deployment preventing the service from running correctly +* Possible Causes: + * Errors in the application code or container image + * Misconfiguration in your service or deployment manifest + * Insufficient resources or quota limits in the cluster +* Actions: + * Check the logs of the affected service through the UI or with [`okteto logs`](reference/okteto-cli.mdx#logs) + * Validate the container image and configuration settings + * Ensure that resource requests and limits are properly set and the cluster has enough capacity + +## What are the custom error pages I see when accessing my endpoints? + +When you access an endpoint and encounter an error (such as accessing a sleeping namespace or when a service is temporarily unavailable), Okteto displays custom error pages with helpful hints on how to resolve the issue. These pages are designed to provide clear guidance on what went wrong and what actions you can take. + +Common scenarios where you'll see custom error pages include: +- Accessing a sleeping namespace that is in the process of waking up +- Service temporarily unavailable due to deployment or restart + +These error pages are served automatically by the defaultBackend component and require no additional configuration. For more information about namespace sleeping and autowake behavior, see the [Garbage Collection documentation](admin/cleanup.mdx#custom-error-pages). + +## Every time I make a change, tsc detects two changes: + +This is related to how syncthing interacts with `tsc`. Syncthing creates a temporary file and replaces the original file with the new one. + +To solve the problem you just add the flag `--synchronousWatchDirectory` to your `tsc` command. + +## I cannot connect to the Kubernetes cluster using the kubeconfig file generated by Okteto + +Starting with Okteto CLI version `2.20`, the kubeconfig file generated by Okteto uses a [credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins) to get the credentials for your Kubernetes clusters from your Okteto instance. It is a typical pattern used by many Kubernetes providers, such as Google Kubernetes Engine (GKE), Azure Kubernetes Service (AKS), or Amazon Elastic Kubernetes Service (EKS) to connect to Kubernetes clusters. + +We recommend you add the Okteto CLI to your PATH and run the 'okteto context' command to connect your CLI to your Okteto instance before executing the `okteto kubeconfig` command. You can also optionally download your Kubeconfig from the Okteto UI. Please refer to [our documentation](get-started/install-okteto-cli.mdx) for more information on this topic. + +Once you have the CLI installed you have to connect to your instance using the command `okteto context use https://okteto.example.com` as is described [here](get-started/install-okteto-cli.mdx). If you're not logged into Okteto yet, it will also run the login sequence. + +Once your Okteto context is configured to access Okteto, you should be able to connect to your Kubernetes cluster using the kubeconfig file generated by Okteto or generate a new one running [`okteto kubeconfig`](reference/okteto-cli.mdx#kubeconfig). + +You can also disable the usage of the credential plugin by setting the environment variable `OKTETO_USE_STATIC_KUBETOKEN` to `true` before running any Okteto command. Be aware that using those static tokens are not recommended by Kubernetes and you will start getting warnings in your `kubectl` output starting with Kubernetes version `1.27`. + +## How can I use the `--platform` flag with `okteto build`? + +With `okteto build --platform` you can specify the platform (or architecture) for which you'd like to build the container images. For example, you could use a multiplatform image and the `okteto build --platform` command to deploy your web application on a Kubernetes cluster that consists of nodes running on both x86-64 and ARMv7 architectures. +By using the multiplatform images built using this method, you can deploy the same images across the cluster without worrying about the underlying hardware differences. + +Let's consider an example where you have a Node.js application that you want to build and deploy on both x86_64 and ARM-based platforms. You have a Dockerfile in your project directory that defines the build process. +Here's how Okteto CLI can help you build multiplatform images for your application: + +1. Building the image for x86_64 architecture: + +```bash +okteto build -f Dockerfile -t myapp:latest --platform linux/amd64 +``` + +2. Building the image for ARMv7 architecture: + +```bash +okteto build -f Dockerfile -t myapp:latest --platform linux/arm/v7 +``` + +3. Building a multiarchitectural image: + +```bash +okteto build -f Dockerfile -t myapp:latest --platform linux/amd64,linux/arm/v7 +``` + +This command builds a multi-architecture Docker image named `myapp` with the latest tag for both x86_64 and ARM platforms. + +By using these commands, you can easily build the application image for different platforms without needing to maintain separate Dockerfiles or perform manual modifications. +This is particularly useful when you want to deploy your application to heterogeneous environments where you have both x86_64 and ARM-based devices, such as a mixed-cluster Kubernetes setup. diff --git a/versioned_docs/version-1.37/reference/feature-flags.mdx b/versioned_docs/version-1.49/reference/feature-flags.mdx similarity index 79% rename from versioned_docs/version-1.37/reference/feature-flags.mdx rename to versioned_docs/version-1.49/reference/feature-flags.mdx index ae3b9905e..e6469f5df 100644 --- a/versioned_docs/version-1.37/reference/feature-flags.mdx +++ b/versioned_docs/version-1.49/reference/feature-flags.mdx @@ -15,11 +15,18 @@ Below is a list of those variables that you can use to leverage these newer and |--------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------| | OKTETO_AUTOGENERATE_STIGNORE | If true, generates the `.stignore` file when running `okteto up` | `false` | | OKTETO_AUTODEPLOY | If set, forces the deployment of the development environment on `okteto up` | `false` | -| OKTETO_AUTO_DOWN_ENABLED | If set, `okteto up` will run `okteto down` on exit if all the commands are succesful | `false` | +| OKTETO_AUTO_DOWN_ENABLED | If set, `okteto up` will run `okteto down` on exit if all the commands are successful | `false` | | OKTETO_BUILDKIT_FRONTEND_IMAGE | Specifies the default docker image to use for the [BuildKit frontend](https://docs.docker.com/build/buildkit/frontend/) | Built-in Dockerfile frontend | | OKTETO_BUILDKIT_MAX_RETRIES_FOR_TRANSIENT_ERRORS | Specifies the maximum number of retry attempts for build processes that fail due to transient (temporary) BuildKit errors | `3` | | OKTETO_BUILDKIT_WAIT_TIMEOUT | Specifies the maximum duration to wait for BuildKit to become available | `10m` | | OKTETO_BUILDKIT_RETRY_INTERVAL | Specifies the interval between successive checks of BuildKit's availability status | `5s` | +| OKTETO_BUILDKIT_READINESS_TIMEOUT | Specifies the timeout budget for the BuildKit readiness health-check used by the port-forward connector. The value must be greater than 0 | `6s` | +| OKTETO_BUILD_OCI_MEDIATYPES | Controls whether image exports use OCI media types. Set to `false` to fall back to legacy Docker media types for registries that don't support OCI media types | `true` | +| OKTETO_BUILD_COMPRESSION | Sets the compression type of the exported image layers (`gzip`, `estargz`, `zstd`, or `uncompressed`) | BuildKit's default | +| OKTETO_BUILD_COMPRESSION_LEVEL | Sets the compression level of the exported image layers (`0`-`22` for `zstd`, `0`-`9` for `gzip` and `estargz`) | BuildKit's default | +| OKTETO_BUILD_FORCE_COMPRESSION | If `true`, forces recompression of already compressed layers, including base image layers | BuildKit's default | +| OKTETO_BUILD_QUEUE_ENABLED | Enables the [Build Queue System](core/build-service.mdx#build-queue-system) that routes builds to optimal build pods based on real-time metrics and queues builds when all pods are busy | `true` | +| OKTETO_BUILDKIT_QUEUE_WAIT_TIMEOUT | Specifies the maximum duration to wait in the build queue before timing out | `10m` | | OKTETO_COMPOSE_UPDATE_STRATEGY | Defines the update strategy that the compose must translate (it can be one of: `rolling`/`recreate`/`on-delete`) | N/A | | OKTETO_COMPOSE_VOLUME_AFFINITY_ENABLED | Compose services mounting the same volume will be placed on the same node using Kubernetes's pod affinity | `true` | | OKTETO_COMPOSE_WAIT_FOR_DEPENDENCIES | Determines whether the wake job should honor the `depends_on` order defined in Docker Compose files. | `false` | diff --git a/versioned_docs/version-1.37/reference/file-synchronization.mdx b/versioned_docs/version-1.49/reference/file-synchronization.mdx similarity index 88% rename from versioned_docs/version-1.37/reference/file-synchronization.mdx rename to versioned_docs/version-1.49/reference/file-synchronization.mdx index e5cce8b6f..fb12d92d2 100644 --- a/versioned_docs/version-1.37/reference/file-synchronization.mdx +++ b/versioned_docs/version-1.49/reference/file-synchronization.mdx @@ -9,8 +9,8 @@ When you run `okteto up`, an instance of [Syncthing](https://syncthing.net/), a Syncthing provides a web UI to show the state of the file synchronization. You can get the syncthing endpoints and credentials of your development container by running `okteto status --info`: -```console -$ okteto status --info +```bash +okteto status --info ``` ```console @@ -28,7 +28,7 @@ The `.stignore` file must be placed in the root of the folder. :::info -The `okteto init` command will create a default `.stignore` tailored to the typical use cases of your programming language. +Set the `OKTETO_AUTOGENERATE_STIGNORE` feature flag to generate a default `.stignore` tailored to the typical use cases of your programming language when you run `okteto up`. ::: diff --git a/versioned_docs/version-1.49/reference/index.mdx b/versioned_docs/version-1.49/reference/index.mdx new file mode 100644 index 000000000..f61979cf7 --- /dev/null +++ b/versioned_docs/version-1.49/reference/index.mdx @@ -0,0 +1,8 @@ +--- +title: References +description: "Explore Okteto reference documentation including CLI commands, the Okteto Manifest schema, environment variables, and configuration options." +--- + +import CardsList from "@theme/CardsList" + + diff --git a/versioned_docs/version-1.49/reference/known-issues.mdx b/versioned_docs/version-1.49/reference/known-issues.mdx new file mode 100644 index 000000000..a9ed660ed --- /dev/null +++ b/versioned_docs/version-1.49/reference/known-issues.mdx @@ -0,0 +1,51 @@ +--- +title: Known Issues +description: Known issues and workarounds for Okteto development environments, including hot-reload limitations and Windows terminal compatibility. +sidebar_label: Known Issues +id: known-issues +--- + +## Development environments do not hot-reload code changes + +If you are using a hot reloader in your development environment, it might happen that your hot reloader does not pick the code changes even when they are properly synchronized to your development environment. + +This is usually because the default *max watchers* value on your Kubernetes nodes is too low. To fix this issue, update the value of `/proc/sys/fs/inotify/max_user_watches` in all your Kubernetes nodes (we recommend the value `10048576`). + +For example, you can do it by running this command on each node: + +```bash +sudo sysctl -w fs.inotify.max_user_watches=10048576 +``` + +[Okteto](https://okteto.com) uses a Daemon Set to apply this change automatically to every Kubernetes node. + +## The okteto prompt doesn't look right in Windows + +Okteto's remote prompt uses [ANSI escape sequences](https://devblogs.microsoft.com/commandline/whats-new-in-windows-console-in-windows-10-fall-creators-update/) to display the namespace and development environment name in different colors. + +If you're using PowerShell and the terminal looks funky, this feature might not enabled. Run the command below to enable ANSI Color globally: + +```powershell +Set-ItemProperty HKCU:\Console VirtualTerminalLevel -Type DWORD 1 +``` + +This [stackoverflow answer](https://stackoverflow.com/questions/51680709/colored-text-output-in-powershell-console-using-ansi-vt100-codes) has more information on this topic. + +## Pulling an image fails with an `EOF` error + +Image pulls run on the Kubernetes node, not on your machine, so a pull can fail for any pod the cluster schedules. During `okteto up`, the failure surfaces as a Development Container that won't activate: + +```bash +couldn't activate your development container + Failed to pull image "node:25-alpine3.22": failed to pull and unpack image "docker.io/library/node:25-alpine3.22": failed to copy: httpReadSeeker: failed open: failed to do request: Get "https://production.cloudfront.docker.com/...": EOF +``` + +The `EOF` means the connection to the host in the error closed before the image layer finished downloading. The usual cause is an egress policy on the cluster — a firewall, proxy, or domain allowlist — that doesn't permit that host. Registries commonly serve manifests from one host and redirect layer downloads to a separate CDN or storage host, and those hosts change over time, so an allowlist scoped to the registry alone starts failing on layer downloads while the manifest still resolves. + +Docker Hub is the most common case. It serves manifests from `registry-1.docker.io` (after authenticating against `auth.docker.io`) and redirects layers to a CDN host. Docker added the CDN domain `production.cloudfront.docker.com` in May 2026, so allowlists that only covered the registry and an older CDN began failing with this error. + +To resolve it: + +1. Allow egress from your cluster to your registry's hosts over HTTPS, including the CDN or storage host it redirects layer downloads to. Because these hosts can change, prefer wildcards where your firewall supports them. For Docker Hub, allow `*.docker.io` and `*.docker.com`; Docker's [allowlist reference](https://docs.docker.com/desktop/setup/allow-list/) lists the current hosts, including `registry-1.docker.io`, `auth.docker.io`, and `production.cloudfront.docker.com`. +2. If a TLS-inspecting proxy sits in front of the cluster, trust the certificate authority that signs the registry and CDN hosts. Docker Hub's CloudFront CDN uses Amazon Trust Services, for example, so its certificates fail validation when your trust store only includes a previous CA. +3. Mirror the image in the [Okteto Registry](core/container-registry.mdx) or another registry your cluster can reach, and reference it with the [`image`](reference/okteto-manifest.mdx#image-string-optional) field in your Okteto Manifest. diff --git a/versioned_docs/version-1.37/reference/manifest-migration.mdx b/versioned_docs/version-1.49/reference/manifest-migration.mdx similarity index 94% rename from versioned_docs/version-1.37/reference/manifest-migration.mdx rename to versioned_docs/version-1.49/reference/manifest-migration.mdx index b3400640e..282b4e03d 100644 --- a/versioned_docs/version-1.37/reference/manifest-migration.mdx +++ b/versioned_docs/version-1.49/reference/manifest-migration.mdx @@ -1,6 +1,6 @@ --- title: Migrating to Okteto CLI 2.0 -description: Migrating to Okteto CLI 2.0 +description: Migrate from Okteto Manifest v1 to the v2 format introduced in Okteto CLI 2.0, which consolidates build, deploy, and development into a single command. sidebar_label: Migrating to Okteto CLI 2.0 id: manifest-migration --- @@ -40,7 +40,7 @@ You will continue to use your compose file, providing slight modifications by in ```yaml name: frontend -image: okteto/node:16 +image: ghcr.io/okteto/node:16 command: bash sync: - .:/app @@ -55,7 +55,7 @@ deploy: compose: docker-compose.yml dev: frontend: - image: okteto/node:16 + image: ghcr.io/okteto/node:16 command: bash sync: - .:/app @@ -97,7 +97,7 @@ deploy: #### frontend/okteto.yaml ```yaml name: frontend -image: okteto/node:16 +image: ghcr.io/okteto/node:16 command: bash sync: - .:/app @@ -106,7 +106,7 @@ sync: #### api/okteto.yaml ```yaml name: api -image: okteto/golang:1 +image: ghcr.io/okteto/golang:1 command: bash sync: - .:/app @@ -144,12 +144,12 @@ deploy: dev: frontend: - image: okteto/node:16 + image: ghcr.io/okteto/node:16 command: bash sync: - frontend:/app api: - image: okteto/golang:1 + image: ghcr.io/okteto/golang:1 command: bash sync: - api:/app @@ -177,7 +177,7 @@ deploy: #### frontend/okteto.yaml ```yaml name: frontend -image: okteto/node:16 +image: ghcr.io/okteto/node:16 command: bash sync: - .:/app @@ -186,7 +186,7 @@ sync: #### api/okteto.yaml ```yaml name: api -image: okteto/golang:1 +image: ghcr.io/okteto/golang:1 command: bash sync: - .:/app @@ -227,12 +227,12 @@ deploy: dev: frontend: - image: okteto/node:16 + image: ghcr.io/okteto/node:16 command: bash sync: - frontend:/app api: - image: okteto/golang:1 + image: ghcr.io/okteto/golang:1 command: bash sync: - api:/app diff --git a/versioned_docs/version-1.37/reference/okteto-cli.mdx b/versioned_docs/version-1.49/reference/okteto-cli.mdx similarity index 92% rename from versioned_docs/version-1.37/reference/okteto-cli.mdx rename to versioned_docs/version-1.49/reference/okteto-cli.mdx index 644e0139c..15ca008b9 100644 --- a/versioned_docs/version-1.37/reference/okteto-cli.mdx +++ b/versioned_docs/version-1.49/reference/okteto-cli.mdx @@ -16,8 +16,8 @@ For a complete comparison of features, refer to the [open-source README](https:/ ## Synopsis -```console -$ okteto [options] [parameters] +```bash +okteto [options] [parameters] ``` Use `okteto command --help` for information on a specific command. The synopsis for each command shows its parameters and their usage. Optional parameters are shown in square brackets. @@ -27,7 +27,7 @@ Use `okteto command --help` for information on a specific command. The synopsis | Options | Type | Description | Default | | :--------------------------------------------- | :-----------------------: | :------------------------: | :------------------------: | | _--help_ | bool | Show help info | | -| _-l, --log-level_ | _debug, info, warn, error_ | Amount of information output | warm | +| _-l, --log-level_ | _debug, info, warn, error_ | Amount of information output | warn | | _--log-output_ | _tty, plain, json_ | Output format for logs | tty | @@ -39,8 +39,8 @@ Enable / Disable analytics collection. Analytics are enabled by default. If [telemetry](self-hosted/helm-configuration.mdx#telemetry) is disabled, analytics are disabled for all developers. -```console -$ okteto analytics [parameters] +```bash +okteto analytics [parameters] ``` | Options | Description | @@ -65,8 +65,8 @@ Please reach [out to us](mailto://hello@okteto.com) if you have any questions or Build and push the images defined in the `build` section using the [Okteto Build Service](core/build-service.mdx). -```console -$ okteto build [image...] +```bash +okteto build [image...] ``` :::tip @@ -94,7 +94,7 @@ In "Dockerfile" mode, the following additional flags can be used (very similar t | _--cache-from_ | list | List of cache source images (optional) | | | _--export-cache_ | string | Image tag for exported cache when build (optional) | | | _--platform_ | string | Specify which platform to build the container image for (optional) | | -| _--secret_ | list | Secret files exposed to the build. Format: `id=mysecret,src=/local/secret` | | +| _--secret_ | list | Secret files exposed to the build. Format: `id=mysecret,src=/local/secret` or `id=mysecret,env=MY_ENV_VAR` | | | _-t, --tag_ | string | Tag name to be pushed (optional) | | | _--target_ | string | Target build stage to build (optional) | | @@ -109,8 +109,8 @@ Set the default Okteto Context. An Okteto Context is a group of cluster access parameters. Each context contains a Kubernetes cluster, a user, and a namespace. The current Okteto Context is the default cluster/namespace for any Okteto CLI command. -```console -$ okteto context +```bash +okteto context ``` :::tip @@ -152,16 +152,16 @@ Delete one or more Okteto Contexts. For example, to delete the Okteto Context "https://okteto.example.com", run: -```console -$ okteto context delete https://okteto.example.com +```bash +okteto context delete https://okteto.example.com ``` #### list List available Okteto Contexts. -```console -$ okteto context list +```bash +okteto context list ``` ```console @@ -178,8 +178,8 @@ minikube default docker Print the current Okteto Context. -```console -$ okteto context show +```bash +okteto context show ``` | Options | Type | Description | Default | @@ -206,8 +206,8 @@ Set the default Okteto Context. `okteto context use` is an alias of `okteto cont Deploy your Development Environment by running the commands specified in the `deploy` section of your Okteto Manifest. -```console -$ okteto deploy +```bash +okteto deploy ``` If there are pending changes in the images defined in your Okteto Manifest, `okteto deploy` automatically builds and pushes all them. @@ -232,6 +232,19 @@ The command is executed relative to the path where the Okteto Manifest is locate | _-v, --var_ | list | Set a variable for the deploy commands (can be set more than once) | | | _-w, --wait_ | bool | Wait until the deployment finishes and pods are healthy | `false` | +#### Comparison with `pipeline deploy` and `preview deploy` + +`okteto deploy`, [`okteto pipeline deploy`](reference/okteto-cli.mdx#deploy-1), and [`okteto preview deploy`](reference/okteto-cli.mdx#deploy-2) all run the commands in the `deploy` section of your Okteto Manifest. They differ in where the command runs and what it creates: + +| Command | Where it runs | Manifest source | What it creates | +| :------ | :------------ | :-------------- | :-------------- | +| `okteto deploy` | Your local machine, or the cluster with `--remote` | The Okteto Manifest in your working directory | A [Development Environment](development/index.mdx) | +| `okteto pipeline deploy` | A job in the cluster that clones a Git repository | The Okteto Manifest at the root of the cloned repository | A [Development Environment](development/index.mdx) | +| `okteto preview deploy` | A job in the cluster that clones a Git repository | The Okteto Manifest at the root of the cloned repository | A [Preview Environment](previews/index.mdx) in a dedicated Namespace | + +- Run `okteto deploy` for day-to-day development against the Okteto Manifest in your working directory. Add the `--remote` flag to run the deploy commands in the cluster with [Remote Execution](core/remote-execution.mdx). +- Run `okteto pipeline deploy` to deploy a Development Environment from a Git repository without cloning it locally, such as from a CI/CD pipeline. This is equivalent to clicking the **Deploy Dev Environment** button in the Okteto UI. +- Run `okteto preview deploy` to deploy an ephemeral [Preview Environment](previews/index.mdx) for a branch or pull request in its own Namespace. ### destroy @@ -239,8 +252,8 @@ Destroy your Development Environment. It automatically destroys all the Kubernetes resources created by [okteto deploy](reference/okteto-cli.mdx#deploy). If you need to destroy external resources (like s3 buckets or other Cloud resources), use the [destroy](reference/okteto-manifest.mdx#destroy-string-optional) section of the Okteto Manifest. -```console -$ okteto destroy +```bash +okteto destroy ``` The `okteto destroy` command will only destroy resources matching the specified Development Environment name. By default, this is the name of the folder, but you can specify the [name in the Okteto Manifest](reference/okteto-manifest.mdx#name-string-optional), or with the `--name` flag. @@ -257,7 +270,7 @@ You can use `okteto destroy --all` to delete all Development Environments in an | Options | Type | Description | Default | | :------------------------------------------------- | :----: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------- | | _--all_ | bool | Destroy all Development Environments, excluding resources annotated with `dev.okteto.com/policy: keep` | `false` | -| _-d, --dependencies_ | bool | Force destroy repositories in the `dependencies` section | Set by cluster config | +| _--dependencies_ | bool | Force destroy repositories in the `dependencies` section | Set by cluster config | | _-f, --file_ | string | The path to the Okteto Manifest | `okteto.yml`| | _--force-destroy_ | bool | Forces the Development Environment to be destroyed even if there is an error executing the custom destroy commands defined in the Okteto Manifest | `false` | | _--name_ | string | The name of the Development Environment | The repo/folder name | @@ -272,8 +285,8 @@ You can use `okteto destroy --all` to delete all Development Environments in an Generate a doctor file with all the information relevant for troubleshooting an issue. Use it when filing an issue or asking the Okteto community for help. -```console -$ okteto doctor [devContainer] +```bash +okteto doctor [devContainer] ``` The `doctor` command should be run from the folder where you ran `okteto up`. @@ -296,8 +309,8 @@ The following command flags are available: Deactivate your Development Container, stops the file synchronization service, and restores your previous deployment configuration. -```console -$ okteto down [devContainer] +```bash +okteto down [devContainer] ``` The `down` command should be run from the same location as `okteto up`. @@ -320,8 +333,8 @@ Learn more about this and other [feature flags](reference/feature-flags.mdx). List the public endpoints of your Development Environment. -```console -$ okteto endpoints +```bash +okteto endpoints ``` | Options | Type | Description | @@ -337,8 +350,8 @@ The `exec` command allows you to execute a `COMMAND` inside your Development Con If only one Development Container is running, `okteto exec` will automatically connect to it. If multiple Development Containers are activated, you'll be presented with a selector to choose which one you want to connect to. -```console -$ okteto exec [devContainer] -- COMMAND +```bash +okteto exec [devContainer] -- COMMAND ``` Make sure to run the `exec` command from the same directory where you ran `okteto up`. @@ -352,16 +365,16 @@ Make sure to run the `exec` command from the same directory where you ran `oktet Displays the full help. -```console -$ okteto help +```bash +okteto help ``` ### kubeconfig Download credentials for the Kubernetes cluster selected via `okteto context`. -```console -$ okteto kubeconfig +```bash +okteto kubeconfig ``` ```console @@ -372,8 +385,8 @@ $ okteto kubeconfig Fetch the logs of your Development Environment. -```console -$ okteto logs [serviceName] +```bash +okteto logs [serviceName] ``` The first argument is optional and it's a regex matching the name of the containers you want to fetch the logs from. @@ -394,8 +407,8 @@ For example, `okteto logs api` fetches the logs of any container starting with ` Configure the default namespace of the Okteto Context. -```console -$ okteto namespace +```bash +okteto namespace ``` :::tip @@ -424,8 +437,8 @@ Use the arrow keys to navigate: ↓ ↑ → ← Create an Okteto Namespace. By default the command will switch to the new namespace, add `--use=false` to create the namespace, and it will keep the current namespace active. -```console -$ okteto namespace create test-cindy +```bash +okteto namespace create test-cindy ``` ```console @@ -437,8 +450,8 @@ $ okteto namespace create test-cindy Delete an Okteto Namespace. If the Okteto Manifest deployed in the Okteto Namespace include `destroy` commands, they will be executed as part of this command. By default, it deletes the default namespace in the Okteto Context. -```console -$ okteto namespace delete test-cindy +```bash +okteto namespace delete test-cindy ``` ```console @@ -449,8 +462,8 @@ $ okteto namespace delete test-cindy List your Okteto Namespaces. -```console -$ okteto namespace list +```bash +okteto namespace list ``` ```console @@ -471,8 +484,8 @@ Configure the default namespace of the Okteto Context. `okteto namespace use` is Sleeps an Okteto Namespace. By default, it sleeps the default namespace in the Okteto Context. -```console -$ okteto namespace sleep [name] +```bash +okteto namespace sleep [name] ``` ```console @@ -486,8 +499,8 @@ If you'd like to sleep an Okteto Namespace other than the default one, you can p Wakes an Okteto Namespace. By default, it wakes the default namespace in the Okteto Context. -```console -$ okteto namespace wake [name] +```bash +okteto namespace wake [name] ``` ```console @@ -501,8 +514,8 @@ If you'd like to wake an Okteto Namespace other than the default one, you can pr [Development Environments](development/index.mdx) management commands. -```console -$ okteto pipeline [command] +```bash +okteto pipeline [command] ``` Available subcommands: @@ -512,8 +525,8 @@ Available subcommands: Runs a job in the cluster that clones a repository and executes [okteto deploy](reference/okteto-cli.mdx#deploy) on it. This is equivalent to clicking the **Deploy Dev Environment** button on the Okteto UI and selecting a git repository. -```console -$ okteto pipeline deploy +```bash +okteto pipeline deploy ``` ##### Options @@ -538,8 +551,8 @@ $ okteto pipeline deploy Runs a job in the cluster that clones a repository and executes [okteto destroy](reference/okteto-cli.mdx#destroy) on it. This is equivalent to clicking the **Destroy** button on the Okteto UI. -```console -$ okteto pipeline destroy +```bash +okteto pipeline destroy ``` ##### Options @@ -557,8 +570,8 @@ $ okteto pipeline destroy List all your Development Environments in the current Okteto Namespace. -```console -$ okteto pipeline list +```bash +okteto pipeline list ``` Run `okteto pipeline list` to get the status and info of your Development Environments. @@ -573,16 +586,16 @@ Run `okteto pipeline list` to get the status and info of your Development Enviro [Preview environment](previews/index.mdx) management commands. -```console -$ okteto preview [command] +```bash +okteto preview [command] ``` #### deploy Deploy a Preview Environment. -```console -$ okteto preview deploy [name] +```bash +okteto preview deploy [name] ``` Run `okteto preview deploy` to automatically deploy a Preview Environment for your branch. @@ -604,8 +617,8 @@ Run `okteto preview deploy` to automatically deploy a Preview Environment for yo Destroy a Preview Environment. -```console -$ okteto preview destroy [name] +```bash +okteto preview destroy [name] ``` Run `okteto preview destroy` to destroy a Preview Environment by name. @@ -620,8 +633,8 @@ If the Okteto Manifest includes `destroy` commands, they will be executed as par List the endpoints of a Preview Environment. -```console -$ okteto preview endpoints [name] +```bash +okteto preview endpoints [name] ``` | Options | Type | Description | Default | @@ -634,8 +647,8 @@ Output flag can be used to parse the endpoints and add them to your PR with a cu List all your Preview Environments. -```console -$ okteto preview list +```bash +okteto preview list ``` Run `okteto preview list` to get the status and scope of your Preview Environments. @@ -650,8 +663,8 @@ Run `okteto preview list` to get the status and scope of your Preview Environmen Sleep an Preview Environment. Only users with admin access or who own the Preview Environment can take this action. -```console -$ okteto preview sleep [name] +```bash +okteto preview sleep [name] ``` More on sleeping resources [here](admin/cleanup.mdx#manually-sleeping-resources). @@ -660,8 +673,8 @@ More on sleeping resources [here](admin/cleanup.mdx#manually-sleeping-resources) Wake a Preview Environment. You must provide the name of a Preview Environment as an argument for this command. -```console -$ okteto namespace wake [name] +```bash +okteto preview wake [name] ``` ### restart @@ -669,8 +682,8 @@ $ okteto namespace wake [name] Restarts the containers corresponding to the `services` section for a given Development Container. This is useful to reload configurations that cannot be hot-reloaded. -```console -$ okteto restart [devContainer] +```bash +okteto restart [devContainer] ``` The `restart` command should be run from the same location than `okteto up`. @@ -684,8 +697,8 @@ The `restart` command should be run from the same location than `okteto up`. Status of the file synchronization process for a given Development Container. -```console -$ okteto status [devContainer] --info +```bash +okteto status [devContainer] --info ``` ```console @@ -709,13 +722,18 @@ The `status` command should be run from the same location than `okteto up`. Run tests using [Remote Execution](core/remote-execution.mdx#how-remote-execution-works). -```console -$ okteto test [testContainerName] +```bash +okteto test [testContainerName] ``` Since tests run inside the cluster, all internal endpoints are available inside the test execution. For example, if you deployed an api service on port 8080 it will be accessible at: `http://api.${OKTETO_NAMESPACE}:8080`. [Dynamic endpoints](core/okteto-variables.mdx#configuring-dynamic-endpoints) are also available within the test commands. +:::tip Environment variables from .env +If a `.env` file exists in the same directory as your `okteto.yml`, all variables defined in it are automatically injected into the test container's environment — no extra configuration in the manifest is required. If your manifest lives inside an `.okteto` subfolder, place the `.env` in the parent directory instead. + +Use the `-v` / `--var` flag to pass individual variables at the CLI level instead. +::: | Options | Type | Description | Default | | :--------------------------------------------- | :------: | :--------------------------------------------------------------------------------------------------------------------- | :---------- | @@ -733,10 +751,12 @@ Activate a Development Container. If needed, `okteto up` builds the images and runs the deploy commands defined in your [Okteto Manifest](reference/okteto-manifest.mdx). -```console -$ okteto up [devContainer] +```bash +okteto up [devContainer] ``` +The `devContainer` argument is optional and it's the name of a Development Container defined in the [`dev`](reference/okteto-manifest.mdx#dev-object-optional) section of your Okteto Manifest. If you omit it, `okteto up` activates the only Development Container in your Okteto Manifest, or presents a selector when there's more than one. + When you run `okteto up`, okteto scales to zero the specified deployment and creates a mirror deployment. The mirror deployment is a copy of the original deployment manifest with the following development-time improvements: - Okteto overrides the container-level configuration of the original deployment with the values defined in your [Okteto Manifest](reference/okteto-manifest.mdx). A typical example of this is to replace the production container image with one that contains your development runtime. @@ -776,8 +796,8 @@ This command helps you catch configuration errors, typos or invalid syntax in yo By default, it will use the Okteto Manifest in the current directory, alternatively you can specify a different path using the `--file` flag. -```console -$ okteto validate +```bash +okteto validate ``` The following command flags are available: @@ -790,8 +810,8 @@ The following command flags are available: Show the current installed Okteto CLI binary version -```console -$ okteto version +```bash +okteto version ``` Available subcommands: @@ -800,8 +820,8 @@ Available subcommands: Show information about how to update the Okteto CLI binary. -```console -$ okteto version update +```bash +okteto version update ``` ```console @@ -857,8 +877,8 @@ After you've ran `okteto kubeconfig` you should be able to communicate with the When running -```console -$ okteto kubetoken # example: okteto kubetoken https://okteto.example.com cindy +```bash +okteto kubetoken # example: okteto kubetoken https://okteto.example.com cindy ``` You should see a message like this: diff --git a/versioned_docs/version-1.37/reference/okteto-manifest.mdx b/versioned_docs/version-1.49/reference/okteto-manifest.mdx similarity index 81% rename from versioned_docs/version-1.37/reference/okteto-manifest.mdx rename to versioned_docs/version-1.49/reference/okteto-manifest.mdx index 9b71de1f0..5345c56cd 100644 --- a/versioned_docs/version-1.37/reference/okteto-manifest.mdx +++ b/versioned_docs/version-1.49/reference/okteto-manifest.mdx @@ -39,7 +39,7 @@ dev: - frontend:/usr/src/app test: unit: - image: okteto/golang:1 + image: ghcr.io/okteto/golang:1 commands: - "go test ." ``` @@ -47,7 +47,7 @@ test: ## Validating and Autocompleting the Okteto Manifest in your IDE -Okteto provides a JSON Schema for the Okteto Manifest to enhance your development experience by enabling autocompletion, real-time validation, and improved error detection within your IDE. +Okteto provides a JSON Schema for the Okteto Manifest that enables autocompletion, real-time validation, and error detection in your IDE. To configure this in **Visual Studio Code**, install the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) and add the following to your workspace or user settings.json: @@ -56,7 +56,7 @@ To configure this in **Visual Studio Code**, install the [YAML extension](https: "yaml.schemas": { "https://raw.githubusercontent.com/okteto/okteto/master/schema.json": [ "okteto.yml", - "okteto.yaml", + "okteto.yaml" ] } } @@ -90,6 +90,10 @@ build: SOURCE_IMAGE: ${OKTETO_BUILD_BASE_IMAGE} secrets: npmrc: .npmrc + server_cert: + file: certs/server.cert + npm_token: + env: NPM_TOKEN ``` Each image supports the following fields: @@ -99,7 +103,39 @@ Each image supports the following fields: - `depends_on`: list of images that need to be built first. - `dockerfile`: the path to the Dockerfile. It's a relative path to the build context (default: `Dockerfile`). - `image`: the name of the image to build and push. In clusters that have Okteto installed, this is optional (if not specified, the [Okteto Registry](core/container-registry.mdx) is used). -- `secrets`: list of secrets exposed to the build. The value of each secret refers to a file. Okteto will resolve references containing a `$` sign in this file to environment variables on the machine Okteto is running on. +- `secrets`: list of secrets exposed to the build. Each secret can be defined in one of three forms: + + **Shorthand (file path):** + ```yaml + secrets: + my_secret: /path/to/secret/file + ``` + + **Explicit file key:** + ```yaml + secrets: + my_secret: + file: /path/to/secret/file + ``` + + **Environment variable:** + ```yaml + secrets: + my_secret: + env: MY_ENV_VAR + ``` + + The shorthand and `file` forms are equivalent. Okteto resolves references containing a `$` sign in secret files to environment variables on the machine Okteto is running on. The `env` form reads the secret value directly from an environment variable. A secret cannot specify both `file` and `env`. + + To consume a secret during the build, use the `--mount=type=secret` flag in your Dockerfile: + + ```dockerfile + RUN --mount=type=secret,id=npm_token \ + cat /run/secrets/npm_token + ``` + + The `id` in the Dockerfile mount must match the secret name defined in `okteto.yaml`. + - `target`: build the specified stage as defined inside the Dockerfile. See the [multi-stage official docs](https://docs.docker.com/develop/develop-images/multistage-build/) for details. You can build all these images by running `okteto build`, or `okteto build xxx` to build a single one. @@ -108,7 +144,7 @@ You can build all these images by running `okteto build`, or `okteto build xxx` If you use multiple Dockerfiles, you can use different ignore-files for each Dockerfile. You do so using a special naming convention for the ignore-files. Place your ignore-file in the same directory as the Dockerfile, and prefix the ignore-file with the name of the Dockerfile, as shown in the following example. e.g. `dev.Dockerfile` and `dev.Dockerfile.dockerignore` ::: -Follow this document for a list of [environment variables](core/okteto-variables.mdx#built-in-environment-variables-for-images-in-okteto-registry) available in your deploy commands to refer to the images built in the `build` section of your Okteto Manifest. +For a list of [environment variables](core/okteto-variables.mdx#built-in-environment-variables-for-images-in-okteto-registry) available in your deploy commands to refer to images built in the `build` section, see the variables reference. > Okteto will automatically add all the build environment variables from all previous images in the dependency chain as build arguments. To refer to them, remember to add the `ARG` instruction on your Dockerfile. @@ -184,7 +220,7 @@ deploy: command: echo "$OKTETO_FOLDER" # Prints /app ``` -Follow this document for a list of [environment variables](core/okteto-variables.mdx#default-environment-variables) available in your deploy commands. +See the [environment variables](core/okteto-variables.mdx#runtime-environment-variables-injected-into-pods) available in your deploy commands. #### Deploy remotely (recommended) {#deploy-remotely} @@ -192,7 +228,7 @@ If you define an image in your `deploy` section, `okteto deploy` will run in rem ```yaml deploy: - image: okteto/pipeline-runner:1.0.0 + image: ghcr.io/okteto/pipeline-runner:1.0.0 context: . commands: - helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE} @@ -209,7 +245,7 @@ deploy: - helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE} ``` -Follow our docs to know more about [remote execution and how it works](core/remote-execution.mdx). +See [Remote Execution](core/remote-execution.mdx) for details on how remote mode works. #### Deploy with Compose @@ -268,7 +304,7 @@ Your deploy commands will be executed before deploying your Docker Compose files #### Divert Divert allows you to create lightweight development environments that include only the services you are actively working on while leveraging an existing shared environment for all other microservices. -This approach significantly reduces infrastructure costs and complexity, especially in large microservices environments. +This reduces infrastructure costs and complexity in large microservices architectures. Okteto supports two different drivers: `nginx` (default) and `istio`. @@ -296,9 +332,27 @@ deploy: ``` - `driver`: Specifies the backend to divert requests. Use `nginx` (or leave this field unspecified) to use the default Nginx driver. -- `namespace`: The namespace that holds the full shareable environment. When a request is directed to a service that wasn't created by the `deploy` command, Okteto will automatically direct it to the environment running on this namespace. +- `namespace`: The namespace that holds the full shareable environment. When a request is directed to a service that wasn't created by the `deploy` command, Okteto will automatically direct it to the environment running on this namespace. This must be an Okteto-managed Namespace — one that Okteto deployed. Namespaces that Okteto did not deploy are not officially supported as divert targets. + +**Environment Variable Support:** + +The `namespace` field supports environment variable substitution: + +```yaml +divert: + namespace: ${OKTETO_SHARED_NAMESPACE:-staging} +``` + +**Behavior:** + +When you run `okteto deploy` with a `divert` configuration: -When `divert` is enabled, Okteto injects the key `okteto-divert` within the header [`baggage`](https://www.w3.org/TR/baggage/) into every request that passes through your development ingress. This header allows Okteto to route the request intelligently between services running in your personal namespace and services running in a shared environment. +1. **Deployment**: Only resources defined in your `deploy.commands` are created in your namespace +2. **Header Injection**: Okteto injects the key `okteto-divert` within the header [`baggage`](https://www.w3.org/TR/baggage/) into every request that passes through your development ingress +3. **Traffic Routing**: Requests with your baggage header route to your namespace; missing services fall back to the shared namespace +4. **DNS Resolution**: Services resolve to the shared namespace when not deployed locally + +This header allows Okteto to route requests between services running in your personal Namespace and services running in a shared environment. :::tip To maintain request routing across service boundaries, we recommend propagating the `baggage` (with the key `okteto-divert`) header to all downstream service calls. @@ -307,16 +361,42 @@ Beyond request routing, this header can also be used to: - Redirect requests to services in other namespaces - Dynamically select the correct database instance for read/write operations -Check out [this GitHub repository](https://github.com/okteto-community/divert-showcase/) for practical examples of how to integrate Divert into your service communication flows. +Check out [Using Divert](../development/using-divert.mdx#header-propagation) for language-specific examples of header propagation. ::: +**Additional Examples:** + +With local database: +```yaml +deploy: + commands: + - helm upgrade --install mongodb bitnami/mongodb + - helm upgrade --install catalog chart/catalog --set image=${OKTETO_BUILD_CATALOG_IMAGE} + divert: + namespace: staging +``` + +Using dependencies with divert: +```yaml +dependencies: + mongodb: + repository: https://github.com/okteto/mongodb + wait: true + +deploy: + commands: + - helm upgrade --install catalog chart/catalog --set image=${OKTETO_BUILD_CATALOG_IMAGE} + divert: + namespace: staging +``` + Use the `istio` driver if your development environments use Istio for managing service-to-service communication. -When divert is enabled, Okteto injects the the key `okteto-divert` within the header [`baggage`](https://www.w3.org/TR/baggage/) to every request coming from the developer Namespace. +When divert is enabled, Okteto injects the key `okteto-divert` within the header [`baggage`](https://www.w3.org/TR/baggage/) to every request coming from the developer Namespace. If a request reaches the shared Namespace and matches a diverted virtual service, Okteto automatically redirects the request back to the developer Namespace. To divert a virtual service as part of your development environment, use the following notation: @@ -339,11 +419,18 @@ deploy: ``` - `driver`: Specifies the backend to divert requests. Use `istio` to use the Istio driver. -- `virtualServices`: A list of virtual services to divert. Each virtual service is defined by it's name, Namespace, and an optional list of routes to be diverted. By default, all routes are diverted. -- `hosts`: The list of hosts you want to divert in the developer namespace. Requests to these virtual services will have the key `okteto-divert` as part of the `baggage` header injected. +- `virtualServices`: A list of Istio VirtualService resources in the shared namespace to modify for traffic diversion. Okteto adds header-based routing logic to these virtual services so that requests with the baggage header are sent to the developer's namespace. Each entry is defined by its name, namespace, and an optional list of routes to be diverted. +- `hosts` (optional): A list of virtual services to copy into the developer namespace with a dedicated host (e.g., `https://service-a-.`). Requests reaching this host automatically have the `okteto-divert` key injected as part of the `baggage` header. The copied virtual service internally points to the original in the shared namespace, so the rest of the request flow passes through the shared environment with divert headers applied. Use this for services you are **not** deploying in your development environment — it provides a dedicated URL to reach your version of the app without manually adding the baggage header to requests against the staging endpoint. Services you deploy in your own namespace already have their own endpoints. +**Related Documentation:** + +- **[Divert Core Concepts](../core/divert.mdx)** - Understanding Divert architecture and traffic routing +- **[Using Divert](../development/using-divert.mdx)** - Implementation guide with header propagation examples +- **[Divert Tutorial](/docs/tutorials/divert)** - Step-by-step getting started guide +- **[Self-Hosted Configuration](../self-hosted/install/divert/index.mdx)** - Admin setup for Divert drivers + ### destroy ([string], optional) A list of commands to destroy external resources created by your development environment. @@ -357,7 +444,15 @@ destroy: - helm uninstall movies ``` -Follow this document for a [list of variables](core/okteto-variables.mdx#default-environment-variables) available in your destroy commands. +You can name your commands with the following syntax: + +```yaml +destroy: + - name: Uninstall Movies App + command: helm uninstall movies +``` + +See the [environment variables](core/okteto-variables.mdx#runtime-environment-variables-injected-into-pods) available in your destroy commands. #### Destroy remotely (recommended) {#destroy-remotely} @@ -365,7 +460,7 @@ If you define an image in your `destroy` section, `okteto destroy` will run in r ```yaml destroy: - image: okteto/tfenv-ci:1.4 + image: ghcr.io/okteto/tfenv-ci:1.4 context: . commands: - terraform destroy --auto-approve @@ -382,7 +477,7 @@ destroy: - helm uninstall movies ``` -Follow our docs to know more about [remote execution and how it works](core/remote-execution.mdx). +See [Remote Execution](core/remote-execution.mdx) for details on how remote mode works. ### dev (object, optional) @@ -411,7 +506,7 @@ Each development container supports the following fields: #### affinity (Affinity, optional) Affinity allows you to constrain which nodes your development container is eligible to be scheduled on, based on labels on the node. -More information about Kubernetes affinities is [available here](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity). +See the Kubernetes documentation on [affinity and anti-affinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity) for details. ```yaml @@ -458,7 +553,7 @@ Environment variables with only a key, or with a value with a `$` sign resolve t ```yaml environment: environment: development - name: user-${USER:peter} ## will be replaced by the value of $USER or by "peter" if the variable USER does not exist + name: user-${USER:-peter} ## will be replaced by the value of $USER or by "peter" if the variable USER does not exist DBPASSWORD: ## will be given the value of $DBPASSWORD if it exists ``` @@ -467,7 +562,7 @@ They can also be defined as a list, for example: ```yaml environment: - environment=development - - name=user-${USER:peter} ## will be replaced by the value of $USER or by "peter" if the variable USER does not exist + - name=user-${USER:-peter} ## will be replaced by the value of $USER or by "peter" if the variable USER does not exist - DBPASSWORD ``` @@ -540,10 +635,11 @@ If Okteto can't forward a port (typically because they are already taken), the ` #### initContainer (object, optional) Allows you to override the okteto init container configuration of your development container. +The security context of the init containers is configured with the [securityContext](#securitycontext-object-optional) field. ```yaml initContainer: - image: okteto/bin:1.2.22 + image: ghcr.io/okteto/okteto:3.14.0 resources: requests: cpu: 30m @@ -565,15 +661,15 @@ interface: 0.0.0.0 Sets the docker image of your development container. Defaults to the image specified in your deployment. -> More information on development images [here](development/images.mdx) +> See the [development images](development/images.mdx) documentation for more details. You can use an environment variable to replace the image, or any part of it: ```yaml -image: okteto/dev:$USER +image: ghcr.io/okteto/dev:$USER ``` -> More information on how to use private images for your development container [is available here](reference/faqs.mdx#how-to-use-private-images). +> See [how to use private images](reference/faqs.mdx#how-to-use-private-images) for your Development Container. #### imagePullPolicy (string, optional) @@ -632,12 +728,12 @@ The development mode used for a development environment. There are two options a - `sync`: the standard and default mode. This mode will synchronize your code with the remote development container - `hybrid`: use this mode if you want to run your service locally but run the rest of your application components in the cluster -More information about development modes is [available here](development/containers/index.mdx). +See [development modes](development/containers/index.mdx) for details. #### nodeSelector (map[string]string, optional) List of labels that the node must have to include the development container on it. -More information about Kubernetes node selectors is [available here](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector). +See the Kubernetes documentation on [node selectors](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) for details. ```yaml nodeSelector: @@ -687,7 +783,7 @@ This value will also apply to the `priorityClassName` of the pods defined in you #### probes (boolean, optional) If set to true, liveness, readiness, and start probes are enabled when running `okteto up` (default: `false`). -More information about Kubernetes probes is [available here](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/). +See the Kubernetes documentation on [liveness, readiness, and startup probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/) for details. Use the extended notation below to have more control over which probes to enable/disable: @@ -766,6 +862,8 @@ Allows you to override the pod security context of your development container. Okteto supports overriding the `fsGroup`, `runAsUser`, `runAsGroup`, `runAsNonRoot`, `allowPrivilegeEscalation`, `readOnlyRootFilesystem` and `capabilities` values. They're not set by default, and they follow the [same syntax used in Kubernetes](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/). +The container-level values (`runAsUser`, `runAsGroup`, `runAsNonRoot`, `allowPrivilegeEscalation`, `readOnlyRootFilesystem` and `capabilities`) are also applied to the init containers that `okteto up` adds to your pod (`okteto-bin` and `okteto-init-volume`). These init containers don't inherit the security context of the containers in your original Kubernetes manifest, so if your cluster enforces a pod security policy (for example, with Kyverno or Pod Security Admission), set the values the policy requires in this section. Setting `seccompProfile` is not supported. + ```yaml securityContext: runAsUser: 1000 @@ -805,7 +903,7 @@ serviceAccount: default #### services ([object], optional) A list of services that you want to put on developer mode along your development container. -The services work just like the development container, with one exception: they won't be able to start an interactive session. +Services work the same as the development container, with one exception: they cannot start an interactive session. For example, imagine that you have a python-based application with an API and a Worker service. If you define the manifest as shown below, running `okteto up` would give you a remote terminal into the web development container, while synchronizing your changes with both web and worker. @@ -864,12 +962,12 @@ sync: - $HOME/.ssh:/root/.ssh ``` -> Use the `.stignore` file on each local folder to avoid synchronizing build artifacts, dependencies, or git metadata. [More information is available here](reference/file-synchronization.mdx) +> Use the `.stignore` file on each local folder to avoid synchronizing build artifacts, dependencies, or git metadata. See the [file synchronization reference](reference/file-synchronization.mdx) for details. File sync can only update files that can be modified by your development container User ID. If you are using Okteto with persistent volumes, remember to set the field [securityContext.runAsUser](#securitycontext-object-optional) if your development container User ID is not `root`. -> You can use [secrets](reference/okteto-manifest.mdx#secrets-string-optional) to synchronize a single file instead of a folder +> `sync` works on folders. To inject a single file, use [secrets](reference/okteto-manifest.mdx#secrets-string-optional) instead, but note that a secret is only copied when the development container is created and is not kept synchronized afterwards. There is also an extended `sync` notation to fine tune the file synchronization service: @@ -906,7 +1004,7 @@ timeout: #### tolerations ([object], optional) A list of tolerations that will be injected into your development container. -More information about Kubernetes tolerations is [available here](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/). +See the Kubernetes documentation on [taints and tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) for details. ```yaml @@ -927,12 +1025,9 @@ volumes: - /root/.cache/go-build/ ``` -You can also mount a relative subpath of your local folder: - -```yaml -volumes: - - data:/var/lib/mysql -``` +:::warning +The `local:remote` syntax in the `volumes` field is deprecated. Okteto converts these entries into `sync` folders and logs a warning. Use the [`sync`](#sync-string-required) field instead. +::: #### workdir (string, optional) @@ -940,7 +1035,7 @@ Sets the working directory of your development container. ### external (object, optional) -A list of external resources that are part of your development environment. Use this section for resources that are deployed outside of the Okteto cluster, like Cloud resources or dashboards. +A list of external resources that are part of your development environment. Use this section for resources that are deployed outside of the Okteto cluster, like Cloud resources or dashboards. ```yaml external: @@ -995,7 +1090,7 @@ If the url value is declared in both places, the one declared in the deploy sect #### icon (string, optional) - Sets the icon that will be shown in the Okteto UI. The supported values for icons are listed below. If empty, it will default to `default`. +Sets the icon that will be shown in the Okteto UI. The supported values for icons are listed below. If empty, it will default to `default`.
@@ -1156,7 +1251,7 @@ A dictionary of Test Containers to run tests using [Remote Execution](core/remot ```yaml test: unit: - image: okteto/golang:1 + image: ghcr.io/okteto/golang:1 artifacts: - coverage.out caches: @@ -1168,7 +1263,7 @@ test: integration: depends_on: - unit - image: okteto/golang:1 + image: ghcr.io/okteto/golang:1 context: integration commands: - make tests diff --git a/versioned_docs/version-1.37/reference/ssh-server.mdx b/versioned_docs/version-1.49/reference/ssh-server.mdx similarity index 96% rename from versioned_docs/version-1.37/reference/ssh-server.mdx rename to versioned_docs/version-1.49/reference/ssh-server.mdx index 652ffd99c..9de2f0332 100644 --- a/versioned_docs/version-1.37/reference/ssh-server.mdx +++ b/versioned_docs/version-1.49/reference/ssh-server.mdx @@ -28,14 +28,14 @@ The SSH server makes it possible to integrate your development container with ID Once the development container is up and running, you can SSH into it with the following command: -```console -$ ssh -p PORT localhost +```bash +ssh -p PORT localhost ``` You can also SSH using the host entry added to your local SSH config: -```console -$ ssh MANIFEST_NAME.okteto +```bash +ssh MANIFEST_NAME.okteto ``` ### Secure by default diff --git a/versioned_docs/version-1.37/reference/supported-github-actions.mdx b/versioned_docs/version-1.49/reference/supported-github-actions.mdx similarity index 100% rename from versioned_docs/version-1.37/reference/supported-github-actions.mdx rename to versioned_docs/version-1.49/reference/supported-github-actions.mdx diff --git a/versioned_docs/version-1.49/release-notes.mdx b/versioned_docs/version-1.49/release-notes.mdx new file mode 100644 index 000000000..12ea7c9b4 --- /dev/null +++ b/versioned_docs/version-1.49/release-notes.mdx @@ -0,0 +1,472 @@ +--- +title: Release notes +description: Latest features, bug fixes, breaking changes, and improvements in each Okteto release, with Kubernetes compatibility details. +sidebar_label: Release notes +id: release-notes +--- + +import Image from '@theme/Image'; + +## 1.49.0 + +8 October 2026 + +This version is compatible with Kubernetes versions 1.34 to 1.36 \ +Okteto Chart release 1.49 is designed to work with [Okteto CLI 3.24.x](https://github.com/okteto/okteto/releases/tag/3.24.0) + +### Breaking Changes {#breaking-changes-1.49} + +- **Kubernetes 1.33 Removal**: Support for Kubernetes [1.33](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.33.md) has been removed in this release. Customers running Kubernetes 1.33 should upgrade to 1.34 or later before installing Chart 1.49 +- **`safe-to-evict` annotation now defaults to `false`**: Okteto marks the pods it creates in development Namespaces as not safe to evict, so the Kubernetes cluster autoscaler no longer scales down nodes that run active development sessions. Previously these pods were marked safe to evict, which could restart development services during scale-down. To restore the previous behavior, set [`addSafeToEvictAnnotation.value`](self-hosted/helm-configuration.mdx#addsafetoevictannotation) to `true` + +### Important Notes {#important-notes-1.49} + +- The [Resource Manager](admin/resource-manager.mdx#how-it-works) is configured in **Automatic** mode by default for **new installations**. Instances upgrading to this version retain their configured value +- [Remote Execution](core/remote-execution.mdx) is now enabled by default for **new installations**. Instances upgrading to this version retain their configured value + +### New Features {#new-features-1.49} + +- You can now configure the default [compression](https://docs.docker.com/build/exporters/#compression) used by BuildKit at instance level using the [`buildOpts`](self-hosted/helm-configuration.mdx#buildopts) Helm setting or the [Admin Variables](reference/feature-flags.mdx) `OKTETO_BUILD_COMPRESSION`, `OKTETO_BUILD_COMPRESSION_LEVEL` and `OKTETO_BUILD_FORCE_COMPRESSION`. You can define the variables per operation using User Variables or Deployment Variables +- **Kubernetes 1.36 Support**: Added support for Kubernetes [1.36](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.36.md) + +### Improvements {#improvements-1.49} + +- OpenID Connect now returns a clear error when different users from the [authentication provider](self-hosted/install/auth/openid-connect.mdx) map to the same Okteto user + +## 1.48.1 + +10 September 2026 + +This version is compatible with Kubernetes versions 1.33 to 1.35 \ +Okteto Chart release 1.48 is designed to work with [Okteto CLI 3.23.x](https://github.com/okteto/okteto/releases/tag/3.23.0) + +### Bug Fixes + +- Fixed an issue where git repository URLs containing embedded credentials could be exposed in plain text across the app +- [Okteto CLI 3.23.1](https://github.com/okteto/okteto/releases/tag/3.23.1): Fixed `okteto pipeline deploy` and `okteto preview deploy` failing when run from a repository that uses git worktrees + +## 1.48.0 + +4 September 2026 + +This version is compatible with Kubernetes versions 1.33 to 1.35 \ +Okteto Chart release 1.48 is designed to work with [Okteto CLI 3.23.x](https://github.com/okteto/okteto/releases/tag/3.23.0) + +### Important Notes {#important-notes-1.48} + +- **Legacy tolerations settings deprecated**: The `tolerations.oktetoPool`, `tolerations.devPool`, and `tolerations.buildPool` Helm settings are deprecated and will be removed in Okteto Chart 2.0. The chart has printed a warning when they are set since 1.21; the deprecation is now also documented in `values.yaml` and in the [Helm configuration reference](self-hosted/helm-configuration.mdx#tolerations). Use `globals.tolerations` and `globals.nodeSelectors` for the Okteto and dev pools, and `buildkit.tolerations` and `buildkit.nodeSelectors` for the build pool, following the [migration guide](https://community.okteto.com/t/important-update-migrating-to-new-implementation-of-okteto-pod-tolerations-and-node-selectors/1281) +- **Removed chart settings**: The `oktetoAI` and `prepullImages.includeAgent` settings have been removed from the Okteto Chart and are ignored if still present in your values. You can safely delete them + +### New Features {#new-features-1.48} + +- **Opt out of node CA injection**: New `daemonset.injectCA.enabled` Helm setting, which defaults to `true`. When you use a private CA or the chart's self-signed certificate, the Okteto daemonset installs the CA into each node's trust store and restarts `containerd` once per node. On newly provisioned nodes, most visibly with autoscalers such as Karpenter, that restart interrupts image pulls in progress and can leave workloads scheduled on the node marked as failed until they retry. Set it to `false` to disable only that task and [trust the CA at the node level](self-hosted/install/certificates/bring-your-own-certificate.mdx#injecting-the-ca-into-cluster-nodes) through your cloud provider instead. The other daemonset tasks and CA trust in the Okteto components are unaffected + +### Improvements {#improvements-1.48} + +- **PKCS#8 private keys for the wildcard certificate**: The Okteto API and the registry garbage-collection job now accept PKCS#8 private keys (`BEGIN PRIVATE KEY`) for the [wildcard certificate](self-hosted/install/certificates/bring-your-own-certificate.mdx), in addition to PKCS#1 RSA and SEC1 EC keys. Previously, a PKCS#8 key, the format most modern tooling emits, made the API fail at startup with `couldn't find a valid cert`, even though every other component accepted it +- Upgraded the bundled ingress-nginx to address [CVE-2026-42533](https://github.com/okteto/app/pull/10364), a high-severity heap buffer overflow in the NGINX controller + +### Bug Fixes {#bug-fixes-1.48} + +- Fixed BuildKit pods being marked ready while still loading their build cache, which could route builds to an instance that couldn't serve them yet. The readiness probe now waits until the daemon accepts builds; its thresholds can be tuned under [`buildkit.readinessProbe`](self-hosted/helm-configuration.mdx#buildkit) +- Fixed the resource list in the Namespace view hanging indefinitely when the Okteto Registry accepted connections but never responded. The image ownership check that enriches pull-error messages is now time-bounded and is skipped for images hosted outside the Okteto Registry +- Fixed the **Redeploy** button in the resources sidebar being enabled for resources that can't be redeployed, such as resources being destroyed or requiring a force destroy. The sidebar now hides the button in those states, matching the resource details view +- Fixed long repository URLs not truncating in the Redeploy dialog, which broke the dialog layout +- [Okteto CLI 3.23.0](https://github.com/okteto/okteto/releases/tag/3.23.0): Fixed `okteto up` failing to establish the local SSH tunnel on macOS, most often with a VPN connected, with `ssh: handshake failed ... write: broken pipe`. The CLI dialed an empty-host address (`:PORT`), which macOS routed unreliably. Both sync and hybrid modes were affected + +## 1.47.0 + +6 August 2026 + +This version is compatible with Kubernetes versions 1.33 to 1.35 \ +Okteto Chart release 1.47 is designed to work with [Okteto CLI 3.22.x](https://github.com/okteto/okteto/releases/tag/3.22.0) + +### Important Notes {#important-notes-1.47} + +- **OCI media types enabled by default in builds**: The BuildKit bundled with Okteto was upgraded from 0.29 to 0.31, which includes several upstream CVE fixes. With this upgrade, images built with `okteto build` are pushed to the registry using OCI media types by default. This changes only how pushed images are stored; pulling images is unaffected. Major registries have supported OCI media types for years ([registry support matrix](https://github.com/moby/buildkit/issues/6171)), and the Okteto Registry supports them. If you push images to a registry that doesn't support OCI media types, set the [`OKTETO_BUILD_OCI_MEDIATYPES`](reference/feature-flags.mdx) feature flag to `false` as an [Admin Variable](admin/dashboard.mdx#admin-variables) to fall back to legacy Docker media types + +### New Features {#new-features-1.47} + +- **Disabling Kubernetes service links in Docker Compose**: Docker Compose services now support a per-service [`x-enable-service-links`](reference/docker-compose.mdx#x-enable-service-links-boolean-optional) field. Set it to `false` to stop Kubernetes from injecting service link environment variables such as `_SERVICE_HOST` and `_PORT` into the service's containers, which can break applications that expect a plain port number — or no value — under those names. This brings Docker Compose deployments to parity with `enableServiceLinks: false` in Kubernetes manifests. The field is opt-in and requires Okteto CLI 3.22.0 or later + +### Improvements {#improvements-1.47} + +- **Okteto skill setup from the Namespace view**: The Namespace view now includes a shortcut to set up the Okteto skill, making [Agentic Workflows](agentic/index.mdx) easier to discover + +### Bug Fixes {#bug-fixes-1.47} + +- [Okteto CLI 3.22.0](https://github.com/okteto/okteto/releases/tag/3.22.0): Fixed the CLI hanging without output — or crashing with a goroutine deadlock error — when the connection to BuildKit through the port-forward failed. The CLI now reports the connection error + +## 1.46.0 + +3 July 2026 + +This version is compatible with Kubernetes versions 1.33 to 1.35 \ +Okteto Chart release 1.46 is designed to work with [Okteto CLI 3.21.x](https://github.com/okteto/okteto/releases/tag/3.21.0) + +### New Features {#new-features-1.46} + +- **Workload identity for Docker Compose services**: Docker Compose services now support a per-service [`x-okteto-identity-token`](reference/docker-compose.mdx#x-okteto-identity-token-object-optional) directive. Okteto projects an audience-scoped, automatically refreshed Kubernetes ServiceAccount token into the running container, so a service can authenticate to a cloud provider through OIDC web-identity federation (for example, AWS STS) without static, manually rotated credentials. The directive is cloud-agnostic: Okteto manages only the token projection, and you set the provider variables such as `AWS_ROLE_ARN`, `AWS_REGION`, and `AWS_WEB_IDENTITY_TOKEN_FILE` per service. It applies only to services that declare it, and requires Okteto CLI 3.21.0 or later + +### Improvements {#improvements-1.46} + +- **Linked pull request in the Preview Environment view**: The Preview Environment details view now shows the pull request associated with the environment. Previously this link appeared only in the Preview Environments list +- **Chart version in the Help menu**: The Okteto Chart version is now shown in the Help menu for all users. This makes it easier to confirm the installed version when reporting an issue +- Upgraded the bundled ingress-nginx to address [CVE-2026-49975](https://github.com/okteto/app/pull/10229), a high-severity HTTP/2 vulnerability in the ingress-nginx controller +- [Okteto CLI 3.21.0](https://github.com/okteto/okteto/releases/tag/3.21.0): The BuildKit readiness check timeout is now configurable through the [`OKTETO_BUILDKIT_READINESS_TIMEOUT`](reference/feature-flags.mdx) environment variable, with the default raised from 4 to 6 seconds. This prevents intermittent `context deadline exceeded` errors when building or deploying remotely over slow or high-latency connections + +### Bug Fixes {#bug-fixes-1.46} + +- [Okteto CLI 3.21.0](https://github.com/okteto/okteto/releases/tag/3.21.0): Fixed `okteto destroy --all` hanging until it timed out, and reporting a false error, when run against a Sleeping Namespace. The command now completes and leaves the Namespace in its previous status + +## 1.45.0 + +5 June 2026 + +This version is compatible with Kubernetes versions 1.33 to 1.35 \ +Okteto Chart release 1.45 is designed to work with [Okteto CLI 3.20.x](https://github.com/okteto/okteto/releases/tag/3.20.0) + +### Improvements {#improvements-1.45} + +- **Filter resources by status in the Namespace view**: The resource list in a Namespace can now be filtered by status, such as **Deployed** or **Error**, making it faster to find a specific service in Namespaces that run many of them +- Upgraded the bundled ingress-nginx to address [CVE-2026-9256](https://github.com/okteto/app/pull/10182), a high-severity vulnerability in the ingress-nginx controller + +### Bug Fixes {#bug-fixes-1.45} + +- Fixed the GitHub branch selector in the Deploy dialog showing stale results from a previous search after a branch was unselected + +## 1.44.0 + +8 May 2026 + +This version is compatible with Kubernetes versions 1.33 to 1.35 \ +Okteto Chart release 1.44 is designed to work with [Okteto CLI 3.19.x](https://github.com/okteto/okteto/releases/tag/3.19.0) + +### Important Notes {#important-notes-1.44} + +- **Ingress NGINX distribution**: The `ingress-nginx` Helm dependency in the Okteto Chart is now sourced from Okteto's OCI fork at `ghcr.io/okteto/ingress-nginx-chart` instead of the upstream Helm repository. Standard installs and upgrades are unaffected because the dependency is packaged with the Okteto Chart, so the OCI registry is not contacted at install time. Workflows that re-resolve chart dependencies from source (for example, running `helm dep update` against the chart source, or configuring ArgoCD against the chart source repo) require Helm 3.8.0+ or ArgoCD 2.3.0+ for OCI support + +### New Features {#new-features-1.44} + +- **Environment Variables in `build.secrets`**: The Okteto Manifest and Docker Compose stacks now support environment variables in the [`build.secrets`](reference/okteto-manifest.mdx#build-object-optional) section, complementing the existing file-based references. This enables passing dynamic build-time secrets directly from your environment without staging intermediate files + +### Improvements {#improvements-1.44} + +- The Git Catalog deploy flow now responds to the Enter key, making catalog deploys keyboard-accessible +- Improved the error message returned by the CLI when invalid environment-variable syntax is used in `build.secrets`, making it clearer what is expected + +### Bug Fixes {#bug-fixes-1.44} + +- Fixed the Deploy dialog preserving its previous state after a deploy completed, instead of resetting +- Fixed tooltip flickering in the Dashboard +- [Okteto CLI 3.19.0](https://github.com/okteto/okteto/releases/tag/3.19.0): Fixed `okteto deploy` returning a generic manifest error instead of a compose-specific error when a file matching the compose filename pattern was syntactically invalid + +## 1.43.1 + +22 April 2026 + +This version is compatible with Kubernetes versions 1.33 to 1.35 \ +Okteto Chart release 1.43 is designed to work with [Okteto CLI 3.18.x](https://github.com/okteto/okteto/releases/tag/3.18.0) + +### Bug Fixes + +- Fixed an issue where the pipeline runner image bundled in the chart contained zstd-compressed layers, which may cause container startup failures on clusters running certain containerd v1 versions + +## 1.43.0 + +9 April 2026 + +This version is compatible with Kubernetes versions 1.33 to 1.35 \ +Okteto Chart release 1.43 is designed to work with [Okteto CLI 3.18.x](https://github.com/okteto/okteto/releases/tag/3.18.0) + +### Breaking Changes {#breaking-changes-1.43} + +- **Kubernetes 1.32 Removal**: Support for Kubernetes [1.32](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.32.md) has been removed in this release. Customers running Kubernetes 1.32 should upgrade to 1.33 or later before installing Chart 1.43 +- **ArgoCD Certificate Configuration**: Customers using ArgoCD must update their `ignoreDifferences` configuration to include `/stringData/*` paths for Secret objects. Without this update, ArgoCD syncs may cause webhook TLS failures. See the updated [ArgoCD setup documentation](self-hosted/manage/argocd.mdx) for the corrected configuration + +### New Features {#new-features-1.43} + +- **Kubernetes 1.35 Support**: Added support for Kubernetes [1.35](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.35.md) + +- **[Agentic Workflows](agentic/index.mdx)**: New documentation section covering how to connect AI agents like Claude Code to your Okteto environments. Whether you're pair-programming with an agent in your IDE or letting it handle tasks autonomously, Okteto gives agents isolated, live environments using the same CLI and `okteto.yaml` manifest that human developers use + +### Improvements {#improvements-1.43} + +- Upgraded Ingress NGINX to 1.15.1 for Kubernetes 1.35 compatibility. This version also addresses several high-severity security vulnerabilities ([CVE-2026-24512](https://github.com/kubernetes/kubernetes/issues/136678), [CVE-2026-4342](https://github.com/kubernetes/kubernetes/issues/137893)) related to configuration injection in the ingress-nginx controller +- Upgraded BuildKit to v0.28.1 for improved build performance and stability +- Okteto AI: Updated to Claude Sonnet 4.6, the latest AI model for software development tasks +- Improved self-signed certificate generation in the Helm chart to resolve compatibility issues with ArgoCD-managed upgrades. Fixed a `stringData` vs `data` mismatch in `ignoreDifferences` configuration that caused webhook TLS verification failures +- [Okteto CLI 3.18.0](https://github.com/okteto/okteto/releases/tag/3.18.0) Handle missing Gateway API CRDs gracefully in compose endpoints + +### Bug Fixes {#bug-fixes-1.43} + +- Fixed the redeploy button being visible in the resources list for users without the required permissions + +## 1.42.0 + +12 March 2026 + +This version is compatible with Kubernetes versions 1.32 to 1.34 \ +Okteto Chart release 1.42 is designed to work with [Okteto CLI 3.17.x](https://github.com/okteto/okteto/releases/tag/3.17.0) + +### Deprecation Notice {#deprecation-notice-1.42} + +- ⚠️ Important: **Support for Kubernetes [1.32](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.32.md) will be removed in the next release** (1.43). Support for Kubernetes [1.35](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.35.md) will be added. Please plan your cluster upgrades accordingly. + +### New Features {#new-features-1.42} + +- **Build Queue Enabled by Default**: The [build queue system](core/build-service.mdx#build-queue-system) introduced as opt-in in 1.41 is now enabled by default. Build requests are automatically routed to the optimal Okteto Build pod based on real-time metrics, and when all build pods are busy, builds enter a queue to ensure consistent performance. Customers on significantly older CLI versions will continue using the legacy build path automatically. If you need to opt out, set the admin variable `OKTETO_BUILD_QUEUE_ENABLED` to `false` via [Admin Variables](admin/dashboard.mdx#admin-variables) + +### Improvements {#improvements-1.42} + +- **Persistent Namespace and Preview Indicators**: The "Keep Awake" option has been renamed to "Persistent" across the Dashboard and CLI for consistency. Namespaces and Preview Environments marked as [persistent](core/namespaces.mdx#mark-a-namespace-as-persistent-to-prevent-it-from-sleeping-and-deletion) now display a visual indicator in both the Okteto Dashboard and the CLI (`okteto namespace list` and `okteto preview list`), making it easier to identify which environments are exempt from automatic sleep and garbage collection +- Updated the Deploy dialog UI with a new drawer design for improved consistency across the Dashboard +

+ +

+ +### Bug Fixes {#bug-fixes-1.42} +- Fixed a panic in the API that occurred in rare situations where a Kubernetes resource was restarting and the error message was not provided by Kubernetes, which caused the API container to restart + +## 1.41.1 + +17 February 2026 + +This version is compatible with Kubernetes versions 1.32 to 1.34 \ +Okteto Chart release 1.41 is designed to work with [Okteto CLI 3.16.x](https://github.com/okteto/okteto/releases/tag/3.16.0) + +### Security {#security-1.41} + +Fixed a critical vulnerability in the OAuth2 authentication flow that could allow an attacker to steal user credentials. We are not aware of any exploitation of this vulnerability in the wild. + +We recommend all self-hosted customers upgrade to 1.41.1 as soon as possible. Full details will be published at a later date. + +## 1.41.0 + +6 February 2026 + +This version is compatible with Kubernetes versions 1.32 to 1.34 \ +Okteto Chart release 1.41 is designed to work with [Okteto CLI 3.16.x](https://github.com/okteto/okteto/releases/tag/3.16.0) + +### Breaking Changes {#breaking-changes-1.41} + +- **Node Selector Fix for Installer Jobs**: Fixed an issue where `globals.nodeSelectors` were not being correctly applied to installer jobs. This fix ensures node selectors are now properly enforced, but may cause pods to fail scheduling if they cannot reach the Okteto Control Plane due to infrastructure network firewalls or node placement constraints. Review your node selector configuration before upgrading. + +### New Features {#new-features-1.41} + +- **Build Queue System**: Okteto now implements a build queue system that ensures consistent build performance and fair resource distribution. Build requests are automatically routed to the optimal Okteto Build pod based on real-time metrics (CPU pressure, memory usage, and IOPS). When all build pods are busy, builds enter a queue and wait until resources become available, preventing overload and ensuring predictable build times. This behavior is disabled by default but can be enabled by setting the `OKTETO_BUILD_QUEUE_ENABLED` feature flag to `true` via [Admin Variables](admin/dashboard.mdx#admin-variables). Learn more about the [Build Queue System](core/build-service.mdx#build-queue-system) + +### Improvements {#improvements-1.41} + +- **Configurable Build Service Thresholds**: Administrators can now configure resource thresholds (CPU pressure, memory usage, and IOPS) directly from the [Build Service admin dashboard](admin/build-service.mdx) to fine-tune when build pods are considered busy +- **Restart Build Pods**: Administrators can now [restart individual Okteto Build pods directly from the Okteto Admin panel](admin/build-service.mdx#restarting-a-buildkit-pod). This makes it easier to recover from Okteto Build issues without requiring Kubernetes admin access or contacting Okteto support. +- [Okteto CLI 3.16.0](https://github.com/okteto/okteto/releases/tag/3.16.0) All container logs are now included with `okteto doctor` + +### Bug Fixes {#bug-fixes-1.41} + +- **Activity Metrics Accuracy Fix**: Fixed an issue affecting instances with personal namespace garbage collection enabled, where system-initiated garbage collection operations were incorrectly counted as user activity, inflating usage metrics. The root cause was a loop where personal namespaces cycled between sleeping and active states, generating repeated system operations. Both issues are now resolved, ensuring reliable activity data and accurate namespace state reporting. [Read the post-mortem](https://community.okteto.com/t/post-mortem-okteto-user-activity-metrics-incident/1452) +- **Pod Affinity Fix for Shared Volumes**: Fixed an issue where pods sharing persistent volume claims (PVCs) were not always scheduled on the same node. This ensures that services using shared storage in okteto up are correctly co-located. +- [Okteto CLI 3.16.0](https://github.com/okteto/okteto/releases/tag/3.16.0) Fixed a race condition when running parallel builds locally where the `.okteto/.secret` folder could be deleted while other concurrent build processes were still using it, causing "no such file or directory" errors +- [Okteto CLI 3.16.0](https://github.com/okteto/okteto/releases/tag/3.16.0) Improved handling of transient network errors during builds, reducing false failures caused by temporary connectivity issues + + + +## 1.40.1 + +17 February 2026 + +This version is compatible with Kubernetes versions 1.32 to 1.34 \ +Okteto Chart release 1.40 is designed to work with [Okteto CLI 3.15.x](https://github.com/okteto/okteto/releases/tag/3.15.0) + +### Security {#security-1.40} + +Fixed a critical vulnerability in the OAuth2 authentication flow that could allow an attacker to steal user credentials. We are not aware of any exploitation of this vulnerability in the wild. + +We recommend all self-hosted customers upgrade to 1.40.1 as soon as possible. Full details will be published at a later date. + +## 1.40.0 + +9 January 2026 + +This version is compatible with Kubernetes versions 1.32 to 1.34 \ +Okteto Chart release 1.40 is designed to work with [Okteto CLI 3.15.x](https://github.com/okteto/okteto/releases/tag/3.15.0) + +### Breaking Changes {#breaking-changes-1.40} + +- **Default Registry Change**: Okteto now pulls images from GitHub Container Registry (ghcr.io) by default instead of Docker Hub. Images are still published to both registries. If you need to keep pulling from Docker Hub, see our [guide on configuring your registry](self-hosted/manage/upgrade.mdx#upgrading-to-okteto-140x--default-registry-change-to-github-container-registry) + +### New Features {#new-features-1.40} + +- **Builds Dashboard**: Track and analyze your build performance with the new [Builds dashboard in Okteto Insights](core/okteto-insights-dashboards.mdx#build-service-dashboard). Monitor build metrics, success rates, and performance trends across your organization to optimize your CI/CD pipeline +- **BuildKit Metrics and cgroups 1 Support**: Added support for BuildKit metrics collection and cgroups v1 compatibility to improve monitoring and resource management capabilities +- Added `OKTETO_MANAGED_POD` environment variable to all pods managed by Okteto for easier identification and filtering + + +### Improvements {#improvements-1.40} + +- Improved registry probe configuration for better reliability and performance +- Upgraded BuildKit to v0.26.3 for enhanced performance, stability, and security +- Updated the [Catalog UI](admin/catalog.mdx) with new drawer design for improved user experience, all functionality remains the same +- Increased default timeout for destroying dependencies during namespace and preview environment deletion from 5 minutes to 30 minutes to better handle complex cleanup scenarios + +### Bug Fixes {#bug-fixes-1.40} + +- [Okteto CLI 3.15.0](https://github.com/okteto/okteto/releases/tag/3.15.0): Fixed an issue where destroy operations would fail when the metrics server or custom metrics server was not available + +### Removal Notice {#removal-notice-1.40} +- Support for Kubernetes [1.31](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.31.md) has been removed in this release. + + +## 1.39.1 + +17 February 2026 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.39 is designed to work with [Okteto CLI 3.14.x](https://github.com/okteto/okteto/releases/tag/3.14.0) + +### Security {#security-1.39} + +Fixed a critical vulnerability in the OAuth2 authentication flow that could allow an attacker to steal user credentials. We are not aware of any exploitation of this vulnerability in the wild. + +We recommend all self-hosted customers upgrade to 1.39.1 as soon as possible. Full details will be published at a later date. + +## 1.39.0 + +5 December 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.39 is designed to work with [Okteto CLI 3.14.x](https://github.com/okteto/okteto/releases/tag/3.14.0) + +### New Features {#new-features-1.39} + +- **Build Service Admin Dashboard**: Administrators can now monitor BuildKit performance and resource utilization through a new [Build Service dashboard](admin/build-service.mdx). Track real-time metrics including CPU pressure, memory usage, I/O pressure, and active builds for each BuildKit pod to ensure optimal build performance across your Okteto instance + +### Improvements {#improvements-1.39} + +- Upgraded BuildKit to v0.26.2 for better performance, stability, and compatibility +- Added support for configuring the reloader image registry via `reloader.imageRegistry` +- Consolidated table columns and filter controls in the Admin view for Previews and Namespaces for a cleaner, more consistent UI +- Improved display of tooltips on disabled buttons in the UI +- Updated UI notifications with improved grouping and display behavior +- [Okteto CLI 3.14.0](https://github.com/okteto/okteto/releases/tag/3.14.0): Improved Smart Builds performance by checking if images are already built in parallel + +### Bug Fixes {#bug-fixes-1.39} + +- Fixed tooltip overflow issues in the Catalog +- AI Agent: Improved SSH forwarder connection handling to prevent dropped or stuck sessions +- Updated Claude Code and npm libraries to address [CVE-2025-64755](https://nvd.nist.gov/vuln/detail/CVE-2025-64755) +- [Okteto CLI 3.14.0](https://github.com/okteto/okteto/releases/tag/3.14.0): Fixed `okteto doctor` to track dev container logs to help troubleshoot `okteto up` issues +- [Okteto CLI 3.14.0](https://github.com/okteto/okteto/releases/tag/3.14.0): Fixed the `--reset` flag behavior in `okteto up` +- [Okteto CLI 3.14.0](https://github.com/okteto/okteto/releases/tag/3.14.0): Fixed SSH forwarder connection handling when connecting with the SSH agent +- [Okteto CLI 3.14.0](https://github.com/okteto/okteto/releases/tag/3.14.0): Fixed `okteto up` support for deployments with `shareProcessNamespace: true` enabled + +## 1.38.1 + +21 November 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.13.x](https://github.com/okteto/okteto/releases/tag/3.13.0) + +### Bug Fixes + +- [Okteto CLI 3.13.3](https://github.com/okteto/okteto/releases/tag/3.13.3): Fixed a timeout issue when contacting the SSH agent during remote deploys where commands in the Okteto Manifest performed SSH operations + +## 1.38.0 + +7 November 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.38 is designed to work with [Okteto CLI 3.13.x](https://github.com/okteto/okteto/releases/tag/3.13.0) + +### Important Notes {#important-notes-1.38} + +- **Upgrade Considerations for Self-Hosted Customers**: Internal certificates have been unified into a [single configuration](self-hosted/helm-configuration.mdx#internalcertificate). During the upgrade, you may experience temporary communication issues lasting a few seconds as the new certificate configuration takes effect +- **ArgoCD Users**: If you manage your Okteto installation with ArgoCD, review our [Argo CD guide](self-hosted/manage/argocd.mdx). The certificate unification may require special attention during the ArgoCD sync process to avoid deployment interruptions. + +### New Features {#new-features-1.38} + +- **Enhanced Preview Environments Performance**: Significantly improved loading performance, reducing load times by up to 15x for customers with large numbers of Preview Environments +- **Advanced Preview Environments Filtering**: Added comprehensive filtering options including search, repository, status, owner, and time-based filters to help teams quickly find specific preview environments +- Added read-only mode for [Known Hosts configuration](self-hosted/manage/crds.mdx#known-hosts), allowing admins to lock down SSH host key management and prevent accidental modifications + +### Improvements {#improvements-1.38} + +- Upgraded to BuildKit v0.25.2 for improved build performance and stability +- Updated Okteto AI Agent base image to Debian Trixie with Go 1.24.6 and Node.js 24 +- Okteto AI: Added support for Claude Sonnet 4.5, the latest AI model optimized for software development tasks +- Improved [Okteto Build cache isolation](core/build-service.mdx#mount-cache-id-management): Cache IDs now incorporate both the target path and repository name to prevent different repositories from accidentally sharing the same cache +- [Okteto CLI 3.13.0](https://github.com/okteto/okteto/releases/tag/3.13.0): Enhanced namespace destruction logic and error handling during resource cleanup + +### Bug Fixes {#bug-fixes-1.38} + +- Fixed a problem when Known Hosts feature was enabled where the ssh-keyscan command kept being executed when it shouldn't +- [Okteto CLI 3.13.0](https://github.com/okteto/okteto/releases/tag/3.13.0): Fixed nil pointer exception in build command when the specified Dockerfile doesn't exist +- [Okteto CLI 3.13.0](https://github.com/okteto/okteto/releases/tag/3.13.0): Improved error handling in log streaming during resource destruction as logs were not being fully displayed +- [Okteto CLI 3.13.0](https://github.com/okteto/okteto/releases/tag/3.13.0): Fixed cache isolation in `okteto test` where different test containers sharing the same cached directory could reuse each other's cache. Caches are now properly isolated and only reused across executions of the same test container + +## 1.37.3 + +21 November 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) + +### Bug Fixes + +- [Okteto CLI 3.12.3](https://github.com/okteto/okteto/releases/tag/3.12.3): Fixed a timeout error contacting with the SSH agent on remote deploys when some of the commands defined in the Okteto Manifest were performing SSH operations + +## 1.37.2 + +15 October 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) + +### Bug Fixes {#bug-fixes-1.37} + +- Fixed repository cloning failures with SSH host verification - Resolved conflicts between automatic SSH scanning and admin-configured known hosts that could cause deployment failures. + +## 1.37.1 + +7 October 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) + +### Improvements {#improvements-1.37.1} + +- Upgrade Redis to 8.2.2 to fix [CVE-2025-49844](https://www.wiz.io/blog/wiz-research-redis-rce-cve-2025-49844) + +## 1.37.0 + +1 October 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) + +### Breaking Changes {#breaking-changes-1.37} + +- Removed the dependency on the Bitnami Redis Helm chart. Okteto now ships its own Kubernetes templates to deploy Redis. As part of this change, the workload has been updated from a StatefulSet to a Deployment, and the available Redis configuration options [have been reduced and standardized](self-hosted/helm-configuration.mdx#redis). If you previously customized Redis using Bitnami-specific values, review and update your Helm values to align with the supported configuration before upgrading. +- We've changed the [default value of `pullAlways` to **false**](self-hosted/helm-configuration.mdx#pullalways) for pods deployed in Okteto-managed namespaces. This speeds up pod creation when images are already present on the node, while still allowing `pullAlways` to be explicitly enabled if needed + +### New Features {#new-features-1.37} + +- Added a centralized [Known Hosts feature to the Admin UI](admin/ssh-known-hosts.mdx) (Admin → Settings → Known Hosts). Admins can now pin trusted SSH host keys and disable automatic ssh-keyscan, ensuring secure, consistent cloning of repositories and submodules without custom runner images + +### Improvements {#improvements-1.37} + +- Improved error handling in the Okteto AI Agent UI for API errors and "Prompt too long" warnings +- Temporal rate limit (QPS exceeded) errors now return as "progressing" instead of failing immediately +- We've renamed AI Agent Fleets to Okteto AI throughout the product +- [Okteto CLI 3.12.0](https://github.com/okteto/okteto/releases/tag/3.12.0): Updated Syncthing to 2.0.x for improved synchronization performance +- [Okteto CLI 3.12.0](https://github.com/okteto/okteto/releases/tag/3.12.0): Added support for `endpoint_mode` in Compose files ([see documentation](reference/docker-compose.mdx#endpoint_mode-string-optional)). + +### Bug Fixes {#bug-fixes-1.37} + +- Fixed issues with endpoint handling in the Okteto AI Agent view, including non-scrollable lists and incorrect display of custom endpoints +- Fixed an "unable to load agent" error when returning focus to the window +- Fixed autoscroll behavior when sending a new prompt in the Agent UI +- [Okteto CLI 3.12.0](https://github.com/okteto/okteto/pull/4760): Improved CLI stability by waiting for SSE when streaming logs for pipeline, preview, deploy, and destroy operations diff --git a/versioned_docs/version-1.37/self-hosted/aks/config.yaml b/versioned_docs/version-1.49/self-hosted/aks/config.yaml similarity index 100% rename from versioned_docs/version-1.37/self-hosted/aks/config.yaml rename to versioned_docs/version-1.49/self-hosted/aks/config.yaml diff --git a/versioned_docs/version-1.37/self-hosted/civo/config.yaml b/versioned_docs/version-1.49/self-hosted/civo/config.yaml similarity index 100% rename from versioned_docs/version-1.37/self-hosted/civo/config.yaml rename to versioned_docs/version-1.49/self-hosted/civo/config.yaml diff --git a/versioned_docs/version-1.37/self-hosted/digitalocean/config.yaml b/versioned_docs/version-1.49/self-hosted/digitalocean/config.yaml similarity index 100% rename from versioned_docs/version-1.37/self-hosted/digitalocean/config.yaml rename to versioned_docs/version-1.49/self-hosted/digitalocean/config.yaml diff --git a/versioned_docs/version-1.37/self-hosted/digitalocean/marketplace.md b/versioned_docs/version-1.49/self-hosted/digitalocean/marketplace.md similarity index 96% rename from versioned_docs/version-1.37/self-hosted/digitalocean/marketplace.md rename to versioned_docs/version-1.49/self-hosted/digitalocean/marketplace.md index 70d22d46f..94585a3a0 100644 --- a/versioned_docs/version-1.37/self-hosted/digitalocean/marketplace.md +++ b/versioned_docs/version-1.49/self-hosted/digitalocean/marketplace.md @@ -1,5 +1,6 @@ --- title: Getting started after deploying Okteto on DigitalOcean +description: "Configure your Okteto instance after deploying from the DigitalOcean Marketplace. Set up DNS, authentication, and connect your Kubernetes cluster." --- import Image from '@theme/Image'; @@ -10,13 +11,13 @@ After you have downloaded your `kubeconfig` file and can successfully connect to The first step is to get your admin token. Run the following command in a terminal shell to retrieve it: -```console +```bash kubectl get sa -n=okteto do-okteto -ojsonpath='{.metadata.labels.dev\.okteto\.com/token}' ``` Second, start a port-forward to the ingress service by running the command below: -```console +```bash kubectl port-forward service/do-ingress-nginx-controller 8443:443 --namespace okteto ``` @@ -41,7 +42,7 @@ Your Okteto instance is now fully configured. It will be available via https://o Run the following command in a terminal shell to get the External IP address of the Load Balancer. -```console +```bash kubectl get svc -n=okteto -l="app=nginx-ingress,component=controller" ``` diff --git a/versioned_docs/version-1.37/self-hosted/eks/config.yaml b/versioned_docs/version-1.49/self-hosted/eks/config.yaml similarity index 100% rename from versioned_docs/version-1.37/self-hosted/eks/config.yaml rename to versioned_docs/version-1.49/self-hosted/eks/config.yaml diff --git a/versioned_docs/version-1.37/self-hosted/gke/config.yaml b/versioned_docs/version-1.49/self-hosted/gke/config.yaml similarity index 100% rename from versioned_docs/version-1.37/self-hosted/gke/config.yaml rename to versioned_docs/version-1.49/self-hosted/gke/config.yaml diff --git a/versioned_docs/version-1.37/self-hosted/helm-configuration.mdx b/versioned_docs/version-1.49/self-hosted/helm-configuration.mdx similarity index 76% rename from versioned_docs/version-1.37/self-hosted/helm-configuration.mdx rename to versioned_docs/version-1.49/self-hosted/helm-configuration.mdx index 57c279a49..6bb8ec4ba 100644 --- a/versioned_docs/version-1.37/self-hosted/helm-configuration.mdx +++ b/versioned_docs/version-1.49/self-hosted/helm-configuration.mdx @@ -34,7 +34,7 @@ subdomain: "example.com" Okteto's frontend and API services will be also accessible via https://okteto.$SUBDOMAIN. Once Okteto is installed, you can use `kubectl` to retrieve the public address of the Okteto NGINX Ingress Controller: -```console +```bash kubectl get service -l=app.kubernetes.io/name=ingress-nginx,app.kubernetes.io/component=controller --namespace=okteto ``` @@ -57,7 +57,7 @@ Use this property to override the Public URL where Okteto is available. This opt publicOverride: "example.com" ``` -Once you set this in your Helm configuration file, make sure to point the Okteto Ingress Controller's IP address to this domain using your DNS provider. The IP address can be found by running the following command (like we did during the [install phase](https://www.okteto.com/docs/get-started/install/amazon-eks/#retrieve-the-ingress-controller-ip-address)): +Once you set this in your Helm configuration file, make sure to point the Okteto Ingress Controller's IP address to this domain using your DNS provider. The IP address can be found by running the following command (like we did during the [install phase](get-started/install/amazon-eks.mdx#retrieve-the-ingress-controller-ip-address)): ```bash kubectl get service -l=app.kubernetes.io/name=ingress-nginx,app.kubernetes.io/component=controller --namespace=okteto @@ -144,7 +144,7 @@ api: The cluster autoscaler service. Disabled by default. It instructs the Kubernetes cluster autoscaler to scale nodes if the real cpu/memory usage of a node is beyond the limits. -Use `tolerations.devPool` to limit the autoscaler analysis to a subset of cluster nodes. +Use [`globals.nodeSelectors.dev`](self-hosted/helm-configuration.mdx#nodeselectors) to limit the autoscaler analysis to a subset of cluster nodes. The deprecated `tolerations.devPool` is still honored and takes precedence over it when set. > **Requirements**: cluster autoscaler and metrics server must be installed in your cluster. @@ -200,10 +200,20 @@ The build service. It's used in combination with `okteto build` to build contain - `annotations`: Annotations to add to the buildkit pods. - `extraEnv`: Environment variables to be set on the buildkit containers. - `hpa.enabled`: Enable horizontal pod autoscaling for the buildkit pods. Disabled by default. -- `hpa.min`: Minimum number of buildkit pods to keep running. -- `hpa.max`: Maximum number of buildkit pods to scale to. -- `hpa.cpu`: The amount of CPU utilization that will cause the HPA to scale the buildkit pods. -- `hpa.metrics`: The [target metrics](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/#autoscaling-on-multiple-metrics-and-custom-metrics) that will cause the HPA to scale the buildkit pods. +- `hpa.min`: Minimum number of buildkit pods to keep running. Defaults to `1`. +- `hpa.max`: Maximum number of buildkit pods to scale to. Defaults to `5`. +- `hpa.metrics`: The [target metrics](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/#autoscaling-on-multiple-metrics-and-custom-metrics) that will cause the HPA to scale the buildkit pods. By default, uses the `okteto_build_active_builds` metric with an average value target of `0.99`. +- `hpa.behavior`: The [scaling behavior](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/#configurable-scaling-behavior) configuration that controls how the HPA scales buildkit pods up and down. By default, scales up quickly (30 second stabilization window) and scales down conservatively (600 second stabilization window). +- `hpa.adapter.enabled`: Controls the creation of the metrics adapter deployment, service, and APIService. Enabled by default when HPA is enabled. The adapter exposes buildkit metrics via the Kubernetes custom metrics API. +- `hpa.adapter.extraEnv`: Environment variables to be set on the adapter containers. +- `hpa.adapter.priorityClassName`: The priority class to be used by the adapter pods. The PriorityClass must already exist in your cluster before using this setting. This value has precedence over `globals.priorityClassName` if both are set. If this value is not set, the pods will inherit the priority class defined by the value set in `globals.priorityClassName`. +- `hpa.adapter.replicaCount`: The number of adapter pods. Defaults to `2`. +- `hpa.adapter.resources`: The resources for the adapter pods. Defaults to 100m CPU and 128Mi memory requests. +- `hpa.adapter.apiService.name`: The name of the APIService. Defaults to `v1beta2.custom.metrics.k8s.io`. +- `hpa.adapter.apiService.group`: The API group. Defaults to `custom.metrics.k8s.io`. +- `hpa.adapter.apiService.version`: The API version. Defaults to `v1beta2`. +- `hpa.adapter.apiService.groupPriorityMinimum`: The priority of the API group. Defaults to `100`. +- `hpa.adapter.apiService.versionPriority`: The priority of the API version. Defaults to `100`. - `labels`: Labels to add to the buildkit pods. - `podManagementPolicy`: The [podManagementPolicy](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#pod-management-policies) of the buildkit pods. Defaults to `Parallel`. - `priorityClassName`: The priority class to be used by buildkit pods. The PriorityClass must already exist in your cluster before using this setting. This value has precedence over `globals.priorityClassName` if both are set. If this value is not set, the pods will inherit the priority class defined by the value set in `globals.priorityClassName`. @@ -217,10 +227,18 @@ The build service. It's used in combination with `okteto build` to build contain - `persistence.enabled`: Configures a persistence volume for buildkit. Enabled by default. - `persistence.class`: The storage class of the persistence volume attached to every buildkit pod. - `persistence.size`: The size of the persistence volume attached to every buildkit pod. Defaults to `750Gi`. -- `persistence.cacheRatio`: What percentage the persistence size should be use for the cache. Value should be between 0 and 1. Defaults to `0.5`. +- `persistence.cacheRatio`: What percentage the persistence size should be used for the cache. Value should be between 0 and 1. Defaults to `0.5`. +- `terminationGracePeriodSeconds`: Duration in seconds for graceful pod termination. Defaults to `600` (10 minutes). This allows ongoing builds to complete before the pod is terminated. +- `readinessProbe.periodSeconds`: How often, in seconds, the readiness probe runs `buildctl debug workers` against the local BuildKit socket. Defaults to `15`. +- `readinessProbe.timeoutSeconds`: Seconds before a readiness check is considered failed. Defaults to `10`. Keep it above `5`, the time `buildctl` waits for the daemon before giving up. +- `readinessProbe.failureThreshold`: Consecutive failed checks before the pod is marked not ready. Defaults to `3`. +- `readinessProbe.successThreshold`: Consecutive successful checks before the pod is marked ready. Defaults to `1`. - `tolerations`: List of tolerations to be added to the Buildkit pods. If not set, the Buildkit pods will inherit the tolerations list set in [`globals.tolerations.okteto`](self-hosted/helm-configuration.mdx#tolerations). - `nodeSelectors`: Dictionary of node selectors to be added to the Buildkit pods. If not set, the Buildkit pods will inherit the node selectors dictionary set in [`globals.nodeSelectors.okteto`](self-hosted/helm-configuration.mdx#nodeselectors). -- `network.mode`: Controls the networking environment for containers during the build process. Defaults to `auto` but can be set to `host`, `none`, or `bridge`. Bridge mode can be useful for preventing port collisions in concurrent builds by isolating network environments. +- `network.mode`: Controls the networking environment for containers during the build process. Defaults to `auto` but can be set to `host`, `none`, or `bridge`. Bridge mode can be useful for preventing port collisions in concurrent builds by isolating network environments. Bridge mode is not compatible with [rootless mode](#rootless). +- `rootless.enabled`: Runs BuildKit in [rootless mode](#rootless), without a privileged container. Defaults to `false`. +- `rootless.image.repository`: Image repository used when rootless mode is enabled. Defaults to `okteto/buildkit`, pulled from the registry defined in `globals.registry`. +- `rootless.image.tag`: Image tag used when rootless mode is enabled. Defaults to the `-rootless` tag that matches your chart version, for example {variables.chartVersion}-rootless. ```yaml buildkit: @@ -242,6 +260,38 @@ buildkit: nodeSelectors: okteto-node-label: build region: west + terminationGracePeriodSeconds: 600 + hpa: + enabled: true + min: 1 + max: 5 + metrics: + - type: Pods + pods: + metric: + name: okteto_build_active_builds + target: + type: AverageValue + averageValue: "0.99" + behavior: + scaleUp: + policies: + - type: Pods + value: 1 + periodSeconds: 30 + scaleDown: + stabilizationWindowSeconds: 600 + policies: + - type: Pods + value: 1 + periodSeconds: 150 + adapter: + enabled: true + replicaCount: 2 + resources: + requests: + cpu: 100m + memory: 128Mi ``` In order to handle timeouts during communication between the client and the buildkit daemon, the following environment variables can be modified on the server side: @@ -266,6 +316,33 @@ If you're trying to configure Buildkit persistency for your Okteto installation, allowfullscreen > +#### rootless + +By default, the BuildKit pods run as a privileged container so that `buildkitd` can create the namespaces and mounts that build steps need. Rootless mode runs `buildkitd` as a non-root user instead, using the `okteto/buildkit:-rootless` image. A build step that escapes its sandbox lands in an unprivileged container rather than in a root process on the node, which limits the impact of a malicious or compromised Dockerfile. + +Rootless mode is disabled by default because it depends on kernel features that are not available on every Linux distribution. The nodes that run BuildKit must allow unprivileged user namespaces (`user.max_user_namespaces` greater than zero), and the `overlayfs` snapshotter requires kernel 5.11 or later (older kernels fall back to `fuse-overlayfs`). Some distributions need extra node configuration. For example, Ubuntu 24.04 and later require `kernel.apparmor_restrict_unprivileged_userns=0`, and Bottlerocket requires `user.max_user_namespaces` to be set through its kernel settings. Check the [BuildKit rootless documentation](https://github.com/moby/buildkit/blob/master/docs/rootless.md) for the requirements of your distribution, and test rootless mode in a non-production cluster before enabling it. + +When `rootless.enabled` is `true`, the chart makes these changes to the BuildKit StatefulSet: + +- Pulls the image defined in `rootless.image` instead of the default BuildKit image. +- Runs the `buildkitd` container and its init container with `runAsNonRoot: true` and `fsGroup: 1000`, and removes the `privileged` flag. +- Sets the seccomp and AppArmor profiles to `Unconfined`, because `buildkitd` still needs the `mount` and `unshare` syscalls. On Kubernetes 1.29 and earlier, the AppArmor profile is set through the `container.apparmor.security.beta.kubernetes.io/buildkitd` pod annotation. +- Starts `buildkitd` with the `--oci-worker-no-process-sandbox` flag, as in the upstream Kubernetes examples. +- Mounts the build cache volume at `/home/user/.local/share/buildkit`. + +Rootless mode has two limitations: + +- `network.mode: bridge` is not supported. The Helm install fails if both settings are combined. +- The BuildKit StatefulSet name includes the rootless setting, so enabling or disabling it creates a new StatefulSet and a new persistent volume. The build cache starts empty after the change. Kubernetes keeps the persistent volume claim of the previous StatefulSet, so delete it manually once you no longer need it. + +```yaml +buildkit: + rootless: + enabled: true +``` + +If you mirror the Okteto images to a private registry, override `rootless.image` as described in the [air-gapped installation guide](self-hosted/manage/air-gapped.mdx#step-2-set-up-a-private-registry-for-required-images). + ### cli Settings for the Okteto CLI. @@ -286,7 +363,7 @@ cli: :::note Please Note: - Modifying these settings will change the image used globally by all users of the Okteto CLI in the cluster - - The hosted CLI version must match the original version to ensure compatibility with the remote. For example, if your cluster supports `okteto/okteto:3.2.0`, the hosted image should be `myregistry/okteto:3.2.0` + - The hosted CLI version must match the original version to ensure compatibility with the remote. For example, if your cluster supports `ghcr.io/okteto/okteto:3.2.0`, the hosted image should be `myregistry/okteto:3.2.0` - This configuration is separate from the initContainer setting in the okteto.yaml manifest. While the CLI settings apply globally to all users and operations, the initContainer setting is specific to a Development Environment or application and can be customized for pre-startup tasks ::: @@ -299,6 +376,7 @@ The daemonset automatically configures every node of your cluster to work better - `extraEnv`: Environment variables to be set on the daemonset containers. - `labels`: Labels to add to the daemonset pods. - `configurePrivateRegistriesInNodes.enabled`: Specifies if the daemonset should configure the private registry credentials in the nodes for kubelet or not. It defaults to `false`. It's disabled if `regcredsManager.pullSecrets.enabled=true`. +- `injectCA.enabled`: Controls whether the daemonset installs the CA into each node's trust store, so the kubelet can pull images from the Okteto Registry when you use a private CA or a self-signed certificate. It defaults to `true`. Set it to `false` only if you add the CA to your nodes' trust store through your own mechanism; otherwise, image pulls from the Okteto Registry fail with a certificate verification error. Disabling it only affects the daemonset: the other daemonset tasks still run, and the Okteto components keep mounting the CA. This setting has no effect when neither `wildcardCertificate.privateCA.enabled` nor `wildcardCertificate.create` is set. - `priorityClassName`: The priority class to be used by the daemonset pods. The PriorityClass must already exist in your cluster before using this setting. This value has precedence over `globals.priorityClassName` if both are set. If this value is not set, the pods will inherit the priority class defined by the value set in `globals.priorityClassName`. The daemonset performs the following tasks on each node: @@ -306,14 +384,22 @@ The daemonset performs the following tasks on each node: - [Overrides](self-hosted/helm-configuration.mdx#overrideregistryresolution) the Okteto Registry hostname resolution to use internal IPs. - [Overrides](self-hosted/helm-configuration.mdx#overridefilewatchers) the default kernel values for file watchers on every node. - Configures the kubelet with registry credentials for [private registries](self-hosted/helm-configuration.mdx#daemonset) (if `configurePrivateRegistriesInNodes.enabled=true` and `regcredsManager.pullSecrets.enabled=false`). -- Installs your CA if `wildcardCertificate.privateCA` is enabled. -- Installs a CA if using self-signed certificates (`wildcardCertificate.create: true`). +- Installs your private CA into each node's trust store if provided (`wildcardCertificate.privateCA: true`). Setting `injectCA.enabled: false` disables this task. +- Installs the Okteto-generated CA into each node's trust store when using self-signed certificates (`wildcardCertificate.create: true`). Setting `injectCA.enabled: false` disables this task. You can restrict the nodes where the daemonset is deployed using `dev` [tolerations](self-hosted/helm-configuration.mdx#tolerations) and [nodeSelectors](self-hosted/helm-configuration.mdx#nodeselectors): ```yaml -tolerations: - devPool: dev +globals: + nodeSelectors: + dev: + okteto-node-pool: dev + tolerations: + dev: + - key: okteto-node-pool + operator: Equal + value: dev + effect: NoSchedule ``` ### defaultBackend @@ -342,13 +428,8 @@ defaultBackend: The defaultBackend provides the following features: -- Autowake namespaces: when a user access an endpoint from an slept namespace, the defaultBackend will issue a wake command. -- Custom error pages: when a user access an endpoint and an error is produced, the defaultBackend will return a custom error page with hints on how to solve it. - -```yaml -tolerations: - devPool: dev -``` +- **Autowake namespaces**: When a user accesses an endpoint from a sleeping namespace, the defaultBackend will issue a wake command. +- **Custom error pages**: When users access endpoints that encounter errors, the defaultBackend serves custom error pages with contextual hints on how to resolve the issue. This provides a better user experience by offering clear explanations and actionable steps instead of generic error messages. Common scenarios include accessing sleeping namespaces, or service unavailability. These error pages work automatically and require no additional configuration. ### frontend @@ -473,41 +554,76 @@ The jobs that deploy your [development environments from Git](development/deploy - `securityContext`: The security context for the installer job container. It's not set by default, and it follows the [same syntax used in Kubernetes](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) - `extraInitContainers`: List of init containers to add to the installer job pods. - - {`installer: - runner: - repository: okteto/pipeline-runner - tag: ${variables.chartVersion} - extraEnv: - - name: NO_PROXY - value: ".example.com" - activeDeadlineSeconds: 1800 - gitSSHUser: git - sshSecretName: "okteto-ssh" - securityContext: - allowPrivilegeEscalation: false - resources: - requests: - cpu: 10m - memory: 50Mi`} + +{`installer: + runner: + repository: okteto/pipeline-runner + tag: ${variables.chartVersion} + extraEnv: + - name: NO_PROXY + value: ".example.com" + activeDeadlineSeconds: 1800 + gitSSHUser: git + sshSecretName: "okteto-ssh" + securityContext: + allowPrivilegeEscalation: false + resources: + requests: + cpu: 10m + memory: 50Mi +`} -### oktetoAI +### installerChecker -The Okteto AI section configures the [Okteto AI](okteto-ai/index.mdx) feature in your cluster: +The CronJob that reconciles Development Environment deploys and destroys stuck in a running state. -- `enabled`: Whether to enable Okteto AI in your cluster. Defaults to `true`. -- `image.repository`: The repository path for the Okteto AI image. Defaults to `okteto/agent`. -- `image.tag`: The image tag to deploy. Defaults to {variables.chartVersion}. -- `resources`: The resources for the Okteto AI Agent pods. +- `enabled`: Whether to run the installer checker. Defaults to `true`. +- `schedule`: The cron schedule for the checker. Defaults to `*/5 * * * *` (every 5 minutes). +- `priorityClassName`: The priority class for the installer checker pods. The PriorityClass must already exist in your cluster before using this setting. This value has precedence over `globals.priorityClassName` if both are set. If this value is not set, the pods will inherit the priority class defined by the value set in `globals.priorityClassName`. ```yaml -oktetoAI: +installerChecker: enabled: true + schedule: "*/5 * * * *" +``` + +### migration + +The Helm hook Job that applies the data and resource migrations required by the Okteto version you are installing. It runs automatically on every install and upgrade. + +:::note +This job is required for Okteto to work correctly and must not be disabled. +::: + +- `annotations`: Annotations to add to the migration job pods. +- `labels`: Labels to add to the migration job pods. +- `resources`: The resources for the migration job pods. +- `priorityClassName`: The priority class for the migration job pods. The PriorityClass must already exist in your cluster before using this setting. This value has precedence over `globals.priorityClassName` if both are set. If this value is not set, the pods will inherit the priority class defined by the value set in `globals.priorityClassName`. + +```yaml +migration: resources: requests: - cpu: 50m - memory: 400Mi + cpu: 10m + memory: 100Mi +``` + +### namespaceDestroyAll + +The Job that destroys every resource in a Namespace, plus the CronJob that recovers Namespaces whose destroy-all Job did not finish. + +- `priorityClassName`: The priority class for the per-Namespace destroy-all job pods. The PriorityClass must already exist in your cluster before using this setting. This value has precedence over `globals.priorityClassName` if both are set. If this value is not set, the pods will inherit the priority class defined by the value set in `globals.priorityClassName`. +- `checker`: Configures the CronJob that recovers stuck Namespaces. + - `schedule`: The cron schedule for the checker. Defaults to `*/3 * * * *` (every 3 minutes). + - `timeoutInSeconds`: Maximum duration of each checker run in seconds. Defaults to `120`. + - `priorityClassName`: The priority class for the checker pods, following the same precedence rules as above. + +```yaml +namespaceDestroyAll: + checker: + schedule: "*/3 * * * *" + timeoutInSeconds: 120 ``` ### privateEndpoints @@ -544,10 +660,9 @@ prepullImages: The following images are prepulled on every node: -- **okteto/backend:{variables.chartVersion}** -- **okteto/pipeline-runner:{variables.chartVersion}** -- **okteto/okteto:{variables.cliVersion}** -- **okteto/agent:{variables.chartVersion}** +- **ghcr.io/okteto/backend:{variables.chartVersion}** +- **ghcr.io/okteto/pipeline-runner:{variables.chartVersion}** +- **ghcr.io/okteto/okteto:{variables.cliVersion}** ### regcredsManager @@ -558,7 +673,6 @@ If `pullSecrets.enabled=false` these credentials are copied to all nodes through - `priorityClassName`: The priority class to be used by the controller manager pods. The PriorityClass must already exist in your cluster before using this setting. This value has precedence over `globals.priorityClassName` if both are set. If this value is not set, the pods will inherit the priority class defined by the value set in `globals.priorityClassName`. - `pullSecrets.enabled`: If enabled, private registry credentials defined in the cluster will be written to user namespaces as pull secrets and no longer be written to the nodes. Defaults to true. -- `internalCertificate.annotations`: Annotations to add to the tls secret used in the controller manager webhook server. - `podAnnotations`: Annotations to add to the controller manager pods. - `podLabels`: Labels to add to the controller manager pods. - `webhookTimeout`: The timeout in seconds for request made to the validating webhook server @@ -571,8 +685,6 @@ regcredsManager: priorityClassName: pullSecrets: enabled: false - internalCertificate: - annotations: {} podLabels: {} podAnnotations: {} webhookTimeout: 30 @@ -714,10 +826,32 @@ The webhook service. Ingress creation, generation of hostnames, enforcement of p - `priorityClassName`: The priority class to be used by the webhook pods. The PriorityClass must already exist in your cluster before using this setting. This value has precedence over `globals.priorityClassName` if both are set. If this value is not set, the pods will inherit the priority class defined by the value set in `globals.priorityClassName`. - `replicaCount`: The number of webhook pods. It defaults to 2. - `resources`: The resources for the webhook pods. -- `internalCertificate.annotations`: Annotations to add to the internal certificate generated for the webhook. ## Advanced Configuration +### addSafeToEvictAnnotation + +Controls the [`cluster-autoscaler.kubernetes.io/safe-to-evict`](https://kubernetes.io/docs/reference/labels-annotations-taints/#cluster-autoscaler-kubernetes-io-safe-to-evict) annotation that Okteto adds to the pods it creates in development Namespaces. + +- `enabled`: Whether Okteto adds the annotation. Enabled by default. If a pod already carries the annotation, Okteto keeps the existing value. +- `value`: The value Okteto sets for the annotation, `true` or `false`. Defaults to `false`. + +```yaml +addSafeToEvictAnnotation: + enabled: true + value: false +``` + +The annotation controls whether the Kubernetes cluster autoscaler may evict a pod when it scales down the node running it: + +- `enabled: true`, `value: false` (default): marks Okteto pods as not safe to evict. The autoscaler will not scale down a node that runs one of these pods, regardless of the pod's shape. This keeps active development sessions stable, at the cost of slower node scale-down and potentially higher infrastructure cost. We recommend keeping this default. Development clusters already scale down aggressively outside working hours and over the weekend, so the stability of active development sessions matters more than aggressive scale-down during the working day. +- `enabled: true`, `value: true`: marks Okteto pods as safe to evict, even when the autoscaler would otherwise protect them (for example, pods with local storage). This favors aggressive scale-down and cost savings, at the cost of development sessions restarting during scale-down. +- `enabled: false`: Okteto does not add the annotation. Pods that already carry it keep their value; for the rest, the autoscaler falls back to its own default heuristics. This does not reliably prevent eviction — for many pod shapes it behaves like `value: true` — so it is not equivalent to `value: false`. Use it when you want the cluster to decide. + +:::note +Before Okteto Chart 1.49, this annotation defaulted to `value: true`. To keep that behavior after upgrading, set `addSafeToEvictAnnotation.value` to `true`. +::: + ### affinity Apply default affinities to pods deployed in namespaces created by Okteto. @@ -756,9 +890,26 @@ autowake: enabled: true ``` +### buildOpts + +Sets the default [compression](https://docs.docker.com/build/exporters/#compression) for the image layers built by the [Okteto Build Service](core/build-service.mdx). Leave a value empty to use the BuildKit default. + +- `compression`: The compression algorithm: `uncompressed`, `gzip`, `estargz`, or `zstd`. +- `forceCompression`: Whether to recompress existing layers that use a different algorithm, including base image layers: `"true"` or `"false"`. +- `compressionLevel`: The compression level: `0`-`9` for `gzip` and `estargz`, `0`-`22` for `zstd`. + +```yaml +buildOpts: + compression: zstd + forceCompression: "true" + compressionLevel: "3" +``` + +Users and Admins can override these defaults with [Okteto Variables](core/okteto-variables.mdx) and [Admin Variables](admin/dashboard.mdx#admin-variables). + ### convertLoadBalancedServices -Converts services with type LoadBalancer into ClusterIP and automatically creates an ingress. Enabled by default. +Converts services with type `LoadBalancer` or `NodePort` into `ClusterIP` and automatically creates an ingress. Services with type `ExternalName` are not affected. Enabled by default. ```yaml convertLoadBalancedServices: @@ -826,7 +977,7 @@ globals: Specifies the node selectors to be applied to pods, categorized under `okteto` or `dev`: - `okteto`: Node selectors applied to pods running in the `okteto` namespace, excluding the [Okteto Daemonset](#daemonset). -- `dev`: Node selectors applied to pods created by user applications, which run in namespaces managed by Okteto. These node selectors are only applied when a corresponding `tolerations.devPool` is defined. It also applies to the [Okteto Daemonset](#daemonset). This is a legacy behavior and may change in future releases. +- `dev`: Node selectors applied to pods created by user applications, which run in namespaces managed by Okteto. It also applies to the [Okteto Daemonset](#daemonset). ```yaml globals: @@ -839,7 +990,9 @@ globals: ``` :::note -Node selectors defined in `globals.nodeSelectors.dev` will not be applied to user workloads unless a `tolerations.devPool` value is also set. This coupling is due to a legacy implementation and may be revised in future updates. +If the nodes you select are tainted, you must also define a matching toleration in [`globals.tolerations.dev`](#tolerations). A node selector on its own will place user workloads on nodes they cannot tolerate, and they will stay `Pending`. + +These node selectors do not apply to the ingress controllers or Reloader. See [Node selectors and tolerations](#node-selectors-and-tolerations). ::: #### priorityClassName @@ -861,13 +1014,12 @@ globals: registry: my-custom-registry:5000 ``` - #### tolerations Specifies the tolerations to be applied to pods, categorized under `okteto` or `dev`: - `okteto`: Tolerations applied to pods running in the `okteto` namespace, excluding the [Okteto Daemonset](#daemonset). -- `dev`: Tolerations applied to pods created by user applications, which run in namespaces managed by Okteto. Required for `globals.nodeSelectors.dev` to take effect. This also applies to the [Okteto Daemonset](#daemonset). +- `dev`: Tolerations applied to pods created by user applications, which run in namespaces managed by Okteto. This also applies to the [Okteto Daemonset](#daemonset). ```yaml globals: @@ -884,8 +1036,14 @@ globals: effect: "NoSchedule" ``` +:::warning +The older `tolerations.oktetoPool`, `tolerations.buildPool` and `tolerations.devPool` values are deprecated and will be removed in Okteto Chart 2.0. Installing the chart while they are set prints a deprecation warning. Use `globals.tolerations` and [`globals.nodeSelectors`](#nodeselectors) instead, together with [`buildkit.tolerations` and `buildkit.nodeSelectors`](#buildkit) for BuildKit. See the [migration guide](https://community.okteto.com/t/important-update-migrating-to-new-implementation-of-okteto-pod-tolerations-and-node-selectors/1281) for the full mapping. +::: + :::note -To apply node selectors for user workloads, you must define a `devPool` entry in `globals.tolerations`. See the [nodeSelectors](#nodeselectors) section for more details. +If the nodes selected by [`globals.nodeSelectors.dev`](#nodeselectors) are tainted, define a matching toleration under `dev` above so that user workloads can schedule onto them. + +These tolerations do not apply to the ingress controllers or Reloader. See [Node selectors and tolerations](#node-selectors-and-tolerations). ::: ### ingress @@ -936,6 +1094,20 @@ injectDevelopmentBinaries: enabled: true ``` +### internalCertificate + +Configure the internal certificate created for internal communication. +This certificate is used by `MutatingWebhookConfiguration` and `ValidatingWebhookConfiguration` Kubernetes objects created by Okteto. + +- `durationDays`: Expiration time (default: 10 years) +- `annotations`: Annotations to add to the `kubernetes.io/tls` secret storing the certificate + +```yaml +internalCertificate: + durationDays: 3650 + annotations: {} +``` + ### kubetoken - `lifetimeSeconds`: The lifetime in seconds of the tokens generated for the [Kubernetes credentials](core/credentials/kubernetes-credentials.mdx) provided by Okteto. This value has to be equal or greater than [`installer.activeDeadlineSeconds`](self-hosted/helm-configuration.mdx#installer) to make sure the tokens are valid during all installer execution. Defaults to 86400 seconds (1 day). @@ -1324,6 +1496,10 @@ wildcardCertificate: key: "ca.crt" ``` +:::note +Setting `create: false` is not enough on its own to serve your own certificate. The [ingress-nginx](self-hosted/helm-configuration.mdx#ingress-nginx) ingress controller reads its default certificate from `ingress-nginx.controller.extraArgs.default-ssl-certificate`, which is not derived from `wildcardCertificate.name`. Whenever you set `create: false`, point that argument at the same secret, as shown in [bring your own certificate](self-hosted/install/certificates/bring-your-own-certificate.mdx). Otherwise that secret no longer exists, the ingress controller falls back to its own built-in fake certificate, and browsers show a certificate warning. +::: + ## Dependencies Okteto will automatically install two instances of [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/) as part of the default installation, using its official [Helm chart](https://kubernetes.github.io/ingress-nginx). @@ -1359,6 +1535,64 @@ ingress-nginx: The full list of values is [available here](https://github.com/kubernetes/ingress-nginx/blob/main/charts/ingress-nginx/values.yaml). +#### Node selectors and tolerations + +[`globals.nodeSelectors`](#nodeselectors) and [`globals.tolerations`](#tolerations) apply to Okteto's own components. They do **not** reach the two ingress controllers or [Reloader](#reloader), which are separate charts and read their own values instead. + +If you run Okteto on dedicated node pools, or on any node pool that carries a taint, configure all of them: + +```yaml +globals: + nodeSelectors: + okteto: + okteto-node-pool: okteto + tolerations: + okteto: + - key: okteto-node-pool + operator: Equal + value: okteto + effect: NoSchedule + +ingress-nginx: + controller: + nodeSelector: + okteto-node-pool: okteto + tolerations: + - key: okteto-node-pool + operator: Equal + value: okteto + effect: NoSchedule + +okteto-nginx: + controller: + nodeSelector: + okteto-node-pool: okteto + tolerations: + - key: okteto-node-pool + operator: Equal + value: okteto + effect: NoSchedule + +reloader: + reloader: + deployment: + nodeSelector: + okteto-node-pool: okteto + tolerations: + - key: okteto-node-pool + operator: Equal + value: okteto + effect: NoSchedule +``` + +:::warning +Leaving these out fails silently. The chart installs successfully, and the ingress controllers and Reloader schedule onto whichever nodes accept them, which on a cluster with dedicated pools is usually the untainted default pool. If every pool in the cluster is tainted, they stay `Pending` instead. +::: + +These charts also accept `affinity`, `topologySpreadConstraints` and `priorityClassName` under the same keys. They are maintained upstream, so check their own value references for the authoritative list: [ingress-nginx](https://github.com/kubernetes/ingress-nginx/blob/main/charts/ingress-nginx/values.yaml), used by both the `ingress-nginx` and `okteto-nginx` keys, and [Reloader](https://github.com/stakater/Reloader#parameters). + +For a worked example on ARM node pools, which GKE taints by default, see [ARM Support](self-hosted/manage/arm-support.mdx). + #### ingress-nginx & okteto-nginx default values Okteto sets specific values on the embedded ingress-nginx chart to enable features dependent on the ingress-controller. The values can be checked with the following command: @@ -1382,6 +1616,8 @@ Refer to this [community guide](https://community.okteto.com/t/how-do-i-configur The Okteto chart uses [Reloader](https://github.com/stakater/Reloader) to perform rolling upgrades to Okteto components when changes happen on specific secrets. Reloader can be customized using the `reloader.reloader` value using [these parameters](https://github.com/stakater/Reloader#parameters). +Reloader does not inherit [`globals.nodeSelectors`](#nodeselectors) or [`globals.tolerations`](#tolerations). If you run Okteto on dedicated or tainted node pools, set its own scheduling values as shown in [Node selectors and tolerations](#node-selectors-and-tolerations). + ## Store Sensitive Configuration Values using a Secret Create a secret named `okteto-cloud-secret` to store the following values instead of setting them in your helm configuration file: diff --git a/versioned_docs/version-1.37/self-hosted/index.mdx b/versioned_docs/version-1.49/self-hosted/index.mdx similarity index 84% rename from versioned_docs/version-1.37/self-hosted/index.mdx rename to versioned_docs/version-1.49/self-hosted/index.mdx index ebbbdd8ea..a64c4d9b9 100644 --- a/versioned_docs/version-1.37/self-hosted/index.mdx +++ b/versioned_docs/version-1.49/self-hosted/index.mdx @@ -33,9 +33,14 @@ If you haven't installed Okteto yet, these cloud-specific guides will walk you t ### The sub-pages in this section will help you to configure and manage your Okteto installation -- [**Complete the installation**](self-hosted/install/certificates/index.mdx) - Includes guides for deploying Okteto through ArgoCD, setting up your own certificates, GitHub integration, and more +- [**Complete the installation**](self-hosted/install/certificates/index.mdx) - Includes guides for deploying Okteto through ArgoCD, setting up your own certificates, GitHub integration, Divert configuration, and more - [**Helm Configuration**](self-hosted/helm-configuration.mdx) - Configuration of your Okteto Helm chart including authentication, garbage collection, and much more - [**Manage Okteto**](self-hosted/manage/upgrade.mdx) - Details on how to maintain your Okteto installation long term +- [**ARM Support**](self-hosted/manage/arm-support.mdx) - Install Okteto on ARM-based clusters (GCP Tau T2A GA, AWS Graviton Beta) + +### Feature Configuration + +- [**Configure Divert**](self-hosted/install/divert/index.mdx) - Set up traffic routing for lightweight development environments with nginx or istio drivers ## Troubleshooting diff --git a/versioned_docs/version-1.37/self-hosted/install/auth/azure-ad.mdx b/versioned_docs/version-1.49/self-hosted/install/auth/azure-ad.mdx similarity index 89% rename from versioned_docs/version-1.37/self-hosted/install/auth/azure-ad.mdx rename to versioned_docs/version-1.49/self-hosted/install/auth/azure-ad.mdx index 25875eef1..0a74951c6 100644 --- a/versioned_docs/version-1.37/self-hosted/install/auth/azure-ad.mdx +++ b/versioned_docs/version-1.49/self-hosted/install/auth/azure-ad.mdx @@ -15,7 +15,7 @@ Please refer to [Azure's official documentation](https://learn.microsoft.com/en- - A working installation of [Okteto](get-started/install/index.mdx) - [Helm](https://helm.sh/docs/intro/install/) 3.0+ installed in your local machine -- Access to an [Azure account](https://portal.azure.com) with permissions to registrate applications in Azure Active Directory +- Access to an [Azure account](https://portal.azure.com) with permissions to register applications in Azure Active Directory ## Create an App Registration @@ -61,7 +61,7 @@ On the left menu, click on "Certificates & secrets". Create a "New client secret />

-On the lest menu, click on "API permissions" and grant the following permissions: +On the left menu, click on "API permissions" and grant the following permissions:

You can also use a [secret](self-hosted/helm-configuration.mdx#store-sensitive-configuration-values-using-a-secret) to store the sensitive part of these credentials. @@ -75,3 +76,17 @@ The `group` field is optional. Only members of the group will be allowed to log The `issuer` and `authorization` endpoints must match the value returned in the provider config discovery. The `mapping` fields are optional. Use them to configure the mapping between Okteto's user attributes and the claim coming from your authentication provider. + +## User identity binding + +Okteto binds each user to a single account in your identity provider. The binding is the provider's issuer together with the claim mapped to `subjectKey`. It defaults to `sub`, which the OpenID Connect standard defines as the only claim guaranteed to be stable and unique for a user. If you point `subjectKey` at any other claim, that guarantee no longer applies, so you are responsible for choosing one whose value your provider keeps stable and unique for every user. If a second provider account resolves to the same Okteto user, Okteto refuses the login with a clear message instead of signing in as the existing user. + +:::warning +Okteto uses the claim mapped to `externalIDKey` (`nickname` by default) as the unique identifier for each user. You are responsible for choosing a claim whose value your authentication provider guarantees to be unique for every user. If two users share the same `externalIDKey` value, the latter will fail to log in due to collision. +::: + +### Changing the subject claim + +Change `subjectKey` only when `sub` is not stable for your provider. Microsoft Entra issues a pairwise `sub` that differs per application registration, so set `subjectKey` to `oid`, which stays stable across registrations there. + +**Decide the subject claim before your first rollout.** Each user is bound to the claim value that was present the first time they logged in, so changing `subjectKey` later stops every user from matching their binding and refuses them all at login. If you need to change it after rollout, contact Okteto to plan the migration and re-bind the affected users safely. \ No newline at end of file diff --git a/versioned_docs/version-1.37/self-hosted/install/auth/token.mdx b/versioned_docs/version-1.49/self-hosted/install/auth/token.mdx similarity index 79% rename from versioned_docs/version-1.37/self-hosted/install/auth/token.mdx rename to versioned_docs/version-1.49/self-hosted/install/auth/token.mdx index 38fdc1b33..69cfd07e2 100644 --- a/versioned_docs/version-1.37/self-hosted/install/auth/token.mdx +++ b/versioned_docs/version-1.49/self-hosted/install/auth/token.mdx @@ -17,25 +17,25 @@ Once you've completed the product evaluation, we recommend switching to another To use token-based authentication, remove the [`auth` section of your Okteto Helm configuration](self-hosted/helm-configuration.mdx#auth) file and [upgrade your Okteto instance](self-hosted/manage/upgrade.mdx) for the new configuration to be applied. Then, follow our post-installation notes to learn how to login to the Okteto UI and configure your Okteto CLI with a randomly generated token. -After you log in, you can also invite other users by generating an "Invitation Link" from the **Admin -> Users** page of the Okteto Dashboard. +After you log in, you can also invite other users by generating an "Invite Link" from the **Admin -> Users** page of the Okteto Dashboard. This option allows you to grant access to other users to continue your evaluation.

An invitation link will be generated that can be shared with the intended user via a secure method. Please note that Okteto does not send invite emails automatically. -Once the the user has opened the invitation link, they can copy their Okteto token and see details on how to connect the Okteto CLI. +Once the user has opened the invitation link, they can copy their Okteto token and see details on how to connect the Okteto CLI.

@@ -46,8 +46,8 @@ If for any reason a user has not yet joined your Okteto instance and cannot find

@@ -55,8 +55,8 @@ If for any reason a user has not yet joined your Okteto instance and cannot find ## Retrieve a User's Token -Okteto generates "Invitation Links" in Token Auth mode to allow other users to log in to Okteto. -When a user logs in to Okteto via the Invitation Link, a "Welcome screen" is presented showing the user's token. +Okteto generates "Invite Links" in Token Auth mode to allow other users to log in to Okteto. +When a user logs in to Okteto via the Invite Link, a "Welcome screen" is presented showing the user's token. This token can be used to log in from the Okteto UI or using the Okteto CLI. The "Welcome screen" prompts the user to store this token securely. diff --git a/versioned_docs/version-1.37/self-hosted/install/certificates/aws-acm.mdx b/versioned_docs/version-1.49/self-hosted/install/certificates/aws-acm.mdx similarity index 100% rename from versioned_docs/version-1.37/self-hosted/install/certificates/aws-acm.mdx rename to versioned_docs/version-1.49/self-hosted/install/certificates/aws-acm.mdx diff --git a/versioned_docs/version-1.37/self-hosted/install/certificates/bring-your-own-certificate.mdx b/versioned_docs/version-1.49/self-hosted/install/certificates/bring-your-own-certificate.mdx similarity index 61% rename from versioned_docs/version-1.37/self-hosted/install/certificates/bring-your-own-certificate.mdx rename to versioned_docs/version-1.49/self-hosted/install/certificates/bring-your-own-certificate.mdx index 1255633c2..e8dac5acd 100644 --- a/versioned_docs/version-1.37/self-hosted/install/certificates/bring-your-own-certificate.mdx +++ b/versioned_docs/version-1.49/self-hosted/install/certificates/bring-your-own-certificate.mdx @@ -7,7 +7,7 @@ id: bring-your-own-certificate # Bring your own Wildcard Certificate -For this, you'll need the private and public keys of your certificate. The certificate must be a PEM-encoded X.509 certificate in PKCS1 format, with `*.SUBDOMAIN` as its `Subject Alternative Name`. +For this, you'll need the private and public keys of your certificate. The certificate must be a PEM-encoded X.509 certificate with `*.SUBDOMAIN` as its `Subject Alternative Name`. The private key can be PEM-encoded PKCS#1 (`BEGIN RSA PRIVATE KEY`), SEC1 (`BEGIN EC PRIVATE KEY`), or, starting with Okteto 1.48, PKCS#8 (`BEGIN PRIVATE KEY`). Import the secret into your kubernetes cluster by running the command below: @@ -29,7 +29,7 @@ ingress-nginx: default-ssl-certificate: $(POD_NAMESPACE)/your-ssl-certificate-secret ``` -You can use any certificate provider you are familiar with if it's compatible with the x.509 and PKCS1 standards. +You can use any certificate provider you are familiar with if it issues x.509 certificates. For example, we have a guide maintained by the community to [configure your certificate with GoDaddy](https://community.okteto.com/t/how-do-i-bring-my-godaddy-certificate-to-okteto/578/1). Finally, [upgrade](self-hosted/manage/upgrade.mdx) your Okteto installation for the new configuration to be applied. @@ -69,3 +69,15 @@ ingress-nginx: Finally, [upgrade your Okteto instance](self-hosted/manage/upgrade.mdx) for the new configuration to be applied. We recommend that you upgrade to the same version that you already have to minimize the changes and help you troubleshoot any issues. + +## Injecting the CA into cluster nodes + +When you enable `privateCA`, the [Okteto daemonset](self-hosted/helm-configuration.mdx#daemonset) installs the CA into each node's trust store by default, so the kubelet can pull images from the Okteto Registry. For `containerd` to trust the new CA, the daemonset restarts it once on each node. This restart interrupts any image pulls in progress and can restart the containers already running on that node. + +To avoid this restart, set [`daemonset.injectCA.enabled`](self-hosted/helm-configuration.mdx#daemonset) to `false` so the daemonset no longer touches the nodes' trust store. With injection disabled, you are responsible for adding the CA to every node's trust store yourself. If a node doesn't trust the CA, image pulls from the Okteto Registry fail with a certificate verification error. + +Please refer to your cloud provider's official documentation for guidance on how to perform this task: + +- **Google Kubernetes Engine (GKE)**: [Access private registries with private CA certificates](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/access-private-registries-private-certificates). +- **Azure Kubernetes Service (AKS)**: [Custom certificate authority](https://learn.microsoft.com/en-us/azure/aks/custom-certificate-authority). +- **Amazon Elastic Kubernetes Service (EKS)**: [Use private certificates to enable a container repository in Amazon EKS](https://aws.amazon.com/blogs/containers/use-private-certificates-to-enable-a-container-repository-in-amazon-eks/). diff --git a/versioned_docs/version-1.49/self-hosted/install/certificates/cert-manager.mdx b/versioned_docs/version-1.49/self-hosted/install/certificates/cert-manager.mdx new file mode 100644 index 000000000..d7490e6fb --- /dev/null +++ b/versioned_docs/version-1.49/self-hosted/install/certificates/cert-manager.mdx @@ -0,0 +1,45 @@ +--- +title: Setting up certificates with cert-manager and Let's Encrypt +description: Configure TLS certificates for Okteto Self-Hosted using cert-manager and Let’s Encrypt. +sidebar_label: Let’s Encrypt +id: cert-manager +--- + +# Setting up certificates with cert-manager and Let’s Encrypt + +[cert-manager](https://github.com/cert-manager/cert-manager) automates certificate requests from [Let’s Encrypt](https://letsencrypt.org/), a free and automated Certificate Authority. + +Okteto requires a wildcard certificate, so you must use a [DNS01](https://cert-manager.io/docs/configuration/acme/dns01/#delegated-domains-for-dns01) auth method in your [Issuer](https://cert-manager.io/docs/concepts/issuer/). See the [list of supported DNS01 providers](https://cert-manager.io/docs/configuration/acme/dns01/) for compatible options. + +The Okteto community maintains guides on using cert-manager with different cloud providers: + +- [Amazon Route53](https://community.okteto.com/t/how-do-i-configure-okteto-with-cert-manager-and-aws-route53/273/2) +- [Google Cloud DNS](https://community.okteto.com/t/how-do-i-configure-okteto-with-cert-manager-and-google-cloud-dns/274/2) +- [Azure Cloud DNS](https://community.okteto.com/t/how-do-i-configure-okteto-with-cert-manager-and-azure-cloud-dns/275/2) + +## Configure Okteto to use your certificate + +Create your `Certificate` resource in the namespace where Okteto is installed. Once cert-manager has issued it, the certificate is stored in the secret named by the `Certificate`'s `spec.secretName`. Add the following to your Helm configuration file, replacing `your-ssl-certificate-secret` with that name, to tell Okteto and NGINX to use your certificate: + +```yaml title="config.yaml" +wildcardCertificate: + create: false + name: your-ssl-certificate-secret + +ingress-nginx: + controller: + extraArgs: + default-ssl-certificate: $(POD_NAMESPACE)/your-ssl-certificate-secret +``` + +:::warning +Both settings are required. `wildcardCertificate.create: false` stops Okteto from generating its self-signed certificate, which also removes the secret that `default-ssl-certificate` points at. If you don't update that argument as well, the ingress controller falls back to its own built-in fake certificate. This fails quietly: cert-manager reports your certificate as `Ready`, and the hosts Okteto creates ingresses for still serve it over SNI, but any request that doesn't match one of those hosts shows a certificate warning. +::: + +Finally, [upgrade](self-hosted/manage/upgrade.mdx) your Okteto installation for the new configuration to be applied. + +This video tutorial walks through configuring certificates for Okteto using cert-manager and Let's Encrypt: + +
+ +
diff --git a/versioned_docs/version-1.37/self-hosted/install/certificates/index.mdx b/versioned_docs/version-1.49/self-hosted/install/certificates/index.mdx similarity index 100% rename from versioned_docs/version-1.37/self-hosted/install/certificates/index.mdx rename to versioned_docs/version-1.49/self-hosted/install/certificates/index.mdx diff --git a/versioned_docs/version-1.37/self-hosted/install/config.yaml b/versioned_docs/version-1.49/self-hosted/install/config.yaml similarity index 100% rename from versioned_docs/version-1.37/self-hosted/install/config.yaml rename to versioned_docs/version-1.49/self-hosted/install/config.yaml diff --git a/versioned_docs/version-1.49/self-hosted/install/divert/index.mdx b/versioned_docs/version-1.49/self-hosted/install/divert/index.mdx new file mode 100644 index 000000000..c576f965e --- /dev/null +++ b/versioned_docs/version-1.49/self-hosted/install/divert/index.mdx @@ -0,0 +1,186 @@ +--- +title: Configure Divert +description: Admin guide for configuring Divert drivers in self-hosted Okteto +sidebar_label: Configure Divert +--- + +Divert enables developers to create lightweight development environments that deploy only the services they're actively working on, while routing traffic to shared services for everything else. This section covers the administrative setup required to enable Divert in your Okteto installation. + +## Divert Drivers + +Okteto supports two drivers for Divert routing: + +| Driver | Description | Default | Purpose | +|--------|-------------|---------|---------| +| **nginx** | Uses Okteto's built-in nginx ingress controller | ✅ Yes | Standard installations with Okteto-managed routing | +| **istio** | Uses Istio's VirtualService for header-based routing | No | Environments with existing Istio service mesh | + +:::info Important Distinction +**Istio and Linkerd serve different purposes:** +- **Istio** is a **divert driver** - an alternative to the nginx driver for environments already using Istio +- **Linkerd** is an **optional enhancement** for the **nginx driver** - it adds service mesh capabilities to nginx-based routing +- You **cannot** use both Istio driver and Linkerd together +- Choose one: nginx driver (with optional Linkerd) **OR** istio driver +::: + +## Okteto's Ingress Controllers + +By default, Okteto deploys two nginx ingress controllers: + +| Controller | Ingress Class | Service Type | Purpose | +|------------|---------------|--------------|---------| +| **`ingress-nginx`** | `okteto-controlplane-nginx` | LoadBalancer | The external-facing controller. Serves the Okteto control plane (API, Frontend, Buildkit, Registry) and forwards wildcard `*.subdomain` traffic to the user traffic controller | +| **`okteto-nginx`** | `okteto-nginx` | ClusterIP | An internal controller dedicated to user/dev namespace ingress traffic | + +Running two separate controllers isolates user traffic from control plane traffic, preventing developer app deployments from disrupting control plane access during reconfigurations and updates, and vice versa (this is an nginx limitation). When using the Istio driver, `okteto-nginx` is disabled in favor of Istio handling user traffic. See the [Istio Installation](istio-installation.mdx) guide for details. + +## nginx Driver (Default) + +The nginx driver is enabled by default in Okteto installations. It uses the `okteto-nginx` ingress controller to inject and route based on the `baggage: okteto-divert=` header. + +### Requirements + +- Standard Okteto installation (no additional configuration needed) +- Optional: [Linkerd service mesh](linkerd-installation.mdx) for enhanced service-to-service routing + +### How It Works + +1. When a developer deploys with `divert` configuration, Okteto creates ingress rules that inject the baggage header +2. Requests through the developer's endpoint automatically include `baggage: okteto-divert=` +3. The nginx ingress controller routes requests to the appropriate namespace based on this header +4. For service-to-service communication, applications must propagate the baggage header + +### Linkerd Integration (Optional) + +For enhanced service mesh capabilities with the nginx driver, you can install Linkerd. This provides: + +- Header-based routing at the service mesh level +- Automatic mTLS between services +- Advanced traffic management and observability +- Improved reliability with retries and circuit breaking + +See [Linkerd Installation](linkerd-installation.mdx) for setup instructions. + +## istio Driver + +The istio driver is designed for environments that already use Istio for service mesh. It leverages Istio's VirtualService for header-based routing without requiring additional components. + +:::warning +The istio driver is for environments that have **already installed Istio** and prefer Istio-native routing. If you don't have Istio, use the nginx driver instead. Do not install Istio just for Divert - the nginx driver is simpler and sufficient. +::: + +### Requirements + +- Okteto configured with Istio ingress mode +- Istio service mesh installed in the cluster +- Istio sidecar injection enabled for Okteto-managed namespaces + +See [Istio Installation](istio-installation.mdx) for full setup instructions, including Helm configuration, installing Istio components, and configuring the ingress gateway. + +### How It Works (Istio) + +1. When a developer deploys with `divert` and `driver: istio`, Okteto: + - Creates/modifies VirtualServices to route based on the baggage header + - Clones the specified host VirtualServices to the developer namespace for header injection +2. Requests through the developer's endpoint include the baggage header +3. Istio's routing rules direct traffic to the appropriate namespace +4. The Istio sidecar propagates headers through the service mesh + +## Developer Configuration + +Once an administrator has configured the Divert infrastructure, developers use the `divert` section in their `okteto.yaml`: + +### nginx Driver Example + +```yaml +deploy: + commands: + - helm upgrade --install myservice chart + divert: + driver: nginx # Optional, this is the default + namespace: staging +``` + +### istio Driver Example + +```yaml +deploy: + commands: + - helm upgrade --install myservice chart + divert: + driver: istio + virtualServices: + - name: frontend-vs + namespace: staging + routes: + - main-route + hosts: + - virtualService: frontend + namespace: staging +``` + +## Header Format + +Both drivers use the same header format (unified in Okteto 1.31+): + +``` +baggage: okteto-divert= +``` + +For backward compatibility with older nginx driver installations, the header `baggage.okteto-divert` is also supported but deprecated. + +## Network Policies + +If you have network policies enabled in your Okteto installation, ensure they allow cross-namespace communication for Divert to function properly. + +### Configuring Network Policies + +If using `networkPolicies.enabled: true` in your Helm values, add rules to allow: + +- Cross-namespace communication between developer namespaces and shared namespaces +- Traffic from the ingress controller to all namespaces + +Example configuration in your Helm values: + +```yaml +networkPolicies: + enabled: true + ingress: + - from: + - namespaceSelector: + matchLabels: + dev.okteto.com/okteto-managed: "true" +``` + +:::tip +For complete network policy configuration options, see the [Helm Configuration reference](../../helm-configuration.mdx#networkpolicies). +::: + +## Troubleshooting + +### Divert Not Working + +1. **Check driver configuration**: Ensure the correct driver is installed and configured +2. **Verify header propagation**: Test with `curl -H "baggage: okteto-divert="` to confirm routing works +3. **Check namespace labels**: For Istio, verify `istio-injection: enabled` label exists +4. **Review ingress configuration**: Ensure ingress rules are being created correctly + +### VirtualServices Not Appearing (Istio) + +1. Verify `virtualServices.enabled: true` in Helm values +2. Check that Istio CRDs are installed +3. Ensure the VirtualService is in a namespace managed by Okteto + +### Cross-Namespace Communication Failing + +1. Check network policies allow the traffic (see [Network Policies section](#network-policies)) +2. Verify DNS resolution works across namespaces +3. Test direct pod-to-pod communication to isolate the issue + +## Next Steps + +- **[Linkerd Installation](linkerd-installation.mdx)** - Enhanced routing with Linkerd (nginx driver only) +- **[Istio Installation](istio-installation.mdx)** - Full Istio setup guide (istio driver) +- **[Using Divert](development/using-divert.mdx)** - Developer implementation guide +- **[Divert Tutorial](/docs/tutorials/divert)** - Getting started guide for developers +- **[Core Concepts](core/divert.mdx)** - Understanding Divert architecture diff --git a/versioned_docs/version-1.49/self-hosted/install/divert/istio-installation.mdx b/versioned_docs/version-1.49/self-hosted/install/divert/istio-installation.mdx new file mode 100644 index 000000000..a7ebefb0c --- /dev/null +++ b/versioned_docs/version-1.49/self-hosted/install/divert/istio-installation.mdx @@ -0,0 +1,419 @@ +--- +title: Istio Installation for Divert +description: Install Istio to use the Istio driver for Divert routing in Okteto +sidebar_label: Istio Installation +--- + +:::info Administrator Guide +This guide is for **Okteto administrators** setting up Istio in the cluster. Developers do not need to install anything - once Istio is configured, Divert works transparently for all developers. +::: + +This guide covers two things: + +1. **Inbound ingress** — routing external user traffic through Istio instead of the default `okteto-nginx` ingress controller +2. **In-cluster divert routing** — using Istio VirtualServices and sidecars for header-based routing between namespaces + +The Istio driver uses Istio's VirtualService for header-based routing and is designed for environments that already use Istio or prefer Istio-native service mesh capabilities. + +:::warning For Istio Driver Only +This installation is **only** required when using the **istio driver**. If you're using the default nginx driver, do not install Istio - see [Configure Divert](index.mdx) for the distinction between drivers. +::: + +## Prerequisites + +- Kubernetes cluster with Okteto installed +- `kubectl` configured with cluster admin access +- `helm` v3.x installed +- **Administrator/operator** access (this is a one-time cluster setup) + +## Understanding Okteto's Ingress Controllers + +Before configuring Istio, it helps to understand how Okteto's ingress controllers work: + +| Controller | Ingress Class | Service Type | Purpose | +|------------|---------------|--------------|---------| +| **`ingress-nginx`** | `okteto-controlplane-nginx` | LoadBalancer | The external-facing controller. Serves the Okteto control plane (API, Frontend, Buildkit, Registry) and forwards wildcard `*.subdomain` traffic to the user traffic controller | +| **`okteto-nginx`** | `okteto-nginx` | ClusterIP | An internal controller dedicated to user/dev namespace ingress traffic | + +Okteto runs two separate nginx controllers to isolate user traffic from control plane traffic. This prevents developer app deployments from disrupting control plane access during reconfigurations and updates, and vice versa (this is an nginx limitation). + +When you enable Istio, you disable `okteto-nginx` so that Istio handles user ingress traffic instead. The `ingress-nginx` controller continues to serve the Okteto control plane and forwards wildcard user traffic to the Istio ingress gateway (via the ingress you create in Step 7). + +:::tip Disabling both ingress controllers +If you want Istio (or another ingress controller) to handle **all** traffic including the Okteto control plane, see [Using your own ingress controller](#using-your-own-ingress-controller) below. +::: + +## Configure Okteto for Istio + +Before installing Istio, update your Okteto Helm values to disable the built-in nginx ingress and enable Istio integration: + +```yaml +# Disable the default okteto-nginx since we will enable Istio ingress mode +okteto-nginx: + enabled: false + +# Enable VirtualService endpoints in the Okteto UI +virtualServices: + enabled: true + +# Inject the Istio sidecar injection label on every namespace managed by Okteto +namespace: + labels: + istio-injection: enabled +``` + +- **`okteto-nginx: enabled: false`** — Disables the built-in nginx ingress controller so Istio can handle ingress +- **`virtualServices: enabled: true`** — Displays VirtualService endpoints in the Okteto UI +- **`namespace: labels: istio-injection: enabled`** — Instructs Istio to inject sidecars into every pod in Okteto-managed namespaces, ensuring all traffic goes through the Istio mesh + +Apply the changes: + +```bash +helm upgrade okteto okteto/okteto -f values.yaml +``` + +## Install Istio + +:::tip Already have Istio installed? +If your cluster already has Istio base CRDs, Istiod, and an ingress gateway running, you can skip Steps 1, 3, 4, 5, and 6. You only need to: +- Set your domain variable (Step 2) +- Configure the ingress to route wildcard traffic to your existing Istio ingress gateway service (Step 7) — update the `service.name` to match your existing gateway's service name +- Verify the installation (Step 8) +::: + +### Step 1: Add the Istio Helm Repository + +```bash +helm repo add istio https://istio-release.storage.googleapis.com/charts +helm repo update +``` + +### Step 2: Set Your Domain + +Export the `OKTETO_DOMAIN` environment variable with the `subdomain` Helm value of your Okteto instance: + +```bash +export OKTETO_DOMAIN=okteto.example.com +``` + +### Step 3: Install Istio Base (CRDs) + +```bash +helm install --namespace istio-system --create-namespace istio-base istio/base --wait +``` + +### Step 4: Prepare the Istio Ingress Namespace + +```bash +kubectl create namespace istio-ingress +kubectl label namespace istio-ingress istio-injection=enabled +``` + +### Step 5: Install Istiod (Control Plane) + +Create a `istiod-helm-values.yaml` file with the following configuration: + +```yaml +meshConfig: + outboundTrafficPolicy: + mode: "ALLOW_ANY" # Dev configuration only — not recommended for production + enableTracing: false + defaultConfig: + holdApplicationUntilProxyStarts: true + terminationDrainDuration: 5s + proxyMetadata: + ISTIO_META_DNS_CAPTURE: "true" + EXIT_ON_ZERO_ACTIVE_CONNECTIONS: "true" +pilot: + env: + PILOT_PUSH_THROTTLE: 20 + PILOT_DEBOUNCE_AFTER: 500ms + autoscaleMin: 2 + autoscaleMax: 4 +istio_cni: + enabled: false +``` + +Install istiod: + +```bash +helm install --namespace istio-system istiod istio/istiod --values istiod-helm-values.yaml --wait +``` + +### Step 6: Install the Istio Ingress Gateway + +Create a `istio-ingress-helm-values.yaml` file: + +```yaml +service: + type: NodePort + ports: + - port: 15021 + targetPort: 15021 + name: status-port + protocol: TCP + - port: 80 + targetPort: 8080 + name: http2 + protocol: TCP + - port: 15443 + targetPort: 15443 + name: tls + protocol: TCP + +autoscaling: + enabled: false +``` + +Install the gateway: + +```bash +helm install --namespace istio-ingress istio-ingress istio/gateway --values istio-ingress-helm-values.yaml --wait +``` + +### Step 7: Configure the Istio Ingress + +Create a `istio-ingress-config.yaml` file to route wildcard user traffic from Okteto's control plane nginx to the Istio ingress gateway: + +```yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: istio-ingress +spec: + ingressClassName: okteto-controlplane-nginx + tls: + - hosts: + - '*.${OKTETO_DOMAIN}' + rules: + - host: '*.${OKTETO_DOMAIN}' + http: + paths: + - path: / + pathType: Prefix + backend: + service: + # This must match the Kubernetes Service name of your Istio + # ingress gateway. If you installed Istio using the steps above, + # this is "istio-ingress". If you're using an existing Istio + # installation, replace this with your gateway service name + # (e.g., "istio-ingressgateway"). + name: istio-ingress + port: + number: 80 +``` + +:::note +The `backend.service.name` must point to the Kubernetes Service fronting your Istio ingress gateway pods. If you are using an existing Istio installation, this is typically `istio-ingressgateway` in the `istio-system` namespace. Adjust the service name and apply the ingress resource to the namespace where the service lives. +::: + +Apply the configuration (using `envsubst` to substitute your domain): + +```bash +envsubst < istio-ingress-config.yaml | kubectl apply -n istio-ingress -f - +``` + +### Step 8: Verify Installation + +Check that all Istio components are running: + +```bash +kubectl get pods -n istio-system +kubectl get pods -n istio-ingress +``` + +All pods should be in `Running` state before continuing. + +## How Istio Enables Divert + +Once configured by administrators, Istio works **transparently for all developers**. When a developer uses Divert with the Istio driver, Okteto: + +1. Creates or modifies VirtualServices to route traffic based on the `baggage: okteto-divert=` header +2. Clones the specified host VirtualServices to the developer's personal namespace for header injection +3. The Istio sidecar propagates the baggage header through all downstream service calls + +Developers don't need to install anything or change their workflow. + +### Traffic Flow with Istio + +``` +Request (no header) + │ + ▼ + ┌─────────────┐ + │ Okteto │ ← nginx control plane + │ Ingress │ + └──────┬──────┘ + │ + ▼ + ┌─────────────┐ + │ Istio │ ← Routes to Istio ingress gateway + │ Ingress │ + └──────┬──────┘ + │ (baggage header injected by VirtualService) + ▼ + ┌─────────────┐ + │ Istio │ ← Routes based on baggage header + │ Sidecar │ + └──────┬──────┘ + │ + ▼ + ┌─────────────┐ + │ Service │ ← Your diverted service (personal namespace) + │ (personal) │ + └──────┬──────┘ + │ (header propagated automatically) + ▼ + ┌─────────────┐ + │ Istio │ ← Routes downstream call + │ Sidecar │ + └──────┬──────┘ + │ + ▼ + ┌─────────────┐ + │ Service │ ← Shared service in staging + │ (staging) │ + └─────────────┘ +``` + +## Network Policies Compatibility + +If you have network policies enabled (`networkPolicies.enabled: true`), ensure your policies allow cross-namespace communication for Divert. Example configuration in your Okteto Helm values: + +```yaml +networkPolicies: + enabled: true + ingress: + - from: + - namespaceSelector: + matchLabels: + dev.okteto.com/okteto-managed: "true" +``` + +:::tip +For complete network policy options, see the [Helm Configuration reference](../../helm-configuration.mdx#networkpolicies). +::: + +## Troubleshooting + +### Sidecar Not Injected + +1. Verify the namespace has the Istio injection label: +```bash + kubectl get namespace --show-labels +``` + +2. Restart deployments to inject sidecars: +```bash + kubectl rollout restart deployment -n +``` + +3. Verify sidecar containers are present: +```bash + kubectl get pods -n -o jsonpath='{.items[*].spec.containers[*].name}' +``` + +### VirtualServices Not Created + +1. Verify `virtualServices.enabled: true` in your Okteto Helm values +2. Check that Istio CRDs are installed: +```bash + kubectl get crd | grep istio +``` +3. Check Okteto logs for errors related to VirtualService creation + +### Traffic Not Routing Correctly + +1. Verify the baggage header format: `baggage: okteto-divert=` +2. Check that the developer's `okteto.yml` uses `driver: istio` +3. Test direct service communication: +```bash + kubectl exec -it -- curl -H "baggage: okteto-divert=" http://service/path +``` +4. Check Istio proxy logs: +```bash + kubectl logs -c istio-proxy -n +``` + +### Ingress Not Working + +1. Verify the `istio-ingress-config.yaml` was applied correctly: +```bash + kubectl get ingress -n istio-ingress +``` +2. Confirm `OKTETO_DOMAIN` was substituted correctly in the ingress manifest +3. Check that `okteto-nginx` is disabled in your Okteto Helm values + +## Using Your Own Ingress Controller + +The configuration above only disables `okteto-nginx` (the user traffic ingress controller) in favor of Istio. The `ingress-nginx` controller still handles control plane traffic (API, Frontend, Buildkit, Registry). + +If you want to disable **both** nginx ingress controllers and use Istio (or another ingress controller) for all traffic, including the Okteto control plane: + +```yaml +ingress-nginx: + enabled: false + +okteto-nginx: + enabled: false + +defaultBackend: + enabled: false +``` + +When disabling both controllers, you must also configure: + +- **`ingress.oktetoIngressClass`** — the ingress class to use for all ingresses created during the Okteto installation +- **`ingress.class`** — the ingress class to use for all ingresses created by Okteto for developer namespaces +- **`ingress.ip`** — the cluster IP of your ingress controller + +:::warning Feature limitations +When disabling Okteto's nginx controllers, the following features are **not available**: +- Autowake Namespaces +- Error Pages +- Private Endpoints +::: + +## Uninstalling Istio + +If you need to remove Istio: + +```bash +# Remove ingress configuration +kubectl delete ingress istio-ingress -n istio-ingress + +# Uninstall Helm releases +helm uninstall istio-ingress -n istio-ingress +helm uninstall istiod -n istio-system +helm uninstall istio-base -n istio-system + +# Remove namespaces +kubectl delete namespace istio-ingress +kubectl delete namespace istio-system +``` + +Re-enable the nginx driver in your Okteto Helm values: + +```yaml +okteto-nginx: + enabled: true + +virtualServices: + enabled: false + +namespace: + labels: {} +``` + +Then upgrade Okteto: + +```bash +helm upgrade okteto okteto/okteto -f values.yaml +``` + +## Next Steps + +- **[Configure Divert](index.mdx)** - Overview of Divert configuration +- **[Using Divert](development/using-divert.mdx)** - Developer implementation guide +- **[Divert with Istio Sample](https://github.com/okteto-community/movies-with-divert-istio)** - Full working example +- **[Istio Documentation](https://istio.io/latest/docs/)** - Official Istio docs diff --git a/versioned_docs/version-1.49/self-hosted/install/divert/linkerd-installation.mdx b/versioned_docs/version-1.49/self-hosted/install/divert/linkerd-installation.mdx new file mode 100644 index 000000000..a665e802e --- /dev/null +++ b/versioned_docs/version-1.49/self-hosted/install/divert/linkerd-installation.mdx @@ -0,0 +1,304 @@ +--- +title: Linkerd Installation for Divert +description: Install Linkerd to enhance Divert routing capabilities with the nginx driver +sidebar_label: Linkerd Installation +--- + +:::info Administrator Guide +This guide is for **Okteto administrators** setting up Linkerd in the cluster. Developers do not need to install anything - once Linkerd is configured in the cluster, Divert works transparently for all developers. +::: + +This guide covers installing Linkerd to enhance Divert's routing capabilities when using the nginx driver. Linkerd provides service mesh functionality that enables more sophisticated traffic routing based on HTTP headers. + +:::warning For nginx Driver Only +Linkerd is **only** for use with the **nginx driver**. If you're using the istio driver, do not install Linkerd - Istio already provides service mesh capabilities. See [Configure Divert](index.mdx) for the distinction between drivers. +::: + +:::info +Linkerd is **optional** for the nginx driver. The basic Divert functionality works without it, but Linkerd enables enhanced service-to-service routing within the mesh. +::: + +## Prerequisites + +- Kubernetes cluster with Okteto installed using the **nginx driver** (default) +- `kubectl` configured with cluster admin access +- `helm` v3.x installed +- Okteto using the default nginx driver (not istio) +- **Administrator/operator** access (this is a one-time cluster setup) + +## Installation Steps + +:::tip For Administrators Only +These steps are performed once by the Okteto administrator. Developers do not need to install the Linkerd CLI or perform any of these steps. Once Linkerd is installed in the cluster, it works transparently for all developers using Divert. +::: + +### Step 1: Install the Linkerd CLI (Administrator Only) + +Install the Linkerd CLI on your **local machine** (as an administrator) to manage the Linkerd installation: + +```bash +# macOS/Linux +curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install | sh + +# Add to PATH +export PATH=$PATH:$HOME/.linkerd2/bin + +# Verify installation +linkerd version +``` + +**Note**: Developers do not need this CLI. It's only for cluster administrators to install and manage Linkerd. + +### Step 2: Validate Cluster Compatibility + +```bash +linkerd check --pre +``` + +Address any issues before proceeding. + +### Step 3: Install Linkerd CRDs + +```bash +linkerd install --crds | kubectl apply -f - +``` + +### Step 4: Install Linkerd Control Plane + +```bash +linkerd install | kubectl apply -f - +``` + +### Step 5: Verify Installation + +```bash +linkerd check +``` + +All checks should pass before continuing. + +### Step 6: Install Linkerd Viz (Optional) + +For observability dashboards: + +```bash +linkerd viz install | kubectl apply -f - +linkerd viz check +``` + +## Configure Okteto for Linkerd + +Once Linkerd is installed in the cluster, configure Okteto to automatically inject Linkerd sidecars into all developer namespaces. This is a one-time configuration by the administrator. + +### Enable Sidecar Injection + +Add the Linkerd annotation to Okteto-managed namespaces by updating your Okteto Helm values: + +```yaml +namespace: + annotations: + linkerd.io/inject: enabled +``` + +Upgrade your Okteto installation: + +```bash +helm upgrade okteto okteto/okteto -f values.yaml +``` + +### Existing Namespaces + +For existing namespaces, add the annotation: + +```bash +kubectl annotate namespace linkerd.io/inject=enabled +``` + +Then restart deployments to inject sidecars: + +```bash +kubectl rollout restart deployment -n +``` + +## How Linkerd Enhances Divert + +Once configured by administrators, Linkerd works **transparently for all developers**. Developers don't need to install anything or change their workflow. When they use Divert, they automatically benefit from: + +1. **Header-based routing**: Linkerd routes requests based on the `baggage` header at the service mesh level +2. **Automatic retries**: Failed requests are automatically retried to the correct service +3. **Load balancing**: Intelligent load balancing across service instances +4. **mTLS**: Automatic mutual TLS between services for enhanced security +5. **Observability**: Detailed metrics and tracing for diverted traffic (visible to administrators) + +**For developers**: Divert "just works" - no CLI installation or special configuration needed. + +### Traffic Flow with Linkerd + +``` +Request with baggage header + │ + ▼ + ┌─────────────┐ + │ Ingress │ + │ (nginx) │ + └──────┬──────┘ + │ (header injected) + ▼ + ┌─────────────┐ + │ Linkerd │ ← Routes based on baggage header + │ Sidecar │ + └──────┬──────┘ + │ + ▼ + ┌─────────────┐ + │ Service │ ← Your diverted service + │ (local) │ + └──────┬──────┘ + │ (header propagated) + ▼ + ┌─────────────┐ + │ Linkerd │ ← Routes downstream call + │ Sidecar │ + └──────┬──────┘ + │ + ▼ + ┌─────────────┐ + │ Service │ ← Shared service in staging + │ (staging) │ + └─────────────┘ +``` + +## ServiceProfiles for Routing (Optional) + +For fine-grained control, create ServiceProfiles: + +```yaml +apiVersion: linkerd.io/v1alpha2 +kind: ServiceProfile +metadata: + name: catalog.staging.svc.cluster.local + namespace: staging +spec: + routes: + - name: GET /api/movies + condition: + method: GET + pathRegex: /api/movies.* + responseClasses: + - condition: + status: + min: 200 + max: 299 +``` + +## Network Policies Compatibility + +If you have network policies enabled (`networkPolicies.enabled: true`), Linkerd works within the existing policy framework. Ensure your policies allow: + +- Cross-namespace communication for Divert functionality +- Traffic to and from Linkerd control plane + +Example network policy configuration in your Okteto Helm values: + +```yaml +networkPolicies: + enabled: true + ingress: + - from: + - namespaceSelector: + matchLabels: + dev.okteto.com/okteto-managed: "true" +``` + +:::tip +For complete network policy options, see the [Helm Configuration reference](../../helm-configuration.mdx#networkpolicies). +::: + +## Monitoring Diverted Traffic (Administrator Only) + +These monitoring capabilities are available to administrators with the Linkerd CLI. Developers use Divert normally without needing any of these tools. + +### Using Linkerd Dashboard + +```bash +linkerd viz dashboard +``` + +Navigate to the namespace view to see: + +- Request rates per service +- Success rates +- Latency percentiles +- Traffic flow between services + +### CLI Monitoring + +```bash +# Watch traffic to a service +linkerd viz stat deploy -n + +# Live traffic tap +linkerd viz tap deploy/ -n +``` + +**Note**: Developers don't need these commands. They use Okteto's standard monitoring and observability features. + +## Troubleshooting + +### Sidecar Not Injected + +1. Verify namespace annotation: +```bash + kubectl get namespace -o jsonpath='{.metadata.annotations}' +``` + +2. Check Linkerd injection status: +```bash + kubectl get pods -n -o jsonpath='{.items[*].spec.containers[*].name}' +``` + +3. Restart deployments: +```bash + kubectl rollout restart deployment -n +``` + +### Header Not Propagating + +1. Verify header format: `baggage: okteto-divert=` +2. Check application code propagates headers +3. Use Linkerd tap to trace the request: +```bash + linkerd viz tap deploy/ --to deploy/ +``` + +### Traffic Not Routing Correctly + +1. Check ServiceProfile routes if configured +2. Verify DNS resolution across namespaces +3. Test direct service communication: +```bash + kubectl exec -it -- curl -H "baggage: okteto-divert=" http://service/path +``` + +## Uninstalling Linkerd + +If you need to remove Linkerd: + +```bash +# Remove viz extension +linkerd viz uninstall | kubectl delete -f - + +# Remove control plane +linkerd uninstall | kubectl delete -f - + +# Remove CRDs +linkerd install --crds | kubectl delete -f - +``` + +Update Okteto Helm values to remove the namespace annotation. + +## Next Steps + +- **[Configure Divert](index.mdx)** - Overview of Divert configuration +- **[Using Divert](development/using-divert.mdx)** - Developer implementation guide +- **[Linkerd Documentation](https://linkerd.io/2/overview/)** - Official Linkerd docs diff --git a/versioned_docs/version-1.37/self-hosted/install/github.mdx b/versioned_docs/version-1.49/self-hosted/install/github.mdx similarity index 96% rename from versioned_docs/version-1.37/self-hosted/install/github.mdx rename to versioned_docs/version-1.49/self-hosted/install/github.mdx index 8241d87a9..b92e731e0 100644 --- a/versioned_docs/version-1.37/self-hosted/install/github.mdx +++ b/versioned_docs/version-1.49/self-hosted/install/github.mdx @@ -1,6 +1,6 @@ --- title: GitHub integration -description: Use our GitHub Integrate so your users can access private repositories in their development environments +description: Use our GitHub Integration so your users can access private repositories in their development environments sidebar_label: GitHub integration id: github-integration --- @@ -112,7 +112,7 @@ If the installation was successful, you should now see a `GitHub` option in the

diff --git a/versioned_docs/version-1.37/self-hosted/install/okteto-registry-storage/aws-s3-bucket.mdx b/versioned_docs/version-1.49/self-hosted/install/okteto-registry-storage/aws-s3-bucket.mdx similarity index 100% rename from versioned_docs/version-1.37/self-hosted/install/okteto-registry-storage/aws-s3-bucket.mdx rename to versioned_docs/version-1.49/self-hosted/install/okteto-registry-storage/aws-s3-bucket.mdx diff --git a/versioned_docs/version-1.37/self-hosted/install/okteto-registry-storage/azure-storage-container.mdx b/versioned_docs/version-1.49/self-hosted/install/okteto-registry-storage/azure-storage-container.mdx similarity index 100% rename from versioned_docs/version-1.37/self-hosted/install/okteto-registry-storage/azure-storage-container.mdx rename to versioned_docs/version-1.49/self-hosted/install/okteto-registry-storage/azure-storage-container.mdx diff --git a/versioned_docs/version-1.37/self-hosted/install/okteto-registry-storage/digitalocean-spaces.mdx b/versioned_docs/version-1.49/self-hosted/install/okteto-registry-storage/digitalocean-spaces.mdx similarity index 100% rename from versioned_docs/version-1.37/self-hosted/install/okteto-registry-storage/digitalocean-spaces.mdx rename to versioned_docs/version-1.49/self-hosted/install/okteto-registry-storage/digitalocean-spaces.mdx diff --git a/versioned_docs/version-1.37/self-hosted/install/okteto-registry-storage/filesystem.mdx b/versioned_docs/version-1.49/self-hosted/install/okteto-registry-storage/filesystem.mdx similarity index 100% rename from versioned_docs/version-1.37/self-hosted/install/okteto-registry-storage/filesystem.mdx rename to versioned_docs/version-1.49/self-hosted/install/okteto-registry-storage/filesystem.mdx diff --git a/versioned_docs/version-1.37/self-hosted/install/okteto-registry-storage/google-cloud-storage.mdx b/versioned_docs/version-1.49/self-hosted/install/okteto-registry-storage/google-cloud-storage.mdx similarity index 100% rename from versioned_docs/version-1.37/self-hosted/install/okteto-registry-storage/google-cloud-storage.mdx rename to versioned_docs/version-1.49/self-hosted/install/okteto-registry-storage/google-cloud-storage.mdx diff --git a/versioned_docs/version-1.37/self-hosted/install/okteto-registry-storage/index.mdx b/versioned_docs/version-1.49/self-hosted/install/okteto-registry-storage/index.mdx similarity index 100% rename from versioned_docs/version-1.37/self-hosted/install/okteto-registry-storage/index.mdx rename to versioned_docs/version-1.49/self-hosted/install/okteto-registry-storage/index.mdx diff --git a/versioned_docs/version-1.37/self-hosted/install/volume-snapshots.mdx b/versioned_docs/version-1.49/self-hosted/install/volume-snapshots.mdx similarity index 69% rename from versioned_docs/version-1.37/self-hosted/install/volume-snapshots.mdx rename to versioned_docs/version-1.49/self-hosted/install/volume-snapshots.mdx index cd4f0ecda..8558c5b6f 100644 --- a/versioned_docs/version-1.37/self-hosted/install/volume-snapshots.mdx +++ b/versioned_docs/version-1.49/self-hosted/install/volume-snapshots.mdx @@ -1,6 +1,6 @@ --- -title: Volume Snapshots -description: Enable volume snapshots in Okteto +title: Volume Snapshots for Self-Hosted Okteto +description: Install and configure a CSI driver and VolumeSnapshotClass to enable the Volume Snapshots feature on your Self-Hosted Okteto instance. sidebar_label: Volume Snapshots id: volume-snapshots --- @@ -8,24 +8,26 @@ id: volume-snapshots import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -Volume snapshots allows you to initialize persistent volume claims with the contents of a preexisting volume snapshot. -Use volume snapshots when working with large datasets or if you want to create development environments with real data coming from your production or staging environments. +Volume Snapshots allow you to initialize persistent volume claims with the contents of a preexisting Volume Snapshot. +Use Volume Snapshots when working with large datasets or to create Development Environments with real data from your production or staging environments. ## Requirements To use the Volume Snapshots feature, you must install a CSI driver that supports snapshots and create the corresponding `VolumeSnapshotClass`. -### Installing the CSI Driver +### CSI driver installation -Volume Snapshots is compatible with any CSI-compliant driver, such as: +Volume Snapshots are compatible with any CSI-compliant driver, such as: - [Google Compute Engine Persistent Disk CSI Driver](https://cloud.google.com/kubernetes-engine/docs/how-to/persistent-volumes/gce-pd-csi-driver) - [Amazon EBS CSI driver](https://docs.aws.amazon.com/eks/latest/userguide/ebs-csi.html) - [DigitalOcean Block Storage CSI Driver](https://github.com/digitalocean/csi-digitalocean) -> Note: As of February 2021, if you're using the Amazon EBS CSI driver, you'll need to install the alpha version to enable Volume Snapshots. More information is available [on their github repository](https://github.com/kubernetes-sigs/aws-ebs-csi-driver). +:::note +As of February 2021, if you use the Amazon EBS CSI driver, you need to install the alpha version to enable Volume Snapshots. See the [AWS EBS CSI driver repository](https://github.com/kubernetes-sigs/aws-ebs-csi-driver) for details. +::: -We recommend you follow your vendor's installation instructions to learn more about this topic. +Follow your vendor's installation instructions for driver-specific setup details. -### Create a VolumeSnapshotClass +### VolumeSnapshotClass Create a `VolumeSnapshotClass` in your cluster to determine the CSI driver and `deletionPolicy` for your `VolumeSnapshots`. @@ -81,15 +83,15 @@ deletionPolicy: Delete -To create the `VolumeSnapshotClass` run the following command after creating the file. +To create the `VolumeSnapshotClass`, run the following command after creating the file: -``` +```bash kubectl apply -f okteto-snapshot-class.yaml ``` -### Create a StorageClass (optional) +### StorageClass (optional) -Optionally, you can also create a storage class. This storage class will be used by Okteto when creating the volumes. +Optionally, you can also create a storage class. Okteto uses this storage class when creating the volumes. -To create the `StorageClass` run the following command after creating the file. +To create the `StorageClass`, run the following command after creating the file: -``` +```bash kubectl apply -f okteto-snapshot-sc.yaml ``` ## Enabling Volume Snapshots -To enable Volume Snapshots on your Okteto instance, update your `config.yaml` file with the following values, and run a [helm upgrade](https://okteto.com/docs/self-hosted/install/upgrade/#upgrade-your-okteto-enterprise-instance) to apply the new configuration. +To enable Volume Snapshots on your Okteto instance, update your `config.yaml` file with the following values, and run a [helm upgrade](self-hosted/manage/upgrade.mdx#upgrade-your-okteto-instance) to apply the new configuration. -More information on the different configuration settings [is available here](self-hosted/helm-configuration.mdx#volumesnapshots). +See the [Volume Snapshots Helm configuration](self-hosted/helm-configuration.mdx#volumesnapshots) for all available settings. -By default, all users in your cluster will be able to use any of the available snapshots as a data source for their development environments. You can limit this via the `enableNamespaceAccessValidation` key in the `volumeSnapshots` section of the configuration, value of `true` will enable the validation. +By default, all users in your cluster can use any available snapshot as a data source for their Development Environments. To restrict this, set the `enableNamespaceAccessValidation` key to `true` in the `volumeSnapshots` section of the configuration. ## Using Volume Snapshots in your Development Environment diff --git a/versioned_docs/version-1.37/self-hosted/manage/air-gapped.mdx b/versioned_docs/version-1.49/self-hosted/manage/air-gapped.mdx similarity index 86% rename from versioned_docs/version-1.37/self-hosted/manage/air-gapped.mdx rename to versioned_docs/version-1.49/self-hosted/manage/air-gapped.mdx index 4f7024906..1d87a8160 100644 --- a/versioned_docs/version-1.37/self-hosted/manage/air-gapped.mdx +++ b/versioned_docs/version-1.49/self-hosted/manage/air-gapped.mdx @@ -43,20 +43,20 @@ Since Okteto doesn’t support `imagePullSecrets`, ensure your Kubernetes cluste Push the following images to your private registry for the Okteto Chart installation: -- **okteto/backend:{variables.chartVersion}** -- **okteto/frontend:{variables.chartVersion}** -- **okteto/buildkit:{variables.chartVersion}** or **okteto/buildkit:{variables.chartVersion}-rootless** -- **okteto/registry:{variables.chartVersion}** -- **okteto/pipeline-runner:{variables.chartVersion}** or **okteto/pipeline-runner:{variables.chartVersion}-rootless** -- **okteto/daemon:{variables.chartVersion}** -- **okteto/agent:{variables.chartVersion}** -- **okteto/ingress-nginx-chroot:{variables.chartVersion}** -- **okteto/reloader:{variables.chartVersion}** -- **okteto/redis:{variables.chartVersion}** +- **ghcr.io/okteto/backend:{variables.chartVersion}** +- **ghcr.io/okteto/frontend:{variables.chartVersion}** +- **ghcr.io/okteto/buildkit:{variables.chartVersion}** or **ghcr.io/okteto/buildkit:{variables.chartVersion}-rootless** +- **ghcr.io/okteto/registry:{variables.chartVersion}** +- **ghcr.io/okteto/pipeline-runner:{variables.chartVersion}** or **ghcr.io/okteto/pipeline-runner:{variables.chartVersion}-rootless** +- **ghcr.io/okteto/daemon:{variables.chartVersion}** +- **ghcr.io/okteto/agent:{variables.chartVersion}** +- **ghcr.io/okteto/ingress-nginx-chroot:{variables.chartVersion}** +- **ghcr.io/okteto/reloader:{variables.chartVersion}** +- **ghcr.io/okteto/redis:{variables.chartVersion}** For each Okteto CLI version, push the following images to your private registry: -- **okteto/okteto:{variables.cliVersion}** +- **ghcr.io/okteto/okteto:{variables.cliVersion}** :::info For Okteto Chart {variables.chartVersion}, we recommend enforcing the usage of Okteto CLI {variables.cliVersion} in your developer's machines to reduce maintenance overhead @@ -89,9 +89,8 @@ okteto-nginx: registry: <> reloader: - image: - repository: <>/okteto/reloader - + global: + imageRegistry: <> ``` diff --git a/versioned_docs/version-1.37/self-hosted/manage/argocd.mdx b/versioned_docs/version-1.49/self-hosted/manage/argocd.mdx similarity index 97% rename from versioned_docs/version-1.37/self-hosted/manage/argocd.mdx rename to versioned_docs/version-1.49/self-hosted/manage/argocd.mdx index a8f9eddfc..714d8c76d 100644 --- a/versioned_docs/version-1.37/self-hosted/manage/argocd.mdx +++ b/versioned_docs/version-1.49/self-hosted/manage/argocd.mdx @@ -95,6 +95,12 @@ ignoreDifferences: jqPathExpressions: - '.webhooks[].clientConfig.caBundle' + # APIService caBundle managed/patched by Okteto + - group: 'apiregistration.k8s.io' + kind: 'APIService' + jsonPointers: + - '/spec/caBundle' + # Internal service account managed by Okteto - kind: 'ServiceAccount' name: 'okteto-bot' diff --git a/versioned_docs/version-1.49/self-hosted/manage/arm-support.mdx b/versioned_docs/version-1.49/self-hosted/manage/arm-support.mdx new file mode 100644 index 000000000..414773ecc --- /dev/null +++ b/versioned_docs/version-1.49/self-hosted/manage/arm-support.mdx @@ -0,0 +1,161 @@ +--- +title: ARM Support +description: How to install and configure Okteto on ARM-based Kubernetes clusters +sidebar_label: ARM Support +id: arm-support +--- + +Okteto supports installation on ARM-based Kubernetes clusters for Self-Hosted deployments. Running Okteto on ARM lets developers build and test against the same architecture as their target operational clusters, avoiding compatibility differences that can surface when developing on a different architecture than the one that runs the application. + +## Support Status + +| Cloud Provider | Recommended Instance | Status | +|---|---|---| +| Google GKE | Tau T2A (`t2a-standard-4`) | GA | +| Amazon EKS | Graviton 2/3 (`m7g.xlarge`) | Beta | + +ARM support is covered by the same release pipeline as x86. All control plane images are published as multi-arch (amd64 + arm64). + +:::note +ARM support is available for **Self-Hosted deployments only**. Bring Your Own Cloud (BYOC) deployments are not supported. +::: + +## Requirements + +- **Fresh installations only.** Migrating an existing x86 cluster to ARM is not supported. ARM clusters must be provisioned from scratch. +- **Homogeneous clusters.** All nodes in the cluster must be ARM-based. Mixed architecture clusters (ARM + x86 nodes) are not supported. + +## Google GKE (GA) + +ARM support on GCP using Tau T2A instances is generally available. Automated tests run against ARM clusters on GCP for every release and in weekly scheduled runs. + +### Cluster Configuration + +We recommend creating a GKE cluster using Tau T2A nodes. The recommended instance type is `t2a-standard-4`: + +```bash +gcloud container clusters create CLUSTER_NAME \ + --zone ZONE \ + --machine-type=t2a-standard-4 \ + --num-nodes=3 \ + --disk-size=250 +``` + +:::note +Tau T2A instances are only available in certain GCP regions and zones. See the [GCP documentation](https://cloud.google.com/compute/docs/general-purpose-machines#t2a_machines) for regional availability. +::: + +### Helm Configuration + +GKE automatically applies `kubernetes.io/arch=arm64:NoSchedule` taints to ARM nodes. You must add the following tolerations to your `config.yaml` so that Okteto components can be scheduled on those nodes: + +```yaml +globals: + tolerations: + okteto: + - key: "kubernetes.io/arch" + operator: "Equal" + value: "arm64" + effect: "NoSchedule" + dev: + - key: "kubernetes.io/arch" + operator: "Equal" + value: "arm64" + effect: "NoSchedule" +ingress-nginx: + controller: + tolerations: + - key: "kubernetes.io/arch" + operator: "Equal" + value: "arm64" + effect: "NoSchedule" +okteto-nginx: + controller: + tolerations: + - key: "kubernetes.io/arch" + operator: "Equal" + value: "arm64" + effect: "NoSchedule" +reloader: + reloader: + deployment: + tolerations: + - key: "kubernetes.io/arch" + operator: "Equal" + value: "arm64" + effect: "NoSchedule" +``` + +For the full installation walkthrough, follow the [GKE installation guide](get-started/install/google-gke.mdx). + +## Amazon EKS (Beta) + +:::warning Beta +ARM support on Amazon EKS is in **Beta**. The functionality is complete, but automated test coverage on EKS ARM is still maturing — validation is performed manually when introducing support for new Kubernetes versions. Until coverage matures, running this on operational clusters carries a higher chance of encountering an unexpected issue. +::: + +AWS Graviton 2 and Graviton 3 instances are supported. The recommended instance type is `m7g.xlarge`, which is equivalent in size to the standard `m5.xlarge` used in the default EKS guide. + +### Cluster Configuration + +```bash +eksctl create cluster -f - <>`. +If you're already using your own custom metrics adapter (such as [Prometheus Adapter](https://github.com/kubernetes-sigs/prometheus-adapter)), you can disable Okteto's built-in adapter by setting `buildkit.hpa.adapter.enabled: false` in your Helm configuration. In that case, you can scrape metrics directly from the BuildKit pods on port 8080. All metrics have the `okteto_build` prefix. +::: ## 5. Follow Best Practices for Dockerfiles and Remote Execution @@ -128,4 +134,4 @@ To make the most of your BuildKit configuration, we have the following recommend - Adhere to [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/). - Reduce file transfer times to BuildKit by using [.dockerignore](https://docs.docker.com/reference/dockerfile/#dockerignore-file) and [.oktetoignore](core/remote-execution.mdx#ignoring-files) files. - Use [BuildKit cache mounts](https://docs.docker.com/build/cache/optimize/) to persist cache folders between image builds. This can significantly speed up build times by caching dependencies and build artifacts. -- Use [Test Container caches](https://www.okteto.com/docs/reference/okteto-manifest/#caches-string-optional) to persist cache folders between test executions. This ensures that test dependencies are cached, reducing the time taken for subsequent test runs. +- Use [Test Container caches](reference/okteto-manifest.mdx#caches-string-optional) to persist cache folders between test executions. This ensures that test dependencies are cached, reducing the time taken for subsequent test runs. diff --git a/versioned_docs/version-1.37/self-hosted/manage/crds.mdx b/versioned_docs/version-1.49/self-hosted/manage/crds.mdx similarity index 86% rename from versioned_docs/version-1.37/self-hosted/manage/crds.mdx rename to versioned_docs/version-1.49/self-hosted/manage/crds.mdx index edfaa2d0d..216c59eab 100644 --- a/versioned_docs/version-1.37/self-hosted/manage/crds.mdx +++ b/versioned_docs/version-1.49/self-hosted/manage/crds.mdx @@ -10,7 +10,7 @@ import TabItem from "@theme/TabItem"; As part of Okteto's installation, several Custom Resource Definitions (CRDs) are installed in your cluster. These CRDs primarily store different types of information necessary for Okteto's functionality. You can view the list of Okteto's CRDs by exploring the `crds` folder in the templates of the [Okteto Helm Chart](https://artifacthub.io/packages/helm/okteto/okteto) or by running the following command: -```console +```bash kubectl get crd | grep okteto.com ``` @@ -148,7 +148,7 @@ For example, if you want to add a configuration for **GCP Cloud Credential**, yo - `metadata.name`: `gcp-credentials-config` - `spec.audience`: This is the intended audience for the credential. It is typically a URL or a string that identifies the target service or application that will use the credential. - `spec.projectNumber`: This is the unique identifier for your Google Cloud project. It is a numeric value that is assigned to your project when you create it in the Google Cloud Console. -- `spec.providerId`: his is the identifier for the identity provider. It is used to specify which identity provider will be used to authenticate the credentials. +- `spec.providerId`: This is the identifier for the identity provider. It is used to specify which identity provider will be used to authenticate the credentials. - `spec.workloadIdentityPoolId`: This is the identifier for the Workload Identity Pool. It is used to specify the pool of identities that can be used to authenticate the credentials. ```yaml title="gcp-cloud-credential.yaml" @@ -245,4 +245,65 @@ kubectl apply -f okta-deprovisioning-crd.yaml Once the CRD and secret are configured, go back to the **Okta admin console** and verify the webhook. After verification, Okteto will start receiving `User Deactivated` and `User Deleted` events, automatically de-provisioning users from the system. -Events sent to the webhook appear in the `Reports -> System Log` tab of Okta which can be useful for troubleshooting. \ No newline at end of file +Events sent to the webhook appear in the `Reports -> System Log` tab of Okta which can be useful for troubleshooting. + +## Known Hosts + +SSH Known Hosts can be managed through the Admin dashboard, or via one of the CRDs installed by Okteto. Managing them with CRDs lets you define host key entries declaratively and keep them under GitOps. + +:::note +Entries created via CRDs will be visible in the UI but treated as read-only. If you omit the label "app.kubernetes.io/managed-by: okteto", the item is shown as read-only in the UI. +::: + + +### 1. Prepare the known_hosts content + +Collect the public host keys you want to trust, one per line, in standard OpenSSH known_hosts format, e.g.: + +``` +github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl +``` + +### 2. Create the Required Secret + +Create an Opaque Kubernetes Secret with two base64-encoded keys: +- `content`: the full known_hosts file content (base64-encoded) +- `enabled`: a boolean flag (true/false, base64-encoded) + - "true" → dHJ1ZQ== + - "false" → `ZmFsc2U=` + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: ssh-known-hosts-secret + namespace: okteto +type: Opaque +data: + content: + enabled: +``` + +### 3. Create the CRD Configuration + +Reference the Secret from a DynamicConfig: + +```yaml +apiVersion: admin.okteto.com/v1 +kind: DynamicConfig +metadata: + name: ssh-known-hosts + namespace: okteto +secretRef: ssh-known-hosts-secret +``` + +### 4. Apply the Configuration + + ```sh +kubectl apply -f ssh-known-hosts-secret.yaml +kubectl apply -f ssh-known-hosts-crd.yaml +``` + +### 5. Verify in the Admin Dashboard + +Open the Admin dashboard and check the SSH Known Hosts section. The entries from your CRD should be listed. If enabled is true, the configuration is active. \ No newline at end of file diff --git a/versioned_docs/version-1.37/self-hosted/manage/diagnostics.mdx b/versioned_docs/version-1.49/self-hosted/manage/diagnostics.mdx similarity index 100% rename from versioned_docs/version-1.37/self-hosted/manage/diagnostics.mdx rename to versioned_docs/version-1.49/self-hosted/manage/diagnostics.mdx diff --git a/versioned_docs/version-1.49/self-hosted/manage/okteto-license.mdx b/versioned_docs/version-1.49/self-hosted/manage/okteto-license.mdx new file mode 100644 index 000000000..2f871148c --- /dev/null +++ b/versioned_docs/version-1.49/self-hosted/manage/okteto-license.mdx @@ -0,0 +1,57 @@ +--- +title: Okteto License +description: How to obtain and install your Okteto license key. For how billing works and how seats are counted, see the Billing page. +sidebar_label: Okteto License +id: okteto-license +--- + +This page covers how to obtain and install your Okteto license key. + +:::tip +For how billing works, what your license includes, how seats are counted, and how true-ups are handled, see [Billing](admin/billing.mdx). +::: + +## When a license is required + +Okteto requires a license key to use any of our paid products: [BYOC and Self-Hosted](byoc-vs-self-hosted.mdx). The license is what unlocks the platform, but it does not by itself determine your bill. Your seat count, allowance, and any overages are governed by your Order Form and our [billing model](admin/billing.mdx). + +## How to obtain a license + +There are two ways: + +1. Fill out the self-hosted [Free Tier form](https://www.okteto.com/free-trial/) on our website. +1. [Contact us](https://www.okteto.com/get-demo/) to schedule a demo. + +When you fill out the self-hosted Free Tier form, you will automatically receive an email containing a license key for your Free Tier access. This option does not require any interaction with Okteto or our teams and gives you the control and independence to try Okteto Self-Hosted on your schedule and at your own pace. The Free Tier license only works with Self-Hosted. + +The alternative option of contacting us for a demo will get you in touch with someone from our team to guide you through a personalized demo and gives you the opportunity to ask questions and explore our product side-by-side with our team. This process can result in Free Tier access to either Okteto BYOC or Self-Hosted. + +No credit card is required to start. + +## How to install the license + +### Bring Your Own Cloud + +No action required. Okteto manages the license for BYOC instances. + +### Self-Hosted + +Add your license key to your `config.yaml` using the `license:` key. For example: + +```yaml +license: ABC123...XYZ456 +``` + +:::note +You can also optionally include your Okteto license using [Cloud Secrets](self-hosted/helm-configuration.mdx#secret). +::: + +After updating the license, [upgrade](upgrade.mdx) your Okteto instance for the new license to take effect. + +## Checking your seat usage + +Your current account count is visible in the [Admin Dashboard](admin/dashboard.mdx) and via the [Okteto API](admin/okteto-api.mdx). For the rules on what counts as a seat and how overages are handled, see [Billing](admin/billing.mdx). + +## License expiration + +When a paid license expires, your instance keeps running but new accounts cannot be created until the license is renewed. Free Tier and trial licenses block all logins on expiration. Reach out to your account team well before your renewal date. diff --git a/versioned_docs/version-1.49/self-hosted/manage/troubleshooting.mdx b/versioned_docs/version-1.49/self-hosted/manage/troubleshooting.mdx new file mode 100644 index 000000000..c84a6ade2 --- /dev/null +++ b/versioned_docs/version-1.49/self-hosted/manage/troubleshooting.mdx @@ -0,0 +1,505 @@ +--- +title: Troubleshoot your Okteto instance +description: Questions and answers to common issues when installing or upgrading your Okteto instance +sidebar_label: Troubleshooting +id: troubleshooting +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +Welcome to the Okteto troubleshooting guide. This page provides answers to some common issues encountered while using Okteto. +Please also review our [FAQ Guide](reference/faqs.mdx) for additional help. + +## How to extract logs from Okteto when asking for help + +### For Developers: +When reaching out to Okteto for support or when asking the [Okteto Community](http://community.okteto.com), run [`okteto doctor` to generate a doctor file](reference/okteto-cli.mdx#doctor) with the okteto logs for a given development container. + +### For Administrators of Okteto: +Please use our [Okteto Diagnostics tool](self-hosted/manage/diagnostics.mdx) to create a support bundle with cluster information, logs for okteto components, and other relevant information. + +## BYOC log access + +In Okteto BYOC, log access depends on the cloud provider. In addition to the log viewing options available to Okteto users, anyone with access to the cloud provider logging solution for the account or project can review the logs that are forwarded there for some or all workloads in the cluster. These logs are stored in the default standard locations defined by each logging service and can be filtered using labels or the corresponding query system by namespace, node, pod, and similar resource attributes. + +### AWS BYOC + +For Okteto BYOC installations on AWS, all cluster logs are sent to [Amazon CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html). Inspect CloudWatch when you need workload, application, or cluster-level logs directly from AWS. +These logs are stored in CloudWatch Logs log groups in the same AWS account and Region, commonly under EKS and Container Insights log groups such as `/aws/eks//cluster` and `/aws/containerinsights//...`. + +The AWS setup for BYOC grants Okteto the access it needs to operate the platform, as documented in the [AWS BYOC onboarding guide](byoc/aws/index.mdx). Customers should use their own AWS access to review workload logs in CloudWatch. + +### GCP BYOC + +For Okteto BYOC installations on GCP, system logs and logs from the `okteto` namespace are sent to [Google Cloud Logging](https://cloud.google.com/logging/docs). There is also an opt-in way to send all cluster logs to Cloud Logging; contact your Okteto technical contact to activate it. +These logs are stored in Cloud Logging log buckets, typically the system-managed `_Default` and `_Required` buckets. + +The current GCP BYOC onboarding flow grants Okteto administrative access in the customer project, as documented in the [GCP BYOC onboarding guide](byoc/gcp/index.mdx). Customers should use their own GCP access to review the system logs and `okteto` namespace logs that are available in Cloud Logging. + +## How to Check That Your Okteto Instance is Healthy +### 1. Sanity check the Okteto Helm release + +On your terminal, run the following commands to check the status of your Okteto Helm release: + +```bash +helm list -n okteto +helm get values "okteto" -n okteto -o yaml +``` + +The following are sample outputs of the commands: + + + +```bash +~ % helm list +NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION +okteto okteto 22 2025-10-02 10:26:07.428432 -0400 EDT deployed okteto-1.36.0 464e721e7 +``` + + + + +```bash +~ % helm get values "okteto" -n okteto -o yaml +buildkit: + persistence: + enabled: true +ingress: + annotations: + nginx.ingress.kubernetes.io/proxy-send-timeout: 180 +ingress-nginx: + controller: + config: + large-client-header-buffers: 4 100k + proxy-connect-timeout: "180" + proxy-read-timeout: "180" + proxy-send-timeout: "180" + extraArgs: + default-ssl-certificate: $(POD_NAMESPACE)/okteto-letsencrypt +insights: + enabled: true +license: +okteto-nginx: + controller: + config: + large-client-header-buffers: 4 100k + proxy-connect-timeout: "180" + proxy-read-timeout: "180" + proxy-send-timeout: "180" +registry: + storage: + filesystem: + persistence: + enabled: true +subdomain: jona.okteto.me +wildcardCertificate: + create: false + name: okteto-letsencrypt +``` + + + + + +### 2. Wait for workloads to become “Available” + +Check that all Deployments and StatefulSets have completed their rollouts and that all Pods are in the Ready state: + +```bash +# Deployments & StatefulSets rollouts +kubectl rollout status deploy -l app.kubernetes.io/instance="okteto" -n okteto --timeout=120s +kubectl rollout status sts -l app.kubernetes.io/instance="okteto" -n okteto --timeout=120s + +# All pods to Ready (every container ready) +kubectl wait pod -l app.kubernetes.io/instance="okteto" -n okteto --for=condition=Ready --timeout=180s +``` +If any of the commands hits the timeout, consider jumping to [Step 8. Anything looks bad?](#8-anything-looks-bad) to investigate further. + + +### 3. Spot Unhealthy Pods + +Check for Pods that are not in the Ready state or that have container restarts: + +```bash +# Pods not Ready +kubectl get pods -l app.kubernetes.io/instance="okteto" -n okteto --field-selector=status.phase!=Running -o wide + +# Restarts > 0 +kubectl get pods -l app.kubernetes.io/instance="okteto" -n okteto -o custom-columns='POD:.metadata.name,READY:.status.containerStatuses[*].ready,RESTARTS:.status.containerStatuses[*].restartCount'| (read; echo "$REPLY"; sort -k3 -nr) +``` + + +### 4. Inventory resources created by Okteto Helm release + +Check that all the resources created by the Okteto Helm release are in a healthy state: + +```bash +kubectl get all -l app.kubernetes.io/instance="okteto" +kubectl get ingress,service -l app.kubernetes.io/instance="okteto" +kubectl get cm,secret,pvc -l app.kubernetes.io/instance="okteto" +``` + +The following are sample outputs of the commands: + + + +```bash +~ % kubectl get all -l app.kubernetes.io/instance="okteto" +NAME READY STATUS RESTARTS AGE +pod/okteto-api-d6ccbfc8d-8fgb5 1/1 Running 0 3m7s +pod/okteto-api-d6ccbfc8d-bqrlp 1/1 Running 0 3m7s +pod/okteto-buildkit-8c96f331e1-0 1/1 Running 0 3m5s +pod/okteto-daemon-ggbh2 1/1 Running 0 3m8s +pod/okteto-daemon-hr8w4 1/1 Running 0 3m8s +pod/okteto-eventsexporter-0 1/1 Running 0 3m4s +pod/okteto-frontend-56d6fc4696-rblcn 1/1 Running 0 3m6s +pod/okteto-frontend-56d6fc4696-vlv5f 1/1 Running 0 3m6s +pod/okteto-ingress-nginx-controller-7bd8f79fbc-79gjs 1/1 Running 0 3m7s +pod/okteto-ingress-nginx-controller-7bd8f79fbc-hc9cq 1/1 Running 0 3m7s +pod/okteto-ingress-nginx-defaultbackend-88d58c8bd-9xr9g 1/1 Running 0 3m6s +pod/okteto-ingress-nginx-defaultbackend-88d58c8bd-z7zlf 1/1 Running 0 3m6s +pod/okteto-mutation-webhook-66548b9669-t9rcb 1/1 Running 0 3m5s +pod/okteto-mutation-webhook-66548b9669-z6k6w 1/1 Running 0 3m4s +pod/okteto-okteto-nginx-controller-7bb7686cdb-k5h5t 1/1 Running 0 3m7s +pod/okteto-okteto-nginx-controller-7bb7686cdb-w6jh9 1/1 Running 0 3m7s +pod/okteto-prepullimages-86c2t 4/4 Running 0 3m8s +pod/okteto-prepullimages-nt9g7 4/4 Running 0 3m8s +pod/okteto-redis-5998c6c5f4-c549r 1/1 Running 0 3m6s +pod/okteto-regcreds-6c7444697-4tvmh 1/1 Running 0 3m5s +pod/okteto-regcreds-6c7444697-r5r24 1/1 Running 0 3m6s +pod/okteto-registry-565bd4ff94-9skgf 1/1 Running 0 3m5s +pod/okteto-reloader-54d478cbbd-bzjb2 1/1 Running 0 3m7s +pod/okteto-ssh-agent-59dd765ff-5kk89 1/1 Running 0 3m5s +pod/okteto-ssh-agent-59dd765ff-kr4vt 1/1 Running 0 3m5s + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +service/okteto-api ClusterIP 34.118.228.121 8080/TCP 3m11s +service/okteto-buildkit ClusterIP 34.118.232.126 443/TCP 3m11s +service/okteto-cluster-endpoint ExternalName kubernetes.default.svc.cluster.local 443/TCP 3m9s +service/okteto-eventsexporter ClusterIP 34.118.227.140 8080/TCP 3m10s +service/okteto-frontend ClusterIP 34.118.230.239 8080/TCP 3m10s +service/okteto-ingress-nginx-controller LoadBalancer 34.118.239.1 34.11.21.218 80:32340/TCP,443:31322/TCP 3m12s +service/okteto-ingress-nginx-defaultbackend ClusterIP 34.118.238.41 80/TCP 3m10s +service/okteto-mutation-webhook ClusterIP 34.118.232.212 443/TCP 3m8s +service/okteto-okteto-nginx-controller ClusterIP 34.118.232.157 80/TCP,443/TCP 3m11s +service/okteto-redis ClusterIP 34.118.238.162 6379/TCP 3m9s +service/okteto-regcreds ClusterIP 34.118.230.229 443/TCP 3m9s +service/okteto-registry ClusterIP 34.118.227.250 5000/TCP 3m9s +service/okteto-ssh-agent ClusterIP 34.118.230.24 3000/TCP 3m8s + +NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE +daemonset.apps/okteto-daemon 2 2 2 2 2 3m8s +daemonset.apps/okteto-prepullimages 2 2 2 2 2 3m8s + +NAME READY UP-TO-DATE AVAILABLE AGE +deployment.apps/okteto-api 2/2 2 2 3m7s +deployment.apps/okteto-frontend 2/2 2 2 3m6s +deployment.apps/okteto-ingress-nginx-controller 2/2 2 2 3m8s +deployment.apps/okteto-ingress-nginx-defaultbackend 2/2 2 2 3m7s +deployment.apps/okteto-mutation-webhook 2/2 2 2 3m5s +deployment.apps/okteto-okteto-nginx-controller 2/2 2 2 3m7s +deployment.apps/okteto-redis 1/1 1 1 3m6s +deployment.apps/okteto-regcreds 2/2 2 2 3m6s +deployment.apps/okteto-registry 1/1 1 1 3m6s +deployment.apps/okteto-reloader 1/1 1 1 3m7s +deployment.apps/okteto-ssh-agent 2/2 2 2 3m5s + +NAME DESIRED CURRENT READY AGE +replicaset.apps/okteto-api-d6ccbfc8d 2 2 2 3m7s +replicaset.apps/okteto-frontend-56d6fc4696 2 2 2 3m6s +replicaset.apps/okteto-ingress-nginx-controller-7bd8f79fbc 2 2 2 3m7s +replicaset.apps/okteto-ingress-nginx-defaultbackend-88d58c8bd 2 2 2 3m6s +replicaset.apps/okteto-mutation-webhook-66548b9669 2 2 2 3m5s +replicaset.apps/okteto-okteto-nginx-controller-7bb7686cdb 2 2 2 3m7s +replicaset.apps/okteto-redis-5998c6c5f4 1 1 1 3m6s +replicaset.apps/okteto-regcreds-6c7444697 2 2 2 3m6s +replicaset.apps/okteto-registry-565bd4ff94 1 1 1 3m5s +replicaset.apps/okteto-reloader-54d478cbbd 1 1 1 3m7s +replicaset.apps/okteto-ssh-agent-59dd765ff 2 2 2 3m5s + +NAME READY AGE +statefulset.apps/okteto-buildkit-8c96f331e1 1/1 3m5s +statefulset.apps/okteto-eventsexporter 1/1 3m5s + +NAME SCHEDULE TIMEZONE SUSPEND ACTIVE LAST SCHEDULE AGE +cronjob.batch/okteto-destroy-all-checker */3 * * * * False 0 103s 3m5s +cronjob.batch/okteto-gc @hourly False 0 3m5s +cronjob.batch/okteto-insights-metrics */5 * * * * False 0 103s 3m5s +cronjob.batch/okteto-installer-checker */5 * * * * False 0 103s 3m5s +cronjob.batch/okteto-periodic-metrics @hourly False 0 3m4s +cronjob.batch/okteto-resourcemanager */5 * * * * False 0 103s 3m4s +cronjob.batch/okteto-telemetry @daily False 0 3m4s +``` + + + +```bash +~ % kubectl get ingress,service -l app.kubernetes.io/instance="okteto" +NAME CLASS HOSTS ADDRESS PORTS AGE +ingress.networking.k8s.io/okteto okteto-controlplane-nginx okteto.jona.okteto.me 34.21.79.137 80, 443 202d +ingress.networking.k8s.io/okteto-buildkit okteto-controlplane-nginx buildkit.jona.okteto.me 34.21.79.137 80, 443 202d +ingress.networking.k8s.io/okteto-cluster-endpoint okteto-controlplane-nginx kubernetes.jona.okteto.me 34.21.79.137 80, 443 202d +ingress.networking.k8s.io/okteto-registry okteto-controlplane-nginx registry.jona.okteto.me 34.21.79.137 80, 443 202d +ingress.networking.k8s.io/okteto-wildcard okteto-controlplane-nginx *.jona.okteto.me 34.21.79.137 80, 443 202d + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +service/okteto-api ClusterIP 34.118.233.67 8080/TCP 202d +service/okteto-buildkit ClusterIP 34.118.236.79 443/TCP 202d +service/okteto-cluster-endpoint ExternalName kubernetes.default.svc.cluster.local 443/TCP 202d +service/okteto-eventsexporter ClusterIP 34.118.230.3 8080/TCP 202d +service/okteto-frontend ClusterIP 34.118.232.147 8080/TCP 202d +service/okteto-ingress-nginx-controller LoadBalancer 34.118.231.219 34.21.79.137 80:31270/TCP,443:32017/TCP 202d +service/okteto-ingress-nginx-defaultbackend ClusterIP 34.118.230.224 80/TCP 202d +service/okteto-mutation-webhook ClusterIP 34.118.233.42 443/TCP 202d +service/okteto-okteto-nginx-controller ClusterIP 34.118.228.30 80/TCP,443/TCP 202d +service/okteto-redis-headless ClusterIP None 6379/TCP 202d +service/okteto-redis-master ClusterIP 34.118.228.154 6379/TCP 202d +service/okteto-regcreds ClusterIP 34.118.226.123 443/TCP 202d +service/okteto-registry ClusterIP 34.118.225.14 5000/TCP 202d +service/okteto-ssh-agent ClusterIP 34.118.232.197 3000/TCP 202d + +NAME DATA AGE +configmap/okteto 167 202d +configmap/okteto-helm-release-meta 6 91d +configmap/okteto-ingress-config 1 202d +configmap/okteto-ingress-nginx-controller 15 202d +configmap/okteto-okteto-nginx-controller 14 202d +configmap/okteto-preflight 1 202d +configmap/okteto-redactor 1 202d +configmap/okteto-redis-configuration 4 202d +configmap/okteto-redis-health 6 202d +configmap/okteto-redis-scripts 1 202d +configmap/okteto-registry-config 1 202d +configmap/okteto-support-bundle 1 202d + +NAME TYPE DATA AGE +secret/okteto Opaque 2 202d +secret/okteto-mutation-webhook kubernetes.io/tls 3 202d +secret/okteto-regcreds kubernetes.io/tls 3 202d +secret/okteto-registry-http-secret Opaque 1 202d + +NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS VOLUMEATTRIBUTESCLASS AGE +persistentvolumeclaim/storage-okteto-buildkit-7c80387317-0 Bound pvc-79219185-22de-4ccb-acd8-3228b3bb7323 100Gi RWO standard-rwo 86d +persistentvolumeclaim/storage-okteto-buildkit-7c80387317-1 Bound pvc-9e19e7f8-6f2f-4685-8a2d-dc340f4639e1 100Gi RWO standard-rwo 86d +``` + + + + +```bash +~ % kubectl get cm,secret,pvc -l app.kubernetes.io/instance="okteto" +NAME DATA AGE +configmap/okteto 167 202d +configmap/okteto-helm-release-meta 6 91d +configmap/okteto-ingress-config 1 202d +configmap/okteto-ingress-nginx-controller 15 202d +configmap/okteto-okteto-nginx-controller 14 202d +configmap/okteto-preflight 1 202d +configmap/okteto-redactor 1 202d +configmap/okteto-redis-configuration 4 202d +configmap/okteto-redis-health 6 202d +configmap/okteto-redis-scripts 1 202d +configmap/okteto-registry-config 1 202d +configmap/okteto-support-bundle 1 202d + +NAME TYPE DATA AGE +secret/okteto Opaque 2 202d +secret/okteto-mutation-webhook kubernetes.io/tls 3 202d +secret/okteto-regcreds kubernetes.io/tls 3 202d +secret/okteto-registry-http-secret Opaque 1 202d + +NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS VOLUMEATTRIBUTESCLASS AGE +persistentvolumeclaim/storage-okteto-buildkit-7c80387317-0 Bound pvc-79219185-22de-4ccb-acd8-3228b3bb7323 100Gi RWO standard-rwo 86d +persistentvolumeclaim/storage-okteto-buildkit-7c80387317-1 Bound pvc-9e19e7f8-6f2f-4685-8a2d-dc340f4639e1 100Gi RWO standard-rwo 86d +``` + + + + + +### 5. Check that services have endpoints + +Verify that all Services have healthy Endpoints: + +```bash +kubectl get svc -l app.kubernetes.io/instance="okteto" -n okteto + +kubectl get endpoints -l app.kubernetes.io/instance="okteto" -n okteto +``` + +The following are sample outputs of the commands: + + + + +```bash +~ % kubectl get svc -l app.kubernetes.io/instance="okteto" -n okteto +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +okteto-api ClusterIP 34.118.233.67 8080/TCP 234d +okteto-buildkit ClusterIP 34.118.236.79 443/TCP 234d +okteto-cluster-endpoint ExternalName kubernetes.default.svc.cluster.local 443/TCP 234d +okteto-eventsexporter ClusterIP 34.118.230.3 8080/TCP 234d +okteto-frontend ClusterIP 34.118.232.147 8080/TCP 234d +okteto-ingress-nginx-controller LoadBalancer 34.118.231.219 34.21.79.137 80:31270/TCP,443:32017/TCP 234d +okteto-ingress-nginx-defaultbackend ClusterIP 34.118.230.224 80/TCP 234d +okteto-mutation-webhook ClusterIP 34.118.233.42 443/TCP 234d +okteto-okteto-nginx-controller ClusterIP 34.118.228.30 80/TCP,443/TCP 234d +okteto-redis ClusterIP 34.118.227.133 6379/TCP 20d +okteto-regcreds ClusterIP 34.118.226.123 443/TCP 234d +okteto-registry ClusterIP 34.118.225.14 5000/TCP 234d +okteto-ssh-agent ClusterIP 34.118.232.197 3000/TCP 234d +``` + + + + +```bash +~ % kubectl get endpoints -l app.kubernetes.io/instance="okteto" -n okteto +NAME ENDPOINTS AGE +okteto-api 10.112.0.9:8080,10.112.2.16:8080 234d +okteto-buildkit 10.112.2.29:1234 234d +okteto-eventsexporter 10.112.0.215:8080 234d +okteto-frontend 10.112.0.10:8080,10.112.2.17:8080 234d +okteto-ingress-nginx-controller 10.112.0.11:443,10.112.2.18:443,10.112.0.11:80 + 1 more... 234d +okteto-ingress-nginx-defaultbackend 10.112.0.16:8080,10.112.2.19:8080 234d +okteto-mutation-webhook 10.112.0.13:8443,10.112.2.20:8443 234d +okteto-okteto-nginx-controller 10.112.0.15:443,10.112.2.21:443,10.112.0.15:80 + 1 more... 234d +okteto-redis 10.112.0.14:6379 20d +okteto-regcreds 10.112.0.17:9443,10.112.2.22:9443 234d +okteto-registry 10.112.2.30:5000 234d +okteto-ssh-agent 10.112.0.19:3000,10.112.2.23:3000 234d +``` + + + + + +### 6. Validate your DNS configuration + +Verify that the Okteto subdomain is resolving and accessible: + +```bash +curl -i --max-time 5 "https://okteto./healthz" +``` + +### 7. Test your Okteto Instance End-to-End + +Go through the build, deploy, and up commands with the Movies Okteto sample to test that Okteto deployments are working as expected: + +```bash +git clone https://github.com/okteto/movies +cd movies +okteto build +okteto deploy +okteto up +``` + +### 8. Anything looks bad? + +Check the events and describe the failing Pods or other resources to gather more information about what might be wrong: + +```bash +# a) Events (cluster is telling you what’s wrong) +kubectl get events -n okteto --sort-by=.lastTimestamp | tail -n 40 + +# b) Describe the failing thing (image pulls, scheduling, probe failures) +kubectl describe pod +``` + +## Daemon fails with “open /etc/hosts: permission denied” + +If the `okteto-daemon` pods fail with an error like: + +```json +{“level”:”fatal”,”service”:”daemon”,”error”:”open /etc/hosts: permission denied”,”timestamp”:”...”,”message”:”tasks initialization failed”} +``` + +This means the node's operating system does not allow Okteto to modify the `/etc/hosts` file. Okteto requires write access to `/etc/hosts` on cluster nodes to configure [internal registry resolution](self-hosted/helm-configuration.mdx#overrideregistryresolution). + +**This commonly happens when using an unsupported node OS**, such as [Bottlerocket](https://aws.amazon.com/bottlerocket/) on AWS EKS. Bottlerocket uses a read-only root filesystem, which prevents Okteto from writing to `/etc/hosts`. + +To resolve this issue: + +1. **Switch to a supported node OS.** On AWS EKS, use Amazon Linux 2023 (AL2023) or Amazon Linux 2 (AL2). See [Amazon EKS installation requirements](get-started/install/amazon-eks.mdx) for details. +2. **Recreate your node group** with the supported AMI family. For example, using `eksctl`: + ```bash + eksctl create nodegroup \ + --cluster="${CLUSTER_NAME}" \ + --region="${AWS_REGION}" \ + --node-type="m5.xlarge" \ + --node-ami-family="AmazonLinux2023" + ``` +3. **Drain and delete the old node group** running the unsupported OS. + +## UPGRADE FAILED: “okteto” has no deployed releases + +This error will occur on your second install/upgrade if your initial install failed. If the first install failed, delete the existing install before trying again: + +``` +helm uninstall okteto +``` + +## Registry pods keep restarting + +This can happen when the pods can't read/write from your cloud storage bucket. Double check that the cloud IAM you created has read/write access to the specified bucket. + +## Deployment pipelines stay in "progressing" forever + +This can happen for several reasons, among others, the installer job couldn't be started due to an error in Kubernetes API, or due to an overload in the cluster. +In order to find out what the problem is, there's a way to list all the jobs and pods for a specific pipeline. + +You need the pipeline name (it is the name displayed on Okteto UI) and the namespace where it is deployed. With that information, you can get jobs and pods running these commands: + +```bash +kubectl get jobs -l=dev.okteto.com/pipeline-name=movies -l=dev.okteto.com/pipeline-namespace=cindy --namespace=okteto +``` + +```bash +kubectl get pods -l=dev.okteto.com/pipeline-name=movies -l=dev.okteto.com/pipeline-namespace=cindy --namespace=okteto +``` + +The [`installerChecker`](self-hosted/helm-configuration.mdx#installerchecker) CronJob clears deploys that get stuck in this state. If a pipeline stays in `progressing`, check its recent runs for details. + +## Using a Custom CNI + +If you're using a custom CNI on your cluster then there may be some additional configuration needed for webhooks. +In certain cases the CNI used on the worker nodes is not the same as the CNI used by the control plane and host networking will need to be used for webhooks. +In addition, the ports may need to be changed to avoid collisions. + +The Okteto Webhook is configured by setting`webhook.hostNetwork` to `true`. The ports are set with `webhook.port`. +More information on the Okteto Webhook configuration can be found [here](self-hosted/helm-configuration.mdx#webhook). + +## Docker Hub credentials misconfiguration + +As you can [configure your own Docker Hub account](admin/dashboard.mdx#registry-credentials) in Okteto, it could happen that the credentials are not properly set. If that is the case, kubelet won't be able to pull public images from Docker Hub, which can be an important issue in the cluster. + +If this ever happens in your cluster, there is a way to fix it: +- [Update the container image used by the daemonset pods](self-hosted/helm-configuration.mdx#daemonset). **Important note**, use a container registry different than Docker Hub to pull the image without credential problems. For example, you can use `ghcr.io/okteto/busybox`. +- Change or remove the credentials for the Docker Hub registry. +- [Upgrade your cluster](self-hosted/manage/upgrade.mdx) with the new configuration. + +After this, the Okteto daemonset will be able to configure the right credentials for Docker Hub. Once you verify everything is working, you can restore the original base image for the Okteto daemonset. + +## We are here to help + +[Reach out to us](https://community.okteto.com/), we're always happy to help! diff --git a/versioned_docs/version-1.37/self-hosted/manage/uninstall-okteto.mdx b/versioned_docs/version-1.49/self-hosted/manage/uninstall-okteto.mdx similarity index 98% rename from versioned_docs/version-1.37/self-hosted/manage/uninstall-okteto.mdx rename to versioned_docs/version-1.49/self-hosted/manage/uninstall-okteto.mdx index d6eee6b5e..b667aa85a 100644 --- a/versioned_docs/version-1.37/self-hosted/manage/uninstall-okteto.mdx +++ b/versioned_docs/version-1.49/self-hosted/manage/uninstall-okteto.mdx @@ -9,7 +9,7 @@ id: uninstall-okteto To delete an existing release use: -```console +```bash helm uninstall okteto ``` diff --git a/versioned_docs/version-1.37/self-hosted/manage/upgrade.mdx b/versioned_docs/version-1.49/self-hosted/manage/upgrade.mdx similarity index 81% rename from versioned_docs/version-1.37/self-hosted/manage/upgrade.mdx rename to versioned_docs/version-1.49/self-hosted/manage/upgrade.mdx index 4346ce22c..16b93d99f 100644 --- a/versioned_docs/version-1.37/self-hosted/manage/upgrade.mdx +++ b/versioned_docs/version-1.49/self-hosted/manage/upgrade.mdx @@ -17,7 +17,7 @@ To ensure a successful Okteto upgrade, we recommend testing it on a dedicated te ### How to Upgrade To upgrade a new release, modify the `config.yaml` with your desired changes and then use: -```console +```bash helm repo update helm upgrade okteto okteto/okteto -f config.yaml --namespace=okteto --version ``` @@ -35,6 +35,55 @@ _You can use `helm ls` to find the name of your release._ Please review [the release notes](release-notes.mdx) before upgrading. New features, known issues, and configuration changes will be listed there. +## 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 + +If you need to continue pulling images from Docker Hub, add the following configuration to your Helm values file (`config.yaml`): + +```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 using: + + + { +`helm repo update +helm upgrade okteto okteto/okteto -f config.yaml --namespace=okteto --version ${variables.chartVersion} +`} + + +:::tip +If you need to use a different registry (neither ghcr.io nor docker.io), see our [Air-Gapped Networks guide](air-gapped.mdx) for instructions on configuring a custom registry. +::: + +## Upgrading to Okteto 1.38.x – Certificate Configuration Changes + +- **Internal Certificate Unification**: Internal certificates have been unified into a [single configuration](self-hosted/helm-configuration.mdx#internalcertificate). During the upgrade, you may experience temporary communication issues lasting a few seconds as the new certificate configuration takes effect. This is expected behavior and should resolve automatically. +- **ArgoCD Installations**: If you manage your Okteto installation with ArgoCD, review our [Argo CD guide](self-hosted/manage/argocd.mdx). The certificate unification may require special attention during the ArgoCD sync process 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](self-hosted/helm-configuration.mdx#redis). @@ -96,7 +145,7 @@ To avoid installation errors, use the `defaultBackend.nameOverride` setting to s ## Upgrading to Okteto 1.25.x – CLI 3.0.0 Upgrade -Starting with the [1.25 release](release-notes.mdx#1250), 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](https://www.okteto.com/blog/cli-three-release/) before upgrading your cluster. +Starting with the [1.25 release](archived-release-notes.mdx#1250), 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](https://www.okteto.com/blog/cli-three-release/) before upgrading your cluster. ## Upgrading to Okteto 1.22.x – Role & Binding Config Migration diff --git a/versioned_docs/version-1.37/testing/getting-started-test.mdx b/versioned_docs/version-1.49/testing/getting-started-test.mdx similarity index 99% rename from versioned_docs/version-1.37/testing/getting-started-test.mdx rename to versioned_docs/version-1.49/testing/getting-started-test.mdx index 2bd83c8b5..d76ee2863 100644 --- a/versioned_docs/version-1.37/testing/getting-started-test.mdx +++ b/versioned_docs/version-1.49/testing/getting-started-test.mdx @@ -199,7 +199,7 @@ The Test Container to run integration tests looks like this: ```yaml title="okteto.yaml" test: e2e: - image: okteto/playwright:chromium + image: ghcr.io/okteto/playwright:chromium context: e2e caches: - yarn/.cache diff --git a/versioned_docs/version-1.37/testing/index.mdx b/versioned_docs/version-1.49/testing/index.mdx similarity index 86% rename from versioned_docs/version-1.37/testing/index.mdx rename to versioned_docs/version-1.49/testing/index.mdx index b5b769fb7..2579e713f 100644 --- a/versioned_docs/version-1.37/testing/index.mdx +++ b/versioned_docs/version-1.49/testing/index.mdx @@ -11,12 +11,12 @@ Okteto Test is a new feature designed to seamlessly integrate testing into your ## Why Okteto Test? -This is how the software development process looks like for application based on microservicies before adopting Okteto: +This is how the software development process looks like for application based on microservices before adopting Okteto:

@@ -29,7 +29,7 @@ After adopting Okteto for Development Environments, this is how the software dev

@@ -40,7 +40,7 @@ But there's still a gap: CI is running on a different platform. Why not leverage

diff --git a/versioned_docs/version-1.49/variables.json b/versioned_docs/version-1.49/variables.json new file mode 100644 index 000000000..7afe67a68 --- /dev/null +++ b/versioned_docs/version-1.49/variables.json @@ -0,0 +1,7 @@ +{ + "kubernetesMinVersion": "1.34", + "kubernetesMaxVersion": "1.36", + "cliVersion": "3.24.0", + "chartVersion": "1.49.0", + "syncthingVersion": "2.1.3" +} diff --git a/versioned_sidebars/version-1.37-sidebars.json b/versioned_sidebars/version-1.49-sidebars.json similarity index 87% rename from versioned_sidebars/version-1.37-sidebars.json rename to versioned_sidebars/version-1.49-sidebars.json index 244f4491d..d1e92d7f6 100644 --- a/versioned_sidebars/version-1.37-sidebars.json +++ b/versioned_sidebars/version-1.49-sidebars.json @@ -22,6 +22,7 @@ "get-started/install/digitalocean-doks", "get-started/install/google-gke", "get-started/install/microsoft-aks", + "get-started/install/nutanix-nkp", "get-started/install/openshift" ] }, @@ -42,8 +43,11 @@ { "type": "category", "label": "For Developers", + "link": { + "type": "doc", + "id": "get-started/dev-quickstart" + }, "items": [ - "get-started/dev-quickstart", "get-started/using-okteto-cli-and-dashboard", "get-started/advanced-commands-and-concepts" ] @@ -52,7 +56,11 @@ }, { "type": "category", - "label": "Core concepts", + "label": "Core Concepts", + "link": { + "type": "doc", + "id": "core/index" + }, "items": [ { "type": "category", @@ -72,6 +80,7 @@ ] }, "core/namespaces", + "core/divert", "core/build-service", "core/okteto-insights-dashboards", "core/okteto-manifest", @@ -82,6 +91,31 @@ "core/use-volume-snapshots" ] }, + { + "type": "category", + "label": "AI Agent Environments", + "link": { + "type": "generated-index", + "title": "AI Agent Environments", + "description": "Give AI agents isolated, production-like environments to build, test, and verify their changes against real services and data. Connect your own agent tooling to Okteto environments with Agentic Workflows.", + "slug": "/ai-agent-environments" + }, + "items": [ + { + "type": "category", + "label": "Agentic Workflows", + "link": { + "type": "doc", + "id": "agentic/index" + }, + "items": [ + "agentic/collaborative-workflows", + "agentic/autonomous-workflows", + "agentic/best-practices" + ] + } + ] + }, { "type": "category", "label": "Development Environments", @@ -91,6 +125,7 @@ }, "items": [ "development/using-okteto-cli", + "development/using-divert", { "type": "category", "label": "Development Containers", @@ -147,17 +182,6 @@ } ] }, - { - "type": "category", - "label": "Okteto Test", - "link": { - "type": "doc", - "id": "testing/index" - }, - "items": [ - "testing/getting-started-test" - ] - }, { "type": "category", "label": "Preview Environments", @@ -172,15 +196,13 @@ }, { "type": "category", - "label": "Okteto AI", + "label": "Okteto Test", "link": { "type": "doc", - "id": "okteto-ai/index" + "id": "testing/index" }, "items": [ - "okteto-ai/index", - "okteto-ai/ai-getting-started", - "okteto-ai/okteto-ai-admin-config" + "testing/getting-started-test" ] }, { @@ -192,7 +214,9 @@ }, "items": [ "admin/dashboard", + "admin/billing", "admin/catalog", + "admin/build-service", "admin/custom-installer-image", "admin/cleanup", "admin/ssh-known-hosts", @@ -231,6 +255,7 @@ }, "admin/okteto-api", "admin/okteto-insights", + "admin/previews", { "type": "category", "label": "Private Repositories", @@ -312,6 +337,18 @@ "self-hosted/install/auth/token" ] }, + { + "type": "category", + "label": "Configure Divert", + "link": { + "type": "doc", + "id": "self-hosted/install/divert/index" + }, + "items": [ + "self-hosted/install/divert/linkerd-installation", + "self-hosted/install/divert/istio-installation" + ] + }, "self-hosted/install/github-integration", "self-hosted/install/volume-snapshots" ] diff --git a/versions.json b/versions.json index 32522b299..67b9d7123 100644 --- a/versions.json +++ b/versions.json @@ -1,4 +1,5 @@ [ + "1.49", "1.48", "1.47", "1.46", @@ -9,6 +10,5 @@ "1.41", "1.40", "1.39", - "1.38", - "1.37" + "1.38" ] From cb97fd2ec2372670a0f2877c06c89ffb7eb9251f Mon Sep 17 00:00:00 2001 From: Nacho Fuertes Date: Thu, 8 Oct 2026 14:07:34 +0200 Subject: [PATCH 2/2] Archive 1.37 release notes in the 1.49 snapshot The official version is served from versioned_docs/version-1.49, so moving the 1.37 notes only in src/content left them in the live release notes and out of the live archive. Apply the same move to the snapshot. Reorder the README versioning steps so the release notes are archived before running docs:version, which keeps future snapshots consistent. Co-Authored-By: Claude Opus 5.5 (1M context) Signed-off-by: Nacho Fuertes --- README.md | 40 ++++++------ .../version-1.49/archived-release-notes.mdx | 64 +++++++++++++++++++ versioned_docs/version-1.49/release-notes.mdx | 64 ------------------- 3 files changed, 84 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index 7fe50771d..a0ae68723 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,14 @@ Example: } ``` -### Step 2: Create the New Version +### Step 2: Archive Old Release Notes + +Move the oldest version's release notes from active to archived. Do this before creating the new version so the snapshot includes the archived notes; the official version is served from the snapshot, not from `src/content`. The oldest version is the last item in [`versions.json`](versions.json). + +1. **Cut the oldest version section** from the bottom of [`src/content/release-notes.mdx`](src/content/release-notes.mdx) +2. **Paste it at the top** of [`src/content/archived-release-notes.mdx`](src/content/archived-release-notes.mdx) (after the intro paragraph, before other versions) + +### Step 3: Create the New Version Run the docusaurus version command with the new version number: @@ -87,7 +94,7 @@ This command will: - Create `versioned_sidebars/version-1.XX-sidebars.json` with the sidebar config - Add `1.XX` to the top of `versions.json` -### Step 3: Update docusaurus.config.js +### Step 4: Update docusaurus.config.js Modify the `presets.docs.versions` section of [`docusaurus.config.js`](docusaurus.config.js): @@ -121,7 +128,7 @@ Modify the `presets.docs.versions` section of [`docusaurus.config.js`](docusauru 5. **Remove the oldest version entry** from the `versions` object. The object lists only the official version and the five versions before it, so its oldest entry is not the oldest version in `versions.json`. For example, when releasing `1.41`, remove the `'1.35'` entry. Versions in `versions.json` without an entry still build with the default label, path, and `unmaintained` banner. -### Step 4: Update netlify.toml Redirects +### Step 5: Update netlify.toml Redirects Update the redirect rules at the bottom of [`netlify.toml`](netlify.toml): @@ -149,7 +156,7 @@ Update the redirect rules at the bottom of [`netlify.toml`](netlify.toml): status = 302 ``` -### Step 5: Update archives.md +### Step 6: Update archives.md Update [`src/pages/archives.md`](src/pages/archives.md): @@ -167,7 +174,7 @@ Update [`src/pages/archives.md`](src/pages/archives.md): 3. **Remove the oldest version** from the "Previously released versions" table -### Step 6: Remove the Oldest Version Files +### Step 7: Remove the Oldest Version Files Identify the oldest version from `versions.json` (should be at the bottom) and remove its files: @@ -179,13 +186,6 @@ rm -rf versioned_sidebars/version-1.29-sidebars.json **Manually remove the oldest version** from [`versions.json`](versions.json) (remove from the bottom of the array). -### Step 7: Archive Old Release Notes - -Move the oldest version's release notes from active to archived: - -1. **Cut the oldest version section** from the bottom of [`src/content/release-notes.mdx`](src/content/release-notes.mdx) -2. **Paste it at the top** of [`src/content/archived-release-notes.mdx`](src/content/archived-release-notes.mdx) (after the intro paragraph, before other versions) - ### Step 8: Verify the Build Run the build to catch any broken links or anchors: @@ -225,26 +225,26 @@ For agents or scripts automating this process, here are the key parameters: **Files to modify:** 1. **src/content/variables.json** - Update with new release values -2. **Run command:** `yarn run docusaurus docs:version {NEW_VERSION}` -3. **docusaurus.config.js:** +2. **src/content/release-notes.mdx** - Cut bottom section for `{OLDEST_VERSION}` +3. **src/content/archived-release-notes.mdx** - Paste `{OLDEST_VERSION}` section at top (after intro). Steps 2 and 3 must run before the snapshot in step 4, which copies both files into `versioned_docs/version-{NEW_VERSION}/` +4. **Run command:** `yarn run docusaurus docs:version {NEW_VERSION}` +5. **docusaurus.config.js:** - `lastVersion: '{NEW_VERSION}'` - `current.label: '{NEXT_VERSION}'` - `current.path: '{NEXT_VERSION}'` - Add `'{NEW_VERSION}': { label: '{NEW_VERSION}', path: '/', banner: 'none' }` at top of versions - Change `'{PREV_VERSION}'` path from `'/'` to `'{PREV_VERSION}'` and banner from `'none'` to `'unmaintained'` - Remove the oldest entry from versions, which is `NEW_VERSION - 6` (e.g., `'1.35'` when releasing `1.41`). This is not `{OLDEST_VERSION}`: the config lists only the official version and the five before it -4. **netlify.toml:** +6. **netlify.toml:** - Official redirect: `from = "/docs/{NEW_VERSION}/*"` - Unreleased redirect: `to = "/docs/{NEXT_VERSION}/:splat"` - Add deprecated redirect: `from = "/docs/{OLDEST_VERSION}/*"` -5. **src/pages/archives.md:** +7. **src/pages/archives.md:** - Update current version table to `{NEW_VERSION}` - Add `{PREV_VERSION}` to previous versions table - Remove `{OLDEST_VERSION}` from previous versions table -6. **Delete files:** `versioned_docs/version-{OLDEST_VERSION}/` and `versioned_sidebars/version-{OLDEST_VERSION}-sidebars.json` -7. **versions.json** - Remove `{OLDEST_VERSION}` from array (should be last item) -8. **src/content/release-notes.mdx** - Cut bottom section for `{OLDEST_VERSION}` -9. **src/content/archived-release-notes.mdx** - Paste `{OLDEST_VERSION}` section at top (after intro) +8. **Delete files:** `versioned_docs/version-{OLDEST_VERSION}/` and `versioned_sidebars/version-{OLDEST_VERSION}-sidebars.json` +9. **versions.json** - Remove `{OLDEST_VERSION}` from array (should be last item) 10. **Run:** `yarn build` to verify **Version count:** Maintain exactly 12 versions in `versions.json` after completion. diff --git a/versioned_docs/version-1.49/archived-release-notes.mdx b/versioned_docs/version-1.49/archived-release-notes.mdx index acff9a089..0cabc5af8 100644 --- a/versioned_docs/version-1.49/archived-release-notes.mdx +++ b/versioned_docs/version-1.49/archived-release-notes.mdx @@ -7,6 +7,70 @@ id: archived-release-notes Here you can find the release notes for archived versions of Okteto. +## 1.37.3 + +21 November 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) + +### Bug Fixes + +- [Okteto CLI 3.12.3](https://github.com/okteto/okteto/releases/tag/3.12.3): Fixed a timeout error contacting with the SSH agent on remote deploys when some of the commands defined in the Okteto Manifest were performing SSH operations + +## 1.37.2 + +15 October 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) + +### Bug Fixes {#bug-fixes-1.37} + +- Fixed repository cloning failures with SSH host verification - Resolved conflicts between automatic SSH scanning and admin-configured known hosts that could cause deployment failures. + +## 1.37.1 + +7 October 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) + +### Improvements {#improvements-1.37.1} + +- Upgrade Redis to 8.2.2 to fix [CVE-2025-49844](https://www.wiz.io/blog/wiz-research-redis-rce-cve-2025-49844) + +## 1.37.0 + +1 October 2025 + +This version is compatible with Kubernetes versions 1.31 to 1.33 \ +Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) + +### Breaking Changes {#breaking-changes-1.37} + +- Removed the dependency on the Bitnami Redis Helm chart. Okteto now ships its own Kubernetes templates to deploy Redis. As part of this change, the workload has been updated from a StatefulSet to a Deployment, and the available Redis configuration options [have been reduced and standardized](self-hosted/helm-configuration.mdx#redis). If you previously customized Redis using Bitnami-specific values, review and update your Helm values to align with the supported configuration before upgrading. +- We've changed the [default value of `pullAlways` to **false**](self-hosted/helm-configuration.mdx#pullalways) for pods deployed in Okteto-managed namespaces. This speeds up pod creation when images are already present on the node, while still allowing `pullAlways` to be explicitly enabled if needed + +### New Features {#new-features-1.37} + +- Added a centralized [Known Hosts feature to the Admin UI](admin/ssh-known-hosts.mdx) (Admin → Settings → Known Hosts). Admins can now pin trusted SSH host keys and disable automatic ssh-keyscan, ensuring secure, consistent cloning of repositories and submodules without custom runner images + +### Improvements {#improvements-1.37} + +- Improved error handling in the Okteto AI Agent UI for API errors and "Prompt too long" warnings +- Temporal rate limit (QPS exceeded) errors now return as "progressing" instead of failing immediately +- We've renamed AI Agent Fleets to Okteto AI throughout the product +- [Okteto CLI 3.12.0](https://github.com/okteto/okteto/releases/tag/3.12.0): Updated Syncthing to 2.0.x for improved synchronization performance +- [Okteto CLI 3.12.0](https://github.com/okteto/okteto/releases/tag/3.12.0): Added support for `endpoint_mode` in Compose files ([see documentation](reference/docker-compose.mdx#endpoint_mode-string-optional)). + +### Bug Fixes {#bug-fixes-1.37} + +- Fixed issues with endpoint handling in the Okteto AI Agent view, including non-scrollable lists and incorrect display of custom endpoints +- Fixed an "unable to load agent" error when returning focus to the window +- Fixed autoscroll behavior when sending a new prompt in the Agent UI +- [Okteto CLI 3.12.0](https://github.com/okteto/okteto/pull/4760): Improved CLI stability by waiting for SSE when streaming logs for pipeline, preview, deploy, and destroy operations + ## 1.36.2 12 September 2025 diff --git a/versioned_docs/version-1.49/release-notes.mdx b/versioned_docs/version-1.49/release-notes.mdx index 12ea7c9b4..2d572508e 100644 --- a/versioned_docs/version-1.49/release-notes.mdx +++ b/versioned_docs/version-1.49/release-notes.mdx @@ -406,67 +406,3 @@ Okteto Chart release 1.38 is designed to work with [Okteto CLI 3.13.x](https://g - [Okteto CLI 3.13.0](https://github.com/okteto/okteto/releases/tag/3.13.0): Fixed nil pointer exception in build command when the specified Dockerfile doesn't exist - [Okteto CLI 3.13.0](https://github.com/okteto/okteto/releases/tag/3.13.0): Improved error handling in log streaming during resource destruction as logs were not being fully displayed - [Okteto CLI 3.13.0](https://github.com/okteto/okteto/releases/tag/3.13.0): Fixed cache isolation in `okteto test` where different test containers sharing the same cached directory could reuse each other's cache. Caches are now properly isolated and only reused across executions of the same test container - -## 1.37.3 - -21 November 2025 - -This version is compatible with Kubernetes versions 1.31 to 1.33 \ -Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) - -### Bug Fixes - -- [Okteto CLI 3.12.3](https://github.com/okteto/okteto/releases/tag/3.12.3): Fixed a timeout error contacting with the SSH agent on remote deploys when some of the commands defined in the Okteto Manifest were performing SSH operations - -## 1.37.2 - -15 October 2025 - -This version is compatible with Kubernetes versions 1.31 to 1.33 \ -Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) - -### Bug Fixes {#bug-fixes-1.37} - -- Fixed repository cloning failures with SSH host verification - Resolved conflicts between automatic SSH scanning and admin-configured known hosts that could cause deployment failures. - -## 1.37.1 - -7 October 2025 - -This version is compatible with Kubernetes versions 1.31 to 1.33 \ -Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) - -### Improvements {#improvements-1.37.1} - -- Upgrade Redis to 8.2.2 to fix [CVE-2025-49844](https://www.wiz.io/blog/wiz-research-redis-rce-cve-2025-49844) - -## 1.37.0 - -1 October 2025 - -This version is compatible with Kubernetes versions 1.31 to 1.33 \ -Okteto Chart release 1.37 is designed to work with [Okteto CLI 3.12.x](https://github.com/okteto/okteto/releases/tag/3.12.0) - -### Breaking Changes {#breaking-changes-1.37} - -- Removed the dependency on the Bitnami Redis Helm chart. Okteto now ships its own Kubernetes templates to deploy Redis. As part of this change, the workload has been updated from a StatefulSet to a Deployment, and the available Redis configuration options [have been reduced and standardized](self-hosted/helm-configuration.mdx#redis). If you previously customized Redis using Bitnami-specific values, review and update your Helm values to align with the supported configuration before upgrading. -- We've changed the [default value of `pullAlways` to **false**](self-hosted/helm-configuration.mdx#pullalways) for pods deployed in Okteto-managed namespaces. This speeds up pod creation when images are already present on the node, while still allowing `pullAlways` to be explicitly enabled if needed - -### New Features {#new-features-1.37} - -- Added a centralized [Known Hosts feature to the Admin UI](admin/ssh-known-hosts.mdx) (Admin → Settings → Known Hosts). Admins can now pin trusted SSH host keys and disable automatic ssh-keyscan, ensuring secure, consistent cloning of repositories and submodules without custom runner images - -### Improvements {#improvements-1.37} - -- Improved error handling in the Okteto AI Agent UI for API errors and "Prompt too long" warnings -- Temporal rate limit (QPS exceeded) errors now return as "progressing" instead of failing immediately -- We've renamed AI Agent Fleets to Okteto AI throughout the product -- [Okteto CLI 3.12.0](https://github.com/okteto/okteto/releases/tag/3.12.0): Updated Syncthing to 2.0.x for improved synchronization performance -- [Okteto CLI 3.12.0](https://github.com/okteto/okteto/releases/tag/3.12.0): Added support for `endpoint_mode` in Compose files ([see documentation](reference/docker-compose.mdx#endpoint_mode-string-optional)). - -### Bug Fixes {#bug-fixes-1.37} - -- Fixed issues with endpoint handling in the Okteto AI Agent view, including non-scrollable lists and incorrect display of custom endpoints -- Fixed an "unable to load agent" error when returning focus to the window -- Fixed autoscroll behavior when sending a new prompt in the Agent UI -- [Okteto CLI 3.12.0](https://github.com/okteto/okteto/pull/4760): Improved CLI stability by waiting for SSE when streaming logs for pipeline, preview, deploy, and destroy operations