# Okteto Documentation ## docs - [Search the documentation](/docs/search.md) - [Tutorials](/docs/tutorials.md) - [AWS Lambda functions with Okteto](/docs/tutorials/aws-lambda.md): Deploy an AWS Lambda function in your development environment - [Docker Compose on Kubernetes](/docs/tutorials/compose-getting-started.md): Develop an application with Okteto using Docker Compose files - [Use Volume Snapshots to Create Development Environments with Real Data](/docs/tutorials/create-and-use-volume-snapshots.md): Learn how to generate volume snapshots of an application’s database, and how to use it when creating a new Development Environment. - [Getting started with Okteto Divert](/docs/tutorials/divert.md): Simplify your Development Environments with Divert - [Getting started with Okteto External Resources](/docs/tutorials/external-resources.md): Include external resources in your development environments - [Getting started with Okteto](/docs/tutorials/getting-started-with-okteto.md): A step by step guide to configure an Okteto Manifest - [Optimize your Okteto Development Environment](/docs/tutorials/optimize-your-development-environment.md): Our recommendations on how to optimize your Okteto Environments - [Getting started with Preview Environments](/docs/tutorials/preview-environments.md): Deploy a Preview Environment for every pull request using GitHub Actions - [Using LaunchDarkly and Okteto To Automate Feature Flag Management](/docs/tutorials/using-launchdarkly-and-okteto-to-automate-modern-feature-flag-management.md): Leverage feature flags during development with LaunchDarkly and Okteto - [Configure Webpack to work inside a container](/docs/tutorials/webpack.md): Optimize your configurations to work inside a Docker container - [Okteto Administration](/docs/admin.md): Administering your Okteto instance - [Billing](/docs/admin/billing.md): 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. - [Build Service Management](/docs/admin/build-service.md): Monitor and manage BuildKit performance and resource utilization - [Catalog ScaleEnterpriseSelf-Hosted](/docs/admin/catalog.md): Administrators can create a Catalog of pre-defined development environments for developers to use. - [Garbage Collector](/docs/admin/cleanup.md): The Garbage Collector helps keep your infra costs under control by sleeping or deleting inactive environments. - [Cloud Credentials](/docs/admin/cloud-credentials.md): Manage and configure cloud credentials for your Okteto instance - [Configure access to your AWS account using IAM Roles](/docs/admin/cloud-credentials/aws-cloud-credentials.md): Configure AWS IAM credentials for your Okteto instance using OIDC federation to grant development environments access to AWS resources. - [Configure access to your GCP account using Workload ID](/docs/admin/cloud-credentials/gcp-cloud-credentials.md): Configure Google Cloud credentials for your Okteto instance using Workload Identity Federation to grant development environments access to GCP resources. - [Custom Installer Image](/docs/admin/custom-installer-image.md): Use a custom installer image to deploy your Development Environments - [Admin Dashboard ScaleEnterpriseSelf-Hosted](/docs/admin/dashboard.md): The Admin Dashboard provides a centralized interface to manage users, Namespaces, integrations, and settings for your Okteto instance. - [Okta User Deprovisioning](/docs/admin/integrations/okta-user-deprovisioning.md): Automatically deprovision okteto users when they are removed from Okta - [Okteto API Documentation](/docs/admin/okteto-api.md): Programmatic access to resources managed by Okteto - [Okteto Insights](/docs/admin/okteto-insights.md): Configure Okteto Insights for detailed analytics on resource usage, build, and deployment metrics - [Managing Preview Environments ScaleEnterpriseSelf-Hosted](/docs/admin/previews.md): Manage Preview Environments from the Admin Dashboard - [GitHub](/docs/admin/private-repositories/github-app.md): Use our GitHub Integration so your users can access private repositories in their development environments - [Authenticating with an SSH Key ScaleEnterpriseSelf-Hosted](/docs/admin/private-repositories/ssh-key.md): Use an SSH key so your users can access private repositories in their development environments - [Registry Credentials](/docs/admin/registry-credentials.md): Manage and configure your registry credentials - [Amazon ECR](/docs/admin/registry-credentials/amazon-ecr.md): Get Private Registry credentials from Amazon ECR - [Azure Container Registry](/docs/admin/registry-credentials/azure-acr.md): Get Private Registry credentials from Azure Container Registry - [DockerHub](/docs/admin/registry-credentials/dockerhub.md): Get Private Registry credentials from DockerHub - [Google Artifact Registry](/docs/admin/registry-credentials/google-artifact-registry.md): Get Private Registry credentials from Google Artifact Registry - [Resource Manager](/docs/admin/resource-manager.md): Automated resource management that adapts to changes in real utilization over time - [SSH Known Hosts](/docs/admin/ssh-known-hosts.md): Centrally manage trusted known hosts for SSH connections in Okteto - [Agentic Workflows](/docs/agentic.md): Install the Okteto plugin for Claude Code to give AI agents the knowledge to deploy, test, and debug code in Okteto environments - [Autonomous Workflows](/docs/agentic/autonomous-workflows.md): How AI agents handle the full development lifecycle from ticket to pull request using Okteto - [Best Practices and Troubleshooting](/docs/agentic/best-practices.md): Common pitfalls when using AI agents with Okteto and how to avoid them - [Collaborative Workflows](/docs/agentic/collaborative-workflows.md): How developers and AI agents work together using okteto up and okteto exec - [AI Agent Environments](/docs/ai-agent-environments.md): Give AI agents isolated, production-like environments to build, test, and verify their changes against real services and data. Launch managed agents from the Okteto Dashboard with Okteto AI, or connect your own agent tooling with Agentic Workflows. - [Archived Release Notes](/docs/archived-release-notes.md): Release notes from archived Okteto versions that are no longer actively maintained, covering features and changes from older releases. - [The Okteto Platform](/docs/byoc-vs-self-hosted.md): The difference between Okteto's Bring Your Own Cloud (BYOC) and Self-Hosted product offerings - [Okteto Bring Your Own Cloud (BYOC)](/docs/byoc.md): Introduction to Okteto Bring Your Own Cloud (BYOC) - [Okteto BYOC on AWS](/docs/byoc/aws.md): How to get started with Okteto BYOC on AWS - [Okteto BYOC on GCP](/docs/byoc/gcp.md): How to get started with Okteto BYOC on GCP - [Core Concepts](/docs/core.md): Okteto organizes development around Namespaces, credentials, networking, builds, and a central manifest. - [Okteto Build Service](/docs/core/build-service.md): The Okteto Build Service allows you to build your container images remotely - [Okteto Registry](/docs/core/container-registry.md): The Okteto Registry allows every Okteto Namespace to have its own space to store its container images - [Environment Variables](/docs/core/credentials/environment-variables.md): Specify your credentials using environment variables - [Download your Kubernetes credentials](/docs/core/credentials/kubernetes-credentials.md): Download your Kubernetes credentials and start developing your applications in Okteto - [Personal Access Tokens](/docs/core/credentials/personal-access-tokens.md): Use Personal Access Tokens to Interact with the Okteto API - [Divert](/docs/core/divert.md): Intelligent traffic routing for efficient microservice development - [Automatic SSL endpoints](/docs/core/endpoints/automatic-ssl.md): Automatically create an SSL endpoint for your deployments - [Private endpoints](/docs/core/endpoints/private-endpoints.md): Restrict access to your application's endpoints - [Okteto Namespaces](/docs/core/namespaces.md): Organize your Development Environments with Okteto Namespaces for you and your team - [Okteto Insights Dashboards](/docs/core/okteto-insights-dashboards.md): Use Okteto Insights for detailed analytics on resource usage, build, and deployment metrics - [Okteto Manifest Overview](/docs/core/okteto-manifest.md): An overview of the Okteto Manifest and its core features. - [Okteto Variables](/docs/core/okteto-variables.md): Okteto Variables allows you to save application configuration in Okteto and automatically inject them during deployment time - [Remote Execution](/docs/core/remote-execution.md): How Okteto runs your commands in the cluster - [Volume Snapshots in Development Environments](/docs/core/use-volume-snapshots.md): Okteto Volume Snapshots let you initialize persistent volumes from previous snapshots to populate Development Environments with production or staging data. - [User Roles and Permissions in Okteto](/docs/core/user-roles-and-permissions.md): Understand User Roles and Permissions in the Okteto Platform - [Development Environments on Kubernetes](/docs/development.md): Okteto Development Environments let you code locally while your application runs on Kubernetes, with real-time file sync and hot reload. - [Development Containers](/docs/development/containers.md): In this section, we'll see how you can use Development Containers on Okteto - [File Sync Mode](/docs/development/containers/file-sync.md): In this section, we'll see how you can use File Sync mode to develop on Okteto - [Getting Started with Okteto and ASP.NET](/docs/development/containers/file-sync/aspnetcore.md): This tutorial will show you how to develop and debug an ASP.NET application using Okteto - [Getting Started with Okteto and Go](/docs/development/containers/file-sync/golang.md): This tutorial will show you how to develop and debug a Go application using Okteto - [Getting Started with Okteto and Java](/docs/development/containers/file-sync/java.md): This tutorial will show you how to develop and debug a Java application using Okteto - [Getting Started with Okteto and Node.js](/docs/development/containers/file-sync/node.md): This tutorial will show you how to develop and debug a Node.js application using Okteto - [Getting Started with Okteto and PHP](/docs/development/containers/file-sync/php.md): This tutorial will show you how to develop and debug a PHP application using Okteto - [Getting Started with Okteto and Python](/docs/development/containers/file-sync/python.md): This tutorial will show you how to develop and debug a Python application using Okteto - [Getting Started with Okteto and Ruby](/docs/development/containers/file-sync/ruby.md): This tutorial will show you how to develop and debug a Ruby application using Okteto - [Hybrid Development Mode](/docs/development/containers/hybrid.md): In this section, you'll see how you can use using hybrid mode to develop on Okteto - [Getting Started with Hybrid Mode for Frontend Development](/docs/development/containers/hybrid/hybrid-frontend.md): This tutorial will show you how to develop a frontend service using hybrid mode - [Getting Started with Hybrid Mode for Java Development](/docs/development/containers/hybrid/hybrid-java.md): This tutorial will show you how to develop a java service using hybrid mode - [Deploy your Development Environments](/docs/development/deploy.md): In this section, we'll learn different ways to deploy your Development Environment - [Deploy Development Environments from your Catalog ScaleEnterpriseSelf-Hosted](/docs/development/deploy/deploy-from-catalog.md): Deploy development environments directly from your Catalog - [Deploy your Development Environments from your Git Repositories](/docs/development/deploy/deploy-from-git.md): Deploy your development environments directly from your Git repositories - [Develop On Okteto Button](/docs/development/deploy/develop-on-okteto-button.md): Deploy your development environments from your Git repositories - [From private repositories](/docs/development/deploy/from-private-repositories.md): Deploy your development environments from your private Git repositories - [Development images](/docs/development/images.md): Configure development images for your Development Containers - [Using Divert](/docs/development/using-divert.md): Practical guide for implementing Divert in your development workflow - [Using the Okteto CLI](/docs/development/using-okteto-cli.md): Introduction to Okteto CLI - [Advanced Commands & Concepts for Developers](/docs/get-started/advanced-commands-and-concepts.md): Introduction to development concepts within Okteto - [Deploy Your Application to Okteto](/docs/get-started/deploy-your-app.md): In this section, we'll see how you can onboard your apps to Okteto - [Build your container images with Okteto](/docs/get-started/deploy-your-app/build.md): In this section, you'll see how you can build your container images with Okteto - [Add a database as a dependency](/docs/get-started/deploy-your-app/dependencies.md): In this section, we'll see how you can deploy dependencies on other repositories - [Deploy your application](/docs/get-started/deploy-your-app/deploy.md): In this section, we'll show you how to configure Okteto to deploy your app - [Expose your application on a public endpoint](/docs/get-started/deploy-your-app/endpoints.md): In this section, we'll see how to expose your app on public endpoints - [Using Okteto as a Developer](/docs/get-started/dev-quickstart.md): This guide will help you to get started with Okteto as a developer - [Install the Okteto CLI](/docs/get-started/install-okteto-cli.md): This guide will help you get started by installing the Okteto CLI - [Installation Overview](/docs/get-started/install.md): How to install Okteto in your Kubernetes cluster - [Amazon Elastic Kubernetes Service (EKS)](/docs/get-started/install/amazon-eks.md): How to install Okteto onto Amazon Elastic Kubernetes Service (EKS) - [Civo](/docs/get-started/install/civo.md): How to install Okteto onto Civo - [DigitalOcean Kubernetes (DOKS)](/docs/get-started/install/digitalocean-doks.md): How to install Okteto onto DigitalOcean Kubernetes - [Google Kubernetes Engine (GKE)](/docs/get-started/install/google-gke.md): How to install Okteto onto Google Kubernetes Engine (GKE) - [Azure Kubernetes Service (AKS)](/docs/get-started/install/microsoft-aks.md): How to install Okteto onto Azure Kubernetes Service (AKS) - [Red Hat OpenShiftEnterpriseSelf-Hosted](/docs/get-started/install/openshift.md): How to install Okteto onto Red Hat OpenShift - [Using the Okteto CLI and Dashboard](/docs/get-started/using-okteto-cli-and-dashboard.md): Introduction to the Okteto CLI and Dashboard - [Okteto AI](/docs/okteto-ai.md): Launch and manage AI agents from the Okteto Dashboard to develop, test, and debug code in sandboxed environments - [Okteto AI - Getting Started](/docs/okteto-ai/ai-getting-started.md): Launch your first AI agent from the Okteto Dashboard and learn how to get the best results - [Okteto AI - Admin Configuration Guide](/docs/okteto-ai/okteto-ai-admin-config.md): In this section, we will show you how to configure Okteto AI for your team - [Preview Environments](/docs/previews.md): Create a preview environment for your application using Okteto - [Preview environments using GitHub Actions](/docs/previews/using-github-actions.md): Create a preview environment for your application using Okteto and GitHub Actions - [Preview environments using GitLab CI/CD](/docs/previews/using-gitlab-cicd.md): Configure GitLab CI/CD to automatically create Preview Environments for your application using Okteto. - [References](/docs/reference.md): Explore Okteto reference documentation including CLI commands, the Okteto Manifest schema, environment variables, and configuration options. - [Docker Compose Reference](/docs/reference/docker-compose.md): Okteto allows you to develop applications using docker-compose files - [Frequently Asked Questions (FAQs)](/docs/reference/faqs.md): Frequently asked questions about Okteto - [Feature Flags](/docs/reference/feature-flags.md): Okteto's feature flags on the CLI - [File Synchronization](/docs/reference/file-synchronization.md): Okteto keeps your local files synchronized with your development environment - [Known Issues](/docs/reference/known-issues.md): Known issues and workarounds for Okteto development environments, including hot-reload limitations and Windows terminal compatibility. - [Migrating to Okteto CLI 2.0](/docs/reference/manifest-migration.md): 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. - [Okteto CLI](/docs/reference/okteto-cli.md): The Okteto Command Line Interface is a unified tool to manage your development environments - [Okteto Manifest Reference](/docs/reference/okteto-manifest.md): Okteto's Manifest for describing development environments - [SSH Server](/docs/reference/ssh-server.md): Okteto runs an SSH server in your development container - [Supported GitHub Actions](/docs/reference/supported-github-actions.md): Automate your development workflows using GitHub Actions and Okteto - [Release notes](/docs/release-notes.md): Latest features, bug fixes, breaking changes, and improvements in each Okteto release, with Kubernetes compatibility details. - [Okteto Self-Hosted](/docs/self-hosted.md): Introduction to Okteto Self-Hosted - [Getting started after deploying Okteto on DigitalOcean](/docs/self-hosted/digitalocean/marketplace.md): Configure your Okteto instance after deploying from the DigitalOcean Marketplace. Set up DNS, authentication, and connect your Kubernetes cluster. - [Helm Configuration](/docs/self-hosted/helm-configuration.md): List of configuration settings for Okteto - [Authentication](/docs/self-hosted/install/auth.md): Configure your authentication provider - [Use Azure AD as your Authentication Provider](/docs/self-hosted/install/auth/azure-ad.md): Use Azure AD as the authentication provider of your Okteto Self-hosted instance - [Use Bitbucket as your Authentication Provider](/docs/self-hosted/install/auth/bitbucket.md): Use Bitbucket as the authentication provider of your Okteto Self-hosted instance - [Use GitHub as your Authentication Provider](/docs/self-hosted/install/auth/github.md): Use GitHub as the authentication provider of your Okteto Self-hosted instance - [Use Gitlab as your Authentication Provider](/docs/self-hosted/install/auth/gitlab.md): Use Gitlab as the authentication provider of your Okteto Self-hosted instance - [Use Google as your Authentication Provider](/docs/self-hosted/install/auth/google.md): Use Google as the authentication provider of your Okteto Self-hosted instance - [Use Okta as your Authentication Provider](/docs/self-hosted/install/auth/okta.md): Use Okta as the authentication provider of your Okteto Self-hosted instance - [Use OpenID Connect (OIDC) as your Authentication Provider](/docs/self-hosted/install/auth/openid-connect.md): Use OpenID Connect (OIDC) as the authentication provider of your Okteto Self-hosted instance - [Use Tokens as your Authentication Provider](/docs/self-hosted/install/auth/token.md): Use Tokens as the authentication provider of your Okteto Self-hosted instance - [Configure the Okteto Wildcard Certificate](/docs/self-hosted/install/certificates.md): Configure your certificates with Okteto - [Setting up certificates with AWS ACM](/docs/self-hosted/install/certificates/aws-acm.md): Setting up certificates with AWS ACM - [Bring your own Wildcard Certificate](/docs/self-hosted/install/certificates/bring-your-own-certificate.md): Bring your own wildcard certificate - [Setting up certificates with cert-manager and Let’s Encrypt](/docs/self-hosted/install/certificates/cert-manager.md): Configure TLS certificates for Okteto Self-Hosted using cert-manager and Let’s Encrypt. - [Configure Divert](/docs/self-hosted/install/divert.md): Admin guide for configuring Divert drivers in self-hosted Okteto - [Istio Installation for Divert](/docs/self-hosted/install/divert/istio-installation.md): Install Istio to use the Istio driver for Divert routing in Okteto - [Linkerd Installation for Divert](/docs/self-hosted/install/divert/linkerd-installation.md): Install Linkerd to enhance Divert routing capabilities with the nginx driver - [GitHub integration](/docs/self-hosted/install/github-integration.md): Use our GitHub Integration so your users can access private repositories in their development environments - [Configure the Okteto Registry with external storage](/docs/self-hosted/install/okteto-registry-storage.md): Configure the Okteto Registry with external storage - [Okteto Registry with Amazon S3 Bucket](/docs/self-hosted/install/okteto-registry-storage/aws-s3-bucket.md): Configure the Okteto Registry with Amazon S3 Bucket - [Okteto Registry with Azure Storage Container](/docs/self-hosted/install/okteto-registry-storage/azure-storage-container.md): Configure the Okteto Registry with Azure Storage Container - [Okteto Registry with DigitalOcean Spaces](/docs/self-hosted/install/okteto-registry-storage/digitalocean-spaces.md): Configure the Okteto Registry with DigitalOcean Spaces - [Okteto Registry with Filesystem storage](/docs/self-hosted/install/okteto-registry-storage/filesystem.md): Configure the Okteto Registry with Filesystem storage - [Okteto Registry with Google Cloud Storage](/docs/self-hosted/install/okteto-registry-storage/google-cloud-storage.md): Configure the Okteto Registry with Google Cloud Storage - [Volume Snapshots for Self-Hosted Okteto](/docs/self-hosted/install/volume-snapshots.md): Install and configure a CSI driver and VolumeSnapshotClass to enable the Volume Snapshots feature on your Self-Hosted Okteto instance. - [Air-Gapped Network EnvironmentsEnterpriseSelf-Hosted](/docs/self-hosted/manage/air-gapped.md): Installing Okteto in Air-Gapped Network Environments - [Configure Argo CD](/docs/self-hosted/manage/argocd.md): How to Install Okteto in Argo CD - [ARM Support](/docs/self-hosted/manage/arm-support.md): How to install and configure Okteto on ARM-based Kubernetes clusters - [Backup and Restore](/docs/self-hosted/manage/backup.md): Backup and Restore your Okteto instance - [Configuring BuildKit for High Performance](/docs/self-hosted/manage/buildkit-high-performance.md): Configuring BuildKit for High Performance - [Custom Resource Definitions](/docs/self-hosted/manage/custom-resource-definitions.md): Custom resource definitions (CRDs) installed by Okteto - [Diagnostics](/docs/self-hosted/manage/diagnostics.md): Okteto Diagnostics - [Okteto License](/docs/self-hosted/manage/okteto-license.md): How to obtain and install your Okteto license key. For how billing works and how seats are counted, see the Billing page. - [Troubleshoot your Okteto instance](/docs/self-hosted/manage/troubleshooting.md): Questions and answers to common issues when installing or upgrading your Okteto instance - [Uninstalling Okteto](/docs/self-hosted/manage/uninstall-okteto.md): How to uninstall Okteto from your Kubernetes cluster - [Upgrade your Okteto instance](/docs/self-hosted/manage/upgrade.md): How to upgrade your Okteto instance - [Welcome to Okteto Test](/docs/testing.md): In this section, we'll see how you can use Test Containers on Okteto - [Getting started with Okteto Test](/docs/testing/getting-started-test.md): In this section, we'll see how you configure Test Containers for your application - [Okteto: the environment platform for agentic development](/docs/index.md): 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. --- # Full Documentation Content > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. [Skip to main content](#__docusaurus_skipToContent_fallback) [![Okteto Logo](/docs/img/logo.svg)![Okteto Logo](/docs/img/logo.svg)](https://www.okteto.com) Search [Product](https://www.okteto.com)[Blog](https://www.okteto.com/blog/)[Community](https://community.okteto.com) [1.46](#) - [1.47 (Unreleased)](/docs/1.47/) - [1.46 (Latest release)](/docs.md) - [1.45](/docs/1.45/) - [1.44](/docs/1.44/) - [1.43](/docs/1.43/) - [1.42](/docs/1.42/) - [1.41](/docs/1.41/) - [1.40](/docs/1.40/) - *** - [Archives](/docs/archives/) - [Release Notes](/docs/release-notes.md) [Get Started](https://www.okteto.com/free-trial) # Search the documentation Type your search here 1.47 (current) Powered by[](https://www.algolia.com/) Docs * [Installation Guide](/docs/get-started/install.md) * [Getting Started Guide](/docs/get-started/deploy-your-app.md) * [Okteto Manifest](/docs/core/okteto-manifest.md) * [Okteto CLI Reference](/docs/reference/okteto-cli.md) * [Release Notes](/docs/release-notes.md) Resources * [Blog](https://www.okteto.com/blog/) * [Community](https://community.okteto.com) * [GitHub](https://github.com/okteto/okteto) * [YouTube](https://www.youtube.com/@OktetoHQ) * [Pricing](https://www.okteto.com/pricing) * [llms.txt](https://www.okteto.com/docs/llms.txt) Contact Us * * [Twitter](https://twitter.com/oktetohq) * [Get 30 Days Free](https://www.okteto.com/free-trial) Copyright © 2026 Okteto, Inc. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Tutorials [](/docs/tutorials/getting-started-with-okteto.md) Getting started with Okteto A step by step guide to configure an Okteto Manifest ![Getting started with Okteto](/docs/img/logos/okteto.svg) [](/docs/tutorials/preview-environments.md) Getting started with Preview Environments Deploy a Preview Environment for every pull request using GitHub Actions ![Getting started with Preview Environments](/docs/img/logos/okteto.svg) [](/docs/tutorials/aws-lambda.md) AWS Lambda functions with Okteto Deploy an AWS Lambda function in your development environment ![AWS Lambda functions with Okteto](/docs/img/logos/aws.svg) [](/docs/tutorials/compose-getting-started.md) Docker Compose on Kubernetes Develop an application with Okteto using Docker Compose files ![Docker Compose on Kubernetes](/docs/img/logos/docker.svg) [](/docs/tutorials/external-resources.md) Getting started with Okteto External Resources Include external resources in your development environments ![Getting started with Okteto External Resources](/docs/img/logos/okteto.svg) [](/docs/tutorials/webpack.md) Configure Webpack to work inside a container Optimize your configurations to work inside a Docker container ![Configure Webpack to work inside a container](/docs/img/logos/webpack.svg) [](/docs/tutorials/using-launchdarkly-and-okteto-to-automate-modern-feature-flag-management.md) Using LaunchDarkly and Okteto To Automate Feature Flag Management Leverage feature flags during development with LaunchDarkly and Okteto ![Using LaunchDarkly and Okteto To Automate Feature Flag Management](/docs/img/logos/launchdarkly.svg) [](/docs/tutorials/divert.md) Getting started with Okteto Divert Simplify your Development Environments with Divert ![Getting started with Okteto Divert](/docs/img/logos/okteto.svg) [](/docs/tutorials/optimize-your-development-environment.md) Optimize your Okteto Development Environment Our recommendations on how to optimize your Okteto Environments ![Optimize your Okteto Development Environment](/docs/img/logos/okteto.svg) [](/docs/tutorials/create-and-use-volume-snapshots.md) Use Volume Snapshots to Create Development Environments with Real Data Learn how to generate volume snapshots of an application’s database, and how to use it when creating a new Development Environment. ![Use Volume Snapshots to Create Development Environments with Real Data](/docs/img/logos/okteto.svg) --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # AWS Lambda functions with Okteto This tutorial will show you how to deploy a Development Environment in Okteto that contains an AWS Lambda function with Okteto. We use [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam-overview.html) to create the Lambda function in this tutorial. You can find the code for the sample app we work with for this tutorial [here](https://github.com/okteto/aws-lambda). If you'd like to see an alternate approach using [Terraform](https://www.terraform.io/) instead of AWS SAM CLI, checkout this [sample app](https://github.com/okteto-community/aws-lambda-with-terraform). ## Prerequisites * Access to an Okteto instance * Access to an AWS account with the permissions to create IAMs ## Step 1: Configure Cloud Credentials Okteto needs sufficient permissions to make necessary AWS service calls and manage AWS resources to create the Lambda Function in your AWS account. This can be done by [configuring Cloud Credentials](/docs/admin/cloud-credentials/aws-cloud-credentials.md). Make sure to give the following permissions to the IAM role you create when configuring Cloud Credentials: * AWSCloudFormationFullAccess * IAMFullAccess * AWSLambda\_FullAccess * AmazonAPIGatewayAdministrator * AmazonS3FullAccess ## Step 2: Create your Okteto manifest In order to deploy a Lambda function in Okteto, you need to create an Okteto manifest. If you clone our [sample app](https://github.com/okteto/aws-lambda), you'll find a starter Okteto Manifest there which looks like this: okteto.yaml ``` deploy: image: okteto/aws-sam commands: - name: build function command: sam build - name: deploy function command: | sam deploy --no-confirm-changeset --no-fail-on-empty-changeset --s3-prefix "${OKTETO_NAMESPACE}" --stack-name "${OKTETO_NAMESPACE}-okteto-lambda" --resolve-s3 FUNCTION_URL=$(aws cloudformation describe-stacks --region us-east-1 --stack-name ${OKTETO_NAMESPACE}-okteto-lambda --query "Stacks[0].Outputs[0].OutputValue" --output text) # use external resources to display the URL in the Okteto UI echo "OKTETO_EXTERNAL_LAMBDA_ENDPOINTS_FUNCTION_URL=$FUNCTION_URL" >> $OKTETO_ENV destroy: image: okteto/aws-sam commands: - name: destroy function command: sam delete --no-prompts --stack-name "${OKTETO_NAMESPACE}-okteto-lambda" --region us-east-1 external: lambda: icon: function endpoints: - name: function ``` info This manifest takes advantage of our [External Resources](/docs/tutorials/external-resources.md) feature manage the lifecycle of external resources as part of your Okteto development environment. [Learn more about External Resources here](/docs/tutorials/external-resources.md). Details: * The `deploy.image` field tells Okteto to use the image `okteto/aws-sam` which contains the AWS SAM CLI required to run the deploy commands. This image is present on [our Docker Hub image registry](https://hub.docker.com/r/okteto/aws-sam). Feel free to create your own image and use it here instead in case you need other tooling. * The `deploy.commands` section includes all the commands needed to build and deploy the function. * The `destroy` section includes the commands needed to destroy the Lambda function. This will be invoked when the environment or the namespace are destroyed. ## Step 3: Deploy your Development Environment Deploy your Development Environment by running the following command: ``` okteto deploy ``` After a few seconds, your Development Environment will be fully deployed and your AWS Lambda function will be up and running. Every time you redeploy the Development Environment, the AWS Lambda function will be recreated with your latest code. The source code used on this tutorial [is available here](https://github.com/okteto/aws-lambda). ## Next steps Congratulations, you just deployed **your first AWS Lambda function in Okteto** 🚀. Head over to our getting started guides for [Go](/docs/development/containers/file-sync/golang.md), [ASP.NET](/docs/development/containers/file-sync/aspnetcore.md), [Java](/docs/development/containers/file-sync/java.md), [Node.js](/docs/development/containers/file-sync/node.md), [PHP](/docs/development/containers/file-sync/php.md), [Python](/docs/development/containers/file-sync/python.md), or [Ruby](/docs/development/containers/file-sync/ruby.md) to see how to integrate it with the rest of your applications. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Docker Compose on Kubernetes This tutorial will show you how to develop an application with Okteto using Docker Compose files. [Docker Compose](/docs/reference/docker-compose.md) are for developers who don't want to deal with the complexities of Kubernetes manifests. Okteto implements and extends the [Compose Specification](https://github.com/compose-spec/compose-spec) to make it easy to develop Docker Compose applications on Kubernetes. ## Prerequisites * Install the Okteto CLI. Follow this [guide](/docs/development/using-okteto-cli.md) if you haven't done it yet. * Configure Access to your Okteto Namespace [using the Okteto CLI](/docs/core/credentials/kubernetes-credentials.md#download-your-kubernetes-credentials-using-the-okteto-cli) or [using the Okteto dashboard](/docs/core/credentials/kubernetes-credentials.md). ## Step 1: Deploy your Development Environment Get a local version of the Sample App by executing the following commands: ``` $ git clone https://github.com/okteto/compose-getting-started $ cd compose-getting-started ``` The Sample App is a simple web application implemented using Python, with Redis for storage. The `docker-compose.yml` file defines the components of the Sample App: ``` services: vote: build: vote scale: 2 environment: - FLASK_ENV=development command: python app.py ports: - 8080:8080 volumes: - ./vote:/src redis: image: redis ports: - 6379 volumes: - redis:/data volumes: redis: ``` The equivalent Kubernetes manifests would have more than 300 lines of yaml! Deploying the Sample App is as simple as executing this command: ``` $ okteto deploy ``` ``` i Using cindy @ okteto.example.com as context ✓ Deploying compose i Endpoints available: - https://vote-cindy.okteto.example.com/ ✓ Development environment 'compose-getting-started' successfully deployed ``` The `deploy` command will create the necessary deployments, services, persistent volumes, and ingress rules needed to run the Sample App. Cool no 😎? Open your browser and go to the URL of your development environment, shown as part of the `okteto deploy` logs ( in this case). ## Step 2: Developing time! In order to hot-reload your application in your remote development environment, run the this command: ``` $ okteto up vote ``` ``` i Using cindy @ okteto.example.com as context i Development environment 'compose-getting-started' already deployed. i To redeploy your development environment run 'okteto deploy' or 'okteto up vote --deploy' ✓ Persistent volume successfully attached ✓ Images successfully pulled ✓ Files synchronized Context: okteto.example.com Namespace: cindy Name: vote Forward: 8080 -> 8080 * Serving Flask app 'app' (lazy loading) * Environment: development * Debug mode: on * Running on all addresses. WARNING: This is a development server. Do not use it in a production deployment. * Running on http://10.8.35.69:8080/ (Press CTRL+C to quit) * Restarting with stat * Debugger is active! * Debugger PIN: 838-277-059 ``` From this moment, all you code changes will be immediately synched and hot-reloaded by your development environment. For example, open the `vote/app.py` file in your IDE and modify the voting options on lines 16-17. ``` def getOptions(): option_a = "Local development" option_b = "Cloud development" ``` Save your changes. Check the output of your development environment: ``` * Detected change in '/src/app.py', reloading * Restarting with stat * Debugger is active! * Debugger PIN: 838-277-059 ``` Access the URL of your application again. Your code changes were instantly applied. No commit, build, or push required! ## Next steps Congratulations, you just developed **your first application with Okteto** 🚀. Read the docs for the [Docker Compose](/docs/reference/docker-compose.md) and the [available Okteto CLI commands](/docs/reference/okteto-cli.md) to learn more about developing your Docker Compose application on Okteto. Head over to [our getting started guides](/docs/development/containers.md) to see how to configure Okteto to live-update your application with different programming languages and **debuggers**. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Use Volume Snapshots to Create Development Environments with Real Data Okteto Volume Snapshots allow you to initialize your development environments 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 without having to manually copying databases or execute error-prone seed scripts. tip Volume Snapshots are also useful for loading test data when running tests in Okteto Test. If your tests require a database with preloaded data, you can configure your test environment to restore from a snapshot instead of initializing an empty database. This ensures consistency across test runs and reduces setup time. In this tutorial, you'll: * ✅ deploy an application to Okteto * ✅ learn how to create a volume snapshot of the application's database * ✅ and then learn how to use it when creating a new Development Environment ## Prerequisites In order to follow this tutorial, you should have: * A **Kubernetes cluster with Okteto** installed * Familiarity with **Kubernetes manifests** * [kubectl](https://kubernetes.io/docs/tasks/tools/) installed on your machine * At least one [VolumeSnapshotClass](https://kubernetes.io/docs/concepts/storage/volume-snapshot-classes/) defined on your cluster. If you are on Okteto BYOC, you already have this. ## Step 1: Deploy the Sample Application For this tutorial, we’ll deploy a CRUD recipe application that stores data in MongoDB. Clone the repository: ``` $ git clone https://github.com/okteto/fastapi-snapshot-app $ cd fastapi-snapshot-app ``` In the `manifests` folder, the `k8s.yml` manifest file is responsible for the deployment of the application's service, and the `mongo.yml` manifest file is responsible for deploying the database service. The database service in this case is a MongoDB service. Deploy your development environment using the command below: ``` okteto deploy ``` Expected output: ``` ... Executing command 'Deploy Application'... persistentvolumeclaim/data created service/mongodb created statefulset.apps/mongodb created deployment.apps/fastapi-snapshot-demo created service/fastapi-snapshot-demo created Command 'Deploy Application' successfully executed ``` ![Okteto dashboard showing the fastapi-snapshot-app deployment with MongoDB, StatefulSet, and deployment logs](/docs/assets/images/deployed-73f895958b9f5b6f56c4590444003543.png) ✅ Your application is now running in Okteto. Take note of the **endpoint URL** under **Endpoints** in the Okteto Dashboard. ## Step 2: Populate the Application Database Before taking a snapshot, add sample data. This is the data that we'll be including in the Development Environments that we'll create in the next steps). ``` curl -X 'POST' \ 'https://fastapi-snapshot-demo-cindy.okteto.example.com/recipe' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "name": "Donuts", "ingredients": ["Flour", "Milk", "Sugar", "Vegetable Oil"] }' ``` ``` curl -X 'POST' \ 'https://fastapi-snapshot-demo-cindy.okteto.example.com/recipe' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "name": "Pancake", "ingredients": ["Flour", "Milk", "Sugar", "Baking Powder", "Vegetable Oil"] }' ``` Verify that the database has been populated by retrieving the list of recipes present: ``` curl -X 'GET' \ 'https://fastapi-snapshot-demo-cindy.okteto.example.com/recipe' \ -H 'accept: application/json' ``` Expected response: ``` { "data": [ { "id": "60ce68651eeddf1c5ab796d1", "name": "Donuts", "ingredients": [ "Flour", "Milk", "Sugar", "Vegetable Oil" ] }, { "id": "60ce689c1eeddf1c5ab796d2", "name": "Pancake", "ingredients": [ "Flour", "Milk", "Sugar", "Baking Powder", "Vegetable Oil" ] } ] } ``` ## Step 3: Create a Database Snapshot A Volume Snapshot will capture the database state at this moment. Create a new manifest file `snapshot.yml` in the `manifests` folder and add the following to it: ``` apiVersion: snapshot.storage.k8s.io/v1 kind: VolumeSnapshot metadata: name: mongo-snapshot spec: volumeSnapshotClassName: okteto-snapshot-class source: persistentVolumeClaimName: data ``` In the Volume Snapshot Manifest above, you are creating a Volume Snapshot named `mongo-snapshot`, the snapshot will be created from the persistent volume `data` which was created when deploying the development environment. Next, apply the Volume Snapshot from your terminal: ``` okteto kubeconfig kubectl apply -f manifests/snapshot.yml ``` ``` volumesnapshot.snapshot.storage.k8s.io/mongo-snapshot created ``` Finally, verify that the volume snapshot has been created successfully. ``` kubectl get volumesnapshot ``` ``` NAME READYTOUSE SOURCEPVC SOURCESNAPSHOTCONTENT RESTORESIZE SNAPSHOTCLASS SNAPSHOTCONTENT CREATIONTIME AGE mongo-snapshot true data 1Gi okteto-snapshot-class snapcontent-1b8d8e7a-0b09-43c5-adeb-a08005ffbb4d 32s 34s ``` ✅ Now we have a snapshot that can be used for new development environments! ## Step 4: Deploy a Development Environment Using the Snapshot ### 1. Create a New Namespace for Development ``` okteto namespace create namespace-with-snapshot ``` ### 2. Modify the Application Manifest to Use the Volume Snapshot Create a new folder in the parent directory and copy `k8s.yml` and `mongo.yml` into it: ``` mkdir manifests-with-snapshot cp manifests/{fastapi.yml,mongo.yml} manifests-with-snapshot ``` Update the `PersistentVolumeClaim` in the `mongo.yml` manifest to include the `dev.okteto.com/from-snapshot-name` and `dev.okteto.com/from-snapshot-namespace` annotations, as shown below, replacing $YOUR\_SOURCE\_NAMESPACE with the name of the Okteto namespace where you created the volume snapshot (e.g. cindy). ``` kind: PersistentVolumeClaim apiVersion: v1 metadata: name: data annotations: dev.okteto.com/from-snapshot-name: mongo-snapshot dev.okteto.com/from-snapshot-namespace: $YOUR_SOURCE_NAMESPACE spec: storageClassName: csi-okteto accessModes: - ReadWriteOnce resources: requests: storage: 1Gi ... ``` ### 3. Deploy the New Development Environment Using the Newly Created Manifest Duplicate your `okteto.yml` file: ``` cp okteto.yml okteto.with-snapshot.yml ``` And update it so that the deploy steps uses the new manifests: ``` build: fastapi: context: . deploy: - name: Deploy Application command: | kubectl apply -f manifests-with-snapshot/mongo.yml envsubst < manifests-with-snapshot/fastapi.yml | kubectl apply -f - ``` Deploy the environment on the new namespace: ``` okteto deploy -n=namespace-with-snapshot -f okteto.with-snapshot.yml ``` Expected output: ``` ... Executing command 'Deploy Application'... persistentvolumeclaim/data created service/mongodb created statefulset.apps/mongodb created deployment.apps/fastapi-snapshot-demo created service/fastapi-snapshot-demo created Command 'Deploy Application' successfully executed ``` ✅ Your new development environment is now running with real data! It can be accessed from the UI ## Step 5: Verify the Data Clone The final step is to retrieve the list of recipes from the newly deployed application. This is to verify that the development environment was created with the expected data. Run the following command to check if the development database contains the same data as the original: ``` curl -X 'GET' \ 'https://fastapi-snapshot-demo-namespace-with-snapshot.example.okteto.com/recipe' \ -H 'accept: application/json' ``` Expected response: ``` { "data": [ { "id": "60ce68651eeddf1c5ab796d1", "name": "Donuts", "ingredients": ["Flour", "Milk", "Sugar", "Vegetable Oil"] }, { "id": "60ce689c1eeddf1c5ab796d2", "name": "Pancake", "ingredients": ["Flour", "Milk", "Sugar", "Baking Powder", "Vegetable Oil"] } ] } ``` ✅ Success! The new environment has been created with a cloned database. ## Conclusion In this tutorial, you learned how to: ✔ Deploy an application with a database in Okteto ✔ Create a Volume Snapshot to capture its state ✔ Use the snapshot to spin up a new development environment with real data By using Okteto Volume Snapshots, you can: * Quickly replicate staging or production data for testing * Eliminate the need for manual database migrations * Speed up the development and debugging process 📖 Next Steps: [Explore more on Okteto Volume Snapshots](/docs/core/use-volume-snapshots.md) The code used for this article can be found on [GitHub](https://github.com/okteto/fastapi-snapshot-app). --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Getting started with Okteto Divert Divert allows you to create Development Environments that include only the services you are actively working on while leveraging a shared environment for all other microservices. This dramatically reduces infrastructure costs and setup time, especially in large microservice applications. In this tutorial, you'll learn how to use [Okteto Divert](/docs/reference/okteto-manifest.md#divert) to set up a Development Environment that contains only the services you are actively working on, while all other services automatically fall back to a shared environment. tip Learn more about Divert's architecture and traffic routing in the [Divert core concepts guide](/docs/core/divert.md). ## Prerequisites * Access to an Okteto instance * [Okteto CLI](/docs/get-started/install-okteto-cli.md) installed and configured * [ModHeader](https://modheader.com/) browser extension (or similar header modification tool) ## Sample Application We'll use the [Movies with Divert](https://github.com/okteto-community/movies-with-divert) sample application, which consists of five microservices: | Service | Technology | Purpose | | ----------- | ---------------- | ------------------------- | | Frontend | React/Node.js | User interface | | API Gateway | Go | Public API routing | | Catalog | Node.js/Express | Movie catalog management | | Rent | Java/Spring Boot | Rental logic | | Worker | Go | Background job processing | The application also includes MongoDB, PostgreSQL, and Kafka for data storage and messaging. ## Step 1: Deploy the Shared Environment First, deploy the complete Movies application to serve as the shared environment. ### Clone the Repository ``` git clone https://github.com/okteto-community/movies-with-divert cd movies-with-divert ``` ### Deploy to a Shared Namespace ``` okteto preview deploy \ --repository https://github.com/okteto-community/movies-with-divert \ --label=okteto-shared \ movies-shared ``` This command: 1. Creates a namespace called `movies-shared` 2. Deploys all five services plus their databases 3. Labels it as a shared environment Wait for all services to be ready, then visit the application at its endpoint (e.g., `https://movies-movies-shared.okteto.example.com`). Rent a few movies to populate the database with test data. ## Step 2: Deploy Your Personal Development Environment Now let's deploy only the Catalog service for development, while using the shared environment for everything else. ### Set the Shared Namespace ``` export OKTETO_SHARED_NAMESPACE="movies-shared" ``` ### Deploy the Catalog Service ``` okteto deploy -f okteto.catalog.yaml ``` Let's examine the `okteto.catalog.yaml` manifest: ``` build: catalog: context: catalog deploy: commands: - helm upgrade --install catalog .hacks/catalog/chart --set image=${OKTETO_BUILD_CATALOG_IMAGE} - helm upgrade --install mongodb .hacks/mongodb/chart divert: driver: nginx namespace: ${OKTETO_SHARED_NAMESPACE:-staging} dev: catalog: image: node:18 command: bash sync: - catalog:/app forward: - 9229:9229 ``` Key elements: * **build**: Builds only the catalog service image * **deploy.commands**: Deploys catalog and its MongoDB dependency * **deploy.divert**: Routes missing services to the shared namespace * **dev**: Configuration for live development with `okteto up` ## Step 3: Test Your Diverted Environment ### Without the Baggage Header First, test the shared environment directly: ``` curl https://movies-movies-shared.okteto.example.com/api/catalog/healthz ``` Response: ``` {"status": "ok", "namespace": "movies-shared"} ``` ### With the Baggage Header Now test with the divert header pointing to your namespace: ``` curl -H "baggage: okteto-divert=cindy" \ https://movies-movies-shared.okteto.example.com/api/catalog/healthz ``` Response: ``` {"status": "ok", "namespace": "cindy"} ``` The request was routed to your personal catalog service! ### Using ModHeader in Your Browser 1. Install the [ModHeader](https://modheader.com/) browser extension 2. Add a request header: * **Name**: `baggage` * **Value**: `okteto-divert=` 3. Visit the shared environment URL With the header enabled, requests will route to your diverted services while falling back to shared services for everything else. ## Step 4: Start Developing Start a development session with hot-reload: ``` okteto up -f okteto.catalog.yaml ``` This: 1. Swaps your deployed catalog with a development container 2. Syncs your local `catalog/` folder to the container 3. Forwards port 9229 for debugging Make changes to your local code and see them reflected immediately in your running environment. ## Available Divert Configurations The repository includes several pre-configured manifests for different development scenarios: ### Frontend Development (`okteto.frontend.yaml`) **Use when**: Working on React UI components ``` export OKTETO_SHARED_NAMESPACE="movies-shared" okteto deploy -f okteto.frontend.yaml ``` Deploys: Frontend only Shares: All backend services and databases ### Catalog Development (`okteto.catalog.yaml`) **Use when**: Working on movie catalog or MongoDB integration ``` export OKTETO_SHARED_NAMESPACE="movies-shared" okteto deploy -f okteto.catalog.yaml ``` Deploys: Catalog service, MongoDB Shares: Frontend, API, Rent, Worker, other databases ### API Gateway Development (`okteto.api.yaml`) **Use when**: Working on the public API ``` export OKTETO_SHARED_NAMESPACE="movies-shared" okteto deploy -f okteto.api.yaml ``` Deploys: API Gateway only Shares: All other services and databases ### Rentals Development (`okteto.rentals.yaml`) **Use when**: Working on rental logic or Kafka integration ``` export OKTETO_SHARED_NAMESPACE="movies-shared" okteto deploy -f okteto.rentals.yaml ``` Deploys: Rent service, Worker, Kafka, PostgreSQL Shares: Frontend, Catalog, API, MongoDB ## Understanding the Traffic Flow With Divert enabled, here's how traffic flows for a user working on the Catalog service: The key insight: only Catalog and MongoDB run in your namespace. Everything else comes from the shared environment, saving significant resources. ## Cleanup When you're done developing, delete your personal namespace: ``` okteto namespace delete cindy ``` The shared environment remains available for other developers. ## Alternative: Divert with Queues For applications using message queues, check out the [TacoShop with Divert Queues](https://github.com/okteto-community/tacoshop-with-divert-queues) example, which demonstrates: * SQS queue routing based on the baggage header * Message filtering by namespace * Producer/consumer patterns for diverted environments ## Next Steps Congratulations! You've deployed your first diverted Development Environment 🚀 * Learn about [Divert Core Concepts](/docs/core/divert.md) for architecture details * Explore [Using Divert](/docs/development/using-divert.md) for advanced configuration * Try [okteto up](/docs/development/containers/file-sync.md) for live code synchronization * Check out the [TacoShop example](https://github.com/okteto-community/tacoshop-with-divert-queues) for queue-based architectures * Review the [Istio Divert sample](https://github.com/okteto-community/getting-started-with-divert-istio) if using Istio service mesh --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Getting started with Okteto External Resources The External Resources feature in Okteto is a powerful mechanism that enables you to manage the lifecycle of external resources as part of your Okteto development environment. This means you can define the external resources that comprise your application, include those resources in Okteto's garbage collection process, and even destroy those resources when you finish working with your development environment. Here are just a few examples of external resources you can use with Okteto: * A markdown file (e.g. README, API Documentation) * MongoDB Atlas Instance * LaunchDarkly environments * Amazon SQS queues * Amazon S3 buckets * Amazon RDS databases * AWS Lambda Functions * GCP Cloud Storage * GCP Cloud Functions * GCP BigQuery * Backstage * Atlassian Confluence Documents This is not an exhaustive list and only demonstrates the flexibility of this feature. You can include *anything* as an external resource. You no longer need to use different tools to work on your application in Okteto and you won't need to worry about rogue external resources continuing to run once you are done with your work. When you configure External Resources in Okteto you can see those resources within the Okteto UI, can click to go directly to those resources in their respective platform, and include them in your Okteto `deploy` and `destroy` configurations. ## Overview When you configure the `external` section in your [Okteto manifest](/docs/reference/okteto-manifest.md), keep in mind the following: * You can create a container image that includes any external tools (to Okteto) that you need in order to provision or access your external resources. * This container image can be included in your Okteto manifest's `deploy` and `destroy` sections * External resources are destroyed when your Okteto namespace is deleted * External resources are covered by Okteto's [garbage collection process](/docs/admin/cleanup.md#delete-unused-namespaces) ## Configuring external resources Using external resources with Okteto requires configuring three areas of your Okteto manifest: 1. The `deploy` section to provision your external resources (e.g. call the AWS API to create an s3 bucket) 2. The `destroy` section to ensure the external resource is destroyed (as appropriate) when your development environment is destroyed 3. The `external` section to populate the Okteto UI and link to the external resource You can leverage [Okteto Variables](/docs/core/okteto-variables.md) to pre-define access keys, credentials, etc, for these external resources and refer to such variables in your Okteto manifest using the `$SOME_VAR` syntax. info Note for `Admins`: We strongly recommend configuring external resource variables in [Variables in the Admin dashboard](/docs/admin/dashboard.md#admin-variables) to centralize and manage them securely. ### Configuring the `deploy` section When you use an external resource with Okteto it needs to be provisioned like any other resource. If we use the example above of creating an AWS S3 bucket, we could add the following to our Okteto manifest in the `deploy` section: ``` deploy: image: okteto/pipeline-runner:1.0.0-sam commands: - name: Create an AWS S3 bucket command: | sh s3/deploy.sh ``` In this example we're using a [script](https://github.com/okteto/external-resources-aws/blob/main/s3/deploy.sh) that contains all of the instructions to do the provisioning work and executing that script in this particular stage of the Okteto `deploy` section. tip You can also use the `OKTETO_BUILD_XXX_IMAGE` ENV VAR in the `deploy` section to refer to specific container images. ### Configuring the `destroy` section We also need to ensure that the external resources we provision are destroyed when we are finished using our development environment. If we don't include them in the `destroy` step, we risk accumulating zombie resources that continue to operate and potentially accrue additional cloud spend. This also allows Okteto to perform this process for you so you never have to worry about it. Here's a sample `destroy` section using the same AWS S3 bucket example above: ``` destroy: image: okteto/pipeline-runner:1.0.0-sam commands: - name: Delete AWS S3 bucket command: | sh s3/destroy.sh ``` ### Configuring the `external` section Lastly, we want our external resources to be visible in the Okteto UI and accessible to developers working with them. To accomplish this, we need to define the `external` section in the Okteto manifest. This section takes the external resources you've provisioned in the `deploy` section and makes them a clickable element within the Okteto UI so any developer working in the same namespace can directly access that external resource. In the example below we're including a README file that documents the external resource we're using (S3 bucket) as well as the S3 bucket itself. You can see additional configuration details in our [References section](/docs/reference/okteto-manifest.md#external-object-optional): ``` external: readme: icon: okteto notes: README.md endpoints: - name: readme url: https://github.com/okteto/external-resources-aws s3: icon: aws notes: s3/notes.md endpoints: - name: bucket ``` tip You can also use the [dynamic endpoints](/docs/reference/okteto-manifest.md#use-dynamic-endpoints-for-an-external-url) feature here to provide more flexibility in the URLs. Every keyword that you see here is opinionated except for `readme:` and `s3:`. Those two keywords, the names of the external resources being defined here, can be anything you want them to be. For example, if we want to call the `readme:` resource `dundie_award:` you can do so. Similarly, you could name `s3:` something like `parkour:` and it will work just fine. Whatever name you use to label these resources will be what's shown in the Okteto UI. Choose wisely! ## Customizing your external resource UI elements As you configure your external resources in this section, keep in mind the following definitions: `notes:` is used to provide context in the form of a relative link to a markdown file. The contents are displayed in the Okteto UI (see below). ![External resources notes section](/docs/assets/images/external_resources_notes_example+1.37-c1d2ce7a6c100a6dc70b6da5ec6c2398.png) `icon:` specifies one of several predefined icons you can use when this resource is rendered in the Okteto UI. The current list of supported icons is: | | | | | | | | :---------------------------------------------: | :---------------------------------------------------------------: | :------------------------------------------------------------------------: | :------------------------------------------------------------: | :---------------------------------------------------------: | :------------------------------------------------------------: | | `aws`
![AWS icon](/docs/img/icons/aws.svg) | `container`
![container icon](/docs/img/icons/container.svg) | `dashboard`
![dashboard icon](/docs/img/icons/dashboard.svg) | `database`
![database icon](/docs/img/icons/database.svg) | `default`
![default icon](/docs/img/icons/default.svg) | `function`
![function icon](/docs/img/icons/function.svg) | | `gcp`
![gcp icon](/docs/img/icons/gcp.svg) | `graph`
![graph icon](/docs/img/icons/graph.svg) | `launchdarkly`
![launchdarkly icon](/docs/img/icons/launchdarkly.svg) | `mongodb`
![mongodb icon](/docs/img/icons/mongodb.svg) | `okteto`
![okteto icon](/docs/img/icons/okteto.svg) | `storage`
![storage icon](/docs/img/icons/storage.svg) | `endpoints:` contain information on how to access the external resource using: * `name:` to name the endpoint you're defining * `url:` to provide the specific url for accessing the resource The name of the endpoint is used to inject or modify environment variables. In this example, one of those would be: `OKTETO_EXTERNAL_FUNCTIONS_ENDPOINTS_DATA_AGGREGATOR_URL`. This is also referred to as [Dynamic Endpoints](/docs/reference/okteto-manifest.md#use-dynamic-endpoints-for-an-external-url). All of this information can be found and in a more concise format in our [References section](/docs/reference/okteto-manifest.md#external-object-optional). ### Using dynamic endpoints with external resources [Dynamic Endpoints](/docs/reference/okteto-manifest.md#use-dynamic-endpoints-for-an-external-url) is an Okteto feature that lets you define non-static URLs in your Okteto manifest. There are generally three endpoint scenarios: 1. A static, unchanging URL that you know and that will remain the same across all users and development environments 2. A hybrid URL that may have a static component but incorporate a dynamic one such as a username (e.g. user1.example.com/endpoint) 3. A fully dynamic URL that my be completely unique per user Using the Dynamic Endpoints feature Okteto provides means you can omit the `url:` key from a specific external resource in your Okteto manifest and instead compile that URL within the `deploy` section (either directly or within an included script). For example, if have the following `deploy` section defined: ``` deploy: image: okteto/pipeline-runner:1.0.0-sam commands: - name: Create an AWS SQS queue command: | sh sqs/deploy.sh ``` We can define the endpoint dynamically within the `deploy.sh` script ([example here](https://github.com/okteto/external-resources-aws/blob/main/sqs/deploy.sh)). In simpler terms, the URL is dynamically compiled on this line: ``` dashboard="https://${AWS_REGION}.console.aws.amazon.com/sqs/v2/home?region=${AWS_REGION}#/queues/${encoded}" ``` That will compile the appropriate URL, using Okteto environment variables, that specify where a developer in the same namespace will go when they click on the AWS SQS external resource component in the Okteto UI (see below). ![AWS SQS external resource demo UI component](/docs/assets/images/external_resources_sqs_demo+1.37-eb146e2a000ce6212608d901400471f5.png) ## `Destroy` external resources from the Okteto UI When you're done working on your application that uses external resources, you can ensure those resources are removed by clicking on the dev environment for your application, selecting the specific external resource you'd like to destroy, and clicking the `Destroy` button above the output area of the page. This will ensure that the external resource does not remain active and idle when your development completes. This helps keep costs down when resources are not in use. ## Example: Deploy a Development Environment with External Resources Now that we've walked through a sample of an `external` configuration, let's look at using this within the broader context of an application we're working on. You can navigate to our [demo repo](https://github.com/okteto/external-resources-aws) to follow along if you'd like. In this example we'll be configuring and deploying a development environment that includes polyglot microservices, an AWS SQS queue, and an S3 bucket. ![Application architecture diagram](/docs/assets/images/external_resources_architecture-b1fb6e6da97babd33be1196eb81b3008.png) ### Prerequisites 1. Okteto CLI 2.14 or newer 2. An AWS account 3. An Okteto account 4. Create a set of [IAM keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) for your AWS account 5. Create the following [Okteto Variables](/docs/core/okteto-variables.md): AWS\_ACCESS\_KEY\_ID: The Access Key ID of your IAM user AWS\_SECRET\_ACCESS\_KEY: The Secret Access Key of your IAM user AWS\_REGION: The region in AWS you would like to use for the external resources Notice the `external` configuration in this demo. It specifies most attributes except for `url` for most of these resources. ``` external: readme: icon: okteto notes: README.md endpoints: - name: readme url: https://github.com/okteto/external-resources-aws sqs: icon: aws notes: sqs/notes.md endpoints: - name: queue s3: icon: aws notes: s3/notes.md endpoints: - name: bucket api-docs: icon: dashboard notes: check/notes.md endpoints: - name: docs ``` The `url:` keys are missing from most external resource (`sqs`, `s3`, and `api-docs`) because they've been defined in the `deploy` > `commands` > `command` section using the [Okteto Variables](/docs/core/okteto-variables.md) you defined [above](#prerequisites) and the [dynamic endpoints](#using-dynamic-endpoints-with-external-resources) feature. Alternatively, you could remove the respective `deploy` commands and add the `url` endpoints here manually, but this is a good example of how flexible the manifest file can be. Once you've configured the prerequisites, you can deploy this on your Okteto instance: ``` $ git clone https://github.com/okteto/external-resources-aws $ cd external-resources-aws $ okteto context use $OKTETO_CONTEXT $ okteto deploy ``` The `okteto deploy` command will deploy the Okteto environment, external resources, and anything else defined within your Okteto manifest `deploy` section. You can think of this command as the "on button" for your remote cloud development environment within Okteto. Once the application has been deployed in Okteto, you can work on the `menu` microservice by running the command: `okteto up menu`. In this specific example, once you've executed this command you'll also need to run `yarn start` from the container. tip To start the other services in this example (`kitchen` and `check`) you'll need to run these commands from the container, respectively: * go run main.go * python main.py --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Getting started with Okteto This tutorial provides a step by step guide to configure an [Okteto Manifest](/docs/reference/okteto-manifest.md). ## Overview The tutorial is composed of the following steps: * Step 1: Code the Hello World application * Step 2: Define a Dockerfile for building the Docker image of the Hello World application * Step 3: Create Kubernetes manifests to deploy the Hello World application on Okteto * Step 4: Generate your Okteto Manifest * Step 5: Deploy your Development Environment * Step 6: Configure a Remote Development Container * Step 7: Develop on your Remote Development Container Let's get started! ## Step 1: Code the Hello World application We will use a simple Hello World application to illustrate how to configure an Okteto Manifest. The Hello World application is a simple web service that responds "Hello World!" to every request. It's written in Go, but Okteto can be used with any application that runs on Kubernetes. First, make a new directory called `hello-world` and move inside it: ``` mkdir hello-world cd hello-world ``` Create a new file under the name `main.go` with the following content: ``` package main import ( "fmt" "net/http" ) func main() { fmt.Println("Starting hello-world server...") http.HandleFunc("/", helloServer) if err := http.ListenAndServe(":8080", nil); err != nil { panic(err) } } func helloServer(w http.ResponseWriter, r *http.Request) { fmt.Fprint(w, "Hello world!") } ``` `main.go` implements a Golang web server that listens on port 8080 and responds to every Http request with the message *Hello world!* Next, initialize your go module running the following command: ``` go mod init go-getting-started ``` ## Step 2: Define a Dockerfile for building the Docker image of the Hello World application You need to build a Docker image and push it to a Docker registry before Okteto can run your application. To do that, you need to define a `Dockerfile`. A `Dockerfile` file is a sequence of instructions to build the Docker image of your application. If you're not familiar with Docker, we strongly recommend you [learn about it](https://scotch.io/tutorials/getting-started-with-docker). Open a new file under the name `Dockerfile` with the following content: ``` FROM golang:buster WORKDIR /app ADD . . RUN go build -o app EXPOSE 8080 CMD ["./app"] ``` ## Step 3: Create Kubernetes manifests to deploy the Hello World application on Okteto To deploy an application to Okteto, you need to define it using Kubernetes manifests. Let's start by creating a new folder for the Kubernetes manifests: ``` mkdir k8s ``` When you use a Kubernetes manifest, you tell Kubernetes how you want your application to run. This time, you'll create a deployment object. Create a new file `k8s/deployment.yaml` with the following content: ``` apiVersion: apps/v1 kind: Deployment metadata: name: hello-world spec: selector: matchLabels: app: hello-world replicas: 1 template: metadata: labels: app: hello-world spec: containers: - name: hello-world image: okteto.dev/hello-world:latest ports: - containerPort: 8080 ``` The deployment manifest has three main sections: * `metadata` defines the name for your deployment. * `replicas` defines how many copies of it you want running. * `template` tells Kubernetes what to deploy, and what labels to add. In this case, a single container, with the `okteto.dev/hello-world:latest` image we will build in our Okteto Pipeline, listening on port 8080, and with the `app: hello-world` label. Note that this label is the same used in the `selector` section. tip If you want to know more about Kubernetes deployment objects, check the [official docs](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). You'll now need a way to access your application. You can expose an application on Kubernetes by creating a service object. Create a new file called `k8s/service.yaml` with the following content: ``` apiVersion: v1 kind: Service metadata: name: hello-world spec: type: LoadBalancer ports: - name: http port: 8080 selector: app: hello-world ``` The service manifest has four main sections: * `metadata` tells Kubernetes how to name your service * `type` tells Kubernetes how you want to expose your service. In this case, it will expose it externally through a Load Balancer. In you want to **expose your application using ingress**, check the [docs](/docs/core/endpoints/automatic-ssl.md#bring-your-own-ingress). * `ports` tells Kubernetes which ports you want to expose * `selector` tells Kubernetes how to direct traffic. In this case, any pod with the `app: hello-world` label will receive traffic. tip Kubernetes manifests can get complex to manage. As your application grows, we recommend you pack your application using [Helm](https://helm.sh/). You now have everything ready to define the Okteto Manifest of the Hello World application. ## Step 4: Generate your Okteto Manifest You can automate the deployment of the Hello World application with an Okteto Manifest to provide a one-click deployment experience for anyone in your team or your open source community. To define your Okteto Manifest, create a new file `okteto.yaml` with the following content: ``` build: hello-world: image: okteto.dev/hello-world:latest context: . dockerfile: Dockerfile deploy: - kubectl apply -f k8s ``` The Okteto Manifest has a [build](/docs/core/okteto-manifest.md#build) section to define how to build the image of my application. The Okteto Manifest also has a [deploy](/docs/core/okteto-manifest.md#deploy) section to define the sequence of commands to deploy the Hello World application. In this case, it deploys the Hello World application using `kubectl` and the Kubernetes manifests you created on Step 2. You can make use of tools such as `kubectl`, `helm`, `okteto`, and `kustomize` in your `deploy` commands. ## Step 5: Deploy your Development Environment [Install](/docs/development/using-okteto-cli.md) the Okteto CLI and configure access to Okteto: ``` okteto context use https://okteto.example.com ``` ``` ✓ Using context cindy @ okteto.example.com ``` In order to deploy your application, run the following command: ``` okteto deploy ``` ``` i Using cindy @ okteto.example.com as context i Images were already built. To rebuild your images run 'okteto build' or 'okteto deploy --build' ✓ kubectl apply -f k8s i Endpoints available: - https://hello-world-cindy.okteto.example.com/ ✓ Development environment 'go-getting-started' successfully deployed ``` and that's all, your application will be built and deployed in seconds! ## Step 6: Configure a Remote Development Container Building and deploying your application for each code change can be tedious. In prevent that, you can configure how to live update your application while you are coding defining a development container. To do that, add the following content to your Okteto Manifest: ``` dev: hello-world: image: okteto/golang:1 command: bash sync: - .:/usr/src/app ``` This is the meaning of the fields we are using here: * `image`: the image used by the development container. More information on development images [here](/docs/development/images.md). * `command`: the start command of the development container. * `sync`: the folders that will be synchronized between your local machine and the development container. Now execute the following command to activate your development container: ``` okteto up ``` ``` ✓ Persistent volume successfully attached ✓ Images successfully pulled ✓ Files synchronized Namespace: cindy Name: hello-world Welcome to your development container. Happy coding! cindy:hello-world app> ``` Working in your development container is the same as working on your local machine. Start the application by running the following command: ``` cindy:hello-world app> go run main.go ``` ``` Starting hello-world server... ``` Go back to the browser, and reload the page to test that your application is running. ## Step 7: Develop on your Remote Development Container Open the file `main.go` in your favorite local IDE and modify the response message on line 17 to be *Hello world from Okteto!*. Save your changes. ``` func helloServer(w http.ResponseWriter, r *http.Request) { fmt.Fprint(w, "Hello world from Okteto!") } ``` Okteto will synchronize your changes to your development container. Cancel the execution of `go run main.go` from the development container shell by pressing `ctrl + c`. Rerun your application: ``` cindy:hello-world app> go run main.go ``` ``` Starting hello-world server... ``` Go back to the browser and reload the page. Your code changes were instantly applied. No commit, build, or push required 😎! ## Next steps Congratulations, you just configured **your first Okteto Manifest** 🚀 Head over to [our getting started guides](/docs/development/containers/file-sync.md) to see how to configure Okteto to live-update your application with different programming languages and **debuggers**. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Optimize your Okteto Development Environment Fast, reliable environments are at the core of a great developer experience. Whether you’re writing code, running automated tests, spinning up preview environments for your team, or deploying AI agents, every second counts. Long build times and slow environments don’t just waste time—they break developer focus, reduce iteration speed, and delay feedback loops. By applying a few optimizations, you can significantly improve the speed and consistency of your Okteto environments. These changes will give your developers shorter feedback cycles, help your QA and test engineers validate changes faster, make preview environments feel more “production-like,” and allow your AI agents to operate at full efficiency. The following best practices will help you and your team get the most out of Okteto. ## Image & Build Optimization ### 1: Pin Images Instead of Using `latest` Always use explicit version tags or SHA digests. Using `latest` forces Kubernetes to pull images every time, preventing node cache reuse and slowing startup. ``` # ❌ Bad image: registry/redis:latest # ✅ Good image: registry/redis:8.2.1 # or image: registry/redis@sha256:2678c... ``` ### 2. Use Okteto Smart Builds Okteto tracks builds at the commit and configuration level. If another teammate already built an identical image, Okteto skips the build entirely. When Okteto Smart Builds is enabled, you'll see logs like this: ``` % okteto deploy i Using cindy @ demo.okteto.dev as context i Okteto Smart Builds is skipping build of 'worker' because it's already built from cache. i Okteto Smart Builds is skipping build of 'tests' because it's already built from cache. i Okteto Smart Builds is skipping build of 'frontend' because it's already built from cache. i Okteto Smart Builds is skipping build of 'catalog' because it's already built from cache. i Okteto Smart Builds is skipping build of 'rent' because it's already built from cache. i Okteto Smart Builds is skipping build of 'api' because it's already built from cache. ``` > In most git repositories, Okteto Smart Builds will be enabled by default, [please refer to Okteto's documentation if that's not the case](/docs/core/build-service.md#smart-builds). ### 3. Order Dockerfile Lines by Update Frequency Put rarely updated instructions first and frequently updated ones last to maximize image caching. Please refer [to Docker's documentation on the topic](https://docs.docker.com/build/cache/optimize/#order-your-layers) to learn more about this. ``` # Rarely changes FROM node:20-alpine RUN apk add --no-cache bash # Changes occasionally COPY package.json package-lock.json ./ RUN npm install # Changes frequently COPY src/ ./src ``` ### 4. Avoid `COPY . .` in Dockerfiles Copy only what you need. Copying everything invalidates the cache whenever any file changes. [This document has more information on the COPY command](https://docs.docker.com/build/building/best-practices/#add-or-copy). ``` # ❌ Bad COPY . . # ✅ Good COPY package.json . COPY src/ src/ ``` ### 5. Avoid Recursive Operations in Dockerfiles ``` # Dockerfile # ❌ Bad RUN chown -R user:group /app/dist # ✅ Good COPY --from=build --chown=user:group /app/dist /app/dist ``` ### 6. Use Mount Caches When running building container images, you can take advantage of BuildKit’s cache mounts to persist build and dependency caches between runs. This dramatically reduces test setup time by reusing previously downloaded packages or compiled artifacts. Common caches to mount: * Node.js: `node_modules` or npm/yarn caches * Java: `.m2` (Maven) * Go: `.cache/go-build` ``` # Dockerfile FROM golang:1.24 WORKDIR /app COPY go.mod . COPY go.sum . RUN go mod download COPY main.go main.go RUN --mount=type=cache,sharing=private,target=/root/.cache/go-build \ CGO_ENABLED=0 \ GOOS=linux \ go build -o /usr/src/api ... ``` [Learn more here](https://docs.docker.com/build/cache/optimize/#use-cache-mounts). ## Context & Sync Management ### 7. Use `.dockerignore` to Limit Build Context Exclude everything by default, then explicitly include only required files. ``` # .dockerignore # exclude evertyhing by default * # only send this as part of the build context !Dockerfile !okteto.yml !docker-compose.yml !package.json !src/** ``` > For multi-Dockerfile setups, you can create image-specific `.dockerignore` files (e.g., `dev-dockerfile.dockerignore`). ### 8. Use `.oktetoignore` to Control Deployment Context Exclude by default, and only include what’s needed for deployment or testing. The `.oktetoignore` file follows the same syntax that `.gitignore` files. ``` # .oktetoignore # exclude evertyhing by default * # only send this as part of the deploy context [deploy] !helm/** !k8s/** # only send this as part of the test context [test] !tests/** ``` [Learn more about the `.oktetoignore` file here](/docs/core/remote-execution.md#ignoring-files). ### 9. Use `.stignore` to Control File Synchronization Only sync the files needed for active development. As a general rule, avoid syncing generated artifacts. ``` # .stignore # exclude evertyhing by default * # only send this as part of the synchronization context !src/** !public/** ``` [Learn more about the `.stignore` file here](/docs/core/remote-execution.md#ignoring-files). ### 10. Precopy sync content into dev image When using multi-stage Dockerfiles, preload source code into your dev image. This improves initial sync and warms build caches. ``` # Dockerfile FROM golang:1.21 as builder WORKDIR /app COPY go.mod go.sum ./ RUN go mod download COPY main.go main.go RUN go build -o myapp FROM alpine as production WORKDIR /app COPY --from=builder /app/myapp . ``` ``` # okteto.yaml build: myapp: context: . target: production myapp-dev: context: . target: builder dev: myapp: image: ${OKTETO_BUILD_MYAPP_DEV_IMAGE} ``` ## Data & Environment Management ### 11. Replace DB Seed Scripts with Volume Snapshots Instead of running time-consuming and error-prone seed scripts, preload databases with \[Okteto Volume Snapshots]\(/docs/self-hosted/install/volume-snapshots/. This makes environments faster and more realistic. [Learn more about Volume Snapshots here](/docs/core/use-volume-snapshots.md). ### 12. Leverage Okteto Divert Not every use case requires fully isolated environments. With Divert, you can route traffic from a shared environment into your dev container. This saves resources while keeping the experience close to production. * [Our vision for Divert](https://www.okteto.com/blog/why-flexibility-is-key-to-scaling-development-environments) * [Getting Started Guide](/docs/tutorials/divert.md) ## Development ### 13. Use Volumes for Dev Containers You can use volumes to persist files across okteto up sessions. This helps you avoid re-downloading or rebuilding the same dependencies every time your environment starts. Common examples include: * Dependencies: `node_modules`, `vendor/` * Build caches: `.m2`, `.cache/go-build` * Other reusable assets you don’t want to regenerate each time By persisting these files, your environment will start faster and use fewer resources. ``` ... dev: app: volumes: - /usr/src/app/node_modules - /root/.m2 - /root/.cache/go-build ``` [Learn more about Volumes for Dev Containers here](/docs/reference/okteto-manifest.md#volumes-string-optional). ### 14. Use Caches for Okteto Test When running `okteto test`, you can use volumes to persist files across test runs. This prevents reinstalling dependencies or rebuilding caches every time, making your tests faster and more efficient. Typical files to persist: * Dependencies: `node_modules`, `vendor/` * Build caches: `.m2`, `.cache/go-build` * Other reusable assets needed for your test suite By persisting these files, your environment will start faster and use fewer resources. ``` ... test: unit: image: node:22 caches: - /usr/src/app/node_modules - /usr/src/app/downloaded_assets commands: - npm install - npm test ``` [Learn more about Caches for Okteto Test here](/docs/reference/okteto-manifest.md#caches-string-optional). ## Okteto AI Okteto AI can generate production-ready code and handle repetitive tasks. By spinning up AI agents, you can free up developers’ time for high-value work while ensuring that routine changes, fixes, and tests are handled quickly and consistently. * [Our vision for Okteto AI](https://okteto.com/ai) * [Getting Started with Okteto AI](/docs/okteto-ai.md) ## Conclusion & Next Steps Developers always want faster environments. By following these practices, your team will save hundreds of hours waiting for environments to be ready and enjoy smoother development, test, preview, and agent workflows. If you’d like a review of your setup—or just a second pair of eyes, [we’re here to help](https://support.okteto.com). --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Getting started with Preview Environments [Preview Environments](/docs/previews.md) give every pull request its own fully deployed instance of your application. Reviewers can interact with the changes live, without cloning the branch or running anything locally. When the pull request is merged or closed, the environment is automatically destroyed. In this tutorial, you will configure two GitHub Actions workflows for the [Movies](https://github.com/okteto/movies) sample application: one that deploys a Preview Environment when a pull request is opened, and one that cleans it up when the pull request is closed. You will also add end-to-end tests that run automatically against each preview. ## Prerequisites * An [Admin Access Token](/docs/admin/dashboard.md#admin-access-tokens) for your Okteto instance. Creating one requires admin access; if you are not an administrator, ask an admin to generate a token for you. * A [GitHub](https://github.com) account ## Step 1: Fork the sample application Fork the [Movies](https://github.com/okteto/movies) repository to your own GitHub account and clone the fork to your machine. This microservices application includes a React frontend, a Node.js catalog service, a Java rent service, Go API and worker services, and supporting infrastructure (PostgreSQL, Kafka, MongoDB). The repository already has an Okteto Manifest (`okteto.yaml`) that defines how to build and deploy all services, and a `test` section for end-to-end tests using Playwright. It also ships with working preview workflows in `.github/workflows/` that Okteto uses for its own CI — you can keep them as a reference. In this tutorial you rebuild both workflows step by step, wired to your own Okteto instance. GitHub disables workflows on forks by default. Open the **Actions** tab of your fork and click **I understand my workflows, go ahead and enable them** so the preview workflows can run. ## Step 2: Configure your GitHub secrets The GitHub Actions workflows authenticate with Okteto using two secrets. Create them in your fork under **Settings > Secrets and variables > Actions > New repository secret**: | Secret | Value | | ---------------- | ----------------------------------------------------------------------------------------------- | | `OKTETO_TOKEN` | An [Admin Access Token](/docs/admin/dashboard.md#admin-access-tokens) from your Okteto instance | | `OKTETO_CONTEXT` | The URL of your Okteto instance (e.g., `https://okteto.example.com`) | info The workflow also uses `GITHUB_TOKEN`, which GitHub populates automatically. You do not need to create it. ## Step 3: Create the deploy workflow Your fork already contains a `.github/workflows/preview.yaml` from the sample repository. Replace its contents with the workflow below, which triggers whenever a pull request targets the `main` branch: ``` # file: .github/workflows/preview.yaml on: pull_request: branches: - main permissions: contents: read pull-requests: write concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: false jobs: preview: runs-on: ubuntu-latest steps: - name: Context uses: okteto/context@latest with: url: ${{ secrets.OKTETO_CONTEXT }} token: ${{ secrets.OKTETO_TOKEN }} - name: Deploy preview environment uses: okteto/deploy-preview@latest env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: name: pr-${{ github.event.number }} timeout: 15m ``` note The workflow shipped with the sample repository uses an `OKTETO_URL` secret and a preview name tied to Okteto's own CI. The version above uses the secrets you created in Step 2. The workflow does three things: * **Authenticates** with your Okteto instance using `okteto/context` * **Deploys** a Preview Environment named `pr-` using `okteto/deploy-preview`, which builds all container images and runs the `deploy` commands from your Okteto Manifest * **Posts a comment** on the pull request with the URL of the Preview Environment The `permissions` block grants the workflow's `GITHUB_TOKEN` write access to pull requests so `okteto/deploy-preview` can post that comment. Without it, repositories with restricted default workflow permissions reject the comment. Preview Environments are created with [global scope](/docs/previews.md#understanding-preview-scope) by default, which makes them accessible to all members of your Okteto instance — keep this default so your reviewers can open the preview. Setting `scope: personal` is not useful here: because the workflow authenticates with an Admin Access Token, the preview is owned by the `okteto-bot` user, so a personal-scoped preview would be visible only to `okteto-bot` rather than to you. warning Always set `cancel-in-progress: false` for Preview Environment workflows. Setting it to `true` cancels in-progress deployments, which can leave your Preview Environment in an inconsistent state or cause resource leaks. ## Step 4: Add end-to-end tests Extend the deploy workflow to run tests against the Preview Environment after it deploys. Add these steps after the `Deploy preview environment` step: ``` - name: Checkout code uses: actions/checkout@v4 - name: Run end-to-end tests uses: okteto/test@latest with: tests: e2e namespace: pr-${{ github.event.number }} - name: Save test report uses: actions/upload-artifact@v4 if: ${{ !cancelled() }} with: name: playwright-report path: tests/playwright-report/ retention-days: 30 ``` The `okteto/test` action runs the `e2e` test container defined in `okteto.yaml`. The Movies app includes a Playwright test suite that verifies the application works end-to-end. Test artifacts are uploaded to GitHub so you can download and review them if a test fails. note The `namespace` passed to `okteto/test` must match the `name` you gave the Preview Environment in the deploy step. A Preview Environment's Namespace is the same as its name, so if you change one, change the other. The complete `.github/workflows/preview.yaml` file should look like this: ``` # file: .github/workflows/preview.yaml on: pull_request: branches: - main permissions: contents: read pull-requests: write concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: false jobs: preview: runs-on: ubuntu-latest steps: - name: Context uses: okteto/context@latest with: url: ${{ secrets.OKTETO_CONTEXT }} token: ${{ secrets.OKTETO_TOKEN }} - name: Deploy preview environment uses: okteto/deploy-preview@latest env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: name: pr-${{ github.event.number }} timeout: 15m - name: Checkout code uses: actions/checkout@v4 - name: Run end-to-end tests uses: okteto/test@latest with: tests: e2e namespace: pr-${{ github.event.number }} - name: Save test report uses: actions/upload-artifact@v4 if: ${{ !cancelled() }} with: name: playwright-report path: tests/playwright-report/ retention-days: 30 ``` ## Step 5: Create the cleanup workflow Your fork also contains a second workflow, `.github/workflows/preview-closed.yaml`, that destroys the Preview Environment when the pull request is closed or merged. Replace its contents with: ``` # file: .github/workflows/preview-closed.yaml on: pull_request: types: - closed jobs: closed: runs-on: ubuntu-latest steps: - name: Context uses: okteto/context@latest with: url: ${{ secrets.OKTETO_CONTEXT }} token: ${{ secrets.OKTETO_TOKEN }} - name: Destroy preview environment uses: okteto/destroy-preview@latest with: name: pr-${{ github.event.number }} ``` This triggers on the `closed` event type, which fires for both merged and unmerged pull requests. The `okteto/destroy-preview` action removes all resources associated with the Preview Environment. ## Step 6: Open a pull request Commit both workflow files to a new branch and push it to your fork: ``` git checkout -b add-preview-workflows git add .github/workflows/preview.yaml .github/workflows/preview-closed.yaml git commit -m "Update preview environment workflows" git push origin add-preview-workflows ``` Open a pull request from this branch. **Make sure the base repository is your fork** (`/movies`), not `okteto/movies` — GitHub preselects the upstream repository by default, and your secrets only exist in your fork. ## Step 7: Verify the Preview Environment After opening the pull request, navigate to the **Checks** tab. You should see the preview workflow running: ![GitHub checks tab showing the preview workflow running](/docs/assets/images/preview-check-3c8094bb375496944293cb854413b18a.png) Once the deployment completes, the `deploy-preview` action posts a comment on the pull request with the URL of your Preview Environment: ![Pull request comment showing the preview environment URL](/docs/assets/images/preview-message-d189a4e011774512e0d7e79e2de5ee60.png) Click the URL to open the Movies application running in your Preview Environment. The end-to-end tests run automatically after the deployment, and the results appear in the GitHub workflow logs. Every time you push a new commit to the branch, the workflow runs again and updates the Preview Environment with your latest changes. ## Step 8: Merge and clean up When you are satisfied with the changes: 1. Merge the pull request in GitHub 2. The cleanup workflow triggers automatically and destroys the Preview Environment 3. Verify in the Okteto dashboard that the Preview Environment has been removed ## Next steps Congratulations! You deployed your first Preview Environment with automated testing 🚀 Every pull request in your repository now gets its own live environment, complete with end-to-end test results. Reviewers can interact with changes directly instead of reading diffs. * The [Preview Environments overview](/docs/previews.md) covers scope, sharing, and managing previews from the dashboard * Explore [Okteto Test](/docs/testing/getting-started-test.md) for more testing patterns * Configure the [Garbage Collector](/docs/admin/cleanup.md) to automatically clean up idle Preview Environments * Set up Preview Environments with [GitLab CI/CD](/docs/previews/using-gitlab-cicd.md) if your team uses GitLab * See the full list of [supported GitHub Actions](/docs/reference/supported-github-actions.md) for additional workflow options --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Using LaunchDarkly and Okteto To Automate Feature Flag Management ## What Are Feature Flags Feature flags allow developers to enable or disable features in an application without deploying a new version. This enables teams to release new features gradually and test them with a subset of users before rolling them out completely. In today's world, feature flagging has become a standard practice in modern software development. [LaunchDarkly](https://launchdarkly.com/) is a popular feature flagging service that allows developers to manage their features and rollouts with ease. ## What Does Okteto Do Okteto is a platform for modern development experience automation on Kubernetes. One of the features we offer is provisioning and de-provisioning environments that are exactly like production. At Okteto, we've always believed in providing developers with a realistic development environment that's set up instantly and has everything they need for development. Our goal is to give developers the ultimate experience when developing modern applications. This means that if you use feature flags in production, you should be able to work with them during development as well. As part of this philosophy, we recently launched a new feature to our platform: External Resources. This feature makes working with LaunchDarkly during development a breeze. ## Why Develop Using LaunchDarkly With Okteto Developers are already using LaunchDarkly's SDK to write code with feature flags. However, a common problem they face is the difficulty of testing these feature flags during development. A major issue is having to manually set up a LaunchDarkly environment with pre-populated flags for every developer who wants to work on the application or test features. This process takes time away from coding and can lead to a poor developer experience. Additionally, there is no easy way to replicate the same feature flags present in the production environment for each developer. Using LaunchDarkly dashboards as External Resources with Okteto solves both of these problems by: * Automatically provisioning (and deprovisioning) feature flag dashboards * Cloning existing environments, which ensures that the LaunchDarkly environment during development is pre-populated with all necessary flags ## How To Use LaunchDarkly Dashboards As External Resources You can configure a feature flag dashboard in LaunchDarkly to be set up for each developer when they spin up their development environment. This dashboard is already configured to work with the application being developed and requires no configuration from the developer’s side. It has all the flags you want to include from your existing production environments. > To demonstrate the power of using LaunchDarkly as an External Resource in your development environments, we’ve put together a sample application for you to try out: This simple application demonstrates how easy External Resources make working with services that live outside your Kubernetes cluster, a LaunchDarkly dashboard in this case. The application displays some text with an emoji. If you look at the code, you’ll see we use LaunchDarkly’s SDK to change the text and emoji when the feature flag is enabled. When you deploy the application using Okteto, Okteto not only deploys the app itself but also provisions a feature flag dashboard for you in LaunchDarkly. You can view this right from your Okteto dashboard. ![Okteto dashboard showing deployed LaunchDarkly dev environments with endpoints, repository link, and deployment logs](/docs/assets/images/launch-darkly-okteto-dashboard-28377a49ef4e6ec31ddfd0b7ef79dfe5.jpg) If you visit the endpoint shown for the LaunchDarkly dashboard, you should be able to toggle the “Use new emojis” feature flag on and off. Refreshing your application should show you the replaced text and emoji. ![LaunchDarkly Feature flags dashboard showing the Use new emojis flag toggled on](/docs/assets/images/launch-darkly-feature-flags-18cd96e34f6ebf0042df6c3dfc7ce4c6.jpg) The power of this feature is that developers can work in a running development environment that already has all the feature flags that the application uses without needing to set anything up. They don't have to create a dashboard in LaunchDarkly every time or manually clone all the flags they need from the production environment. Another benefit of External Resources is that, like your dev environments, they're ephemeral. This means that when you destroy your dev environment, the LaunchDarkly dashboard will also be destroyed with it. This makes it easier for platform engineers and team leads to manage resources without having to worry about chasing people around. ## Conclusion Leveraging feature flags during development with LaunchDarkly and Okteto can help teams release new features gradually and test them with a subset of users before rolling them out completely. By using this combination: * developers can easily manage feature flags in their development environments * ensure that their code is working correctly before releasing it to production * save a lot of time and effort during development by allowing developers to connect to resources that their application depends on without having to set them up locally. Check out this video demonstrating the benefits you get from using LaunchDarkly dashboards as an External Resource in Okteto: [YouTube video player](https://www.youtube.com/embed/FdD7Tw1ZgXQ?si=EYOn692oZGPKICVL) --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Configure Webpack to work inside a container ### Expose webpack's dev server outside the container In order to make your app reachable outside the container `webpack-dev-server` must be configured to use `0.0.0.0` as host. #### webpack.config.js ``` module.exports = { //... devServer: { host: '0.0.0.0' } }; ``` ### Enable Hot Module Replacement If you want to use the Webpack [Hot Module Replacement](https://webpack.js.org/concepts/hot-module-replacement/) feature to hot reload changes while using the development server, you need to enable it and set the socket port to `443`. * Webpack 5 * Webpack 4 #### webpack.config.js ``` module.exports = { //... devServer: { host: '0.0.0.0', hot: true, client: { webSocketURL: { port: 443 } } } }; ``` #### webpack.config.js ``` module.exports = { //... devServer: { host: '0.0.0.0', hot: true, sockPort: 443 } }; ``` ### Host check configuration Webpack performs a host check when accessing the server. External access to the server won't be allowed unless it's properly configured. Check [webpack's dev server documentation](https://webpack.js.org/configuration/dev-server) for more information. * Webpack 5 * Webpack 4 You can bypass this check entirely by setting the [`allowedHosts`](https://webpack.js.org/configuration/dev-server/#devserverallowedhosts) option to `all`: #### webpack.config.js ``` module.exports = { //... devServer: { host: '0.0.0.0', allowedHosts: 'all' } }; ``` You can bypass this check entirely by setting the [`disableHostCheck`](https://v4.webpack.js.org/configuration/dev-server/#devserverdisablehostcheck) option to `true`: #### webpack.config.js ``` module.exports = { //... devServer: { host: '0.0.0.0', disableHostCheck: true } }; ``` ### Watching files Webpack uses the file system to get notified of file changes and enable features like hot-reloading. You might experience file watching issues if your docker image is not compatible with webpack's file system subsystem. If that's your case, enable the `polling` option: * Webpack 5 * Webpack 4 #### webpack.config.js ``` module.exports = { //... devServer: { host: '0.0.0.0', watchOptions: { poll: true // Or you can set a value in milliseconds. } } }; ``` #### webpack.config.js ``` module.exports = { //... devServer: { host: '0.0.0.0', watchOptions: { poll: true // Or you can set a value in milliseconds. } } }; ``` Check [webpack's documentation](https://webpack.js.org/configuration/watch/#watchoptions) for more information about `watchOptions`. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto Administration ## Learn more about Okteto's administration capabilities Okteto's administration features are designed to empower administrators with robust tools and insights, ensuring efficient management, security, and optimized resource usage across your development environments. This section provides a comprehensive overview of various administration functionalities within Okteto. ## Explore Our Administration Features: ### Okteto Admin Dashboard A web UI for your Okteto instance. Manage users, monitor activity, and oversee environments all in one place. [Learn more about the Admin Dashboard →](/docs/admin/dashboard.md) ### 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. [Configure Okteto AI for your organization →](/docs/okteto-ai/okteto-ai-admin-config.md) ### 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 →](/docs/admin/build-service.md) ### 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. [Explore the Okteto Catalog →](/docs/admin/catalog.md) ### Resource Manager Automate your CPU and memory resource requests to ensure your workloads stay balanced and your cluster resources are optimized. [Explore Resource Manager →](/docs/admin/resource-manager.md) ### Resource Cleanup Optimize your environments with Okteto's Resource Cleanup feature. Automatically sleep unused resources to maintain a lean and efficient development workflow. [Discover Resource Cleanup techniques →](/docs/admin/cleanup.md) ### Okteto Insights Delve into Okteto Insights for detailed analytics on resource usage, build and deployment metrics, enabling data-driven decisions to boost productivity. [Learn how to configure and use Okteto Insights →](/docs/admin/okteto-insights.md) ### Private Repositories Securely manage your code with Private Repositories in Okteto. Configure Github or Private Keys to access your code providers. [Find out how to use Private Repositories →](/docs/admin/private-repositories/github-app.md) ### SSH Known Hosts Centrally manage trusted SSH hosts for Git operations used by Okteto’s installer jobs and remote executions. Prevent host verification failures and enforce organization-wide trust for Git providers. [Configure SSH Known Hosts →](/docs/admin/ssh-known-hosts.md) ### Registry Credentials Pull images from a private registry in addition to [Okteto's Container Registry](/docs/core/container-registry.md). [Learn More about configuring your own Registry Credentials →](/docs/admin/registry-credentials.md) ### Cloud Credentials Dynamically configure Okteto's connection to AWS and GCP, eliminating the need for developers to manage static credentials. [Learn More about Cloud Credentials →](/docs/admin/cloud-credentials.md) ### 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. [Learn about Custom Installer Images →](/docs/admin/custom-installer-image.md) ## Start Administering Like a Pro Dive into each feature to unlock the full administrative potential of Okteto. Whether you're looking to streamline your setup, secure your projects, or gain valuable insights, Okteto Administration provides the tools you need to manage your cloud-native development environment effectively. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # 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](/docs/admin/dashboard.md) or via the [Okteto API](/docs/admin/okteto-api.md) 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](/docs/admin/integrations/okta-user-deprovisioning.md) to delete accounts automatically when users are removed from your identity provider. * **Use the Okteto API.** The [Okteto API](/docs/admin/okteto-api.md) 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](/docs/admin/dashboard.md) and via the [Okteto API](/docs/admin/okteto-api.md). 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](/docs/admin/dashboard.md) or query it via the [Okteto API](/docs/admin/okteto-api.md). To remove accounts automatically when users leave your identity provider, configure [Okta User Deprovisioning](/docs/admin/integrations/okta-user-deprovisioning.md). For Self-Hosted license installation, see [Okteto License](/docs/self-hosted/manage/okteto-license.md). --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # 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](/docs/core/remote-execution.md). 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](/docs/self-hosted/manage/buildkit-high-performance.md). ## 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](/docs/reference/feature-flags.md) 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](/docs/assets/images/admin_build-fb0ff498df0d166b5e2066968aa62d48.png) ## 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](/docs/core/build-service.md) - Learn about how the Okteto Build service works * [BuildKit High Performance](/docs/self-hosted/manage/buildkit-high-performance.md) - Detailed guide on optimizing BuildKit performance at high scale * [BuildKit Helm Configuration](/docs/self-hosted/helm-configuration.md#buildkit) - Configure BuildKit settings in your Helm chart --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # CatalogScaleEnterpriseSelf-Hosted The **Catalog** feature allows `admins` to pre-configure a list of applications from the Okteto Admin Dashboard. These applications are available to developers in the same Okteto instance when launching a development environment from the UI. By using Catalog entries, developers can quickly deploy their environments without needing to manually configure Okteto manifests or set up environment variables. This feature allows Okteto administrators to enhance the developer experience by streamlining workflows, making it easier for developers to begin their projects. ![Catalog table view](/docs/assets/images/admin_catalog_view+1.32-5ffcbf234bfd159b8d84f2f897fe2cfd.png) note If you see a “Read-only” tag next to catalog items in the interface, it means that these items were defined using Custom Resource Definitions (CRDs). Such items cannot be modified through the Admin Dashboard. To make changes, you will need to update the associated CRD directly. For more information, refer to the [Managing Catalog Items using CRDs documentation](/docs/self-hosted/manage/custom-resource-definitions.md#catalog-items). ## Create your Catalog You have two options for creating and managing Catalog items: 1. [Create Catalog items via the Dashboard](#create-and-manage-catalog-items-via-the-dashboard) or 2. [Create Catalog items using Custom Resource Definitions (CRDs)](#create-and-manage-catalog-items-via-custom-resource-definitions-crds) info *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 Item** button to open the **Add Catalog Item** form. #### Add an application to the Catalog Completing this form adds an entry to your Catalog, which is basically a pre-defined application configuration that enables a developer to one-click deploy a development environment using that repository and the definition you’ve provided for it. Fill out as much of the form that makes sense for you. You will see: * Name\* * Repository URL\* * [Default Branch](#define-a-default-branch) * [Manifest Path](#define-a-manifest-path) * [Environment Variables](#add-environment-variables) Only the `Name` and `Repository URL` fields are required. When done, click `Save`. ![Add a repository to the Catalog](/docs/assets/images/admin_catalog_view_add+1.33-11f2e3459233f1a0e435c6cea0f78d6e.png) #### Define a Default Branch The default branch you specify here will be the default branch used when a developer selects this Catalog item to deploy a development environment. You can specify multiple Catalog entries for the same `Repository URL` and set a different `Default Branch` for each one if your use case necessitates that. #### Define a Manifest Path This field should (optionally) point to where your Okteto manifest resides. This provides additional control to provide a smoother experience for developers who deploy a development environment from the Catalog. #### Add Environment Variables You can also (optionally) add Environment Variables to your Catalog entry to standardize how the development environment is deployed. Similar to the Default Branch entry, you could specify multiple catalog entries for the same Repository URL each with different Environment Variables. ![Add environment variables to a Catalog repo](/docs/assets/images/admin_catalog_view_add_env_var+1.32-d507809b135ff141d05c55987ee2edfe.png) ### Create and Manage Catalog Items via Custom Resource Definitions (CRDs) You can also manage your [catalog using Custom Resource Definitions (CRDs)](/docs/self-hosted/manage/custom-resource-definitions.md#catalog-items) to configure and manage items programmatically. This approach is particularly useful for teams leveraging GitOps workflows or automating deployments with tools like kubectl. This approach can be useful if you'd like to have a default Catalog on installation. Using CRDs for catalog items allows you to define configurations as code, which can then be applied to your cluster. Once applied, these catalog items will appear in the Okteto UI, but they cannot be modified through the dashboard. They will be shown with the tag "Read-only." If you prefer to manage Catalog items directly via the UI, you should create them there instead. For detailed instructions on using CRDs in Okteto, including examples, refer to the [Custom Resource Definitions documentation](/docs/self-hosted/manage/custom-resource-definitions.md#catalog-items). ## Deploy a Dev Environment from your Catalog Once you’ve defined your Catalog entries, you can navigate to `Namespaces` → `Deploy Dev Environment` → `Catalog`. In this section you should see all of the repositories you’ve added (and pre-configured). Select an entry you wish to use and click `Deploy`. ![Deploy a development environment from the Catalog](/docs/assets/images/gc_deploy_dev_env+1.17-11f15feb5297c2d74cc6a652142e16f2.png) ![view a Catalog repo's environment variables](/docs/assets/images/gc_deploy_view_env_vars+1.17-b916f8e89850cbb62689be8940ec054b.png) --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Garbage Collector The Okteto Garbage Collector (GC) allows Admins to optimize infrastructure usage by automatically scaling down or deleting inactive Namespaces and Preview Environments, helping control costs and improve resource efficiency. ## Enabling the Garbage Collector The Garbage Collector is enabled by default in Okteto installations. If your GC has been disabled, navigate to **Admin → Garbage Collector** under the Settings section and flip the toggle to "Enabled" to begin using it. Once enabled, the GC automatically scales idle environments to zero and deletes unused Namespaces and Preview Environments based on your configured settings. ## Configuring the Sleep and Delete Periods ### Understanding the Periods Admins can set custom sleep and delete periods for both Namespaces and Preview Environments: * **Sleep Period**: The amount of time, in hours, that an environment must remain idle before the GC scales it down to zero * **Delete Period**: The amount of time (in hours or days) that an environment must remain idle before the GC permanently deletes it. If the sleep period is set, this represents the amount of time that the environment must stay in sleeping status before it is deleted. If sleep period is disabled, this represents the amount of time since the last update in the environment before it is deleted. **Default Values**: * **Namespaces** * Sleep period: 3h * Delete period: 14 days * **Preview Environments** * Sleep period: 1h * Delete period: 7 days ### Configuration Examples Here's how the timing works in practice: **Example 1: Default Namespace Settings (3h sleep, 14d delete)** * Environment becomes idle on Monday 9:00 AM * Will sleep on Monday 12:00 PM (3 hours later) * Will be deleted 14 days after entering sleep mode **Example 2: Aggressive Preview Environment Settings (30min sleep, 2d delete)** * Preview environment idle since Tuesday 2:00 PM * Will sleep on Tuesday 2:30 PM (30 minutes later) * Will be deleted on Thursday 2:30 PM (2 days after sleeping) **Example 3: Sleep Disabled, Delete Only (delete after 7d)** * Environment becomes idle on Friday 10:00 AM * Will be deleted the following Friday 10:00 AM (7 days from last activity) ### Step-by-Step Configuration 1. Navigate to **Admin → Garbage Collector** in your Okteto dashboard 2. In the **Settings for Namespaces** section: * 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 Previews** section: * Configure similarly to Namespaces * Consider shorter periods for temporary environments 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. ![garbage collector settings in the admin dashboard](/docs/assets/images/admin_garbage_collector+1.33-f0cfa27e74fccc13aead015299cfb15f.png) ## Applying Garbage Collection to Personal Namespaces [Personal Namespaces](/docs/core/namespaces.md#personal-namespaces) (automatically created when a user logs in) can follow the same Garbage Collection rules as other namespaces, but this feature must be toggled on in the Admin Dashboard. To enable GC for Personal Namespaces, navigate to **Admin → Garbage Collector** and find the **Settings for Namespaces** section. Here, you can toggle whether the contents of a Personal Namespaces are included in GC. **How It Works** * 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 * **Persistent Volume Claims (PVCs) within Personal Namespaces will not be deleted** as part of the GC process * If a Personal Namespace remains unused past the defined threshold (e.g., 15 days), its **contents** will be cleaned up automatically ## Manually Sleeping Resources The Okteto Garbage Collector automatically scales inactive applications to zero if they haven't been used for longer than the `sleep` period set to automatically save resources in your cluster. ### Manual Sleep Process 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 **Put To Sleep** from the dropdown menu 5. Confirm the action when prompted warning Manually sleeping a Namespace will immediately scale down all deployments and statefulsets. This action cannot be undone automatically - you'll need to manually wake the Namespace or wait for incoming traffic (if auto-wake is enabled). ![sleep option in the namespace actions dropdown menu](/docs/assets/images/cleanup-namespace-sleep+1.42-b75b58c5116d766ae470fc955b7de944.png) ## Understanding the Impact of Garbage Collection ### What Happens During Sleep When the Garbage Collector sleeps a Namespace, it specifically: **Scales to Zero:** * Kubernetes Deployments (replicas set to 0, so that pods are deleted but the deployment config remains) * StatefulSets (replicas set to 0, so that pods are deleted but the statefulset config remains) * DaemonSets (if configured to be managed by GC) **Preserved During Sleep:** * Service accounts, config maps, and secrets * Persistent Volume Claims (PVCs) and their data * Services and ingress configurations * Custom Resource Definitions (CRDs) * Okteto-specific configurations **Performance Impact:** * **Memory usage**: Sleeping Namespaces use minimal cluster memory * **Storage**: No change to persistent storage usage ### What Happens During Deletion When the delete period is reached, the Garbage Collector will: **Completely Remove:** * The entire Namespace and everything inside it will be deleted. For [Personal Namespaces](/docs/core/namespaces.md#personal-namespaces), only the resources inside the Namespace are deleted—the Namespace itself remains. * All deployments, services, config maps, secrets * **Persistent Volume Claims and their data** (except in [Personal Namespaces](/docs/core/namespaces.md#personal-namespaces), where PVCs are preserved and not deleted) * Any custom resources within the Namespace **Cannot Be Recovered:** * Deleted Namespaces cannot be restored * All application data is permanently lost * Users must recreate environments from source danger Deletion is permanent and irreversible. Ensure critical data is backed up or [mark important Namespaces as persistent](#persistent-resources). ## What Counts as Activity? Okteto considers an application inactive if a user hasn't performed any of the following tasks during the `sleep` period. Understanding what activities prevent sleeping is crucial for effective garbage collection. The GC only sleeps environments that have been truly inactive. ### Activities That Prevent Sleeping or Will Wake a Sleeping Namespace * Deploying a Kubernetes Deployment or StatefulSet with `kubectl` or similar tools * Running `okteto deploy` * Running `okteto up` * Maintaining an active `okteto up` session. If the `upSessionByLastSyncedFile` setting is enabled, this only counts if files are actively being synced (based on the last synced file) * Upgrade or redeploy via the UI or the command line Service accounts, config maps, secrets, or volumes you create will be unaffected by the `sleep` operation. Additionally, if you are using the Okteto Nginx Ingress Controller, incoming requests will automatically wake a sleeping Namespace. 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](/docs/self-hosted/helm-configuration.md#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](/docs/self-hosted/helm-configuration.md#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. **To wake all resources at once:** 1. Navigate to your Namespace in the Okteto UI 2. Look for the sleeping resources notification banner 3. Click the **Wake all** button to activate all sleeping resources simultaneously 4. Wait 1-2 minutes for all resources to fully start **To wake specific resources:** 1. Go to **Admin → Namespaces** 2. Find the sleeping Namespace 3. Click the three dots (⋯) and select **Wake Up** 4. Resources will begin starting automatically ![wake all button to activate sleeping resources in a namespace](/docs/assets/images/wake+1.33-2306dd16b7d040031d8dca84fa646380.png) ## Delete Unused Namespaces Namespaces and all the resources and data contained within will be deleted if they stay `sleeping` for longer than the `delete` period. note This only affects [Non-Personal Namespaces](/docs/core/namespaces.md), Personal Namespaces are not automatically deleted when idle. ## Persistent resourcesScaleEnterpriseSelf-Hosted 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](/docs/admin/dashboard.md#namespaces). ![mark a namespace as persistent](/docs/assets/images/namespace-mark-persistent-c174a795922bf583486bfc5200fc024a.png) 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. ## Helm Configuration StepsScaleEnterpriseSelf-Hosted You can set the `sleep` and `delete` periods in the [Admin Dashboard](#configuring-the-sleep-and-delete-periods) following the instructions above. If you are using Okteto Self-Hosted, you can also [configure this in the Helm Chart](/docs/self-hosted/helm-configuration.md#gc) along with options like a Slack webhook for notifications when resources are scaled to zero. ## Troubleshooting ### Common Issues and Solutions **Problem: Garbage Collector Not Sleeping Resources** *Symptoms:* Resources remain active despite exceeding the sleep period *Solutions:* 1. **Check GC Status**: Go to **Admin → Garbage Collector** and verify it's enabled 2. **Verify Timing**: Confirm the sleep period configuration and when the resource was last active 3. **Check for Activity**: Look for recent deployments, `okteto up` sessions, or kubectl operations 4. **Review Labels**: Ensure resources don't have `dev.okteto.com/persistent` label **Problem: Resources Deleted Unexpectedly** *Symptoms:* Important resources were deleted by GC *Solutions:* 1. **Mark as Persistent**: Add `dev.okteto.com/persistent` label to critical Namespaces 2. **Adjust Periods**: Increase delete periods for your use case 3. **Check Activity Tracking**: Ensure team knows what counts as "activity" **Problem: Personal Namespaces Being Affected** *Symptoms:* Personal Namespace contents are being deleted *Solutions:* 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 **Problem: Auto-wake Not Working** *Symptoms:* Incoming requests don't wake sleeping Namespaces *Solutions:* 1. **Check Ingress**: Ensure you're using Okteto's Nginx Ingress Controller 2. **Verify Configuration**: Check if `autowake` is disabled in Helm config 3. **DNS/Routing**: Confirm requests are reaching the correct ingress endpoint ## Best Practices and Use Cases ### Recommended Settings by Team Size **Small Teams (5-15 developers):** * **Namespaces**: Sleep 6h, Delete 21d * **Preview Environments**: Sleep 2h, Delete 3d * **Reasoning**: Longer periods account for time zones and varying work schedules **Medium Teams (15-50 developers):** * **Namespaces**: Sleep 4h, Delete 14d * **Preview Environments**: Sleep 1h, Delete 2d * **Reasoning**: More active development requires faster cleanup of unused resources **Large Teams (50+ developers):** * **Namespaces**: Sleep 3h, Delete 10d * **Preview Environments**: Sleep 30min, Delete 1d * **Reasoning**: High resource utilization demands aggressive cleanup ### Cost Optimization Strategies **1. Implement Graduated Cleanup:** * Short sleep periods (1-2h) for immediate cost savings * Moderate delete periods (7-14d) for safety * Monitor and adjust based on usage patterns **2. Use Labels Strategically:** You can mark Namespaces or specific deployments as persistent directly from the Okteto UI. To do this, follow the instructions in the [section above](#persistent-resources) to use the UI for marking a Namespace as persistent. Alternatively, you can use `kubectl` to add the label manually if you need more granularity: ``` # Mark production-like environments as persistent kubectl label namespace staging dev.okteto.com/persistent=true # Mark specific deployments as persistent within a Namespace kubectl label deployment database dev.okteto.com/persistent=true ``` **3. Monitor Resource Usage:** * Track sleeping vs. active resources weekly * Identify teams/projects with unused environments * Adjust periods based on actual usage patterns **4. Communicate with Teams:** * Provide clear guidelines on what constitutes "activity" * Train developers on waking and managing sleeping resources ### Environment Protection Strategies **Critical Environments:** * Mark as persistent * Set very long delete periods (90d+) * Implement backup strategies for important data **Compliance Requirements:** * Configure longer retention periods for audit trails * Implement data backup before deletion * Document GC policies for compliance reviews --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Cloud Credentials In the Admin Dashboard, you can configure Cloud Credentials for accessing your cloud account. Cloud Credentials are automatically used by Okteto in your Okteto Manifest commands, eliminating the need to manage static credentials. Once configured, all developers can securely access your cloud provider using the Okteto cluster's identity, enhancing overall security and simplifying credential management. ![Cloud credentials view](/docs/assets/images/cloud_credentials_view+1.32-8a9e1ca815ad5d1cd64d77ea677bdb0a.png) Follow our guides below to learn how to configure your Cloud Credentials for supported cloud providers: * [Amazon Web Services](/docs/admin/cloud-credentials/aws-cloud-credentials.md) * [Google Cloud](/docs/admin/cloud-credentials/gcp-cloud-credentials.md) note If you see a “Read-only” tag next to Cloud Credentials in the interface, it means that these items were defined using Custom Resource Definitions (CRDs). Such items cannot be modified through the Admin Dashboard. To make changes, you will need to [update the associated CRD directly](/docs/self-hosted/manage/custom-resource-definitions.md#cloud-credentials). ## Manage Cloud Credentials using CRDs You can also manage your [Cloud Credentials using CRDs](/docs/self-hosted/manage/custom-resource-definitions.md#cloud-credentials). This is useful, for example, if you have your own mechanism to provision Cloud Credentials in your cluster. 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. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Configure access to your AWS account using IAM Roles 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. AWS credentials are configured using [OIDC federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html) to [assume an IAM Role via Web Identity](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage-assume.html). This provides secure and temporary access to your AWS resources. ## Step 1: Register the Identity Provider info Before starting, we recommend installing the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions) The first step in configuring AWS credentials is to register your Kubernetes cluster as an OIDC identity provider in AWS. To do this, Okteto provides the OIDC issuer and subject of your cluster, which can be found under the Integrations -> General section of your Okteto Admin Dashboard. ![OIDC configuration in admin general view](/docs/assets/images/amazon-ecr-oidc-config+1.32-fa9dcee1504951f595d5e5c9da6f19d4.png) Store the values as environment variables, you will use them in the next steps: ``` export OIDC_ISSUER=https://container.googleapis.com/v1/projects/myProject/locations/us-central1/clusters/myCluster export OIDC_SUBJECT=system:serviceaccount:okteto:okteto ``` Next, define the `AUDIENCE`. The `AUDIENCE` is traditionally the client ID of the requester, and tokens will only be exchanged for these audiences. It corresponds to the `aud` field in the JWT payload. We recommend creating a unique audience for each Okteto instance and AWS region. For example: ``` export AUDIENCE=okteto.example.com/us-east-2 ``` Next, run the following command to create the OIDC identity provider in AWS: ``` aws iam create-open-id-connect-provider --url "${OIDC_ISSUER}" --client-id-list "${AUDIENCE}" ``` Once successful, you’ll receive a response with the provider ARN: ``` { "OpenIDConnectProviderArn": "arn:aws:iam::112233445566:oidc-provider/container.googleapis.com/v1/projects/myProject/locations/us-central1/clusters/myCluster" } ``` Store this value in an environment variable, you'll use it in the next step: ``` export PROVIDER_ARN=arn:aws:iam::112233445566:oidc-provider/container.googleapis.com/v1/projects/myProject/locations/us-central1/clusters/myCluster ``` ## Step 2: Create the IAM Role and Grant Access to S3 In this step, you'll create an IAM Role that allows access to S3 and configure it to assume the role using the OIDC identity provider you set up in the previous step. ### Create the Trust Policy First, create the trust policy that allows the role to be assumed by the OIDC identity provider. To do this, create a local file named `trust-policy.json`, copy the contents of the file below, and substitute the placeholder values with the resources that we created in the previous steps: trust-policy.json ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { ":aud": "", ":sub": "" } } } ] } ``` For reference: * **OIDC\_ISSUER**: The OIDC Issuer of your Okteto instance `OIDC_SUBJECT` that we retrieved in Step 1, without the "https\://" part of the url. * **OIDC\_SUBJECT**: The OIDC subject of your Okteto instance `OIDC_SUBJECT` that we retrieved in Step 1. * **AUDIENCE**: The audience `AUDIENCE` that we defined in Step 1. * **PROVIDER\_ARN**: The ARN of the OpenID connect provider `PROVIDER_ARN` that we created in Step 1. A completed file will look similar to this example: trust-policy.json ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::112233445566:oidc-provider/container.googleapis.com/v1/projects/myProject/locations/us-central1/clusters/myCluster" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "container.googleapis.com/v1/projects/myProject/locations/us-central1/clusters/myCluster:aud": "okteto.example.com/us-east-2", "container.googleapis.com/v1/projects/myProject/locations/us-central1/clusters/myCluster:sub": "system:serviceaccount:okteto:okteto" } } } ] } ``` Run the following command to create the IAM Role in AWS with the trust policy you defined: ``` aws iam create-role --role-name okteto-credentials --assume-role-policy-document file://trust-policy.json ``` You will receive a response similar to: ``` { "Role": { "Path": "/", "RoleName": "okteto-credentials", "RoleId": "AR...", "Arn": "arn:aws:iam::112233445566:role/okteto-credentials", "CreateDate": "2024-06-10T15:04:05+00:00", "AssumeRolePolicyDocument": { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::112233445566:oidc-provider/container.googleapis.com/v1/projects/myProject/locations/us-central1/clusters/myCluster" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "container.googleapis.com/v1/projects/myProject/locations/us-central1/clusters/myCluster:aud": "okteto.example.com/us-east-2", "container.googleapis.com/v1/projects/myProject/locations/us-central1/clusters/myCluster:sub": "system:serviceaccount:okteto:okteto" } } } ] } } } ``` Store the `ARN` of the role you just created in an environment variable, you'll use it in the next step: ``` export ROLE_ARN=arn:aws:iam::112233445566:role/okteto-credentials ``` Finally, attach the S3 policy to the IAM Role to grant it full read and write access to your S3 buckets: ``` aws iam attach-role-policy --role-name okteto-credentials --policy-arn arn:aws:iam::aws:policy/AmazonS3FullAccess ``` This grants the IAM Role the necessary permissions to interact with S3. ## Step 3: Configure AWS Cloud Credentials in Okteto Now that you've created the IAM role, the final step is to configure the AWS credentials in Okteto. There are two different ways that Cloud Credentials can be configured in Okteto: 1. **Cloud Credentials in the Okteto Admin Dashboard** - Follow the below steps to add credentials via the Admin dashboard 2. **Cloud Credentials via a CRD** - [Follow this guide to add your cloud provider credentials via a CRD](/docs/self-hosted/manage/custom-resource-definitions.md#cloud-credentials) note Please note that if you add credentials using CRDs they will be displayed in the Dashboard, but they cannot be modified from this view. ### Adding Cloud Credentials Through the Admin Dashboard 1. Go to the [Cloud Credentials view](/docs/admin/cloud-credentials.md) view in the Okteto Admin dashboard 2. Enable the AWS IAM Role option ![AWS IAM Role](/docs/assets/images/aws-cloud-credentials+1.32-52cf044786692bddfdb1ada559d9f4f8.png) 3. Provide the following information: * **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. 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 With the configuration complete, the following example Okteto Manifest can interact with the specified S3 bucket: ``` deploy: image: amazon/aws-cli commands: - aws s3 mb s3://test-bucket --region us-west-2 test: aws: image: amazon/aws-cli commands: - aws s3 ls | grep test-bucket destroy: image: amazon/aws-cli commands: - aws s3 rb s3://test-bucket --region us-west-2 ``` --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Configure access to your GCP account using Workload ID This guide walks you through configuring Google Cloud Platform (GCP) credentials for your Okteto instance to enable the commands in your Okteto Manifests to interact with your GCP account. We will focus on requesting access to Cloud Storage. However, you can extend this approach to grant access to other GCP resources by specifying a role with the necessary permissions. GCP credentials are configured using [Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation). This provides secure and temporary access to your GCP resources. ## Step 1: Create the Workload Identity Pool info We recommend installing the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) before following this tutorial A Workload Identity Pool is a group of identities that can be used to access GCP resources. First, choose a name for your Workload Identity Pool and export it as an environment variable: ``` export POOL_ID=okteto-pool ``` Next, create the Workload Identity Pool by running the following command: ``` gcloud iam workload-identity-pools create ${POOL_ID} --location=global --display-name="Okteto pool" ``` ## 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. ![OIDC configuration in admin general view](/docs/assets/images/amazon-ecr-oidc-config+1.32-fa9dcee1504951f595d5e5c9da6f19d4.png) Store these values as environment variables, you will use them in the next steps: ``` export OIDC_ENDPOINT=https://container.googleapis.com/v1/projects/myProject/locations/us-central1/clusters/myCluster export OKTETO_SERVICE_ACCOUNT=system:serviceaccount:okteto:okteto ``` The `AUDIENCE` is traditionally the client ID of the requester, and tokens will only be exchanged for these audiences. It corresponds to the `aud` field in the JWT payload. We recommend creating a unique audience for each Okteto instance and GCP region: For example: ``` export AUDIENCE=okteto.example.com/us-central1 ``` Run the following command to create the identity provider: ``` gcloud iam workload-identity-pools providers create-oidc myCluster \ --location=global \ --workload-identity-pool=${POOL_ID} \ --display-name="Okteto Identity Provider" \ --attribute-mapping="google.subject=assertion.sub" \ --issuer-uri="${OIDC_ENDPOINT}" \ --allowed-audiences=${AUDIENCE} ``` ## Step 3: Create the IAM Policy Binding Now, grant the Okteto Kubernetes service account the permissions required to access the specified GCP resources. First, retrieve the `PROJECT_ID` and `PROJECT_NUMBER` values from your Google Cloud project. You can get them by going to your [Project's settings in the Google Cloud Console](https://console.cloud.google.com/iam-admin/settings). Next, set the following variables: ``` export PROJECT_ID=myProject-123 export PROJECT_NUMBER=118593354781 export PRINCIPAL=iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_ID}/subject/${OKTETO_SERVICE_ACCOUNT} ``` Finally, run the following command to bind the appropriate IAM role to the service account: ``` gcloud projects add-iam-policy-binding ${PROJECT_ID} --role=roles/storage.admin --member=principal://${PRINCIPAL} --condition=None ``` This grants the Okteto service account permission to access Cloud Storage resources. ## Step 4: Configure GCP Cloud Credentials in Okteto Now that you've created the IAM Policy Binding, the final step is to configure the GCP credentials in Okteto. There are two different ways that Cloud Credentials can be configured in Okteto: 1. **Cloud Credentials in the Okteto Admin Dashboard** - Follow the below steps to add credentials via the Admin dashboard 2. **Cloud Credentials via a CRD** - [Follow this guide to add your cloud provider credentials via a CRD](/docs/self-hosted/manage/custom-resource-definitions.md#cloud-credentials) note Please note that if you add credentials using CRDs they will be displayed in the Dashboard, but they cannot be modified from this view. ### Adding Cloud Credentials Through the Admin Dashboard Go to the [Cloud Credentials view](/docs/admin/cloud-credentials.md) view in the Okteto Admin dashboard and enable the GCP Workload ID option: ![GCP Workload ID](/docs/assets/images/gcp-cloud-credentials+1.32-83c2d956e7e5213a5fbaa2511058485b.png) Provide the following information: * **Project Number**: The GCP project id `PROJECT_NUMBER` where the resources are located * **Workload Identity Pool ID**: The Pool ID `POOL_ID` you created in Step 1 * **Provider ID**: The OIDC Provider ID created in Step 2 * **Audience JWT Claim**: The Audience `AUDIENCE` you specified during the Identity Provider setup ## Example Okteto Manifest With the configuration complete, the following Okteto Manifest can interact with the specified storage buckets: ``` deploy: image: gcr.io/google.com/cloudsdktool/google-cloud-cli:stable commands: - gcloud storage buckets create gs://test-bucket test: gcp: image: gcr.io/google.com/cloudsdktool/google-cloud-cli:stable commands: - gcloud storage ls | grep test-bucket destroy: image: gcr.io/google.com/cloudsdktool/google-cloud-cli:stable commands: - gcloud storage buckets delete gs://test-bucket ``` --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Custom Installer Image You can specify a custom installer image to deploy your Development Environments. Use this if you want to use tools, frameworks, or custom configurations not included in the [default installer image](https://github.com/okteto/pipeline-runner). ## Requirements To use the Custom Installer Image feature, you first need to create your own Docker image, and push it to a registry that can be accessed by your Okteto instance. ### Defining the Custom Image When creating your image, we recommend extending the image from [the latest version](https://github.com/okteto/pipeline-runner/releases) of the default pipeline runner image. Your image can include anything that you need when deploying Development Environments for your organization. The example below shows you how to include `wget`: ``` FROM ghcr.io/okteto/pipeline-runner:1.46.0 RUN apt-get upgrade && apt-get install wget ``` ### Build and Publish the Custom Image Once the image has been defined, build it and push it to your container registry. ``` docker build -t REGISTRY/REPOSITORY:TAG . docker push REGISTRY/REPOSITORY:TAG ``` ## Configure your Custom Image * Self-Hosted * BYOC To enable the custom image, update your Okteto Helm configuration file with the following values, and run a [helm upgrade](/docs/self-hosted/manage/upgrade.md) to apply the new configuration. ``` installer: runner: registry: REGISTRY repository: REPOSITORY tag: TAG ``` If your instance is hosted by Okteto, contact support to configure your custom image in your Okteto Instance. ## Using the Custom Image Once the configuration has been applied, all the Development Environments will be deployed using your custom image. 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. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Admin DashboardScaleEnterpriseSelf-Hosted The Admin Dashboard provides a web UI to see various details of your Okteto instance in a centralized location and offers features for managing parts of the Okteto experience for your users. ## Accessing the dashboard 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](/docs/assets/images/admin_dashboard_sidebar+1.41-96ea7d97a881c0c489d14211718f2c1f.png) The Admin Dashboard consists of the following views: Cluster Management * [Overview](#overview) * [Installation](#installation) * [Catalog](#catalog) * [Users](#users) * [Build Service](#build-service) * [Nodes](#nodes) * [Namespaces](#namespaces) * [Previews](#previews) Settings * [Command Line (CLI)](#command-line-cli) * [Deployments](#deployments) * [SSH Known Hosts](#ssh-known-hosts) * [Admin Variables](#admin-variables) * [Garbage Collector](#garbage-collector) * [Resource Manager](#resource-manager) * [Okteto AI](#okteto-ai) Integrations * [General Integrations](#general-integrations) * [Admin Access Tokens](#admin-access-tokens) * [Registry Credentials](#registry-credentials) * [Cloud Credentials](#cloud-credentials) We will cover these in more detail below. ## Overview The overview section of the Admin Dashboard is designed to give you a high level view of your Okteto instance. This section currently shows you the following information: * Your current pricing plan and license expiration date * Number of available seats * Okteto Helm chart version * Okteto CLI version * Kubernetes version * Number of nodes in your cluster * 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. ![Okteto installation view](/docs/assets/images/installation_view_sidebar+1.33-d83b0c602dfca2519f41b17010775a8f.png) From this page you can follow a simple step-by-step guide to get the major components setup and have your Okteto installation ready to go in minutes. Each of these tasks comes with documentation to help guide you and are also skippable in case they don't apply to you or you simply wish to complete them later. ## Catalog This section of the Admin dashboard allows you to build a library of ready-to-use development environments for your team. By setting up these environments in advance, developers can quickly deploy them from the Deploy Dev Environment UI, significantly speeding up their setup process and reducing the need for initial configuration. ![Catalog table view](/docs/assets/images/admin_catalog_view+1.32-5ffcbf234bfd159b8d84f2f897fe2cfd.png) Please see our [Catalog documentation](/docs/admin/catalog.md) to learn more about creating and deploying from an Okteto Catalog. ## Users From this section you can manage all users in your Okteto instance. This is a list of all users that have created an account in your Okteto instance, their respective roles, and with appropriate actions to manage their membership. info The `User` column is also the user's default `namespace` name/id. For example, a `User` value of "darryl" means that that user's namespace will also be called "darryl". Any additional namespaces created by "darryl" will show up only in the `Namespaces` tab. 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 `Developer` or `Admin` from the dropdown menu in the `Role` column) * Remove users (Click **Remove** from the overflow menu on the far right) caution Removing the user will automatically remove all the namespaces owned by the deleted user. ## 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](/docs/assets/images/admin_build-fb0ff498df0d166b5e2066968aa62d48.png) 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](/docs/core/build-service.md#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 →](/docs/admin/build-service.md) ## Nodes In this section of the Admin Dashboard, you can find the following system information about your Kubernetes cluster, separated by node: * Number of running pods * Number of volumes in use * Memory utilization * CPU utilization ## Namespaces This view enables you to manage all of the Namespaces within your Okteto instance, including the ability to view (masquerade as the user), wake, or persist any Namespace. The top of the Namespace table also shows you the default settings for the [garbage collection](/docs/self-hosted/helm-configuration.md#gc) configuration. 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 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](/docs/self-hosted/helm-configuration.md#gc) process * [Transfer a Namespace](/docs/core/namespaces.md#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](/docs/admin/cleanup.md#what-counts-as-activity). ## Previews Similar to the [Namespaces section](#namespaces), the `Previews` section shows you a list of all [Preview Environments](/docs/previews.md) that exist in your Okteto instance. 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. [See the full Preview Environments management guide →](/docs/admin/previews.md) ## Command Line (CLI) The Command Line section allows you to manage how developers interact with Okteto via their CLI. Here, you can enable [remote execution by default](/docs/core/remote-execution.md) and configure the minimum accepted CLI version that developers can use. As an Okteto Admin, you can now enforce a minimum accepted CLI version for your developers. This feature ensures compatibility, encourages feature adoption, and maintains a consistent experience across your team. ### How Enforcing a Minimum Accepted CLI Version Works **Admin Configuration** * Set the minimum accepted CLI version through the Okteto Admin Dashboard. Let's say the installed CLI version on the cluster is *3.2.0*, the options are: * **Any Version**: No restriction, developers can use any CLI version * **Current Version**: Restricts developers to use same CLI version installed on cluster or newer, i.e. >= v3.2 * **Previous Version**: Restrict developers to at least the prior minor version, i.e. >= 3.1 * **Two Previous Versions**: Restrict developers to at least two prior minor versions, i.e. >= 3.0 **CLI Version Enforcement** * Commands fail if a developer uses a CLI version older than the minimum setting, displaying an error prompting them to update their CLI. note Version enforcement only applies to those using [Okteto CLI 3.2.0](https://github.com/okteto/okteto/releases/tag/3.2.0) and above. ## Deployments The Deployments section of the Admin Dashboard allows administrators to configure default behavior when redeploying or destroying resources with declared dependencies. From this panel, you can enable the following options: * **Redeploy Including Dependencies**: When enabled, redeploying a resource will also automatically redeploy its direct dependencies by default * **Destroy Including Dependencies**: When enabled, destroying a resource will also destroy its direct dependencies by default 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. [Learn how to configure SSH Known Hosts →](/docs/admin/ssh-known-hosts.md) ## Admin Variables The Admin Variables section of the Admin dashboard lets you define cluster-wide variables. You can refer to these variables directly in your Okteto manifest using the `$SOME_VAR` syntax. They are also injected into the [environment running](/docs/core/okteto-manifest.md#deploy) the commands in the `deploy` section of the manifest. info Variables [defined by the user](/docs/core/okteto-variables.md) take precedence over variables and build secrets defined through the manifest. We recommend using [build secrets](/docs/reference/okteto-manifest.md#secrets-string-optional) to inject sensitive data into your Dockerfile. The example below shows how to configure your Okteto manifest to mount a local `.env` file into your Dockerfile: ``` build: api: context: . secrets: my_env: .env ``` You can refer to this secret from your Dockerfile using the syntax below: ``` RUN --mount=type=secret,id=my_env,target=/etc/secrets/.env cat /etc/secrets/.env ``` The content of the `.env` file would be: ``` ${MY_PASSWORD} ``` where `MY_PASSWORD` can be a local environment variable or an Okteto Secret, and it gets substituted by Okteto before mounting the file as a build secret. ## Garbage Collector Configure sleep and delete periods for Okteto Namespaces and Preview Environments from the UI. [See our cleanup guide for full details on setting sleep and delete periods for your environments and other options available →](/docs/admin/cleanup.md) ## Resource Manager Automatically optimize the 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. [See our Resource Manager documentation for a full guide on how to automatically optimize your environments →](/docs/admin/resource-manager.md) ## 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](/docs/assets/images/admin_ai_agent_fleets-9902c3503f1245102f1ebe0101542acb.png) 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.6**, 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 →](/docs/okteto-ai/okteto-ai-admin-config.md) ## General Integrations This section allows you to configure Okteto integrations with other tools. The following options available are: * Configuring your Git SSH key * Getting your [Okteto Insights](/docs/admin/okteto-insights.md) token * Configuring [OpenID Connect (OIDC)](/docs/admin/registry-credentials/amazon-ecr.md#using-iam-roles-via-openid-connect-oidc-federation) ## Admin Access Tokens You can use Admin Access Tokens instead of OAuth to authenticate with Okteto. Admin Access Tokens are created and work in the same manner as [*Personal* Access Tokens](/docs/core/credentials/personal-access-tokens.md), with the difference that they have admin permissions. They are intended to be used over personal access tokens for shared automations, e.g. [Preview Environments](/docs/previews.md). Automations run with Admin Access tokens are performed by the [`okteto-bot` user](/docs/self-hosted/helm-configuration.md#oktetobotuser). info It is important that you set the [`scope` to `global`](/docs/admin/dashboard.md#previews) for Preview Environments created with the `okteto-bot` user so that users other than `okteto-bot` can view the environment. ![Admin Access Tokens view](/docs/assets/images/admin_access_tokens+1.33-faf8a668761f9a16313b287bc79f9003.png) ## Registry Credentials If you choose to pull images from a private registry in addition to [Okteto's Container Registry](/docs/core/container-registry.md), you can configure credentials for that service here. [Review this page for a full description of how to configure and start using your own Registry Credentials →](/docs/admin/registry-credentials.md) ## Cloud Credentials Dynamically configure Okteto's connection to AWS and GCP, eliminating the need for developers to manage static credentials. [Review this page for a full description of how to configure and start using Cloud Credentials →](/docs/admin/cloud-credentials.md) --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okta User Deprovisioning If you have configured Okta as your identity provider for Okteto, you can automatically deprovision users once they are deleted in Okta. If you haven't yet configured Okta as your identity provider but would like to, please follow our [Installation Guide here](/docs/self-hosted/install/auth/okta.md). Okteto provides an endpoint to receive Okta [event hooks](https://help.okta.com/en-us/content/topics/automation-hooks/event-hooks-main.htm) that will automatically deprovision users when they are deleted or deactivated from Okta. note Only the `user.lifecycle.deactivate` and `user.lifecycle.delete.initiated` events are supported. If more events are added they will be ignored. ## Configuration To set up the Okta event hook for user deprovisioning, follow these steps: ### 1. Configure the Event Hook in Okta Within your Okta management console, navigate to `Workflows -> Event Hooks` and create a new event hook with the following configuration: * **Name**: A descriptive name for the event hook * **URL**: `https://okteto.YOUR_SUBDOMAIN.com/api/okta` * **Authentication Field**: It must be set to `Authorization` as this is the field that Okteto uses to authenticate the request * **Authentication Secret**: Provide a secret value that will be used to authenticate the request. This value should match the value provided in the Okteto Admin Dashboard in the next step (more info below) * **Events**: Select the `User Deactivated` and/or `User Deleted` events tip Okteto handles both the **User Deactivated** and **User Deleted** events the same way, automatically deprovisioning the user in either case. If both events are selected, the User Deleted event will be skipped for users who are already deactivated. ![Okta User Deprovision Configuration](/docs/assets/images/okta-user-deprovision-e0817defff3a2d47feb64376efdf731c.png) ### 2. Configure Okta Deprovisioning in the Okteto Admin Dashboard Okta requires verifying ownership of the URL before sending events. This is a special one-time event that Okta sends to the webhook, and Okteto automatically handles this verification. To be able to receive this event and all subsequent `deactivate` and `delete` events, you need to configure the webhook in the Okteto Admin Dashboard. ![Okta User Deprovision webhook verification](/docs/assets/images/okta-user-deprovision-dashboard+1.32-5212ef21c3d2e0753b2b23cf2d1f86ba.png) To configure deprovisioning in Okteto: 1. Navigate to **Admin → Integrations → Okta Deprovisioning** in the Okteto Admin Dashboard 2. Enter the Okta Event Hook Token used as `Authentication Secret` in your Okta event hook configuration 3. Click Enable to activate deprovisioning Once your event hook is created and Okteto is configured to receive events, you can verify the webhook in the **Okta admin console**. ![Okta User Deprovision webhook verification](/docs/assets/images/okta-user-deprovision-verify-116b03a72ae41fa283385a8bbdbfb46e.png) ### 3. Verify the Configuration Once the event hook is created and the Okteto instance is 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 deprovisioning users from the system. Events sent to the webhook appear in the `Reports -> System Log` tab of Okta which can be useful for troubleshooting. note This feature is compatible with Okteto Chart 1.30 and higher. If you get a 404 error during the verification process, ensure your Okteto instance is at least version 1.30. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto API Documentation The Okteto API `BETA` is defined using OpenAPI, providing access to resources managed by Okteto. Combined with the Okteto CLI or other tools, it allows you to automate workflows, such as deleting unused development volumes within a Namespace or redeploying applications. note 🚧 This API is currently in beta * Endpoints, request/response formats, and authentication mechanisms are subject to change as we refine the API * Backward-incompatible changes may occur before the API reaches general availability (GA) For feedback or issues, contact us at . ## Getting Started The Okteto API `BETA` is accessible with an [Admin Access Token](/docs/admin/dashboard.md#admin-access-tokens) 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** 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. ## Overview The Okteto API allows you to programmatically manage resources such as Namespaces, applications, and other platform-level configurations. In conjunction with the CLI, it can be used to automate tasks like: * [Querying Namespace and application statuses](https://github.com/okteto-community/namespaces-report-csv) * [Redeploying applications to keep them up to date](https://github.com/okteto-community/redeploy-applications) * [Sleep Namespaces based on your own custom settings](https://github.com/okteto-community/sleep-namespaces) * A full list of our examples can be found on [GitHub here](https://github.com/topics/okteto-api) ### Authentication All requests to the Okteto API require authentication via Bearer Tokens. You must include your Admin Access Token in the Authorization header for each request. ### Available Endpoints 🚀 For a complete list of API endpoints, refer to the Swagger API Documentation. The Okteto API includes operations for: * Namespaces → List and manage Development and Preview Environments * Applications → Track applications within Namespaces * Users → List and delete users within your Okteto account Refer to the Swagger page for request parameters, response structures, and error handling details. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto Insights Okteto Insights exposes a metrics endpoint you can scrape to collect analytics on resource usage, builds, and deployments. info For Bring Your Own Cloud (BYOC) customers, Okteto Insights comes pre-configured with Grafana dashboards. See the [Okteto Insights Dashboard documentation](/docs/core/okteto-insights-dashboards.md) for instructions on accessing and understanding the available metrics. Use this guide only if you want to enable another tool to consume Insights data. ## Overview Okteto generates data from developer activity on the platform, including product usage, infrastructure utilization, and performance metrics. You can use this data to monitor the health of your Okteto cluster, track trends in build and deploy times, and measure user activity. ![Okteto Insights Dashboard Example](/docs/assets/images/insights-activity-dashboard-4d12f018439d9445af60bfacde9f1fd7.png) ## Consuming Okteto Insights 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`](/docs/self-hosted/helm-configuration.md#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](/docs/self-hosted/helm-configuration.md#insights). ### Retrieve your Bearer Token To retrieve your Insights bearer token from the Okteto Admin Dashboard, navigate to `Admin` -> `General` under the Integrations section. You can copy your bearer token by clicking on the `Show Insights Token` button in the Insights panel. ### Set up the Dashboards To begin collecting and visualizing Insights data, [use our sample repository](https://github.com/okteto/insights-dashboards). It includes setups for deploying Prometheus and Grafana, along with sample dashboards. If you'd like to configure this yourself, you'll need to configure a scraper to connect to this endpoint using the proper token. An example of a Prometheus scraper configuration is: ``` - job_name: "okteto_scrapper" scrape_interval: 5m scrape_timeout: 30s scheme: https static_configs: - targets: ["okteto.:443"] # replace with your Okteto subdomain authorization: type: Bearer credentials: # replace with the token generated by Okteto ``` caution Okteto Self-Hosted **does not** include a Prometheus instance or storage for this data. You will need to deploy your own Prometheus instance (or another data collection platform) to consume the data and manage counters and metrics using Prometheus’ built-in features The [Open Source Dashboard Repository](https://github.com/okteto/insights-dashboards) includes a Prometheus configuration and is a good starting place for configuration. ## Insights Dashboards 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. Refer to the [Okteto Insights Dashboard documentation](/docs/core/okteto-insights-dashboards.md) for instructions on understanding the available metrics. ![Okteto Insights Dashboard Example](/docs/assets/images/insights-activity-dashboard-4d12f018439d9445af60bfacde9f1fd7.png) ## What data is available Okteto Insights provides the following metric groupings: * [Build Metrics](#build-metrics): Information on Build times and results by environment * [Deploy Metrics](#deploy-metrics): Information on Deploy times and results by environment * [Namespace Metrics](#namespace-metrics): Information on the Sleeping and Awake Namespaces * [Node Metrics](#node-metrics): CPU and Memory stats on your Okteto Nodes * [Pod Metrics](#pod-metrics): CPU and Memory stats on your Okteto Pods * [Preview Metrics](#preview-metrics): Information on Sleeping and Awake Preview Environments * [Test Metrics](#test-metrics): Information on test times and results by environment * [User Metrics](#user-metrics): Information on User activity note All metrics provided by Okteto will have the prefix `okteto_` Okteto will progressively make more data available through this endpoint. The following metrics are available today: ### Build Metrics note Only successful builds are tracked with `okteto_usage_build_duration_seconds`. | Metric Name | Type | Description | Labels | | ------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `okteto_usage_build_duration_seconds` | [histogram](https://prometheus.io/docs/practices/histograms/) | This represents metrics related to build times of the images that are being built within Okteto. This metric only reflects builds that have successfully completed. | `devenv_name`, `image_name`, `namespace`, `repository` | | `okteto_usage_build_result` | [counter](https://prometheus.io/docs/concepts/metric_types/#counter) | This represents metrics related to the result of the builds that are being built within Okteto. | `devenv_name`, `image_name`, `namespace`, `repository`, `result` | * **Build Metrics label definitions:** * **`devenv_name`**: If defined, this represents the name of the deployed development environment it is linked to * **`image_name`**: Represents the name of the image to be built as it appears in the Okteto Manifest * **`namespace`**: Contains the okteto cli context from where the request originated * **`repository`**: Contains the git repository where the okteto manifest that defines this image is hosted * **`result`**: `success`, `failure` or `skipped` represent the status of the image ### Deploy Metrics note Only successful deployments are tracked with `okteto_usage_deploy_duration_seconds`. | Metric Name | Type | Description | Labels | | -------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | `okteto_usage_deploy_duration_seconds` | [histogram](https://prometheus.io/docs/practices/histograms/) | This represents metrics related to the time it takes to deploy a development environment. This metric only show deployments that have successfully completed. | `devenv_name`, `namespace`, `repository`, `phase` | | `okteto_usage_deploy_result` | [counter](https://prometheus.io/docs/concepts/metric_types/#counter) | This represents metrics related to the result of the deployment of a development environment. | `devenv_name`, `namespace`, `repository`, `result` | * **Deploy Metrics label definitions:** * **`devenv_name`**: Represents the name of the deployed development environment * **`namespace`**: Contains the okteto cli context from where the request originated * **`repository`**: Contains the git repository where the okteto manifest that defines this development environment is hosted * **`phase`**: Represents the phase of the deployment (either `compose` or `commands`) for which the time series is being recorded. `compose` refers to the [Compose](/docs/reference/okteto-manifest.md#deploy-with-compose) section, and `commands` refers to the [Commands](/docs/reference/okteto-manifest.md#deploy-with-commands) section of the Okteto manifest's Deploy section, indicating how long it took to complete. Summing the time series would represent the total length of a Deploy action. * **`result`**: Can be `success` or `failure` to represent the status of the deployment ### Namespace Metrics | Metric Name | Type | Description | Labels | | ------------------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------ | | `okteto_system_namespace_status_condition` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the status of a namespace. Preview namespaces are not included here. | `namespace`, `condition`, `owner_id` | | `okteto_system_namespace_created_time` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the creation time of a namespace. | `namespace`, `owner_id` | * **Namespace Metrics label definitions:** * **`namespace`**: Contains the namespace name * **`condition`**: Represents the condition of the namespace, values can be `active` or `sleeping` * **`owner_id`**: Represents the owner ID of the namespace ### Node Metrics | Metric Name | Type | Description | Labels | | ------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `okteto_system_node` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the number of nodes running Okteto. | none | | `okteto_system_node_memory_bytes` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the total memory (in bytes) available for allocating to a node. | `node_name` | | `okteto_system_node_memory_requested_bytes` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the total memory (in bytes) [requested](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) for a node. | `node_name` | | `okteto_system_node_memory_usage_bytes` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the total memory (in bytes) in use for a node. | `node_name` | | `okteto_system_node_cpu_cores` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the total CPU cores available for allocating to a node. | `node_name` | | `okteto_system_node_cpu_requested_cores` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the total CPU cores [requested](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) for a node. | `node_name` | | `okteto_system_node_cpu_usage_cores` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the total CPU cores in use for a node. | `node_name` | * **Node Metrics label definitions:** * **`node_name`**: Contains the name of the node represented ### Pod Metrics | Metric Name | Type | Description | Labels | | -------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `okteto_system_pod_container_cpu_requests_cores` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the total CPU [requested](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) of a pod and standard container at that point in time. | `container_name`, `pod_name`, `namespace`, `node_name`, `devenv_name`, `pod_type`, `controller_type`, `controller_name` | | `okteto_system_pod_container_cpu_limits_cores` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the CPU limits of a specific pod and standard container at that point in time. | `container_name`, `pod_name`, `namespace`, `node_name`, `devenv_name`, `pod_type`, `controller_type`, `controller_name` | | `okteto_system_pod_init_container_cpu_requests_cores` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the CPU requests of a specific pod and init container at that point in time. | `container_name`, `pod_name`, `namespace`, `node_name`, `devenv_name`, `pod_type`, `controller_type`, `controller_name` | | `okteto_system_pod_init_container_cpu_limits_cores` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the CPU limits of a specific pod and init container at that point in time. | `container_name`, `pod_name`, `namespace`, `node_name`, `devenv_name`, `pod_type`, `controller_type`, `controller_name` | | `okteto_system_pod_container_cpu_usage_cores` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the CPU usage of a specific pod and standard container at that point in time. | `container_name`, `pod_name`, `namespace`, `node_name`, `devenv_name`, `pod_type`, `controller_type`, `controller_name` | | `okteto_system_pod_container_memory_requests_bytes` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the memory [requested](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) for a specific pod and standard container at that point in time. | `container_name`, `pod_name`, `namespace`, `node_name`, `devenv_name`, `pod_type`, `controller_type`, `controller_name` | | `okteto_system_pod_container_memory_limits_bytes` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the memory limits for a specific pod and standard container at that point in time. | `container_name`, `pod_name`, `namespace`, `node_name`, `devenv_name`, `pod_type`, `controller_type`, `controller_name` | | `okteto_system_pod_init_container_memory_requests_bytes` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the memory [requested](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) for a specific pod and init container at that point in time. | `container_name`, `pod_name`, `namespace`, `node_name`, `devenv_name`, `pod_type`, `controller_type`, `controller_name` | | `okteto_system_pod_init_container_memory_limits_bytes` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the memory limits for a specific pod and init container at that point in time. | `container_name`, `pod_name`, `namespace`, `node_name`, `devenv_name`, `pod_type`, `controller_type`, `controller_name` | | `okteto_system_pod_container_memory_usage_bytes` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the memory usage of a specific pod and standard container at that point in time. | `container_name`, `pod_name`, `namespace`, `node_name`, `devenv_name`, `pod_type`, `controller_type`, `controller_name` | * **Pod Metrics label definitions:** * **`container_name`**: Contains the name of the container being represented * **`pod_name`**: Contains the name of the pod being represented * **`namespace`**: Contains the namespace name * **`node_name`**: Contains the node name * **`devenv_name`**: If defined, this represents the name of the deployed development environment it is linked to * **`pod_type`**: It determines if the pod is in development mode or not, values can be `development` or `standard` * **`controller_type`**: Represents the type of the top controller that created the pod, values can be `deployment` or `statefulset` * **`controller_name`**: Contains the name of the top controller that created the pod ### Preview Metrics | Metric Name | Type | Description | Labels | | ---------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------- | | `okteto_system_preview_status_condition` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the status of a preview. | `namespace`, `condition`, `scope`, `owner_id` | | `okteto_system_preview_created_time` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the creation time of a preview. | `namespace`, `scope`, `owner_id` | * **Preview Metrics label definitions:** * **`namespace`**: Contains the namespace name * **`condition`**: Represents the condition of the preview, values can be `active` or `sleeping` * **`scope`**: Represents the scope of the preview, values can be `personal` or `global` * **`owner_id`**: Represents the owner ID of the preview ### Test Metrics note Only successful tests are tracked with `okteto_usage_test_duration_seconds`. | Metric Name | Type | Description | Labels | | ------------------------------------ | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | `okteto_usage_test_duration_seconds` | [histogram](https://prometheus.io/docs/practices/histograms/) | This represents metrics related to the time it takes to execute a test container. This metric only show tests that have successfully completed. | `devenv_name`, `namespace`, `repository`, `test_name` | | `okteto_usage_test_result` | [counter](https://prometheus.io/docs/concepts/metric_types/#counter) | This represents metrics related to the result of the tests of a development environment. | `devenv_name`, `namespace`, `repository`, `test_name`, `result` | * **Test Metrics label definitions:** * **`devenv_name`**: Represents the name of the development environment * **`namespace`**: Contains the Okteto CLI context from where the request originated * **`repository`**: Contains the git repository where the Okteto manifest that defines this Development Environment is hosted * **`test_name`**: Represents the test container being executed * **`result`**: Can be `success` or `failure` to represent the status of the test container ### User Metrics | Metric Name | Type | Description | Labels | | ----------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------- | --------------------------- | | `okteto_system_user_last_seen_time` | [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) | This metric represents the last activity of a user. | `id`, `external_id`, `role` | * **User Metrics label definitions:** * **`id`**: Contains the user id * **`external_id`**: The external id of the user * **`role`**: The role of the user ## Troubleshooting and Support ### Metric Server Availability Okteto Insights relies on the Kubernetes Metric Server. If the Metric Server is unavailable, requests to the `/metrics` endpoint, like requests from a [configured scraper](https://www.okteto.com/docs/admin/okteto-insights/#set-up-the-dashboards), will fail. You can troubleshoot the Metric Server or refer to the [documentation](https://kubernetes.io/docs/tasks/debug/debug-cluster/resource-metrics-pipeline/#metrics-server) for further guidance. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Managing Preview EnvironmentsScaleEnterpriseSelf-Hosted The Previews section of the Admin Dashboard provides administrators with a centralized view to manage all [Preview Environments](/docs/previews.md) 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](/docs/core/user-roles-and-permissions.md#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. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # GitHub You can configure Okteto to give your developers access to private GitHub repositories. There are several reasons for considering this approach including: * Your users can select a repo from a list, instead of having to type the full repository URL. * Give everyone on your cluster read-only access to private repositories. * Control access to Okteto and the repositories at the Organization level, or per repository. * The pipelines use an app-scoped token, instead of a shared ssh key. ## Configure your GitHub integration * Self-Hosted * BYOC Follow the guide to [configure the GitHub integration](/docs/self-hosted/install/github-integration.md). If your instance is hosted by Okteto, the GitHub integration is enabled by default. ## Adding or removing private repositories You can update or revoke the permissions over your private repositories or organizations by navigating to **Settings -> Integrations** in the Okteto Dashboard ![Configure private repositories](/docs/assets/images/private-repositories-update-sidebar+1.32-282dae26f58429d182c30033368cc9e4.png) Click on the `Configure GitHub` button to add or remove repositories. This will open a configuration dialog from GitHub. From there, you'll be able to add or remove repositories from any organization you belong to. ![Add Github repositories to Okteto](/docs/assets/images/private-repositories-enable-ad71f1f7579e327643595f4584e7e40c.png) If you select repositories from a different organization (or user account) than the one you used to create the GitHub Application, GitHub will prompt you to install the application in the GitHub organization. Only organization administrators can complete this action. ## GitHub org administrators If you're an administrator, you can grant team members access to your organization's repositories. Please note, even if you grant Okteto permission to all of your organization's repositories, each developer will only have access to those repositories that they are able to access through GitHub. This allows you to maintain security, and ensure that only those authorized to access code may do so. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Authenticating with an SSH KeyScaleEnterpriseSelf-Hosted Okteto generates an SSH key the first time it boots. This key is the identity used by Okteto when cloning repositories while executing a [git deployment pipeline](/docs/development/deploy/deploy-from-git.md). You can use this SSH key to give Okteto permission to clone private repositories. ## Get your Public Key The public SSH is available by navigating to **Admin -> General** underneath the Integrations section. Click on the `Show SSH Key` button to reveal the value. This will only be displayed for users with the `Admin` role. ![Admin General Integrations page showing the Git SSH key, Insights token, and OpenID Connect sections](/docs/assets/images/private-repository-ssh-key-sidebar+1.32-69c591dcbdec9d7fa00a1b1180dc0c34.png) ## Add the Public Key to your Source Code Provider Once you have the public key, follow your source code provider's instructions on how to add the SSH key to your account. We recommend that you create a dedicated `bot` account for Okteto. * * * ## Deploy a Private Repository To deploy a private repository, use the `SSH` url of your git repository. This applies both when using the [`Deploy`](/docs/development/deploy/deploy-from-git.md) dialog in the Okteto UI and the [`okteto pipeline deploy`](/docs/reference/okteto-cli.md#deploy) command from your terminal. ![Deploy dialog with Git URL source selected and an SSH repository URL entered](/docs/assets/images/private-repository-2cf0ed2b97ed52b634a7ea460bd9baa7.png) info Using SSH with any Git provider (GitHub, GitLab, Bitbucket, Azure DevOps, or self-hosted)? Your Okteto admin can centrally manage trusted hosts via [SSH Known Hosts](/docs/admin/ssh-known-hosts.md). This helps avoid host key verification failures during remote deploys and submodule operations. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Registry Credentials 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](/docs/self-hosted/manage/custom-resource-definitions.md#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 admin view](/docs/assets/images/registry_credentials_view+1.32-d83c4ff5b95da1eca9d38cd725b1460d.png) Registry credentials are applied to the [Okteto Build service](/docs/core/build-service.md) to allow private base image in your Dockerfiles. note If you see a “Read-only” tag next to Registry Credentials in the interface, it means that these items were defined using Custom Resource Definitions (CRDs). Such items cannot be modified through the Admin Dashboard. To make changes, you will need to update the associated CRD directly. For more information, refer to the [Managing Private Registry Credentials using CRDs documentation](/docs/self-hosted/manage/custom-resource-definitions.md#private-registries). ## Add Registry Credentials Click in the **Add Credential** button on the top right corner of the Registry Credentials view. A dialog will let you choose the type of credentials, your registry hostname, and your username and password: ![Add Credential dialog with fields for type, hostname, username, and password](/docs/assets/images/registry_credentials_add-5d5b483c3080be2e83dd0c37426b121c.png) 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) Follow our guides below to learn how to retrieve your registry credentials: * [Amazon ECR](/docs/admin/registry-credentials/amazon-ecr.md) * [Azure Container Registry](/docs/admin/registry-credentials/azure-acr.md) * [DockerHub](/docs/admin/registry-credentials/dockerhub.md) * [Google Artifact Registry](/docs/admin/registry-credentials/google-artifact-registry.md) For other registries, if the registry is exposed in a port other than the default http(s) 80/443, the port must be included in the `Hostname`, eg: `my-registry.com:5000`. Finally, click the **Add** button of the dialog. Your registry credentials might take a few minutes to propagate to all of the components in the cluster. ## Edit Registry Credentials The Registry Credentials view enables you to rotate your registry credentials. Click on the **Edit** button on the right of every registry credential. For sensitive data you will only see the last few characters as a hint to verify the value: ![Edit Credential dialog for an AWS IAM User registry with partially masked secret fields](/docs/assets/images/registry_credentials_edit+1.22-7d9f712abec6c9c4dd59b9c0269433f1.png) Click the **Save** button in the dialog. Your registry credentials might take a few seconds to propagate to all of the components in the cluster. ## Remove Registry Credentials The Registry Credentials view enables you to remove registry credentials if you don't need them anymore. Click on the **Remove** button on the right of every registry credential. A confirmation dialog will be shown: ![remove registry credentials confirmation dialog](/docs/assets/images/registry_credentials_remove+1.22-04209718974e7769e1f168365e4ee496.png) Click **Continue** in the confirmation dialog and your registry credentials will be removed from the cluster. ## Manage Registry Credentials using CRDs You can also manage your [Registry Credentials using CRDs](/docs/self-hosted/manage/custom-resource-definitions.md#private-registries). This is useful, for example, if you have your own mechanism to provision credentials/secrets in your cluster. To make sure Okteto is able to access your private registries, you can check if they are available from the [Admin dashboard](/docs/admin/dashboard.md#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](/docs/core/build-service.md) 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](/docs/self-hosted/manage/custom-resource-definitions.md#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. This secret is called `okteto-dockerconfig-static` and is always up to date with your Registry Credentials, either through the UI or using CRDs. This docker config secret is used as a pull secret in installer jobs, in case your installer job image is private. The docker config secret is added in all namespaces and preview environments created by Okteto, with the name `okteto-regcred`. `okteto-regcred` is injected as a pull secret to all pods by the [Okteto Webhook](/docs/self-hosted/helm-configuration.md#webhook) to allow the deployment of private images. note By default, the `okteto-regcred` only contains credentials for the Okteto Registry To disable this behavior set the following configuration in your helm values: ``` regcredsManager: pullSecrets: enabled: false ``` If this behavior is disabled, Okteto can write this secret on every node which allows Kubelet to pull private images at deployment time. To enable this behavior set the following configuration in your helm values: ``` daemonset: configurePrivateRegistriesInNodes: enabled: true ``` note `daemonset.configurePrivateRegistriesInNodes.enabled` is deprecated and it will be removed in Chart 1.23 --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Amazon ECR This tutorial will guide you on how to use your private Elastic Container Registry (ECR) with Okteto. It's recommended that you have the [AWS CLI installed](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions) to follow this tutorial. ECR credentials can be configured with either static credentials belonging to an IAM user or using OIDC federation to assume an IAM Role via Web Identity. ## Using IAM User credentials The steps to configure access to your private ECR using IAM User credentials are: * Create a user with access to your private ECR * Retrieve the user credentials * Configure the credentials in Okteto ### Step 1: Create a user with access to your private ECR info We recommend installing the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions) before following this tutorial Create IAM user with the [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/iam/create-user.html) by executing: ``` aws iam create-user --user-name private-registry-user ``` ``` aws iam attach-user-policy \ --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly \ --user-name private-registry-user ``` ### Step 2: Retrieve the user credentials Once we have the `User` created, we need to retrieve their credentials. Create IAM user access key with the [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/iam/create-access-key.html) by executing: ``` aws iam create-access-key --user-name private-registry-user ``` ``` { "AccessKey": { "UserName": "private-registry-user", "AccessKeyId": "<>", "Status": "Active", "SecretAccessKey": "<>", "CreateDate": "2023-10-10T09:08:27+00:00" } } ``` Remember the value of `AccessKeyId` and `SecretAccessKey`. You will need them in the next step. ### Step 3: Configure the credentials in Okteto Add the following registry credentials to the [Admin Registry Credentials view](/docs/admin/registry-credentials.md#add-registry-credentials): * **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 ## Using IAM Roles via OpenID Connect (OIDC) Federation The steps to configure access to your private ECR using IAM Roles via OpenID Connect (OIDC) Federation are : * Register the Identity Provider * Create the IAM Role and Grant Access to ECR * Configure the credentials in Okteto ### Step 1: Register the Identity Provider info We recommend installing the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions) before following this tutorial The first step in configuring access to your private ECR is to register your Kubernetes cluster as an OIDC identity provider in AWS. To do this, Okteto provides the OIDC endpoint of your cluster, which can be found in the **General** page under the **Integrations** section of your Okteto Admin Dashboard. ![OIDC configuration in admin integrations view](/docs/assets/images/amazon-ecr-oidc-config+1.32-fa9dcee1504951f595d5e5c9da6f19d4.png) Store these values as environment variables, you will use them in the next steps: ``` export OIDC_ENDPOINT=https://container.googleapis.com/v1/projects/myProject/locations/us-central1/clusters/myCluster export OKTETO_SERVICE_ACCOUNT=system:serviceaccount:okteto:okteto ``` The `AUDIENCE` is traditionally the client ID of the requester, and tokens will only be exchanged for these audiences. It corresponds to the `aud` field in the JWT payload. We recommend creating a unique audience for each Okteto instance and AWS region. For example: ``` export AUDIENCE=okteto.example.com/us-east-2 ``` Next, run the following command to create the OIDC identity provider in AWS: ``` aws iam create-open-id-connect-provider --url "${OIDC_ENDPOINT}" --client-id-list "${AUDIENCE}" ``` Once successful, you’ll see a response similar to: ``` { "OpenIDConnectProviderArn": "arn:aws:iam::112233445566:oidc-provider/container.googleapis.com/v1/projects/myProject/locations/us-central1/clusters/myCluster" } ``` Store this value in an environment variable, you'll use in the next step: ``` export ROLE_ARN=arn:aws:iam::112233445566:oidc-provider/container.googleapis.com/v1/projects/myProject/locations/us-central1/clusters/myCluster ``` ### Step 2: Create the IAM Role and Grant Access to ECR In this step, you'll create an IAM Role that allows access to ECR and configure it to be assumed using the OIDC identity provider created in the previous. First, create the trust policy that allows the IAM Role to be assumed by the OIDC identity provider. Save the following content to a file named `trust-policy.json` (replace your environment variables): trust-policy.json ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "${ROLE_ARN}" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "${OIDC_ENDPOINT}:aud": "${AUDIENCE}", "${OIDC_ENDPOINT}:sub": "${OKTETO_SERVICE_ACCOUNT}" } } } ] } ``` Run the following command to create the IAM Role in AWS with the trust policy you defined: ``` aws iam create-role --role-name my-private-registry --assume-role-policy-document file://trust-policy.json ``` You will receive a response similar to this: ``` { "Role": { "Path": "/", "RoleName": "my-private-registry", "RoleId": "AR...", "Arn": "arn:aws:iam::112233445566:role/my-private-registry", "CreateDate": "2024-06-10T15:04:05+00:00", "AssumeRolePolicyDocument": { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "ec2.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } } } ``` Now, attach an ECR policy to allow pulling from the registry: ``` aws iam attach-role-policy --role-name my-private-registry --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly ``` ### Step 3: Configure the credentials in Okteto Now that you've created the IAM Role, the final step is to configure the credentials in Okteto. Add the following registry credentials to the [Admin Registry Credentials view](/docs/admin/registry-credentials.md#add-registry-credentials) in the Okteto Admin Dashboard: Start by navigating to **Admin -> Registry Credentials** under the Integrations section. 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 tip You can also configure these credentials via [Kubernetes CRDs](/docs/self-hosted/manage/custom-resource-definitions.md#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). --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Azure Container Registry This tutorial will guide you on how to use your private Azure Container Registry (ACR) with Okteto. It's recommended that you have the [Azure CLI installed](https://learn.microsoft.com/en-us/cli/azure/) to follow this tutorial. The steps to configure your private ACR with Okteto are: * Create a user with access to your private ACR * Retrieve the user credentials * Configure the credentials in Okteto ## Step 1: Create a user with access to your private ACR First you need to create a `Service Principal` with `role based access control`. To do so, you will need the following information: * `scopes`: the ID of your Azure Container Registry * `role`: `PULL` to have read access to your private ACR You can list your current container registries with: ``` az acr list ``` Pick the name of your ACR and export it to an environment variable: ``` export ACR_NAME=<> ``` Get the ID of your ACR with the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/acr?view=azure-cli-latest#az-acr-show) by executing: ``` ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query "id" --output tsv) ``` Create the ServicePrincipal with PULL access with the [AzureCLI](https://learn.microsoft.com/en-us/cli/azure/azure-cli-sp-tutorial-2#create-a-service-principal-containing-a-password) by executing: ``` az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME --scopes $ACR_REGISTRY_ID --role acrpull ``` ## Step 2: Retrieve the user credentials Get the `APP ID` by executing the following command: ``` APP_ID=$(az ad sp list --display-name $SERVICE_PRINCIPAL_NAME --query "[].appId" --output tsv) ``` Create a `PASSWORD` for that `APP ID`: ``` az ad sp credential reset --id $APP_ID ``` ``` { "appId": "<>", "password": "<>", "tenant": "98e0e81b-dd65-4132-9d6c-ed2ac3e14e28" } ``` Remember the value of `appId` and `password`. You will need them in the next step. ## Step 3: Configure the credentials in Okteto Add the following registry credentials to the [Admin Registry Credentials view](/docs/admin/registry-credentials.md#add-registry-credentials) in the Okteto Admin Dashboard: Start by navigating to **Admin -> Registry Credentials** under the Integrations section. Click "Add Credential" and use the following settings: * **Type**: `Static` * **Hostname**: your Azure Container Registry name (`ACR_NAME`) * **Username**: `appId` from the previous step * **Password**: `password` from the previous step --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # DockerHub This tutorial will guide you on how to use your private DockerHub repositories with Okteto. The steps to configure your private DockerHub repositories with Okteto are: * Create a user with access to your private DockerHub repositories * Retrieve the user credentials * Configure the credentials in Okteto ## Step 1: Create a user with access to your private DockerHub repositories Go to your page and follow these steps: * Account Settings → Security * Click on **New Access Token** * Give it a **Name** and `Read-only` **Permissions** ## Step 2: Retrieve the user credentials When you create the **Access Token** you will get the password to use. ![DockerHub example credentials](/docs/assets/images/credsexampledocker-93698bf69ee51199cd8848a265408841.png) In this example, the `username` is *mnevadom* and the `password` is *password*. Remember these values, you will need them in the next step. ## Step 3: Configure the credentials in Okteto Add the following registry credentials to the [Admin Registry Credentials view](/docs/admin/registry-credentials.md#add-registry-credentials) in the Okteto Admin Dashboard: Start by navigating to **Admin -> Registry Credentials** under the Integrations section. Click "Add Credential" and use the following settings: * **Type**: `Static` * **Hostname**: `index.docker.io` * **Username**: `username` * **Password**: `password` --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Google Artifact Registry This tutorial will guide you on how to use your private Google Artifact Registry with Okteto. It's recommended that you have the [gcloud CLI installed](https://cloud.google.com/sdk/docs/install) to follow this tutorial. The steps to configure your private Google Artifact Registry with Okteto are: * Create a service account with access to your private Google Artifact Registry * Retrieve the service account credentials * Configure the credentials in Okteto ## Step 1: Create a service account with access to your private Google Artifact Registry Export the name your want to use for your service account: ``` export SA_NAME=<> ``` Create a service account with the [gcloud CLI](https://cloud.google.com/sdk/gcloud/reference/iam/service-accounts/create) by executing the following command: ``` gcloud iam service-accounts create ${SA_NAME} --display-name="My Service Account for Okteto" ``` Add a policy to grant read access to your private Google Artifact Registry: ``` gcloud projects add-iam-policy-binding {PROJECT_ID} \ --member=serviceAccount:{SA_NAME}@{PROJECT_ID}.iam.gserviceaccount.com \ --role=roles/artifactregistry.reader ``` ## Step 2: Retrieve the service account credentials Create an Access Key to use these credentials by executing the following command: ``` 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 the required credentials. You will use this file in the next step. ## Step 3: Configure the credentials in Okteto Add the following registry credentials to the [Admin Registry Credentials view](/docs/admin/registry-credentials.md#add-registry-credentials) in the Okteto Admin Dashboard: Start by navigating to **Admin -> Registry Credentials** under the Integrations section. 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` You can also use `_json_key_base64` as `username` and encode your `SA_KEY_FILE.json` as the value of the `password`: ``` cat SA_KEY_FILE.json | base64 ``` --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Resource Manager Okteto's Resource Manager is an automated tool designed to optimize CPU and memory resource requests for your Kubernetes workloads on Okteto. By analyzing the actual utilization of resources, the Resource Manager adjusts the resource requests for your pods, ensuring they are appropriately configured without the need for manual intervention. ## Why Use the Resource Manager? Manually configuring CPU and memory requests in Kubernetes can be tedious and error-prone. Incorrect configurations can lead to poor performance, overloaded nodes, and a slow developer experience on Okteto. The Resource Manager automates this process, dynamically adjusting resource requests based on real-time usage data of the Okteto Cluster. This ensures your pods are running efficiently and your nodes are balanced well, improving overall performance and developer experience. ### Key Benefits * **Improved Workflow Productivity**: Automates resource configuration, allowing developers to focus on coding rather than managing Kubernetes settings * **Optimized Resource Usage**: Ensures resources are neither underutilized nor over-utilized, leading to cost savings and better performance * **Enhanced Developer Adoption**: Improves the performance of development environments, leading to higher satisfaction and adoption rates amongst developers * **Cost Efficiency**: Reduces the overhead associated with manually configuring resources, lowering operational costs ## How it Works The Resource Manager monitors the actual CPU and memory usage of your pods over time. It calculates the average usage and automatically adjusts the resource requests for new pods based on these averages. The system uses the following process: 1. **Data Collection**: The Resource Manager queries the Kubernetes Metric Server to collect CPU and memory usage data for all pods managed by Okteto. The Kubernetes Metric Server is required for using Resource Manager 2. **Average Calculation**: It calculates the average CPU and memory usage for each container family (grouped by development environment, controller name, and container name) 3. **Recommendation Generation**: The Resource Manager generates new resource requests based on the average usage, applying a correction factor to ensure efficiency 4. **Automatic Application**: When a new pod is created, the recommended resource requests are automatically applied unless overridden the annotation `dev.okteto.com/resource-manager: false` 5. **Data lifecycle**: The Resource Manager stores only a running average per container family in Redis (persistence disabled). No historical time-series data is retained. If Redis is cleared, the averages are recalculated on the next scheduled run (default: every 5 minutes). The run cadence is [configurable via the Helm chart](/docs/self-hosted/helm-configuration.md#resourcemanager) ## Configuring the Resource Manager ### Enabling the Resource Manager Resource Manager is available in Okteto chart version 1.26 and above. Refer to our [Helm configuration documentation](/docs/self-hosted/helm-configuration.md#resourcemanager) for available options. #### To enable the Resource Manager: 1. Update and deploy your [Helm chart with the Resource Manager configuration](/docs/self-hosted/helm-configuration.md#resourcemanager) with any changes that pertain to your cluster 2. Once enabled, the Resource Manager will start a cron job every 5 minutes to compute the recommendations **Activate the Resource Manager's Automatic Recommendations Through the UI:** 1. Log in to the Okteto Admin Dashboard 2. Navigate to **Admin -> Resource Manager** under the Settings section 3. If the Resource Manager is enabled, you see "Manual" and "Automatic" radio buttons 4. Select "Automatic" to activate the Resource Manager's automated resource management ![Resource Manager settings in the Admin Dashboard with the Automatic option selected and CPU and memory usage charts](/docs/assets/images/resource-manager-enabled+1.32-242769e4f46989d8afce6752a47b6361.png) Once activated, the Resource Manager will immediately begin adjusting 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: * You can find the full list of settings in our [Helm Reference →](/docs/self-hosted/helm-configuration.md#resourcemanager) info Please note that these settings will override user defined CPU and Memory Requests, when RM is configured in Automatic mode. ## Viewing Resource Metrics and Recommendations ### Resource Metrics View The Resource Manager introduces a new "Metrics" tab in the Okteto Dashboard's Namespace view. It's designed to give you clear insights into the resource usage and performance of your Kubernetes workloads. This tab is available for key resources, including Deployments, StatefulSets, Jobs, CronJobs, and Pods. * To learn more about what metrics are available, see our [Namespace Documentation →](/docs/core/namespaces.md#resource-metrics-view) ## Exclude Resources If you find that the Resource Manager's recommendations are not suitable for a specific component, you can opt-out single resources from being managed by Resource Manager. Set the annotation `dev.okteto.com/resource-manager` to `false` to your pod's metadata to prevent automatic adjustments. Example of Kubernetes manifest: ``` apiVersion: apps/v1 kind: Deployment metadata: name: hello-world spec: selector: matchLabels: app: hello-world template: metadata: annotations: dev.okteto.com/resource-manager: "false" ``` Example of Docker Compose file: ``` services: hello-world: labels: dev.okteto.com/resource-manager: "false" ``` 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: * Selecting "Manual" in the Admin Dashboard to disable the Resource Managers automatic adjustments ## Troubleshooting and Support ### Metric Server Availability The Resource Manager relies on the Kubernetes Metric Server. If the Metric Server is unavailable, the Okteto UI will display an error message. You can troubleshoot the Metric Server or refer to the [documentation](https://kubernetes.io/docs/tasks/debug/debug-cluster/resource-metrics-pipeline/#metrics-server) for further guidance. ### Known Limitation: Support for ReplicaSet and CronJob The Resource Manager does not automatically support optimizing ReplicaSets and CronJobs due to technical limitations. However, you can enable Resource Manager optimizations for ReplicaSets or CronJobs, by adding the label `dev.okteto.com/component-name` to your resources. Example of CronJob manifest, with `dev.okteto.com/component-name` label: ``` apiVersion: batch/v1 kind: CronJob metadata: name: hello-world spec: schedule: "* * * * *" jobTemplate: spec: template: metadata: labels: dev.okteto.com/component-name: "hello-world" ``` --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # SSH Known Hosts The SSH Known Hosts feature enables Okteto administrators to centrally manage trusted SSH hosts for SSH-based Git operations across the organization. This does not affect HTTPS-based Git clones, which rely on certificate authorities for security. By maintaining a single source of truth for the `known_hosts` file, you can ensure secure and reliable repository cloning without requiring custom runner images. ## Key Benefits * **Centralized trust management** - Manage SSH host keys in one place for all teams * **Enhanced security** - Prevent man-in-the-middle attacks by verifying host keys * **Simplified operations** - No need for custom images or per-job SSH configuration ## Getting Started ### Enabling Known Hosts * Navigate to **Admin → Settings → Known Hosts** * Toggle **Enable Known Hosts** to activate the feature (disabled by default) * Once enabled: * Okteto uses this centralized list for all SSH operations * Automatic `ssh-keyscan` is disabled unless explicitly called in commands * All Git clones and submodules honor this trust store ### Configure Trusted Hosts * Add entries directly in the [OpenSSH `known_hosts` format](https://man.openbsd.org/sshd.8#SSH_KNOWN_HOSTS_FILE_FORMAT) * Well-known providers (GitHub, GitLab, Bitbucket, Azure DevOps) are included as commented placeholders ### Clone Fallback Behavior When a Git clone operation fails using one protocol, Okteto automatically attempts to fallback to the other protocol: * If SSH clone fails (e.g., due to missing known host), Okteto attempts HTTPS * If HTTPS clone fails (e.g., due to missing credentials), Okteto attempts SSH **Note:** This fallback only applies to the main repository clone. Submodules use the protocol specified in the `.gitmodules` file without fallback. 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 * **HTTPS authentication:** Use our [GitHub App integration](/docs/admin/private-repositories/github-app.md) The fallback mechanism ensures deployment succeeds if either protocol is properly configured. ## How It Works ### Scope and Application The centralized `known_hosts` applies to: * **Installer jobs** - UI-triggered deploys, previews, and destroy operations * **Remote executor commands** - Commands run from the Okteto Manifest * **CLI operations** - When using `okteto deploy --remote` ### Runtime Behavior * The `known_hosts` file is mounted read-write in jobs (allowing runtime additions for dynamic hosts) * When using `okteto deploy --remote`, the server-level configuration always overrides local `known_hosts` * Changes made during job execution are ephemeral and don't modify the global configuration ### How This Affects the Okteto CLI * Remote executions automatically fetch the centralized list * CLI honors the centralized `known_hosts` when `okteto deploy --remote` is used ### Understanding Deploy Warnings When SSH clone fails due to missing known hosts, you may see a warning in the deployment UI even if the deployment ultimately succeeds. This occurs because: * The initial SSH clone attempt failed and triggered the warning * The automatic HTTPS fallback succeeded * The warning indicates the known hosts configuration should be updated to avoid relying on the fallback mechanism ## Example Configuration When cloning repositories, the system automatically configures Git to use the centralized hosts file: ``` GIT_SSH_COMMAND="ssh -o UserKnownHostsFile=/okteto/known_hosts -o StrictHostKeyChecking=yes" ``` ## Advanced Scenarios ### Working with Dynamic Hosts * Pipelines that clone additional repositories succeed as long as each host appears in the centralized `known_hosts` * Users can still run `ssh-keyscan` explicitly in their commands to add hosts at runtime * Dynamic endpoints created during deploy can append entries to the mounted `known_hosts` within the job. These changes are ephemeral to the job and do not modify the admin-configured global template ### Submodules with SSH Even if your main repository clones via HTTPS, submodules may be configured to use SSH URLs. In these cases: * The main repository clone via HTTPS succeeds normally * Submodule clones require the SSH host to be in the known hosts list * Ensure all submodule hosts are added to the known hosts configuration * Submodule clone failures do not fallback to HTTPS ### Error Handling If a host is missing from the list: * SSH clone will fail with **Host key verification failed** * Okteto will automatically attempt to clone via HTTPS as a fallback * For public repositories, the HTTPS fallback typically succeeds * For private repositories, the HTTPS fallback requires appropriate credentials (GitHub App integration, personal access tokens, etc.) * Check deploy logs for details on which protocol succeeded --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Agentic Workflows 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. note Agentic Workflows are about bringing your own agent tooling to Okteto environments. To launch and manage agents from the Okteto Dashboard instead, see [Okteto AI](/docs/okteto-ai.md). ## Installing the plugin Run these commands in Claude Code: ``` /plugin marketplace add okteto/okteto-agent-skills /plugin install okteto ``` The plugin needs the [Okteto CLI installed and configured](/docs/get-started/install-okteto-cli.md) 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: ``` /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: ``` { "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 are built on the open [Agent Skills](https://agentskills.io) format, so the same `okteto` and `okteto-onboarding` 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: ``` 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` command ships only with the Claude Code plugin. Every other method carries the two skills. ## Skills and commands The plugin installs two skills and one slash command: | | 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. | | `/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. | ## 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: ``` ## 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](/docs/agentic/collaborative-workflows.md) | [Autonomous](/docs/agentic/autonomous-workflows.md) | | ----------------- | ----------------------------------------------------------- | -------------------------------------------------------- | | **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](/docs/agentic/best-practices.md#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 * [Collaborative Workflows](/docs/agentic/collaborative-workflows.md) — work alongside your agent * [Autonomous Workflows](/docs/agentic/autonomous-workflows.md) — let the agent handle it end to end * [Best Practices](/docs/agentic/best-practices.md) — command rules, common pitfalls, and troubleshooting --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # 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 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](/docs/agentic/best-practices.md#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](/docs/core/credentials/personal-access-tokens.md) and set the Okteto context before running any commands: ``` 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](/docs/agentic.md#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](/docs/agentic.md#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: ``` ## 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: ``` okteto deploy --wait okteto endpoints ``` After making the code changes, the agent redeploys and validates: ``` # 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: ``` 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](/docs/agentic/best-practices.md#command-rules). For flag details on any command, see the [CLI Reference](/docs/reference/okteto-cli.md). ## 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](/docs/agentic/best-practices.md#worktree-isolation). ## Next steps * [Collaborative Workflows](/docs/agentic/collaborative-workflows.md) — stay in the loop and iterate with the agent * [Best Practices](/docs/agentic/best-practices.md) — command rules and common pitfalls --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Best Practices and Troubleshooting 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. ``` # 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](/docs/core/build-service.md), which pushes images directly to the Okteto Registry where they're accessible to the environment. ``` # 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. ``` # 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](/docs/agentic/collaborative-workflows.md): the human runs `okteto up`, the agent uses `okteto exec` * In [autonomous mode](/docs/agentic/autonomous-workflows.md): 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. ``` # 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: ``` okteto namespace create ``` Then it passes `-n ` on every command for the rest of the session: ``` 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](/docs/agentic/collaborative-workflows.md), the agent surfaces `okteto destroy` as a suggestion and lets the developer run it. In [autonomous mode](/docs/agentic/autonomous-workflows.md), 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: ``` 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](/docs/agentic.md#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](/docs/agentic.md#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`. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # 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](/docs/development/containers/file-sync.md) 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](/docs/agentic/best-practices.md#command-rules). ## Workflow example: fixing a bug You start the dev environment: ``` 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: ``` # 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](/docs/agentic/best-practices.md#command-rules). For flag details on any command, see the [CLI Reference](/docs/reference/okteto-cli.md). ## 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](/docs/agentic/autonomous-workflows.md) — let the agent handle the full lifecycle without human input * [Best Practices](/docs/agentic/best-practices.md) — command rules and common pitfalls --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. ## [🗃Okteto AI](/docs/okteto-ai.md) [3 items](/docs/okteto-ai.md) --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Archived Release Notes Here you can find the release notes for archived versions of Okteto. ## 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 * 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](/docs/admin/dashboard.md#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 * 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 * 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 * 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](/docs/reference/feature-flags.md) `OKTETO_PARALLEL_WAKE_UPS_FOR_DEVENVS`. When dependencies exist, their defined startup order is still respected ### Improvements * 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 * [Okteto CLI 3.7.0](https://github.com/okteto/okteto/releases/tag/3.7.0): Fixed a bug in the [Smart Builds](/docs/core/build-service.md#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](/docs/reference/okteto-manifest.md#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](/docs/reference/okteto-manifest.md#divert) and [`endpoints`](/docs/reference/okteto-manifest.md#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 * ⚠️ 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 →](/docs/self-hosted/manage/upgrade.md#upgrading-to-okteto-131x--schema-1-image-deprecation) ### New Features * Added a new [Okteto API endpoint](/docs/admin/okteto-api.md) 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](/docs/reference/feature-flags.md) `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 * 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 * 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 * 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](/docs/reference/okteto-manifest.md#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 * ⚠️ 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 →](/docs/self-hosted/manage/upgrade.md#upgrading-to-okteto-131x--schema-1-image-deprecation) ### New Features * Okta User De-provisioning: Okta users can now be [automatically de-provisioned in Okteto](/docs/admin/integrations/okta-user-deprovisioning.md) when removed from Okta * Okteto Test Insights: You can now view average success time metrics for your Okteto Test runs in [Okteto Insights](/docs/core/okteto-insights-dashboards.md#test-dashboard) ### Improvements * 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](/docs/reference/feature-flags.md) `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 * 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](/docs/reference/feature-flags.md) 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 * 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 * 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](/docs/admin/cleanup.md#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)](/docs/admin/okteto-api.md)! 🎉 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 * [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 * Fixed an issue where [Divert](/docs/reference/okteto-manifest.md#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 * 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](/docs/reference/okteto-cli.md#validate), a CLI command allowing you to run validation on your Okteto Manifest * All [external dependencies](/docs/self-hosted/manage/air-gapped.md) 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](/docs/admin/cleanup.md#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](/docs/self-hosted/manage/air-gapped.md#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](/docs/admin/custom-installer-image.md). ### New Features * We now allow the ability for admins of Okteto to [set the minimum accepted CLI version for their team](/docs/admin/dashboard.md#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](/docs/reference/okteto-manifest.md#validating-and-autocompleting-the-okteto-manifest-in-your-ide) * Added support for [overwriting CLI images at the Helm chart level](/docs/self-hosted/helm-configuration.md#cli) * Shipped additional support for the installation of [Okteto in Air-Gapped Environments](/docs/self-hosted/manage/air-gapped.md) * 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](/docs/self-hosted/helm-configuration.md#jobs) ### Improvements * We've reorganized the [Admin Dashboard menu items](/docs/admin/dashboard.md) into groups for easier navigation * For [Catalog](/docs/admin/catalog.md) and [Cloud Credentials](/docs/admin/cloud-credentials.md) 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 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](/docs/admin/resource-manager.md)**: 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](/docs/admin/resource-manager.md) * Added Okteto [Garbage Collector settings to the Admin Dashboard](/docs/admin/cleanup.md): 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](/docs/core/remote-execution.md) 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](/docs/self-hosted/manage/buildkit-high-performance.md) ### 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](/docs/self-hosted/helm-configuration.md#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](/docs/reference/feature-flags.md) 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](/docs/admin/cloud-credentials.md), a central location to manage your cloud provider credentials for `deploy`, `destroy`, and `test` remote operations * Added official [support for Red Hat OpenShift](/docs/get-started/install/openshift.md) * Added support and a new Namespace UI for [resource quotas at the individual Namespace level](/docs/core/namespaces.md#configure-namespace-quotas). This allows administrators to set the maximum resources that can be used per Namespace * Enabling [Okteto Insights Dashboards](/docs/core/okteto-insights-dashboards.md) for all SaaS and BYOC users of Okteto * Added support to allow override of [installer security context](/docs/self-hosted/helm-configuration.md#installer) ### Improvements * Support for [`priorityClassName`](/docs/reference/okteto-manifest.md#priorityclassname-string-optional) and [`accessMode`](/docs/reference/okteto-manifest.md#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](/docs/core/okteto-insights-dashboards.md) 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 This version is compatible with Kubernetes versions 1.27 to 1.30 ### Bug Fixes * Fix high vulnerabilities in backend and pipeline installer images ## 1.24.1 9 September 2024 This version is compatible with Kubernetes versions 1.27 to 1.30 ### Bug Fixes * Fix deploy of development environments from the UI when the git URL is from a self-hosted GitLab instance and it refers to repositories within Groups and Subgroups ## 1.24.0 9 September 2024 This version is compatible with Kubernetes versions 1.27 to 1.30 ### New Features * Announcing the pre-release of CLI 3.0! [Please read our blog post for more details and information on breaking changes](https://okteto.com/blog/cli-three-release) * Enable [multi-user token authentication](/docs/self-hosted/install/auth/token.md) * Added support for [BuildKit Bridge Mode](/docs/self-hosted/helm-configuration.md#buildkit) to avoid port collisions on parallel builds ### Improvements * Added new [Developer Quickstart Guide to the documentation](/docs/get-started/dev-quickstart.md) * Upgraded [ingress-nginx to v1.11.2](https://github.com/kubernetes/ingress-nginx/releases/tag/controller-v1.11.2) adding support for [gRPC timeout settings via annotations](https://github.com/kubernetes/ingress-nginx/pull/11258). This update may introduce a breaking change related to an [uncommon edge case](https://github.com/kubernetes/ingress-nginx/issues/11866) * Updated the "Want to know more" links in an empty namespace * Added [tolerations for EventsExporter StatefulSet](/docs/self-hosted/helm-configuration.md#insights) * Updated pipeline-runner image to v1.0.5 to update cue to 0.9.2 * [Okteto CLI 2.31.0 Upgrade Notice](https://github.com/okteto/okteto/releases/tag/2.31.0): To upgrade to new ECDSA keys, all active development containers will be recreated on the first okteto up after upgrading to 2.31.0 * [Okteto CLI 2.31.0](https://github.com/okteto/okteto/releases/tag/2.31.0): Replaced RSA with ECDSA for SSH keys. This allows the use of debuggers on Visual Studio with Development Containers * [Okteto CLI 2.31.0](https://github.com/okteto/okteto/releases/tag/2.31.0): Prevent Syncthing from restarting and activating [relay](https://docs.syncthing.net/users/relaying.html) if the Synching configuration is lost ### Bug Fixes * Trimmed .git suffix when extracting repository data * Fixed Development Environment UI collapse when a nested item is deleted * Added OKTETO\_TOKEN as a [reserved variable name](/docs/core/credentials/environment-variables.md) in the UI * Fixed git url parsing for URLs with a trailing slash * Fixed an overflow issue with long variable values * Private endpoint cookies now delete upon logout * Fixed duplicated endpoints in the UI if they're shared by more than one resource * Fixed GitHub integration configuration issue in Settings view ### Removal Notice * Support for Kubernetes [1.26](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.26.md) has been removed in this release. ## 1.23.3 9 September 2024 This version is compatible with Kubernetes versions 1.26 to 1.30 ### Bug Fixes * Fix deploy of development environments from the UI when the git URL is from a self-hosted GitLab instance and it refers to repositories within Groups and Subgroups ## 1.23.2 16 August 2024 This version is compatible with Kubernetes versions 1.26 to 1.30 ### Bug Fixes * Fix deploys for repositories with a trailing slash ## 1.23.1 14 August 2024 This version is compatible with Kubernetes versions 1.26 to 1.30 ### Bug Fixes * Updated the backend CLI to 2.30.1 to fix an error when deploying remotely an Okteto Manifest storing a variable with the symbol `=` on [$OKTETO\_ENV](/docs/core/okteto-variables.md#okteto_env) ## 1.23.0 12 August 2024 This version is compatible with Kubernetes versions 1.26 to 1.30 ### Deprecation Notice * Support for Kubernetes 1.26 has been deprecated and will be removed in the next release. ### New Features * Added a [feature flag to enable/disable autowake](/docs/self-hosted/helm-configuration.md#autowake) for Namespaces and Preview Environments on incoming request * Added support for Kubernetes 1.30 ### Improvements * Added support for displaying the correct Dev Environment name when using Groups and Subgroups in GitLab * Fixed how Gitlab Groups and Subgroups are displayed in the Previews view * Prevent the usage of [reserved variable names](/docs/core/okteto-variables.md#reserved-variables) * Updated registry version to return 404 errors for malformed image requests, allowing new builds of the image to be pushed. This resolves issues where improperly stored images prevented successful new builds * Added a dashboard indicator to show whether the Garbage Collector is enabled * Bumped daemon to 0.13.0 and cli to 2.30.0 * [Okteto CLI 2.30.0](https://github.com/okteto/okteto/releases/tag/2.30.0): You can now Build images using the `okteto build` command as part of your Okteto commands in the Okteto Manifest when executing a remote deploy/destroy. Previous to this, no image was being built * [Okteto CLI 2.30.0](https://github.com/okteto/okteto/releases/tag/2.30.0): You can now [specify hosts](/docs/reference/okteto-manifest.md#hosts-string-optional) to resolve to specific IPs for your tests defined under the `test` section of the Okteto Manifest ### Bug Fixes * Fix to gracefully handle localStorage errors * Fixed layout shifting upon loading staged logs * Fix "variables ignored" warning shown on deploy-URL for "Develop On Okteto Button" feature despite not having specified any variables * Okteto CLI 2.30.0: Fixed a bug that was preventing `okteto test` from exporting artifacts when a folder was specified under the `artifacts` key ## 1.22.1 19 July 2024 This version is compatible with Kubernetes versions 1.26 to 1.29 ### Improvements * Updated the backend CLI to 2.29.2 to address potential vulnerabilities * Improved the backend and installer images to enhance overall security * Bumped Buildkit image to v0.12.5-okteto3 to fix critical vulnerabilities ## 1.22.0 8 July 2024 This version is compatible with Kubernetes versions 1.26 to 1.29 ### Breaking Changes * Disabled private registries by default in nodes. [Pull secrets](/docs/admin/registry-credentials.md#how-it-works), enabled by default since `1.20`, are used for deploying pods with private images * Removed the automatic binding between `cluster-admin` cluster role, and every service account created within a namespace managed by Okteto. You can find more information in our [Upgrade Guide here](/docs/self-hosted/manage/upgrade.md#upgrading-to-okteto-122x--role--binding-config-migration). ### New Features * Support of AWS IAM Roles to configure Private Registries. Please see [the specific documentation page](/docs/admin/registry-credentials/amazon-ecr.md) to understand their configuration * Add OIDC endpoint to the cluster overview panel in the Admin Dashboard * Okteto CLI: Make Preview Environments global by default and allow non-admin users to create them ### Improvements * Admin users are now able to perform any operation on any user's namespace via UI, CLI or at the Kubernetes level * Added configuration for developer permissions in global preview environments via role binding to the cluster role set by [`serviceAccounts.roleBindings.previews`](/docs/self-hosted/helm-configuration.md#serviceaccounts) Helm setting * Developers now have read access to global preview environments at the Kubernetes level (after getting Kubernetes context with `okteto kubeconfig`) * Changed Admin Users' role selection label from "User" to "Developer" for consistency * Improved Okteto Insights data collection time * Reorganized 'user' helm setting to 'serviceAccounts' and include one setting to create a role binding for global previews. Please see our [upgrade guide](/docs/self-hosted/manage/upgrade.md#upgrading-to-okteto-122x--role--binding-config-migration) for details on how to adopt the changes * Specified the credentials to be removed in the delete credential confirmation dialog * Upgraded the Okteto CLI version to [2.29.0](https://github.com/okteto/okteto/releases/tag/2.29.0) * Okteto CLI: Admins can now perform operations in any user's namespaces via the CLI context * Okteto CLI: Test artifacts defined under the `test` section are exported even if tests execution fails * Okteto CLI: Images defined in your Okteto manifest targeting dev registry (okteto.dev) and using a custom tag will now benefit from [Okteto Smart Builds](/docs/core/build-service.md#smart-builds) ### Bug Fixes * Fixed a rare issue where the Okteto Dashboard would render nothing during loading * Fixed an issue in the webhook that was preventing a Virtual Service to keep the specified `exportTo` field * Fixed empty space in the Okteto Dashboard while data is being re-fetched * Use globals.nodeSelectors.dev to filter Insights node data * Extend support for globals.nodeSelector in the Autoscaler, node readiness and the nodes admin view * Fixed panic in private-endpoints handler when deployed standalone and accessed for the first time ## 1.21.2 19 July 2024 This version is compatible with Kubernetes versions 1.26 to 1.29 ### Improvements * Updated the backend CLI to 2.28.2 to address potential vulnerabilities * Improved the backend and installer images to enhance overall security * Bumped Buildkit image to v0.12.5-okteto3 to fix critical vulnerabilities ## 1.21.1 11 June 2024 This version is compatible with Kubernetes versions 1.26 to 1.29 ### Deprecation Notice * Announced [deprecation of Okteto Autoscaler](/docs/self-hosted/helm-configuration.md#autoscaler-deprecated). We recommend relying on cpu/memory requests to autoscale your cluster ### Bug Fixes * When [Istio Virtual Services were enabled](/docs/self-hosted/helm-configuration.md#virtualservices), Okteto's webhook no longer removes the property `exportTo` defined in a virtual service object * Fix a view refresh every few minutes in the `General` tab of the Admin Dashboard ## 1.21.0 7 June 2024 This version is compatible with Kubernetes versions 1.26 to 1.29 ### Deprecation Notice * Announced [deprecation of Okteto Autoscaler](/docs/self-hosted/helm-configuration.md#autoscaler-deprecated). We recommend relying on cpu/memory requests to autoscale your cluster ### New Features * The platform will now only obfuscate variables that are longer than 5 characters * We've added the ability to [set custom NodeSelectors](/docs/self-hosted/helm-configuration.md#globals) ### Improvements * Show GitHub installations error notifications only when opening GitHub tab on Deploy dialog * Handle suspended GitHub installation error on the branch selector in the Okteto UI * Enable more error variant feedback on the GitHub BranchSelector in the Okteto UI * Handle suspended Github app installation on the repositories selector in the Okteto UI * Removed ingress name validation in the mutation webhook for ingress created as part of cert-manager challenges * Handle HTTP 5xx errors more gracefully in the Okteto UI * Upgraded the Okteto CLI version to [2.28.0](https://github.com/okteto/okteto/releases/tag/2.28.0). * Okteto CLI: Changed .oktetodeployignore files to use .oktetoignore for [remote executions of deploy and destroy](/docs/core/remote-execution.md#ignoring-files), which allows more granularity to ignore files. You can add global ignore, but also specific ignores per operation * Okteto CLI: Fix to correctly discover the git repository when a manifest is within a subfolder of the repository. This was preventing [Smart Builds](/docs/core/build-service.md#smart-builds) from detecting when an image was previously built ### Bug Fixes * Fix branch selector regression causing "bad-request" error * Ignore ingress, virtual services, and routes without hosts * Fix installer destroy operation when checking branch existence for private registries using SSH protocol ## 1.20.1 28 May 2024 This version is compatible with Kubernetes versions 1.26 to 1.29 ### Bug Fixes * Updated the backend CLI to version 2.27.3 to resolve a panic issue that occurred when using Docker Compose with Okteto Manifests, specifically when the `image` field in a compose service referred to an environment variable ## 1.20.0 21 May 2024 This version is compatible with Kubernetes versions 1.26 to 1.29 ### Deprecation Notice * Announced [deprecation of compose file detection](https://community.okteto.com/t/important-update-migrating-from-okteto-stacks-to-docker-compose/1262) by name ### New Features * Enable [Pull Secrets by default](/docs/admin/registry-credentials.md). If you do not wish to manage pull secrets, please see our [upgrade guide](/docs/self-hosted/manage/upgrade.md#upgrading-to-okteto-120x--pull-secrets-enabled-by-default) to disable. * Added onboarding guides to our documentation on [how to get started with Okteto Insights](/docs/admin/okteto-insights.md) * Added the ability to assign a [PriorityClass](/docs/self-hosted/helm-configuration.md#globals) to Okteto components * Added `globals` and `buildkit` tolerations to the Helm Chart and standardize their helm values ### Improvements * Namespaces without an owner will now be picked up by the Garbage Collector * Removed ingress TLS validation to allow more flexibility in deploying your own ingress objects * Renamed Variables to "Admin Variables" in the Admin section for clarity * Included license issue warning badges on Admin and sidebar menu items * Made error handling and feedback messages more consistent and actionable throughout the UI * In the UI, we renamed all `/cluster/*` routes to `/admin/*` * Updated CLI version in the backend to 2.27.2 * Okteto CLI: Changed the heuristic to mask variables in logs and comments that are longer that 5 characters * Okteto CLI: Added support for variables expansion on `manifest.build.dockerfile` * Okteto CLI: Added support for variable expansion in variables defined in `.env` - for example `"VAR1=${VAR2:-default}"` ### Bug Fixes * Fixed branch selector behavior in UI when Github fails to fetch branches * Fixed a GitHub integration issue where the dialog state wasn't updated after reconfiguring access through the popup for suspended installations * Fixed an issue where personal tokens set to never expire were changed to a 180-day expiration by the next migration job * Trial licenses are now recognized in the onboarding checklist ### Removal Notice * Support for Kubernetes [1.25](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.25.md) has been removed in this release. ## 1.19.4 28 May 2024 This version is compatible with Kubernetes versions 1.25 to 1.29 ### Bug Fixes * Updated the backend CLI to version 2.26.2 to resolve a panic issue that occurred when using Docker Compose with Okteto Manifests, specifically when the `image` field in a compose service referred to an environment variable ## 1.19.3 15 May 2024 This version is compatible with Kubernetes versions 1.25 to 1.29 ### Deprecation Notice * Support for Kubernetes [1.25](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.25.md) has been deprecated and will be removed in the next release. ### Bug Fixes * Fix pulling images from the okteto registry after sharing a namespace when pull secrets is enabled. ## 1.19.2 10 May 2024 This version is compatible with Kubernetes versions 1.25 to 1.29 ### Deprecation Notice * Support for Kubernetes [1.25](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.25.md) has been deprecated and will be removed in the next release. ### Bug Fixes * Fix pulling images from ECR private registries in dev namespaces when pull secrets is enabled. ## 1.19.1 26 April 2024 This version is compatible with Kubernetes versions 1.25 to 1.29 ### Deprecation Notice * Support for Kubernetes [1.25](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.25.md) has been deprecated and will be removed in the next release. ### Improvements * Okteto CLI: the scope of the breaking change introduced in 1.19.0 has been reduced. `okteto deploy` will ignore host volumes of Docker Compose services only if the service defines a `build` section. [Please see our community post for more details](https://community.okteto.com/t/important-update-changes-to-docker-compose-deployment-behavior-in-okteto/1246) ### Bug Fixes * Resolved a bug with migrations occurring during every Okteto upgrade. Tokens that were set to never expire were inadvertently being modified to expire in 180 days. This fix ensures that token expiration times are not altered during Okteto upgrades ## 1.19.0 16 April 2024 This version is compatible with Kubernetes versions 1.25 to 1.29 ### Deprecation Notice * Support for Kubernetes [1.25](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.25.md) has been deprecated and will be removed in the next release. ### New Features * [Okteto Insights](/docs/admin/okteto-insights.md): Pod v2, Build, Deploy, User, Namespace, and Preview metrics are now available * [Smart Builds](/docs/core/build-service.md#smart-builds) now uses `build: context` instead of `project: commit` to detect if an image was already built * Add Grafana to Admin UI to support Okteto Insights for SaaS plan users ### Breaking Changes * Okteto CLI: `okteto deploy` will ignore host volumes defined by Docker Compose services. [Please see our community post for more details](https://community.okteto.com/t/important-update-changes-to-docker-compose-deployment-behavior-in-okteto/1246) ### Improvements * Update buildkit to [v0.12.5](https://github.com/moby/buildkit/releases/tag/v0.12.5) * [maxNamespaces quota](/docs/self-hosted/helm-configuration.md#quotas) doesn't apply to the `okteto-bot` user * Introduced the OKTETO\_IS\_PREVIEW\_ENVIRONMENT variable to identify when a deployment is happening in a preview environment * Hide passwords when creating new private registry credentials * Add CLI environment variable to enable or disable local Docker credentials when building images. This setting defaults to `true` * Support for the compose.yml and compose.yaml file extensions ### Bug Fixes * Okteto CLI: Add CORS PNA to support browser logins from the Okteto CLI * Fix endpoint links in the UI that span the full width of container and break layout * `OKTETO_COMPOSE_VOLUME_AFFINITY_ENABLED` feature flag variable to disable the "force node" behavior when pods share the same PVC * 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 vice versa ## 1.18.2 20 March 2024 This version is compatible with Kubernetes versions 1.25 to 1.28. ### Bug Fixes * Dev environments and preview environments deployed from private repositories using Admin Access Tokens were not able to clone the repository even when the GitHub App had access to it. ## 1.18.1 12 March 2024 This version is compatible with Kubernetes versions 1.25 to 1.28. ### Features * Support a feature flag to disable the logic that forces pods with a shared volume to be scheduled on the same node (`unsupported.forceNodeToPodsWithSamePVCs: false`). ## 1.18.0 27 February 2024 This version is compatible with Kubernetes versions 1.25 to 1.28. ### Features * Implementation of [Admin Access Tokens](/docs/admin/dashboard.md#admin-access-tokens) ### Improvements * Added [instructions for deploying Okteto with ArgoCD](/docs/self-hosted/manage/argocd.md) * Change default value of [ingress.forceIngressSubdomain](/docs/self-hosted/helm-configuration.md#ingress) to false. By default, Okteto won't force deployed applications to match [Okteto's subdomain](/docs/get-started/deploy-your-app/endpoints.md) * Enable by default cluster policy for registry. Enables any of your Okteto users to have read access to any image built in other namespaces. [To limit this to the previous behavior](/docs/self-hosted/helm-configuration.md#registry), set `registry.pullPolicy` to `namespace` * The Okteto CLI used for Pipeline installation has been upgraded to [version 2.25.2](https://github.com/okteto/okteto/releases/tag/2.25.0) * Upgrade BuildKit to `0.12.5` ### Bug Fixes * Hide clear button if namespace search input is empty * In deploy dialog, fix wrong filter when canceling current repository on SelectRepository * Fix filtered namespace view where parent resources were not expanded * Fix closing create access token dialog from keyboard * Fix Scale to Zero Period showing wrong value in Previews UI * Fix wrong "Waking Up" status when switching to a "Sleeping" namespace * Properly render `code` nodes as inline elements inside a list item * Fix BuildKit configuration behind our ingress-controller not working when BuildKit had more than 1 replica ## 1.17.0 23 January 2024 This version is compatible with Kubernetes versions 1.25 to 1.28. ### Features * Enable search in namespace resources UI * Enable admins to [transfer namespace ownership](/docs/core/namespaces.md#transfer-namespace-ownership) * Add [Pod metrics to Okteto Insights](/docs/admin/okteto-insights.md#pod-metrics) ### Improvements * Hoist Personal Access Tokens menu from Setup to Settings * Rename Launch to Deploy in the Okteto UI * Rename Secrets to Variables under both Settings and Admin sections. This rename is for consistency in the UI and delivers no change in functionality * Support for multi-line secrets * Improve buildkit cache reloading on helm upgrades. Please note this upgrade will imply a restart in the build cache ### Bug Fixes * Surface buildkit errors through our ingress controller. Will result in better build error messages * The Okteto Insights endpoint was not exposing build metrics when the Helm release name included the word "okteto" * Fixed a scenario where the runtime of node containers could restart if the Okteto daemon pod were to be recreated, potentially impacting active 'okteto up' sessions ## 1.16.2 17 January 2024 This version is compatible with Kubernetes versions 1.25 to 1.28. ### Bugfixes * Fixed a scenario where node container runtimes could restart if the Okteto daemon pod were to be recreated, potentially impacting active 'okteto up' sessions. ## 1.16.1 10 January 2024 This version is compatible with Kubernetes versions 1.25 to 1.28. ### Bugfixes * The Okteto CLI used for Pipeline installation has been upgraded to version [2.23.3](https://github.com/okteto/okteto/releases/tag/2.23.3). It includes a fix for scenarios where image builds were failing because an image was not being found in the global registry. * The Okteto Insights endpoint was not exposing build metrics when the Helm release name included the word "okteto" ## 1.16.0 20 December 2023 This version is compatible with Kubernetes versions 1.25 to 1.28. ### Features * Add `okteto_usage_build_duration_seconds` build metrics to okteto insights. More info [here](/docs/admin/okteto-insights.md) * A diagnostics tool is now provided to help troubleshoot installations. More info [here](/docs/self-hosted/manage/diagnostics.md) * The Okteto CLI used for Pipeline installation has been upgraded to version [2.23.1](https://github.com/okteto/okteto/releases/tag/2.23.1) * Move garbage collection of `okteto up` based on last synced file behind a feature flag. More info [here](/docs/self-hosted/helm-configuration.md#gc) * Okteto now runs in ARM architecture. This is currently in beta. ### Improvements * Okteto garbage collector cronjob now resolves buildkit and ingress hosts to their internal IPs * Registry Credentials cronjob only update dockerconfig secret if the credentials change. * Okteto Daemon now update kubelet docker config.json file in nodes reactively when the static docker config secret changes. Bumps okteto/daemon to 0.5.1 * Fix network policies configuration to limit buildkit access to the nginx controller * Add Okteto Insights Token to the Admin UI * Updated documentation structure to make content easier to navigate and find. Release notes can now be found at [https://www.okteto.com/docs/release-notes](/docs/release-notes.md), and chart values reference can be found at [https://www.okteto.com/docs/reference/helm-chart-values/](/docs/self-hosted/helm-configuration.md). All documentation changes are listed [here](https://github.com/okteto/docs/pulls?q=is%3Apr+label%3Adoc-restructure+). ## 1.15.1 1 December 2023 This version is compatible with Kubernetes versions 1.25 to 1.27. ### Bugfixes * Fix okteto daemon restart when AWS ECR private registry credentials are defined ## 1.15.0 22 November 2023 This version is compatible with Kubernetes versions 1.25 to 1.27. ### Removal Notice Kubernetes 1.24 is no longer supported ### Improvements * Upgrade ingress-nginx to [1.9.4](https://github.com/kubernetes/ingress-nginx/releases/tag/controller-v1.9.4) (Helm chart version 4.8.3) * Enabled [chroot mode](https://kubernetes.io/blog/2022/04/28/ingress-nginx-1-2-0/) by default in both ingress-nginx controllers managed by Okteto. * `okteto up` sessions are now garbage collected if no files have been synced for an hour ### Bug Fixes * Fallback to default branch for destroy installer jobs * Smart builds work on repositories using `.gitmodules` containing submodules cloned via ssh key * Fix wrong "Scale to Zero Period" value in the UI of Admin → Namespaces ### Features * The Okteto CLI used for Pipeline installation has been upgraded to version [2.22.3](https://github.com/okteto/okteto/releases/tag/2.22.3) ## 1.14.3 1 December 2023 This version is compatible with Kubernetes versions 1.25 to 1.27. ### Bugfixes * Fix okteto daemon restart when AWS ECR private registry credentials are defined ## 1.14.2 8 November 2023 This version is compatible with Kubernetes versions 1.24 to 1.27. ### Bugfixes * Fix private registry credentials integration for registries with custom ports (other that the default 443) ## 1.14.1 27 October 2023 This version is compatible with Kubernetes versions 1.24 to 1.27. ### Improvements * Okteto internal registry is now resolved in private credentials exchange ### Bugfixes * Namespace list in the UI is now scrollable and displays all namespaces. * Fix login with openid through the okteto CLI with custom "audience" and "resource" ## 1.14.0 25 October 2023 This version is compatible with Kubernetes versions 1.24 to 1.27. ### Deprecation Notice * Helm charts catalog is no longer available in the Okteto UI. For alternative approach to deploy Helm charts see * Defining Private Registry credentials in Helm has been deprecated. Private Registry Credentials are now natively supported by Okteto and configurable in the Okteto UI. Credentials defined in Helm will be automatically migrated. * Support for Kubernetes [1.24](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.24.md) has been deprecated and will be removed in the next release. ### Features * Added a new `/metrics` endpoint to expose prometheus node metrics data. More info [here](/docs/admin/okteto-insights.md). * Added native support for Private Registry Credentials, configurable directly in the Okteto UI. More info [here](/docs/admin/dashboard.md#registry-credentials). * The Okteto CLI used for Pipeline installation has been upgraded to version [2.21.0](https://github.com/okteto/okteto/releases/tag/2.21.0) * Add support for Kubernetes [1.27](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.27.md) ### Improvements * Upgrade ingress-nginx to 1.8.2 (Helm chart version 4.7.2) ### Bugfixes * Reduce file permission for okteto-ca-pemstore certificate file in jobs * Reduce expiration threshold for trial licenses from 60 to 7 days ## 1.13.0 27 September 2023 This version is compatible with Kubernetes versions 1.24 to 1.26. ### Breaking Changes Okteto requires you to use a valid license as part of the installation. If you were running a previous version of Okteto and you don't have a valid license, signup for our [Free Tier (5 seats, 1 year)](https://www.okteto.com/free-trial/) or [reach out to us](https://www.okteto.com/contact/). ### Improvements * Updates to [Cloud Secret](/docs/self-hosted/helm-configuration.md#registry) now take immediate effect * The Okteto CLI used for Pipeline installation has been upgraded to version [2.20.0](https://github.com/okteto/okteto/releases/tag/2.20.0) * Pipeline installations now use dynamic kubernetes tokens to talk to the kubernetes api via the [ClientAuthentication API](https://kubernetes.io/docs/reference/config-api/client-authentication.v1/). ### Bugfixes * Documentation now links the exact version version in the docs * During installation/upgrade the current version of Okteto is no longer tied to Helm `.Chart.Version` and `.Chart.AppVersion` * Improve platform and kubernetes version attributes resolution in Telemetry cronjob ## 1.12.1 14 September 2023 This version is compatible with Kubernetes versions 1.24 to 1.26. ### Bugfixes * Update Kubernetes internal dependencies to fix a possible crash/panic when Okteto lists the cluster API Resources. This could happen when destroying the content of a namespace or during Preview Environment operations. * Includes the following commit from `kubernetes/client-go`: . ## 1.12.0 31 August 2023 This version is compatible with Kubernetes versions 1.24 to 1.26. ### Breaking changes * Kubeconfigs downloaded from the Okteto web UI now require Okteto CLI 2.15 or higher to use dynamic tokens for authenticating against Kubernetes. ### Features * The Okteto CLI has been upgraded to version [2.19.2](https://github.com/okteto/okteto/releases/tag/2.19.2). * The Admin view has been redesigned with a new vertical tab column. * Added ["Registry Credentials" to the Admin view](/docs/admin/dashboard.md#registry-credentials) to display configured private registry information. This provides visibility into the private registries in use for your Okteto instance (username/password and AWS Access/Secret only for now) ### Improvements * The Preview list in the Admin view now shows time units in the Garbage Collector settings description. * When waking a Namespace from the Namespace, Preview, or Admin views, the UI now provides feedback for the request. * When a GitHub user does not belong to the allowed GitHub organization and attempts to log in, a specific error is now shown. * When using a GitHub App for authentication that is not yet installed in the GitHub organization and an allowed GitHub organization filter is set, a specific error is now shown. * Resources for Nodes in the Admin view are now correctly aligned. * Priority Classes can now be specified via `priorityClassName` sub-property for the following components: [`api`](/docs/self-hosted/helm-configuration.md#api), [`buildkit`](/docs/self-hosted/helm-configuration.md#buildkit), [`defaultBackend`](/docs/self-hosted/helm-configuration.md#defaultbackend), [`frontend`](/docs/self-hosted/helm-configuration.md#frontend), [`registry`](/docs/self-hosted/helm-configuration.md#registry) and [`webhook`](/docs/self-hosted/helm-configuration.md#webhook). ## 1.11.1 8 August 2023 ### Bugfixes * When deploying compose files, Okteto built-in environment variables (e.g OKTETO\_BUILD\_XXX) were not expanded correctly. ## 1.11.0 2 August 2023 ### Improvements * Upgraded buildkit to v0.11.6. * Upgraded ingress-nginx to 4.7.1. * Underlying Kubernetes cluster version is now shown in the Admin section. * When a GitHub App private key is not valid, a warning message is now shown in a components' logs and when attempting to authenticate or perform a GitHub-related action. * Okteto Web UI documentation links now point to the same version used by the platform instead of the latest version. * Automatic role binding for service accounts can now be disabled. * Added [configuration setting in the daemonset](/docs/self-hosted/helm-configuration.md#daemonset) to disable the configuration of private registry credentials in the nodes ### Bugfixes * When hovering over logs in the Okteto Web UI, a wrong timestamp was shown. * Istio's Virtual Service now show only their own dedicated endpoints when using ["dev.okteto.com/endpoints" annotation](/docs/core/endpoints/automatic-ssl.md#customizing-the-endpoints-shown-in-the-okteto-dashboard). ## 1.10.0 5 July 2023 ### Removal Notice Kubernetes 1.23 is no longer supported. ### Features * Kubernetes supported versions: [1.26](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.26.md), [1.25](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.25.md) and [1.24](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.24.md). * Now you can select an expiration period when creating a new [Personal Access Token](/docs/core/credentials/personal-access-tokens.md#creating-a-personal-access-token). * Administrators have the ability to wake up, put to sleep, or mark any preview environment as keep-awake. * Upgraded ingress-nginx to [4.6](https://github.com/kubernetes/ingress-nginx/releases/tag/controller-v1.7.0). ### Improvements * Kubernetes Annotations can now be added to: * Default self-signed wildcard certificate via `.Values.wildcardCertificate.annotations`. * Internal self-signed webhook certificate via `.Values.webhook.internalCertificate.annotations`. * Dockerconfig via `.Values.secret.annotations`. * Kubernetes Labels can now be added to: * Dockerconfig via `.Values.secret.labels`. ### Bugfixes * When using the default `.Values.subdomain`, pending Domain installation task is now correctly shown. * Cert-manager annotations are now allowed in developer ingresses. * When a license is not specified, the Starter plan is displayed instead of Unknown. * Upgraded the Okteto CLI version to [2.16.5](https://github.com/okteto/okteto/releases/tag/2.16.5). * When using `okteto deploy --remote ...` with private certificates, internal registry requests will now work correctly. * We've added additional form validation to the Launch Dev Environment modal so invalid repo URLs will no longer be accepted and allow the modal to close. * Pipeline destroy actions now use the environment variables used during deployment. ## 1.9.1 22 June, 2023 ### Bugfixes * Upgrade [ingress-nginx](https://github.com/kubernetes/ingress-nginx) from 4.5.0 to 4.5.2 to include the following bugfix: * Fix regression when using regex in ingress path ## 1.9.0 12 June, 2023 ### Deprecation Notice * Support for Kubernetes [1.23](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.23.md) has been deprecated and will be removed in the next release. ### Features * Added support for Kubernetes v1.26. All supported versions: [1.26](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.26.md), [1.25](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.25.md) and [1.24](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.24.md). * Upgraded the Okteto CLI version to [2.16.3](https://github.com/okteto/okteto/releases/tag/2.16.3) * Last user interaction with Okteto is now available at the Admin dashboard, under the Users section. * Support to access Okteto on `127.0.0.1` * Upgrade ingress-nginx to [4.5](https://github.com/kubernetes/ingress-nginx/releases/tag/controller-v1.6.4) * `okteto deploy --remote` supports when Okteto has self-signed certificates and private Certificate Authorities (CAs). ### Improvements * Enabled gzip compression for frontend web server ### Bugfixes * Improve app chunk loading and error handling * Uninstall Helm installations from dev environments on "destroy all" operations * Deactivate any containers in development mode on "sleep namespace" operation * Environment variables defined for a deploy are also available for destroy operation * Container image layer manifest sometimes got corrupted when being uploaded to the Registry, causing "500 Internal Server Error" on following build requests to Buildkit. * When using dual ingress controller (default), requests body size was limited to 1MiB. This has been fixed and increased to 60MiB. ## 1.8.3 15 Jun, 2023 ### Bugfixes * When using dual ingress controller (default), requests body size was limited to 1MiB. This has been fixed and increased to 60MiB. ## 1.8.2 30 May, 2023 ### Bugfixes * Upgraded the Okteto CLI version to [2.15.4](https://github.com/okteto/okteto/releases/tag/2.15.4). * Build optimization now also considers the environment variables used in build args when determining when to rebuild an image. ## 1.8.1 24 May, 2023 ### Bugfixes * Fixed an issue affecting deletion of dev and preview environments when using custom Okteto manifests. The destroy operation did not evaluate the custom manifest used during deployment, which meant the destroy commands were not executed. * Upgraded the Okteto CLI version to [2.15.3](https://github.com/okteto/okteto/releases/tag/2.15.3). * Build optimization now considers environment variables used in build args to determine when to rebuild an image. * Fixed a regression which was preventing the deploy dialog from loading the list of GitHub repositories for new users when the authentication provider was GitHub. ## 1.8.0 10 May, 2023 ### Before you upgrade Okteto 1.8 includes a change in the ingress architecture. If you're using your own ingress controller instead of the ingress-controller embedded with Okteto chart, please checkout the updated section about ["How to use your own ingress controller"](/docs/self-hosted/helm-configuration.md#using-your-own-ingress-controller). ### Breaking changes * The default value for the buildkit service session affinity is now `None`. To keep using `ClientIP` as `sessionAffinity` you need to set `service.sessionAffinity: ClientIP` in your [buildkit configuration](/docs/self-hosted/helm-configuration.md#buildkit). ### Deprecation Notice * Support for Kubernetes [1.22](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.22.md) has been deprecated and will be removed in the next release. ### Features * Kubernetes supported versions: [1.25](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.25.md) ([upgrade guide](/docs/self-hosted/manage/upgrade.md)), [1.24](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.24.md) and [1.23](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.23.md). * Support for custom [labels and annotations](/docs/self-hosted/helm-configuration.md#namespace) in ingresses managed by Okteto. * Upgraded the Okteto CLI version to [2.15.2](https://github.com/okteto/okteto/releases/tag/2.15.2) * Okteto CLI 2.15.2 enables the optimization removed at Okteto CLI 2.14.3. Now we calculate a hash for a given commit with the info around the build. * Okteto Self-Hosted will now show the [installation setup guide](/docs/admin/dashboard.md#installation) by default * External resources can now be destroyed from the Okteto UI * External resources now supports [additional icons](/docs/reference/okteto-manifest.md#icon-string-optional) * Ingresses are now served through two ingress-controllers instances, enabling flexible configuration and improving connection stability. * `ingress-nginx` will continue to be the main gateway for all inbound traffic to Okteto, but will stop processing individual users' ingresses. Instead it will forward users' ingresses to the new `okteto-nginx`. * `okteto-nginx` sits behind `ingress-nginx` and it process exclusively users' ingresses. * For additional configuration of both instances, please check the [ingress-controller configuration section](/docs/self-hosted/helm-configuration.md#ingress-nginx). * Okteto Ingress [defaultBackend](/docs/self-hosted/helm-configuration.md#defaultbackend) is now deployed separately of `ingress-nginx` or `okteto-nginx`. ### Improvements * All external services created or updated by Okteto will now have the `dev.okteto.com/namespace` label * Improved the performance of the query for retrieving endpoints for a preview environment using the `dev.okteto.com/namespace` label * Support baggage header for istio divert driver * Remove the `email` field from the helm values file. It is is now provided by the license * Divert virtual service transformation is now done at the mutation webhook by adding the annotation to the virtualservices * The frontend app now uses proper browser history routing instead of hash routing * Catalog items are now sorted, by default, in the same way in both the admin dashboard and a developer's deploy/redeploy modal * Using personal repositories from Bitbucket is now possible as we've addressed an issue with restricted characters in repository names * Persistent spaces can no longer be put to sleep from the admin dashboard * Improve text readability on deploy resources list ### Bugfixes * Custom endpoints annotation `dev.okteto.com/endpoints` is now mapped with the correct service of an ingress * Fix preview delete confirm modal stating "Delete namespace" * Tabs in the admin panel are now appropriately responsive for smaller screens and resolutions. The last tabs will now wrap properly * External Resources markdown inline code is now rendered correctly as inline instead of a fenced code block * Translation browser extensions causing blank screens due to modifying DOM * Show endpoints coming from virtual services in the Preview List view * Move cache headers from `meta` to nginx so `Cache-Control` headers are applied correctly * Show "managed by" message only when adding a repository to previews and not when launching a development environment * Force non-breaking spaces for leading whitespace on logs * Fix panic produced when deploying a repository with trailing slash * Add disable state to external resources when being destroyed ## 1.7.1 21 April, 2023 ### Bugfixes * Upgraded the Okteto CLI version to [2.14.3](https://github.com/okteto/okteto/releases/tag/2.14.3). * Okteto CLI 2.14.0 introduced an optimization to build only once the image for a given commit. Okteto CLI 2.14.3 disables this optimization while we fix some inconsistencies around its behavior ## 1.7.0 12 April, 2023 ### Removal Notice * Kubernetes [1.21](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.21.md) is no longer supported. ### Deprecation Notice The `cloud.provider` and `cloud.secret` keys in the Helm chart are now deprecated and they will be removed in the future 2.x release. Instead, you can now use [`registry.storage.provider`](/docs/self-hosted/install/okteto-registry-storage.md) and [`registry.secret`](/docs/self-hosted/helm-configuration.md#registry) to configure the registry to use external storage. This change is backward compatible: the old configuration keys will continue to work until they are removed in 2.x. You can follow our [upgrade guide](/docs/self-hosted/manage/upgrade.md). ### Features * Kubernetes supported versions: [1.24](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.24.md), [1.23](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.23.md) and [1.22](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.22.md). * Support for the annotation [dev.okteto.com/endpoints](/docs/core/endpoints/automatic-ssl.md#customizing-the-endpoints-shown-in-the-okteto-dashboard) to customize the endpoints shown in the Okteto UI. * Support for configuring the [service account](/docs/self-hosted/helm-configuration.md#buildkit) of buildkit. * Support for [token-based authentication](/docs/self-hosted/install/auth/token.md) to simplify the installation of Okteto Self-Hosted. * [Personal Access Tokens](/docs/core/credentials/personal-access-tokens.md) will automatically expire after 180 days. For existing tokens, the expiration date will be set to 180 days from when your Okteto instance is upgraded to 1.7 or newer versions * Upgraded the Okteto CLI version to [2.14.2](https://github.com/okteto/okteto/releases/tag/2.14.2) * Upgraded ingress-nginx to [4.3.0](https://github.com/kubernetes/ingress-nginx/releases/tag/helm-chart-4.3.0) * You can now delete external resources from the UI * The default installation of Okteto doesn't require an external storage for the [registry](/docs/self-hosted/helm-configuration.md#registry). It now uses [filesystem storage](/docs/self-hosted/install/okteto-registry-storage/filesystem.md) by default * The default installation of Okteto doesn't require a PVC for [BuildKit](/docs/self-hosted/helm-configuration.md#buildkit). It now uses filesystem storage by default ### Improvements * When `buildkit.ingress.enabled` is true, BuildKit is exposed in the `buildkit.service.port` instead of port 1234. This makes it easier to use your with other ingress controllers * We optimized the redeploy dialog experience. Information loads faster in the dialog, specially when the source is GitHub * Improved confirmation dialogs messages * When your Okteto instance doesn't have an auth provider configured, the login screen shows a message with a link to the documentation on how to configure it * Pod Security Policies are not installed if they are not available in the cluster ### Bugfixes * When redeploying a dev environment from the UI, there was a race condition that was preventing to use the right environment configuration (manifest, variables, branch, etc...) * Sleeping resources now renders `No output.` logs instead of `Loading output...` * Install and destroy jobs are retried when they fail due to transient errors during their execution * Avoid panics in private endpoints when the user is not authenticated * `Sleep` option is not available in the list of namespace actions when the namespace is persistent * Fixed a problem when destroying dev environments from the UI when the manifest has defined an `image` property within the `destroy` section that was preventing the dev environment to be destroyed * Fixed a problem when destroying dev environments with a variable declared in a multiline `destroy` command * External resources were not being grouped under the corresponding dev environment when there was an error in the deployment of the environment ## 1.6.0 15 March, 2023 ### Breaking changes This version comes with a breaking change. The default ingress class for ingresses managed by Okteto changed from `nginx` to `okteto-nginx` to prevent collisions with other controllers that might be already installed in the cluster. There is no action required from the user, all ingresses managed by Okteto will be automatically updated as part of the upgrade. If you want to continue to use the previous ingress class (`nginx`), you can do it by setting the following values in your helm values file: ``` ingress: class: nginx oktetoIngressClass: nginx ingress-nginx: controller: ingressClass: nginx ingressClassResource: name: nginx controllerValue: "k8s.io/ingress-nginx" ``` In some cases, there is a race condition recreating the controller pods in which a controller pod starts before the new ingress class is created in the cluster and that generates 404 errors when accessing Okteto or dev environments. For that reason, we recommend to rollout the ingress controller deployment to avoid this issue (`kubectl rollout restart deployment -n okteto`). ### Deprecation Notice * Support for Kubernetes [1.21](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.21.md) has been deprecated and will be removed next release. ### Features * Kubernetes supported versions: [1.24](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.24.md), [1.23](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.23.md) and [1.22](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.22.md). * Update the Okteto CLI version to [2.13.0](https://github.com/okteto/okteto/releases/tag/2.13.0) * Support [custom quotas](/docs/self-hosted/helm-configuration.md#quotas) for node port and load balancer service types * [Public override support](/docs/self-hosted/helm-configuration.md#publicoverride) for self-signed certificates and bring your own certificate * The wake operation will now wake up dependent services first, following the same order as when the environment was created. * Add support for [dynamic endpoints for external resources](/docs/reference/okteto-manifest.md#use-dynamic-endpoints-for-an-external-url) ### Improvements * Several improvements in the UI to keep the status updated accordingly with the status in user's dev environments * Allow users to access to namespaces that are being terminated to see the operation logs * Added input autofocus in several dialogs * The "Create Namespace" button is now enabled immediately after you start writing the name of the namespace in the "New Namespace" dialog. * You can now filter the available branches in the GitHub deploy dialog * Simplified the admin dashboard by removing duplicated titles in every section. * Do not autodestroy GC job when it ends. Last 3 executions of the job will be kept, so job logs can be accessed * Private endpoints cookie is now set in the backend and specified as "httpOnly" * Upgrade Reloader dependency to [1.0.5](https://github.com/stakater/Reloader/releases/tag/v1.0.5) ### Bugfixes * Skip volume snapshots deletion as part of destroy all operation if "include volumes" check is not selected * Fix "Destroy all", "Delete namespace" and "Wake namespace" operations when using private CAs or self-signed certificates * Display the correct operation name in logs when deleting a namespace or destroying all resources within a namespace * Avoid duplicated log lines when the browser visibility changes * Self-signed certificate is recreated when [subdomain](/docs/self-hosted/helm-configuration.md#subdomain) or [publicOverride](/docs/self-hosted/helm-configuration.md#publicoverride) changes after an upgrade * Fixed view transition when a destroy namespace operation is retried * Fixed missing [custom icons on external resources](/docs/reference/okteto-manifest.md#icon-string-optional) * Fixed autofocus on confirm dialogs * GC deletes pods stuck in `Failed` phase with `NodeAffinity` reason ## 1.5.1 6 March, 2023 ### Bugfixes * Fixed an issue that prevented users from authenticating against the registry when using a separate certificate for the registry (`.Values.registry.ingress.tlsSecret`). ## 1.5.0 14 February, 2023 ### Features * Kubernetes supported versions: [1.23](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.23.md), [1.22](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.22.md) and [1.21](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.21.md). * You can now define an [icon for every endpoint in your external resources list](/docs/reference/okteto-manifest.md#icon-string-optional) * Add support for registry cloud provider storage using: * [GCP Workload Identity](/docs/self-hosted/install/okteto-registry-storage/google-cloud-storage.md) * [AWS IAM Roles for Service Accounts](/docs/self-hosted/install/okteto-registry-storage/aws-s3-bucket.md) ### Improvements * Make env var values editable on deploy/redeploy * Filter repositories results by search term * Delete button is now disabled in the personal namespace * Reduced load time when opening Github redeploy dialog * Added antiAffinity [configuration](/docs/self-hosted/helm-configuration.md#userpodaffinity) for PODs with label `dev.okteto.com/affinity` * Added granular definition support for [networkPolicies](/docs/self-hosted/helm-configuration.md#networkpolicies) created by Okteto. ### Bugfixes * 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. * Keep ingress class on wake if ingress class is different than "sleeping" * Ignore read only Kubernetes API Extension Servers (e.g. metrics.k8s.io) if unavailable on destroy all job runs. * When using Divert, some scenarios may cause its ingress configuration to be dropped * Don't show a pointer cursor type in log lines * Autopreviews are now being deleted when PR is merged or closed * Correctly alignment of non private/divert endpoints and repository at resource details section. * Removed unused configuration values related to cert-manager in the Helm chart * Fixed issue in the OpenID configuration that prevented using ADFS as the identity provider * Get claims from access token when `ADFS` resource is given * Added support for volume snapshots in EKS 1.23 ## 1.4.3 6 March, 2023 ### Bugfixes * Fixed an issue that prevented users from authenticating against the registry when using a separate certificate for the registry (`.Values.registry.ingress.tlsSecret`). ## 1.4.2 February 7, 2023 ### Bugfixes * Fixed issue on instances with self-signed certificates or private CA that prevented the destroy all and destroy namespace actions to work properly. ## 1.4.1 February 1, 2023 ### Bugfixes * Fixed issue that caused the autoscaler to crash when parsing ingresses without the `ingressClassName` attribute. ## 1.4.0 January 19, 2023 ### Features * Kubernetes supported versions: [1.23](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.23.md), [1.22](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.22.md) and [1.21](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.21.md). * You can now define [external resources](/docs/reference/okteto-manifest.md#external-object-optional) in your Okteto manifest. Use this to include resources that exist outside of your Okteto namespace like databases, message brokers, serverless functions, dashboards, etc. * You can now show [virtual services](/docs/self-hosted/helm-configuration.md#virtualservices) endpoints in the Okteto UI * Update okteto cli version to [2.11.1](https://github.com/okteto/okteto/releases/tag/2.11.1) ### Improvements * The commands defined in the `destroy` section of the Okteto manifest will now be executed when destroying a namespace or preview environment * You can now retry and force namespace deletion in the UI * When deleting a namespace/preview, its name will appear in the delete pop-up notification * Sleeping a namespace using the UI now displays a confirmation dialog * The catalog section of the Deploy dialog now includes a search bar * The user-provided NGINX configuration snippet (the `nginx.ingress.kubernetes.io/configuration-snippet` annotation) will now get merged with Okteto's configuration snippet * By default, pod requests are no longer modified by Okteto * Updated the `crd` configuration in the Helm chart to follow recommended practices for [CRD management](/docs/self-hosted/helm-configuration.md#crds) * You can now define [custom affinities](/docs/self-hosted/helm-configuration.md#affinity) for dev containers and installer jobs in helm config * You can now define custom resources (requests and limits) for installer jobs * You can now define tolerations and node selector for the telemetry cronjob * You can now override the images of the [daemon](/docs/self-hosted/helm-configuration.md#daemonset) and autoscaler ### Bugfixes * The branch selector in the Deploy dialog doesn't flicker when the branch is not found * Fixed issue that prevented private repositories of individual GitHub accounts to be correctly displayed in the Deploy dialog * Fixed compatibility issues with Azure Active Directory * Fixed blank screen that sometimes appeared when clicking the "Stop development" button * Fixed race condition when trying to deploy a development environment that was removed from the catalog * Ingresses that are not managed for Okteto won't be deleted when a namespace is put to sleep * Fixed how host aliases are injected in the installer pods as the connection to Okteto's API and registry was not using the internal IPs in some scenarios ## 1.3.0 December 23, 2022 ### Features * Kubernetes supported versions: [1.23](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.23.md), [1.22](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.22.md) and [1.21](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.21.md). * [Catalog](/docs/admin/catalog.md) to provide predefined development environments to every developer * Remove CLI tab from Okteto UI deploy ### Bugfixes * Verification of GitHub usernames is now case insensitive to match GitHub rules * Fix the race condition that enabled users to modify `repo` field on the GitHub redeploy dialog * You can now define "resources" for the okteto daemonset component. Use this to ensure that Kubernetes will reserve resources for the `daemonset` * Fix the race condition that prevented namespace-level resources from being displayed in the UI * Fix wrong "Last updated" time for development environments in the Okteto UI ## 1.2.0 November 25, 2022 ### Features * Kubernetes supported versions: [1.23](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.23.md), [1.22](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.22.md) and [1.21](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.21.md). * Update okteto cli version to [2.9.0](https://github.com/okteto/okteto/releases/tag/2.9.0) * Support for self-signed certificates and private CA with Docker * Buildkit port is now [configurable](/docs/self-hosted/helm-configuration.md#buildkit) * Save costs by allowing to scale down to zero nodes if no user pods are running * Added [configuration to set PSP and AppArmor](/docs/self-hosted/helm-configuration.md) ### Improvements * UI pagination support for GitHub branches list * Populate oauth errors to the user ### Bugfixes * Don't show warning when installing okteto on k8s 1.23.x * Frontend nginx [CVE-2022-40303](https://access.redhat.com/security/cve/CVE-2022-40303)/[CVE-2022-40304](https://access.redhat.com/security/cve/CVE-2022-40304) * Fix loader icon regression * Display license related information properly * Update text in error when using token-based auth * Persist selfsigned wildcard certificate * Allow pods to have their own image pull secret * Added `registry's hostname` to `installer pods` (`/etc/hosts`) pointing to the internal IP, to ensure an internal connection to the component. * Fix user deletion when there is no owner among the namespace members * Virtual services are now correctly displayed in the Okteto UI ## 1.1.0 November 2, 2022 ### Features * Kubernetes supported versions: [1.23](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.23.md), [1.22](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.22.md) and [1.21](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.21.md). * Allow members of a namespace to share it. ### Improvements * Allow disabling the autoscaler. * Support custom labels and annotations in okteto serviceaccounts. * Allow not checking that the domains of the user's app match the okteto subdomain. * Support for extra role bindings for every developer account on each namespace. * Support for keeping pod resources by using `dev.okteto.com/pod-resources: keep` annotation. * Support for custom ingress class for ingresses created by okteto installation. ### Bugfixes * Check if using volume snapshots to delete a PVC. * Fix ingress-nginx default wildcard cert. * Fix internal server error when buildkit is disabled. * Remove ingress rules for buildkit and localhost. * Disable validation for custom clusterRole configuration ## 1.0.0 September 22, 2022 The 1.0.0 comes with two breaking changes, follow our [upgrade guide to 1.x](/docs/self-hosted/manage/upgrade.md) to reduce the disruption of the service to a minimum. ### Removal Notice * Kubernetes [1.19](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.19.md) is no longer supported. ### Deprecation Notice * Support for Kubernetes [1.20](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.20.md) has been deprecated and will be removed next release. ### Features * Kubernetes supported versions: [1.23](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.23.md), [1.22](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.22.md) and [1.21](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.21.md). * Okteto UI now allows users to specify the manifest path when launching a dev environment. ### Improvements * Chart has been renamed from "Okteto Enterprise" to "Okteto". * The cert-manager chart is no longer bundled with Okteto and is no longer installed by default. Okteto now uses a self-signed certificate by default. * Upgrade ingress-nginx to [4.2.1](https://github.com/kubernetes/ingress-nginx/releases/tag/helm-chart-4.2.1). * Exposed gRPC connection configuration for the BuildKit gRPC [server](/docs/self-hosted/helm-configuration.md#buildkit). ### Bugfixes * Fixed an issue where PVCs were not being deleted when volumeSnapshots were enabled. ## 0.15.0 August 18, 2022 ### Deprecation Notice * Deprecate support for Kubernetes [1.19](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.19.md). Support for 1.19 will be dropped in the next release. ### Improvements * Add support for Kubernetes [1.22](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.22.md) * Upgrade Okteto CLI to [2.5.2](https://github.com/okteto/okteto/releases/tag/2.5.2) * Upgrade Buildkit to [0.10.3](https://github.com/moby/buildkit/releases/tag/v0.10.3) * Upgrade ingress-nginx to [4.1.3](https://github.com/kubernetes/ingress-nginx/releases/tag/helm-chart-4.1.3) * Upgrade Reloader dependency to [0.0.118](https://github.com/stakater/Reloader/releases/tag/v0.0.118) * Enable [user pod preferred affinity](/docs/self-hosted/helm-configuration.md#userpodaffinity) by default- Eliminated buildkit upgrade failures related to immutable statefulset fields. * Support the kubernetes endpoints needed by litmus-2.10.2 * Improve the rollout of public services using rolling updates ### Bugfixes * Delete VolumeSnapshotsContent when VolumeSnapshot is deleted * Account for non-existing users in GC job when deleting namespaces ## 0.14.1 August 3, 2022 ### Bugfixes * Private CAs are now correctly propagated to the worker nodes. ## 0.14.0 July 14, 2022 ### Features * Add structured and staged logs for pipelines. Groups logs by stage in the okteto UI. * Support adding custom environment variables for main Okteto components * Support adding custom annotations, labels, and environment variables to the pipeline installer jobs * Display the CLI version used by the pipeline installer jobs in the Okteto UI admin panel * You can now download the Okteto cluster context from the UI ### Improvements * Upgraded Okteto CLI to [2.4.2](https://github.com/okteto/okteto/releases/tag/2.4.2) * Removed deprecated Google Sign-in JavaScript Platform Library in favor of standard OAuth. More info [here](https://developers.googleblog.com/2021/08/gsi-jsweb-deprecation.html). No action is required. * Disable the [helm catalog](/docs/self-hosted/helm-configuration.md#api) on self-hosted installations by default. This makes installing CRDs not mandatory during cluster creation. * Improve K8S rolling update process for Okteto API deployment ### Bugfixes * The webhook will not redeploy snapshots as part of an update operation. * Pipelines are now able to push and pull charts to the internal repository * The deploy button is now disabled in the UI while requests are in-flight. This was causing double deploys in some scenarios. * Fixed memory leak caused by not freeing up some resources after closing the connection when streaming the logs. * Pipelines now show the correct initial date in the logs ## 0.13.0 Jun 16, 2022 ### Features * Add Access Control to [Volume Snapshots](/docs/self-hosted/install/volume-snapshots.md) * Add link to the [Community website](https://community.okteto.com) in the help menu. * Inject `OKTETO_NAMESPACE` and `OKTETO_DOMAIN` environment variables in every pod * Remove Namespace limit on licenses ### Improvements * Upgrade Okteto CLI to [2.3.3](https://github.com/okteto/okteto/releases/tag/2.3.3) * Upgrade Okteto registry to [2.8.1](https://github.com/distribution/distribution/releases/tag/v2.8.1) * Better deduplication in secrets query. Prioritize user secrets over cluster secrets. * Handle PVC update in the mutating webhook. Fixes Okteto CLI issue [#2599](https://github.com/okteto/okteto/issues/2599) * Upgrade crypto package. Fixes [CVE-2022-27191](https://access.redhat.com/security/cve/CVE-2022-27191) * Upgrade frontend nginx server to alpine 1.22. Fixes [CVE-2022-27405](https://access.redhat.com/security/cve/CVE-2022-27405) ### Bugfixes * Fix panic in Preview Environment query for repos with invalid format * Fix component running state calculation for pods with many retries. They previously stayed in the error state. * Fix UI bug with Pull Request names in Preview environment list for non github URLs. ## 0.12.0 May 19, 2022 ### Improvements * Okteto daemonset no longer mounts host volumes nor runs in privilege mode * Add support for [GKE workload identity](https://cloud.google.com/kubernetes-engine/docs/concepts/workload-identity) * Use `ingressClassName` field for ingresses instead of the deprecated `kubernetes.io/ingress.class` annotation * Add [network quotas](/docs/self-hosted/helm-configuration.md#quotas) for okteto up * Invalid ingresses not accepted by the nginx ingress controller are now caught by the webhook * Deploying daemonset is no longer allowed by default * Ingresses are put to sleep alongside all other namespace resources and automatically wake by with incoming requests * Improve pipeline jobs lifecycle and properly handle timeouts. Logs for pipelines that time out are no longer lost * Account for "ready" container condition to check if a component is healthy * 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 inaccessible modal elements on small screens * Upgrade to Okteto CLI 2.2.2 * Upgrade ingress-nginx helm chart to 4.1.0 ### Bugfixes * Fix a panic in the mutation webhook for pods with no labels * Minor UI fixes for deploy's branch selector ### Breaking changes * Ingresses using the `kubernetes.io/ingress.class` annotation will be automatically updated by the okteto webhook and saved as `spec.ingressClassName` with the annotation removed * Okteto Pipelines are executed relative to the path where manifest is located. All relative paths in the manifest will use the context of the subfolder where the manifest is defined ## 0.11.1 May 6, 2022 ### Bugfixes * Provides a buildkit update for addressing authentication issues when building images. ## 0.11.0 April 7, 2022 ### Features * Add support for [Okteto Manifest v2](/docs/reference/okteto-manifest.md) * Allow to "Wake" previews from the Okteto UI * Add support for [Buildkit HPA](/docs/self-hosted/helm-configuration.md#buildkit) (Horizontal Pod Autoscaler) ### Improvements * Avoid placing okteto components in overloaded nodes if used in a single node pool * Reduce Buildkit liveness initial delay from 5m to 10s * Add resource quotas to jobs and cronjobs * Migrate cronjobs to use batch/v1 GV as per v1.25 [deprecation guide](https://kubernetes.io/docs/reference/using-api/deprecation-guide/#v1-25). Backwards compatibility still given for kubernetes versions < 1.21. * Display current Okteto version in Admin view * Pipeline installer can deploy from "okteto-compose.yml" files ### Bugfixes * Automatically reload mutation webhook when internal certificates expire * Fix service resource creating with NodePort defined --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. Okteto consists of two products: our [Okteto CLI](/docs/get-started/install-okteto-cli.md) 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](/docs/get-started/install-okteto-cli.md) 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](/docs/reference/okteto-manifest.md) 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](/docs/core/okteto-variables.md), adding [external resources](/docs/tutorials/external-resources.md) into your development environment, and build and push container images to the [Okteto Registry](/docs/core/container-registry.md). For a more comprehensive list of features, check out our [docs](/docs/self-hosted.md). # 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. | --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # 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)**](/docs/byoc/aws.md) * [**Google Cloud Platform (GCP)**](/docs/byoc/gcp.md) ## 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 **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)**](/docs/byoc/aws.md) * [**Google Cloud Platform (GCP)**](/docs/byoc/gcp.md) --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto BYOC on AWS Okteto's Bring Your Own Cloud (BYOC) model allows you to run the Okteto Platform in your own AWS account while still benefiting from a fully managed experience. This guide walks you through the steps to set up your AWS environment so Okteto can securely install and manage the platform. ## Installation Requirements Before you start, ensure the following: * The [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions) is installed and configured (version 2.15 or later) * You have access to an **empty AWS account** dedicated to Okteto BYOC note 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. ## Step 1: Get the AWS IAM Role Assumption External ID Contact your Okteto sales representative to obtain your unique **AWS IAM Role Assumption External ID**. This is required to securely allow Okteto to assume a role in your AWS account. ## Step 2: Create the IAM Role Create a file named `trust-policy.json` with the following content or download it from [here](/docs/byoc/aws/trust-policy.json): trust-policy.json ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "585768156265" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "REPLACEME" } } } ] } ``` Replace `REPLACEME` with the External ID provided by Okteto. Then, create the IAM role using the trust policy we just created with the AWS CLI: ``` aws iam create-role \ --role-name okteto-byoc-integration \ --assume-role-policy-document file://trust-policy.json ``` ## Step 3: Attach the Necessary Policies Attach the necessary policy to give Okteto access to manage infrastructure: ``` aws iam attach-role-policy \ --role-name okteto-byoc-integration \ --policy-arn arn:aws:iam::aws:policy/AmazonEC2FullAccess aws iam attach-role-policy \ --role-name okteto-byoc-integration \ --policy-arn arn:aws:iam::aws:policy/AmazonS3FullAccess aws iam attach-role-policy \ --role-name okteto-byoc-integration \ --policy-arn arn:aws:iam::aws:policy/AWSCertificateManagerFullAccess aws iam attach-role-policy \ --role-name okteto-byoc-integration \ --policy-arn arn:aws:iam::aws:policy/CloudWatchLogsFullAccess aws iam attach-role-policy \ --role-name okteto-byoc-integration \ --policy-arn arn:aws:iam::aws:policy/IAMFullAccess aws iam attach-role-policy \ --role-name okteto-byoc-integration \ --policy-arn arn:aws:iam::aws:policy/AmazonRoute53FullAccess aws iam attach-role-policy \ --role-name okteto-byoc-integration \ --policy-arn arn:aws:iam::aws:policy/AWSLambda_FullAccess aws iam attach-role-policy \ --role-name okteto-byoc-integration \ --policy-arn arn:aws:iam::aws:policy/AmazonAPIGatewayAdministrator ``` Additionally, include the following in-line policies: ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "EKSFullAccess", "Effect": "Allow", "Action": "eks:*", "Resource": "*" }, { "Sid": "KMSFullAccess", "Effect": "Allow", "Action": "kms:*", "Resource": "*" }, { "Sid": "STSFullAccess", "Effect": "Allow", "Action": "sts:*", "Resource": "*" }, { "Sid": "SNSFullAccess", "Effect": "Allow", "Action": "sns:*", "Resource": "*" }, { "Sid": "VisualEditor0", "Effect": "Allow", "Action": "aps:*", "Resource": "*" } ] } ``` ## Step 4: Share the Role ARN With Your Okteto Representative Finally, provide the IAM Role ARN to your Okteto technical representative. They’ll complete the setup and guide you through connecting your cluster to Okteto. ## ✅ What Happens Next Once you've shared the IAM Role ARN with your Okteto sales representative, we'll take it from here. 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. ## ⚠️ 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](/docs/byoc.md#important-cluster-management-restrictions) section in the main BYOC documentation. > Welcome to Okteto BYOC — we're excited to have you on board! --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto BYOC on GCP Okteto's Bring Your Own Cloud (BYOC) model allows you to run the Okteto Platform in your own GCP project while still benefiting from a fully managed experience. This guide outlines the minimal steps required to prepare your Google Cloud environment so Okteto can install and operate the platform. ## 🔧 Setup Requirements Getting started with Okteto BYOC on GCP is simple. You’ll just need to: * Create a **dedicated GCP project** for Okteto to use
(We recommend naming it something like `okteto-byoc`) > This project should be isolated from your production workloads to ensure security and ease of management. ## Step 1: Share the Project Details Once the project is created, contact your Okteto representative and share the following: * The name and ID of your GCP project ## Step 2: Grant Access 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: ``` gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ --member="serviceAccount:OKTETO_SERVICE_ACCOUNT_EMAIL" \ --role="roles/admin" ``` 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. Our team will: * Set up and configure a GKE cluster in your GCP project * Install Okteto into the GKE cluster * 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. ## ⚠️ 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](/docs/byoc.md#important-cluster-management-restrictions) section in the main BYOC documentation. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Core Concepts 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](/docs/core/namespaces.md) 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](/docs/core/credentials/kubernetes-credentials.md) — connect `kubectl` and other tools to your Okteto Namespace * [Personal Access Tokens](/docs/core/credentials/personal-access-tokens.md) — authenticate CLI and API access * [Environment variables](/docs/core/credentials/environment-variables.md) — manage secrets and configuration ### User roles and permissions Okteto uses [role-based access control (RBAC)](/docs/core/user-roles-and-permissions.md) 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](/docs/core/endpoints/automatic-ssl.md) — auto-generated HTTPS endpoints for your services * [Private endpoints](/docs/core/endpoints/private-endpoints.md) — restrict access to internal services ### Divert [Divert](/docs/core/divert.md) 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](/docs/core/okteto-manifest.md) (`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](/docs/core/okteto-variables.md) 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](/docs/core/build-service.md) builds container images remotely and pushes them automatically to Okteto Registry. ### Container registry Each Okteto Namespace has its own space in [Okteto Registry](/docs/core/container-registry.md) to store and pull images. ### Remote Execution [Remote Execution](/docs/core/remote-execution.md) 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](/docs/core/okteto-insights-dashboards.md) tracks build times, deploy frequency, resource usage, and user activity across your cluster. ### Volume Snapshots [Volume Snapshots](/docs/core/use-volume-snapshots.md) let you initialize a persistent volume from a previous snapshot, so you can seed Development Environments with realistic data. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto Build Service Every time you build your images with Okteto, your build is executed in a remote [BuildKit](https://github.com/moby/buildkit) server running in your cluster, deployed automatically by Okteto. The image is also pushed to the [Okteto Registry](/docs/core/container-registry.md). The following image illustrates this process: ![Build flow from Okteto Manifest through okteto build to a remote BuildKit server, which pushes the image to Okteto Registry](/docs/assets/images/buildkit-f5339b2c69537cf1cc499da268346fc4.png) 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. ## 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](/docs/get-started/install-okteto-cli.md)). For example, if your have the following Okteto Manifest: okteto.yaml ``` build: api: context: api dockerfile: Dockerfile args: GO_VERSION: 1.20 ``` The command `okteto build` will build and push the **api** image to the Okteto Registry using the Okteto Build service: ``` okteto build ``` ``` i Using cindy @ okteto.example.com as context i Building 'api/Dockerfile' in tcp://buildkit.okteto.example.com:443... ... ✓ Image 'registry.okteto.example.com/cindy/api:okteto' successfully pushed ``` Read our documentation about the [`build` section](/docs/reference/okteto-manifest.md#build-object-optional) and the [`okteto build` command](/docs/reference/okteto-cli.md#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: ``` # 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. You can configure the [Buildkit cache size and storage class](/docs/self-hosted/helm-configuration.md#buildkit) when installing Okteto to optimize the BuildKit cache behavior. But the Buildkit cache has its own limitations. Even if every Dockerfile instruction is cached, you might wait 1 or 2 minutes until your build context is sent to Buildkit, Buildkit pulls your base image, detects that each Dockerfile instruction can be cached, and push the final image again to the Okteto Registry. Smart Builds is an Okteto's feature designed to solve this problem. For each image you build, Okteto computes a `hash` based on the build context and the rest of build parameters. Okteto uses this hash to detect if the image has been already built by any other developer. If the image was already built, the build is skipped and the previous image is reused almost immediately. Smart Builds are implemented by pushing a tag with the value of the `hash` to the namespace `okteto` in the Okteto Registry. For example, if you build the following image: okteto.yaml ``` build: api: context: api dockerfile: Dockerfile args: GO_VERSION: 1.20 ``` ``` okteto build ``` ``` i Using cindy @ okteto.example.com as context i Building 'api/Dockerfile' in tcp://buildkit.okteto.example.com:443... ... => pushing manifest for registry.okteto.example.com/okteto/api:09f8e ✓ Image 'registry.okteto.example.com/cindy/api:okteto' successfully pushed ``` As you can see in the following image, the image is pushed to `okteto/api:09f8e`: ![Smart Builds computing a content hash from the Okteto Manifest and pushing the image to Okteto Registry](/docs/assets/images/smart-builds-hash-248773177869bc3a2278851cc112769e.png) Also, `cindy/api:okteto` is re-tagged to `okteto/api:09f8e` to remember the last build performed in a given namespace. The following image illustrates this process: ![Smart Builds re-tagging cindy/api:okteto to the shared hash okteto/api:09f8e in Okteto Registry](/docs/assets/images/smart-builds-cindy-c56a5e641cd584409eecaf2df2f27da8.png) If another user, **David**, builds the same image with the same build context and parameters, the same hash `09f8e` is computed. ``` okteto build ``` ``` i Using david @ okteto.example.com as context i Okteto Smart Builds is skipping build of "api" because it's already built ``` Smart builds detects that the tag `okteto/api:09f8e` already exists and skips the build. Instead, the image `david/api:okteto` is re-tagged to `okteto/api:09f8e` to remember the last build performed in the David's namespace: ![Smart Builds skipping a duplicate build and re-tagging david/api:okteto to the existing hash](/docs/assets/images/smart-builds-david-5362c0caee933d6509ebfd343fd12aec.png) ### Prerequisite: Git environment required Smart Builds needs access to a git repository to compute the content hash correctly. It uses more than just the branch and commit; it also inspects diffs, untracked files, and folder content to determine whether a build can be skipped. **Environment variables are not enough:** setting `OKTETO_GIT_BRANCH` or `OKTETO_GIT_COMMIT` manually will not enable Smart Builds without an actual git repository present. **Using Compose or commands in `deploy`:** when your manifest runs Okteto CLI commands that trigger image builds (for example, under `deploy: commands:` running `okteto deploy -f compose.yml`), ensure the `.git` directory is not excluded by `.oktetoignore`. Otherwise, Smart Builds cannot access git metadata and will fall back to a full build. ### Limitations with explicit image tags Smart Builds are automatically disabled when you explicitly define the `image` field with a custom tag in your build configuration. Smart Builds work by generating a SHA based on your git repository status and using that SHA as the image tag. When you specify your own image tag, Smart Builds cannot determine if the build should be skipped. **Examples that will NOT use Smart Builds:** ``` build: api: # Explicit image tag disables Smart Builds image: "registry.okteto.example.com/${OKTETO_NAMESPACE}/movies-api:custom" context: api dockerfile: Dockerfile ``` **Examples that WILL use Smart Builds:** ``` build: api: # No image field specified - Smart Builds enabled context: api dockerfile: Dockerfile args: GO_VERSION: 1.20 ``` ## Skipping Smart Builds behavior You can force the build of your images and skip the Smart Build optimization by running the following command: ``` okteto build --no-cache ``` ``` i Using cindy @ okteto.example.com as context i Building 'api/Dockerfile' in tcp://buildkit.okteto.example.com:443... ... => pushing manifest for registry.okteto.example.com/okteto/api:09f8e ✓ Image 'registry.okteto.example.com/cindy/api:okteto' successfully pushed ``` The `--no-cache` flag will also disable the Buildkit local cache. You can also disable Smart Builds by setting the environment variable `OKTETO_SMART_BUILDS_ENABLED=false`. If you define `OKTETO_SMART_BUILDS_ENABLED=false` as an [Admin Variable](/docs/admin/dashboard.md#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](/docs/self-hosted/manage/buildkit-high-performance.md#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](/docs/admin/build-service.md). ### 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 The following environment variables can be useful for handling timeouts from the Okteto CLI when communicating with the Okteto Build Service. You can configure them as [Admin Variables](/docs/admin/dashboard.md#admin-variables) if needed: * `OKTETO_KEEPALIVE_CLIENT_TIME_MS`: After this duration of time, if the client doesn't see any activity it will ping the server to see if the transport is still alive. If set below 10s, a minimum value of 10s will be used (default value is infinity.) * `OKTETO_KEEPALIVE_CLIENT_TIMEOUT_MS`: After sending a keepalive ping, the client waits for this duration of time and if no activity is seen even after that the connection is closed. (default value is 20 seconds.) * `OKTETO_KEEPALIVE_CLIENT_PERMIT_WITHOUT_STREAM`: If `true`, the client sends keepalive pings even with no active RPCs. If `false`, when there are no active RPCs, Time and Timeout will be ignored and no keepalive pings will be sent (defaults to `false`.) --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto Registry The Okteto Registry allows every Okteto Namespace to have its own space to store its container images. ## Push container images to the Okteto Registry The recommended way to use the Okteto Registry is by [installing and configuring the Okteto CLI](/docs/get-started/install-okteto-cli.md). The Okteto CLI is automatically configured to interact with the Okteto Registry. For example, if your have the following Okteto Manifest: okteto.yaml ``` build: api: context: api ``` The command `okteto build` will build and push the **api** image to the Okteto Registry: ``` okteto build ``` ``` i Using cindy @ okteto.example.com as context i Building 'api/Dockerfile' in tcp://buildkit.okteto.example.com:443... ... ✓ Image 'registry.okteto.example.com/cindy/movies-with-helm-api:okteto' successfully pushed ``` The final image name depends on the Okteto Registry URL, your current namespace, the name of your development environment and the name of your image in the Okteto Manifest. But you don't need to remember the image names, you should access them using the following environment variables: * **api**: `OKTETO_BUILD_API_IMAGE` * **frontend**: `OKTETO_BUILD_FRONTEND_IMAGE` Read more about the available environment [variables to access your images here](/docs/core/okteto-variables.md#built-in-environment-variables-for-images-in-okteto-registry). ## Pull container images from the Okteto Registry Any image pushed into the Okteto Registry is private. You'll need to authenticate with the registry before pulling an image. Namespaces in Okteto are automatically allowed to pull images that belong to their namespace automatically. If your application uses images from the Okteto Registry, it'll be able to pull container images without any extra configuration. ## Push Helm chart to the Okteto Registry You can push Helm charts to the Okteto Registry, but this process isn't integrated with the Okteto CLI. The first step is to log in to the Okteto Registry where you want to push the Helm chart. For this you will need some credentials that you can obtain by executing the `okteto context show --include-token` command. This command will show you information about the current okteto context in use: ``` { "name": "https://okteto.example.com", "id": "3cf4529c-1gbd-4364-99cf-3f4bbe499adb", "username": "cindy", "token": "i3kDEh4FKqrJzY7e7Qamd8CfTTrjkPOTN5ftHoKl", "namespace": "cindy", "builder": "tcp://buildkit.okteto.example.com:1234", "registry": "registry.okteto.example.com", "personalNamespace": "cindy", "isOkteto": true } ``` You can retrieve your username, password (token), and the domain for your registry from the output. You can also use the environment variables `OKTETO_USERNAME`, `OKTETO_TOKEN`, `OKTETO_NAMESPACE` and `OKTETO_REGISTRY_URL` if your script is running as part of the `deploy` commands of your Okteto Manifest. For example: okteto.yaml ``` deploy: - helm registry login ${OKTETO_REGISTRY_URL} -u ${OKTETO_USERNAME} -p ${OKTETO_TOKEN} ``` Once you are logged in you will need to package the chart. okteto.yaml ``` deploy: - helm package ./chart ``` After that you can push the packaged Helm chart to the registry. okteto.yaml ``` deploy: - helm push ./movies-api-0.1.0.tgz oci://${OKTETO_REGISTRY_URL}/${OKTETO_NAMESPACE} ``` ## Pull Helm chart to the Okteto Registry Once the packaged chart has been pushed to the Okteto Registry, you can pull it by using the command below: okteto.yaml ``` deploy: - helm registry login ${OKTETO_REGISTRY_URL} -u ${OKTETO_USERNAME} -p ${OKTETO_TOKEN} - helm pull oci://${OKTETO_REGISTRY_URL}/${OKTETO_NAMESPACE}/movies-api --version 0.1.0 ``` --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Environment Variables Environment Variables provide another way to specify your credentials. This is the recommended method when scripting tasks or when [creating Preview Environments](/docs/previews.md). The supported environment variables are: * `OKTETO_TOKEN`: Specifies the [Personal Access Token](/docs/core/credentials/personal-access-tokens.md) or [Admin Access Token](/docs/admin/dashboard.md#admin-access-tokens) to use (Required) * `OKTETO_CONTEXT`: Specifies the Okteto URL (Required) * `OKTETO_NAMESPACE`: Specifies the Namespace to use. If missing, it defaults to the Namespace of the current context (Optional) tip You can use the `.env` file to store your credentials. See [Okteto Variables](/docs/core/okteto-variables.md) to learn more. ## Reserved Variables Certain variable names are reserved for use by the Okteto Platform only. These reserved variables can be used within the supported settings mentioned above but should not be used outside of them. This applies to: * Admin Variables * User Variables * Catalog Variables * Variables defined at deployment time The reserved variable names are: * `OKTETO_NAMESPACE` * `OKTETO_CONTEXT` * `OKTETO_TOKEN` * `OKTETO_URL` --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Download your Kubernetes credentials This section explains how to download your Kubernetes credentials and start developing your applications in Okteto with your favorite CLI tools. The first thing you need to do is install the Okteto CLI and ensure the executable is in your PATH. This is needed because the kubeconfig provided by Okteto uses a [credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins) to authenticate access your Kubernetes cluster. It is a common 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. If this is your first time using the Okteto CLI, install it following [this guide](/docs/development/using-okteto-cli.md). After completing those steps, the Okteto CLI should be in your PATH. 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: ``` $ okteto context use https://okteto.example.com ``` ``` Authentication will continue in your default browser ✓ Context 'okteto.example.com' created ``` If you're not logged into Okteto yet, it will also run the login sequence. Now that you have installed Okteto CLI and it is connected to your Okteto instance, you can download the Kubernetes credentials. There are two different ways of doing so: * Download your Kubernetes credentials [using the Okteto CLI](#download-your-kubernetes-credentials-using-the-okteto-cli). * Download your Kubernetes credentials [from the Okteto dashboard](#download-your-kubernetes-credentials-from-the-okteto-dashboard). ## Download your Kubernetes credentials using the Okteto CLI Having your Okteto context configured to access Okteto, run the following command: ``` $ okteto kubeconfig ``` ``` Updated kubernetes context 'okteto_example_com/cindy' in '/Users/cindy/.kube/config' ``` The `okteto kubeconfig` command adds your Kubernetes credentials to your kubeconfig file, and sets it as the current Kubernetes context. Once you do this, you'll have full access to your Kubernetes namespace with `kubectl`, `helm` or any other CLI tool. ## Download your Kubernetes credentials from the Okteto dashboard From the Okteto dashboard you should also find your credentials in the `Settings > Setup` section. Once downloaded, point your `KUBECONFIG` environment variable to the credentials file: * MacOS / Linux * Windows ``` $ export KUBECONFIG=$HOME/Downloads/okteto-kube.config:${KUBECONFIG:-$HOME/.kube/config} ``` ``` > $Env:KUBECONFIG=("$HOME\Downloads\okteto-kube.config;$Env:KUBECONFIG;$HOME\.kube\config") ``` To see that the new configuration is working, enter this command: ``` $ kubectl get all ``` ``` No resources found. ``` ## Using your Kubernetes credentials Once you've downloaded your credentials, you'll have full access to your Kubernetes namespaces on Okteto directly from your terminal, using the tools you're already familiar with, such as `helm`, `kubectl`, `okteto` or `skaffold`. For example, you could use `kubectl` to deploy our `hello-world` application: ``` kubectl apply -f https://raw.githubusercontent.com/okteto/go-getting-started/master/k8s.yml ``` [Credential plugins](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins) are a way of managing Kubernetes cluster credentials in a more secure way as you get time-bound tokens for your service account instead of using auto-generated secret-based ones. If you prefer to use static, auto-generated tokens you can do so by setting the environment variable `OKTETO_USE_STATIC_KUBETOKEN` to `true` before running any Okteto command. Be aware that using static tokens is not recommended by Kubernetes and you will receive warnings in your `kubectl` output from version `1.27` onward encouraging you to stop using them. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Personal Access Tokens You can use Personal Access Tokens instead of OAuth to authenticate with Okteto. They're especially useful for scripting. **Important**: For shared automations, like [Preview Environments](/docs/previews.md), it's recommended that you use [Admin Access Tokens](/docs/admin/dashboard.md#admin-access-tokens). They're created in the same way as described here, but through the [Admin dashboard](/docs/admin/dashboard.md#admin-access-tokens). ### Creating a Personal Access Token 1. Navigate to the Okteto Dashboard 2. Click on the **Settings** icon on the navigation bar at the left. 3. Click on the **New Token** button. ![Personal Access Tokens settings page listing tokens with Renew and Delete actions](/docs/assets/images/tokens-new-sidebar+1.32-befd0e3f50a81d1a15d1b3b13728e023.png) 4. Give your token a descriptive name, select the expiration, and click the **Generate** button. ![New Token dialog with name and expiration dropdown fields](/docs/assets/images/tokens-name-9c769f61a6e462f039f5fb272476fd9b.png) 5. Copy the token to your clipboard. For security reasons, after you navigate off the page, you will not see the token again. ![New Token dialog showing the generated token value with a Copy button](/docs/assets/images/tokens-copy-4b005f041fe80658a0226c733f94a2de.png) warning Treat your tokens like passwords and keep them secret. Always use tokens as environment variables instead of hardcoding them into your programs. ### Token Expiration When you create a token, you can select the expiration, the default expiration is 180 days. Once a token has expired, it can no longer be used to authenticate or for API requests. It is not possible to restore an expired token, you will need to create a new token upon expiration. A banner will be displayed a week before your token expires to remind you of this. We recommend that you take the appropriate measures once you see this banner in order to prevent any potential disruptions. ![tokens expiration banner](/docs/assets/images/tokens-expiration-banner-sidebar+1.32-5bfe11d65f38c8ae7682ab44874d1c3a.png) The state and expiration date of every token will be displayed in the UI. ![tokens expiration banner](/docs/assets/images/tokens-expiration-list+1.32-f980535e4e766b9d70c02859ef4f4742.png) ## Using a Token on the Command Line Once you have a token, you can use it to authenticate with the [Okteto CLI](/docs/reference/okteto-cli.md) instead of using your browser, as shown below: ``` $ okteto context use https://okteto.example.com --token $YOUR_TOKEN ``` Personal Access Tokens can also be used when setting the `OKTETO_TOKEN` environment variable. ``` $ export OKTETO_TOKEN=xxxxxxx $ okteto namespace create test-cindy ``` ### Revoking a Personal Access Token 1. Sign in to your Okteto account. 2. Click on the **Settings** icon on the left tab. 3. Click on the **Personal Access Tokens** sidebar item. 4. Click on the **Delete** button. ![Personal Access Tokens settings page highlighting the Delete button on a token](/docs/assets/images/tokens-new-sidebar+1.32-befd0e3f50a81d1a15d1b3b13728e023.png) 5. Click on the **Delete Token** button to confirm that you want to delete your token. ![confirm token deletion](/docs/assets/images/tokens-delete-confirm-e61160d95d8ec41043a0169c88bb898b.png) Once deleted, the token is automatically revoked, and it can't be recovered. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Divert 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 ### 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: **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](/docs/self-hosted/install/divert.md) 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:** ``` // Extract from incoming request const baggage = req.headers['baggage']; // Include in outgoing requests fetch('http://catalog-service/api/movies', { headers: { 'baggage': baggage } }); ``` **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:** ``` // 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](/docs/development/using-divert.md) for detailed patterns. ## Next Steps * **[Using Divert](/docs/development/using-divert.md)** - Implementation details, manifest configuration, and code patterns * **[Divert Tutorial](/docs/tutorials/divert.md)** - Step-by-step getting started guide * **[Manifest Reference](/docs/reference/okteto-manifest.md#divert)** - Complete configuration options * **[Self-Hosted Configuration](/docs/self-hosted/install/divert.md)** - Admin setup for Divert drivers --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Automatic SSL endpoints Okteto streamlines the development process by automatically adding endpoints to the CLI and UI for services that are running. Simply add the specified annotation to your service's manifest, and Okteto will automatically handle the endpoint creation. If you've configured Endpoints but they aren't appearing, please check our [FAQ guide](/docs/reference/faqs.md#why-are-my-endpoints-not-present-in-the-cli-or-ui) for possible reasons why they might be missing. ## Auto create ingresses from services Okteto can automatically create an SSL endpoint for your deployments. In order to take advantage of this feature, add the `dev.okteto.com/auto-ingress: "true"` annotation to your Service definition. ``` apiVersion: v1 kind: Service metadata: name: hello-world labels: app: hello-world annotations: dev.okteto.com/auto-ingress: "true" spec: type: ClusterIP ports: - port: 8080 protocol: TCP targetPort: 8080 selector: app: hello-world ``` tip A sample of how this should look [is available here](https://github.com/okteto/go-getting-started/blob/master/k8s.yml#L26). Adding this annotation will tell Okteto to automatically create an https ingress rule for you that redirects to the first http port of your service. `NodePort` or `LoadBalancer` services are managed as if they had this annotation too. You can disable this behavior by setting [`convertLoadBalancedServices.enabled`](/docs/self-hosted/helm-configuration.md#convertloadbalancedservices) to `false`. You can see the address of your endpoint by going to the Okteto dashboard or by running the `okteto endpoints` command. The endpoint address will be consistent across redeploys, as long as you don't change your service name. ## Bring your own ingress You can also use your own ingress manifests. This is useful when you have more complex configurations, or you need specific URLs. Keep in mind that all the hosts you use in your ingress must end with`-$NAMESPACE.okteto.example.com`. ### Let Okteto generate the host Okteto can automatically inject the right host names during the creation of your ingresses, while leaving the rest of the configuration intact. In order to take advantage of this feature, add the `dev.okteto.com/generate-host: "true"` annotation to your Ingress definition. ``` apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: hello-world annotations: dev.okteto.com/generate-host: "true" spec: rules: - http: paths: - path: / pathType: Prefix backend: service: name: hello-world port: number: 8080 ``` We recommend you follow this option. This way your ingress configuration can be deployed on any namespace managed by Okteto. ## Customizing the endpoints shown in the Okteto dashboard Okteto provides additional annotations that enable you to customize the endpoints shown in the Okteto dashboard. To hide specific endpoints from the Okteto dashboard, you can use the `dev.okteto.com/hide-from-ui: "true"` annotation. Simply apply this annotation to your `Ingress` or `VirtualService` resource, and the endpoints associated with that resource will not be displayed in the Okteto dashboard. If you want to replace the default endpoints for an `Ingress` or `VirtualService` resource, you can use the `dev.okteto.com/endpoints` annotation. This annotation allows you to define a list of endpoints, separated by commas, that will replace the default endpoints. Additionally, the value of this annotation expands the `OKTETO_NAMESPACE` and `OKTETO_DOMAIN` environment variables, providing an easy way to make your endpoints portable between namespaces. * Kubernetes * Compose ``` apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: movies annotations: dev.okteto.com/generate-host: "true" dev.okteto.com/endpoints: https://movies-${OKTETO_NAMESPACE}.${OKTETO_DOMAIN}/api spec: rules: - http: paths: - path: / pathType: Prefix backend: service: name: frontend port: number: 80 - path: /api pathType: Prefix backend: service: name: api port: number: 8080 ``` ``` version: "3" services: frontend: build: frontend ports: - 80:80 backend: build: backend ports: - 8080 endpoints: labels: dev.okteto.com/endpoints: https://movies-${OKTETO_NAMESPACE}.${OKTETO_DOMAIN}/api rules: - path: / service: frontend port: 80 - path: /api service: backend port: 8080 ``` ## Expose HTTPS Backends Through Ingress If your application communicates over HTTPS instead of HTTP, you'll need to create a dedicated ingress, as demonstrated in the [Bring Your Own Ingress](#bring-your-own-ingress) section, and add the following annotation to it: ``` apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" ... ``` Please note that this won't pass through the certificate served by your application to the requester. Instead, the wildcard certificate of the Okteto instance will be used. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Private endpoints Okteto allows you to restrict access to your application by marking its endpoints as private. Private endpoints can only be accessed by Okteto users who have access to your Okteto namespace, and they'll need to provide their credentials before being granted access. Private endpoints can be identified by the lock icon in the Okteto dashboard: ![private endpoints UI](/docs/assets/images/private-endpoints+1.32-abe0446ed20189152339b1d9e115d7bd.png) ## Enable Private Endpoints for your Application * Kubernetes * Docker Compose Add the annotation below to your service's manifest to make your application's endpoints private: ``` metadata: annotations: dev.okteto.com/auto-ingress: "private" ``` Using this annotation will tell Okteto to create a private http ingress rule for your application. Full example: ``` apiVersion: v1 kind: Service metadata: name: hello-world labels: app: hello-world annotations: dev.okteto.com/auto-ingress: "private" spec: type: ClusterIP ports: - port: 8080 protocol: TCP targetPort: 8080 selector: app: hello-world ``` note Private Endpoints generated this way follow the same rules and restrictions than [Automatic SSL Endpoints](/docs/core/endpoints/automatic-ssl.md). **Advanced Scenarios** You can also use this feature with your own ingresses. This is useful when you have more complex configurations, or when you only want to protect a subset of your application's endpoints. Add the annotation below to your ingress' manifest to make your application's endpoints private: ``` metadata: annotations: dev.okteto.com/private: "true" ``` Full example: ``` apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: hello-world annotations: dev.okteto.com/private: "true" spec: rules: - http: paths: - path: / pathType: Prefix backend: service: name: hello-world 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: * A first ingress with the routes for all the public endpoints * A second ingress, with the `dev.okteto.com/private` annotation, for all your private routes. Private Endpoints is one of the extensions that Okteto added to [Docker Compose](/docs/reference/docker-compose.md) to make it easier to develop cloud-native applications. You can enable private endpoints by adding the `dev.okteto.com/private: "true"` label to your service: ``` name: hello-world services: hello-world: labels: dev.okteto.com/private: "true" image: nginx ports: - 8080:8080 ``` **Advanced Scenarios** You can also define this at the `endpoint` level if needed. ``` name: hello-world endpoints: annotations: dev.okteto.com/private: "true" rules: - path: / service: hello-world port: 8080 services: hello-world: image: nginx expose: - 8080 ``` ## Restrictions Private Endpoints use your Okteto account for authentication, so they're best suited to protect endpoints that you and your team will access via the browser. They're not recommended for automation, or to protect endpoints that will be accessed by your end users. Private Endpoints only restrict external access to your applications. Applications running in your namespace will be able to access your private endpoints without authentication by using the `service` name. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto Namespaces Namespaces in Okteto offer a flexible way to organize your Development Environments. A Namespace can last for a few weeks for developing a feature, or a couple days for a bug fix. Not only do Namespaces give you an individual separation of context while you are working, but you can also use shared Namespaces to collaborate with you team before anyone pushes to git. In Okteto, Namespaces are categorized into two types: * ### Personal Namespaces: Automatically generated for each user, this Namespace is uniquely named after the user's username or email, ensuring a personalized environment. These cannot be deleted, but their resources can be destroyed allowing the Namespace to be reused. * ### Non-Personal Namespaces: These are additional Namespaces created by users or through automation, facilitating broader project collaboration and management. They may be deleted or transferred to other users. The Okteto Dashboard enables you to independently create, launch, and share Namespaces for yourself and your team. ## Manage your Namespaces 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. ![new namespace dialog](/docs/assets/images/new-namespace+1.32-bad8858049f5961e3a6f9958fb63d52c.png) tip As a common pattern, you might name your Namespace by feature number, ticket number, or something similar. Development Environments in Namespaces are pulled from git branches, which is why you may want to be running multiple Namespaces at the same time. The Okteto Admin Dashboard allows you to easily create, [sleep](/docs/admin/cleanup.md#manually-sleeping-resources), and [wake up](/docs/admin/cleanup.md#manually-wake-sleeping-resources) your Namespaces with a simple click. Specifically, you can use the Sleep and Wake dialogs for controlling your Namespace's state. If you prefer to use the command line, here are the Namespace management options available: * Create a Namespace with `okteto namespace create` * Set your kubectl configuration to use your Namespace with `okteto kubeconfig` * Delete a non-personal Namespace using `okteto namespace delete` * [Sleep](/docs/admin/cleanup.md#manually-sleeping-resources) or [wake up](/docs/admin/cleanup.md#manually-wake-sleeping-resources) your Namespace with `okteto namespace sleep [name]` and `okteto namespace wake [name]` commands respectively tip Administrators can specify a global, default threshold for automatically sleeping a Namespace in the [garbage collection](/docs/self-hosted/helm-configuration.md#gc) configuration. ## Sharing and Collaboration with Namespaces By default, you'll be the only person with access to your Namespaces. Invite your teammates to enable true real-time collaboration. Each user is able to collaborate together on an application within a Development Environment all before any code is ever pushed. Test better together. 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). ![share a Namespace](/docs/assets/images/share+1.32-fc41781eb648ee36b751c40dd00a86b3.png) In the `Share` dialog, type the email address of the team members you want to share this Namespace with. Once you press save, Okteto will update the necessary permissions and notify your teammates via email. ## Viewing Resource Metrics and Recommendations ### Resource Metrics View With the addition of Resource Manager, there is a new “Metrics” tab in the Okteto Dashboard Namespace view. To access it, navigate to a Namespace, select a Development Environment’s Resource in the sidebar, and click on the Metrics tab below the endpoints. This view provides detailed insights into the resource usage and performance of your Kubernetes workloads. The Metrics tab is available for core resources, including Deployments, StatefulSets, Jobs, CronJobs, and Pods. If the Resource Manager is not enabled, the Metrics tab will display basic Storage and Pod metrics, along with a CLI guide to view metrics in real-time. #### Metrics Tab View with Resource Manager Set to “Automatic” * **Average CPU and Memory Usage**: When set to Manual, the Resource Manager displays optimization recommendations for resource requests. These may suggest adjustments, such as increasing or decreasing CPU and memory requests based on observed usage patterns. ![resource manager metrics tab with automatic mode](/docs/assets/images/resource-manager-metrics+1.32-18a03df66ce5c64a115a199d74ce880a.png) #### Metrics Tab View with Resource Manager Set to “Manual” * **Resource Manager Recommendations**: If the Resource Manager identifies opportunities for optimizing resource requests, it will display a recommendation. These recommendations might include increasing or decreasing CPU and memory requests based on the actual usage patterns. ![Resource Manager Namespace Metrics](/docs/assets/images/resource-manager-metrics-manual+1.32-074bc502b0981796a2f27f409950c531.png) ## Namespace Administration The Okteto platform will take care of all the required [RBAC roles and bindings](/docs/core/user-roles-and-permissions.md), resources [quotas](/docs/self-hosted/helm-configuration.md#quotas) and limits, and [network policies](/docs/self-hosted/helm-configuration.md#networkpolicies) so everyone in your team can safely deploy and develop applications in Kubernetes. Through the Okteto Dashboard, Admins can perform all operations on any Namespace within the Okteto platform. This includes: * Deleting, sharing, waking, sleeping, and marking Namespaces as persistent * Deploying or deleting applications using both Okteto and `kubectl` * Accessing all resources and sub-resources within any Development Environment * [Transferring Namespace ownership](/docs/core/namespaces.md#transfer-namespace-ownership) between developers * Admins can fine tune a Developer access to Namespaces by configuring [the `serviceAccounts` section within the Okteto Helm configuration](/docs/self-hosted/helm-configuration.md#serviceaccounts). * Configure cpu, memory, pods and storage quotas for each Namespace using [the `quotas` section within the Okteto Helm configuration](/docs/self-hosted/helm-configuration.md#quotas). ### Transfer Namespace Ownership Okteto administrators have the ability to transfer non-personal Namespaces between users. This process can be achieved through the Okteto UI and can be helpful for when you need to manually remove resources from an inactive user. Personal Namespaces that are tied to a user are unable to be transferred. To transfer a Namespace to a new owner, go to the **Okteto Dashboard -> Admin -> Namespaces** under Cluster Management, then locate the Namespace that you would like to transfer. Click on the three dots `...` to display the Namespace menu. From the Namespace menu select `Transfer Ownership`. ![transfer a Namespace](/docs/assets/images/namespace-transfer-owner+1.42-993aadb414ef193ba0a9669b25bfbc98.png) When the Transfer Ownership modal appears, type the email address of the team member who you'd like the transfer the Namespace to. Once you press confirm, ownership of that Namespace will be immediately transferred. If you wish, you can keep the current owner as a member of the Namespace by selecting the option in the Transfer Ownership modal. If this is not selected the current owner will immediately lose access. ![Select a new Namespace owner](/docs/assets/images/namespace-transfer-modal-43dfda0db0b8da5e18c188c95b1d9258.png) note User specific variables will not transfer along with a Namespace. If the Namespace being transferred has user specific variables, please note that future build or destroy actions may fail. 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](/docs/core/okteto-variables.md). ### Mark a Namespace as Persistent to Prevent it from Sleeping and Deletion 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](/docs/self-hosted/helm-configuration.md#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 mark as persistent. Click on the three dots `...` to display the Namespace menu. From the Namespace menu select `Persistent`. ### Garbage collection settings The [Okteto Garbage Collector](/docs/self-hosted/helm-configuration.md#gc) service can automatically scale down [idle applications](/docs/admin/cleanup.md#what-counts-as-activity) and delete unused Namespaces for optimal cost savings and resource management. Please see our [resource cleanup guide](/docs/admin/cleanup.md) to see the management options available and how to configure them. ### Configure Namespace Quotas Administrators can manage resource allocation by setting [quotas](/docs/self-hosted/helm-configuration.md#quotas) for each Namespace. These quotas limit the maximum resources that can be used per Namespace. When enabled, the Okteto dashboard displays the following quotas on the Namespace view: ![Namespace quotas](/docs/assets/images/quotas-38dd3bff43e3d6836d7dd41c2961acbc.png) * **CPU**: Configured with `quotas.requests.cpu`. Limits the total cpu resource requests per Namespace. * **Memory**: Configured with `quotas.requests.memory`. Limits the total memory resource requests per Namespace. * **Storage**: Configured with `quotas.requests.storage`. Limits the total volume storage per Namespace. * **Pods**: Configured with `quotas.resources.maxPods`. Limits the total number of pods per Namespace. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto Insights Dashboards Okteto Insights Dashboards offer visibility into the performance and health of your applications and the infrastructure running on Okteto. These dashboards provide valuable insights into your Okteto cluster, including its overall health, trends in build and deploy times, and user activity on the platform. Analyzing this data helps you better understand and optimize both the performance of your applications and the underlying infrastructure. Whether you’re looking to proactively identify bottlenecks, fine-tune resource allocation, or ensure that your applications are running smoothly, these dashboards provide the key data you need to make informed decisions. ![Okteto Insights Dashboard Example](/docs/assets/images/insights-dashboard-landing-d3ff649b5fdc0658329c8a7084a5dd59.png) *** ## Dashboards Available Okteto provides the following dashboards out of the box: * [Dashboards Available](#dashboards-available) * [Activity Dashboard](#activity-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) * [Pods Dashboard](#pods-dashboard) * [Test Dashboard](#test-dashboard) * [Consuming Insights metrics from other tools](#consuming-insights-metrics-from-other-tools) *** ### Activity Dashboard The Activity dashboard provides metrics to help you track platform adoption and usage across your organization. **Key Metrics:** * Total active users * `okteto up` sessions * Active namespaces and preview environments ![Okteto Activity Insights Dashboard](/docs/assets/images/insights-activity-dashboard-4d12f018439d9445af60bfacde9f1fd7.png) *** ### Build Service Dashboard Analyzes the [Okteto Build Service](/docs/core/build-service.md) 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:** * Total number of replicas for BuildKit pods * Total active builds across all BuildKit pods ![Okteto Build Service Insights Dashboard](/docs/assets/images/insights-build-service-dashboard-9b467150f6f9f3b08e5d14071cadd875.png) **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 Service BuildKit Pod Performance Dashboard](/docs/assets/images/insights-build-service-pods-dashboard-b7dc96eacb4872fc452d470d4dd2f167.png) *** ### Cluster Nodes Dashboard The Cluster Nodes dashboard provides a high-level overview of your cluster nodes' utilization, with a focus on CPU and memory usage. It also can assist in evaluating if the CPU and memory requests of your pods align with actual usage. Pods under-utilizing their CPU/memory requests leads to wasted infrastructure, while Pods exceeding their CPU/memory requests can result in CPU throttling, pod evictions, or unbalanced workloads across the cluster. **Why Use This Dashboard?** * Detect over/under-provisioning of cluster resources * Identify CPU/memory inefficiencies * Ensure workload balancing across nodes ![Okteto Cluster Nodes Insights Dashboard](/docs/assets/images/insights-cluster-nodes-dashboard-65ba6ace31d700929fc22940a3cd4d60.png) *** ### 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](/docs/assets/images/insights-images-dashboard-2e9fee3f7f5cfe3201b23f9432db01e6.png) *** ### Deploy Dashboard The Deploy dashboard helps you analyze the evolution of application deployments, focusing on both duration and error rates. **Key Metrics:** * Deployment duration * Error rate trends **Filter Options:** * **Development Environment** – Select specific Okteto environments to display data for ![Okteto Deploy Insights Dashboard](/docs/assets/images/insights-deploy-dashboard-b429b4c6a39bbbfe4e93b06734e13587.png) *** ### Namespace Dashboard The Namespace Dashboard provides an overview of the CPU and Memory resources consumed per Namespace, helping you monitor and optimize the performance of specific applications or Development Environments. **CPU and Memory Utilization** The graphs track CPU and memory usage, showing: * **CPU Requests vs. Usage**: This shows the trends between requested CPU resources and actual usage. Monitoring discrepancies between the two can help identify over-allocated or under-utilized resources. * **Memory Requests vs. Usage**: This shows the trends between memory requests and actual memory consumption. Understanding these trends helps optimize memory allocation. **Pro Tip:** Use the [Resource Manager](/docs/admin/resource-manager.md) to automate resource balancing. **Pods** The Pods section displays the number of Pods active in the namespace over time, helping you correlate spikes in resource usage with changes in the number of running Pods. **Filter Options** * **Namespace**: The name of the Okteto Namespace to display specific data for ![Okteto Namespace Insights Dashboard](/docs/assets/images/insights-dashboard-namespace-035c0efab6ffca7266b8a84bb3b4bcb4.png) *** ### Nodes Dashboard The Nodes dashboard offers a high-level overview of each cluster node's utilization, focusing on CPU and memory usage. **Key Use Cases:** * Troubleshoot performance issues on specific nodes * Validate workload distribution across nodes **Filter Options** * **Node Name**: The name of the Kubernetes node to display specific data for ![Okteto Nodes Insights Dashboard](/docs/assets/images/insights-nodes-dashboard-d7665b06550211b5429e8d2a2047a4d8.png) *** ### Pods Dashboard The Pods dashboard shows usage information related to each Kubernetes Pod. **Use This Dashboard To:** * Monitor CPU/memory consumption at the pod level * Detect performance issues like memory leaks **Filter Options:** * **Namespace**: The name of the Okteto Namespace to display specific data for, filtered by the selected Development Environment * **Development Environment**: The specific Okteto Development environment to display data for ![Okteto Pods Insights Dashboard](/docs/assets/images/insights-pods-dashboard-86491f1fe59e48b3dc97c8f84ad3973f.png) *** ### Test Dashboard The Test dashboard helps you analyze the evolution of Okteto Test runs, focusing on the average duration it takes for a test to complete successfully. **Key Metrics:** * Average test duration * Success/failure trends **Filter Options** * **Development Environment**: The specific Okteto Development environment to display data for * **Test** to specify the name of the Test Container to display data for ![Okteto Test Insights Dashboard](/docs/assets/images/insights-test-dashboard-13613adbbd8a64ab479c3b9f28f6729b.jpg) *** ## Consuming Insights metrics from other tools You can consume Okteto Insights metrics through external tools.
Check out our [Okteto Insights Admin Documentation](/docs/admin/okteto-insights.md) for more details. For a deeper look at how these dashboards are built, explore our [open-source repository](https://github.com/okteto/insights-dashboards) and learn about the [data available](/docs/admin/okteto-insights.md#what-data-is-available). --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto Manifest Overview The Okteto Manifest is how you configure the behavior for building, deploying, testing, and developing your application in Okteto. These are the main sections of the Okteto Manifest: | Section | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | [build](#build) | Configure a list of images to build for your application | | [dependencies](#dependencies) | Configure a list of git repositories to deploy as part of your application | | [deploy](#deploy) | Configure a list of commands to deploy your application. You can also refer to [Docker Compose](/docs/reference/docker-compose.md) files | | [destroy](#destroy) | Configure a list of commands to destroy your application | | [dev](#dev) | Configure a list of Development Containers to define how `okteto up` works when you are iterating on your application | | [external](#external) | Configure a list of External Resources that exist outside of the Kubernetes cluster (e.g. cloud resources, dashboards). | | [test](#test) | Configure a list of Test Containers to define how [`okteto test`](/docs/testing.md) runs tests for your application | There are other sections to help you build your ideal development experience in Okteto, but this document focuses solely on introducing you to the core concepts of the Okteto Manifest. You can learn more about the other Okteto Manifest options in the [manifest reference](/docs/reference/okteto-manifest.md). ## Build This section contains the instructions for Okteto to build the images for each service of your application. Your `build` section might look like this: ``` build: api: context: api frontend: context: frontend dockerfile: Dockerfile secrets: 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. 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](/docs/reference/okteto-manifest.md#build-object-optional) and how [Okteto Build works](/docs/core/build-service.md). ## Dependencies This section tells Okteto to deploy a list of git repositories as part of the deployment of your application. Your `dependencies` section might look like this: ``` dependencies: mongodb: repository: https://github.com/okteto/mongodb wait: true ``` In this sample the `dependencies` section instructs Okteto to deploy the repo and wait until its resources are available before running the commands in the `deploy` section of the Okteto Manifest. You can learn more about the `dependencies` section [here](/docs/reference/okteto-manifest.md#dependencies-string-optional). ## Deploy This section tells Okteto how to deploy your application. It typically uses a combination of `helm`, `kubectl`, and `okteto` commands. All the resources created by these commands will appear in the Okteto UI as part of a single Development Environment that represents the whole of your application. note If you have external resources you'd like to configure and show within the Okteto development environment, you must configure those in the [external](#external) section. Your `deploy` section might look like this: ``` deploy: - name: Deploy PostgreSQL command: helm upgrade --install postgresql postgresql/postgresql-11.6.21.tgz -f postgresql/values.yml --version 11.6.21 - name: Deploy Frontend command: helm upgrade --install frontend frontend/chart --set image=${OKTETO_BUILD_FRONTEND_IMAGE} - name: Deploy API command: helm upgrade --install api api/chart --set image=${OKTETO_BUILD_API_IMAGE} --set load=${API_LOAD_DATA:-true} ``` In this sample the `deploy` section instructs Okteto to execute three commands: deploy a postgresql database, deploy the `frontend` helm chart (referring the `frontend` image using an environment variable), and deploy the `api` chart (referring the `api` image using an environment variables). Refer to our documentation to learn more about [the `deploy` section](/docs/reference/okteto-manifest.md#deploy-string-optional). info Okteto recommends that you enable [Remote Execution](/docs/core/remote-execution.md) for your deploy commands ## Destroy This section tells Okteto how to destroy your application. The Okteto CLI command `okteto destroy` will automatically destroy any Kubernetes resources created by the `okteto deploy` command. The commands you define in the `destroy` section will ensure any resources external to the Kubernetes cluster are destroyed when destroying the Development Environment. Your `destroy` section might look like this: ``` destroy: image: ghcr.io/okteto/pipeline-runner:1.0.0-sam commands: - name: destroy worker service command: | sam delete --no-prompts --stack-name "${OKTETO_NAMESPACE}-voting-texkhnclxd" --region us-east-1 ``` In this sample the `destroy` section instructs Okteto to delete the worker service running in AWS. When the application is deleted, Okteto will execute this command ensuring orphaned resources don't remain active. You can learn more about the `destroy` section [here](/docs/reference/okteto-manifest.md#deploy-string-optional). info Okteto recommends that you enable [Remote Execution](/docs/core/remote-execution.md) for your destroy commands ## Dev This section contains a list of Development Containers that determine how the Okteto CLI and, specifically, the `okteto up` command behave. This section is how Okteto hot reloads and debug the code between your local computer and your Development Environment. Your `dev` section might look like this: ``` dev: api: command: ["bash"] forward: - 8080:8080 - 9229:9229 sync: - api:/usr/src/app frontend: command: yarn start sync: - frontend:/usr/src/app ``` In this sample, the `api` section will tell Okteto to create a Development Container that exists specifically to sync code between your local computer and the **api** Kubernetes Deployment so you can see your changes in real-time within your Development Environment. You can learn more about the `dev` section [here](/docs/reference/okteto-manifest.md#dev-object-optional). ## External This section contains a list of resources external to the Kubernetes cluster such as cloud resources or dashboards, but that are part of your application. Configuring your external resources enables you to build a more complete development experience in Okteto. Your `external` section might look like this: ``` external: readme: icon: okteto notes: README.md endpoints: - name: Try it out! url: https://github.com/okteto/voting-app-with-external-resources lambda: icon: aws notes: docs/lambda.md endpoints: - name: function ``` This section provides only the metadata to represent and link to external resources in the Okteto UI and does not create any resources in a cloud provider. Creating or destroying the resources themselves is done in the [deploy](#deploy) and [destroy](#destroy) sections, respectively. You can learn more about the `external` section [here](/docs/reference/okteto-manifest.md#external-object-optional). ## Test [Okteto Test](/docs/testing.md) is designed to seamlessly integrate testing into your development workflow on the Okteto platform. This section tells Okteto how to test your application by defining one or more Test Containers. The Okteto CLI command `okteto test` will run your Test Containers using [Remote Execution](/docs/core/remote-execution.md#how-remote-execution-works). Remote execution ensures your Test Containers have a consistent behavior in your inner development loop and your CI scripts. Your `test` section might look like this: ``` test: unit: image: ghcr.io/okteto/golang:1 artifacts: - coverage.out caches: - /go - /root/.cache commands: - "go test . -v" integration: depends_on: - unit image: ghcr.io/okteto/golang:1 context: integration commands: - make tests ``` By default `okteto test` runs all tests when you run `okteto test`. You also run a single Test Container by passing its name as an argument, for example `okteto test unit`. ## Validating and Autocompleting the Okteto Manifest in your IDE [Follow these instructions](/docs/reference/okteto-manifest.md#validating-and-autocompleting-the-okteto-manifest-in-your-ide) to enable inline suggestions and validation for Okteto Manifests in your IDE. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto Variables Configuration is a core concept of every application, we understand how important it is for developers and teams to parametrize their project deployments and Okteto manifests. At Okteto we built different ways for you and your teams to manage and share config values using Okteto Variables. This page is a guide for those who are authoring Okteto manifests and configuring Okteto for their team and organization. If you are interested in runtime variables of dev environments, see [Development Containers](/docs/development/containers.md). ## What are Okteto Variables? Okteto Variables are a way to parametrize your [Okteto manifest](/docs/reference/okteto-manifest.md) and the deploy, destroy and test strategy. ### Types of Variables Each type is designed to solve a specific use-case. * **Built-in by Okteto**: variables injected automatically by Okteto in your deployment * **Deployment Variables**: Used to define variables at deployment time, either from the Okteto CLI or the Okteto UI deploy dialog * **Catalog Variables**: Used to define application-specific variables * **Local Environment Variables**: Used to define variables ad-hoc when using the Okteto CLI * **The `.env` file**: Used to define project or team-specific variables * **User Variables**: Used to define variables at the user level * **Admin Variables**: Used to define variables for all users in the organization note The above listing order is also the order in which the Okteto CLI gives precedence to each variable type. At the top the variables with the highest precedence. Variables with the same name defined in different types will be overridden by the variable with higher precedence. Example: the var `PORT` defined both in `.env` as `PORT=3000` and as `okteto deploy --var PORT=4000`, the value of `PORT` will be `4000` because the `--var` flag has higher precedence. ### Scope Okteto Variables are scoped to the execution of the Okteto CLI. This means that they are: * available for expanding values in the Okteto manifest * available to commands, scripts and tools running as part of `deploy`, `destroy` and `test` commands in the Okteto manifest Okteto Variables **are not** propagated to the development containers. If you need to pass variables to your development containers, see [Development Containers](/docs/development/containers.md). note Variables defined in a specific command item are only scoped to that item by default. For sharing values between steps, see the section [Sharing variables between commands](#sharing-variables-between-commands). ## Use Cases ### Expand values in the Okteto manifest Variables can be used to **expand values** in the the **Okteto Manifest** (see `${PORT}`) okteto.yaml ``` dev: api: command: npm start environment: PORT: ${PORT} ``` ### Deploy, destroy and test commands Okteto Variables can be used in **deploy**, **destroy** and **test** commands in the Okteto manifest. They are injected as environment variables of the steps. Commands, scripts and tools can use them, example: Makefile ``` .PHONY: deploy deploy: terraform init -backend-config=./config/${ENV}/backend.hcl terraform plan -var-file=./config/${ENV}/terraform.tfvars -out tfplan terraform apply tfplan ``` okteto.yaml ``` deploy: commands: - echo "Deploying $ENV" - make deploy ``` ### Sharing variables between commands As mentioned in the section [Scope](#scope), variables defined in each command of your deploy/destroy/test sections only available to that item by default. For example, here we have two command items, in which the variable `MY_VAR` is **not propagated**: okteto.yaml ``` deploy: - export MY_VAR=hello - echo $MY_VAR # -> '' (empty) ``` In the following sections, you will see different ways to share values between steps or CLI commands. #### Sharing Variables Between Deploy and Destroy Okteto automatically shares variables passed with the `--var` flag during the `deploy` command with the `destroy` command. This ensures consistent configuration across both deployment and teardown processes without the need to redefine variables. For example: ``` okteto deploy --var MY_VAR=hello ``` In your destroy section, you can access the `MY_VAR` variable: okteto.yaml ``` destroy: commands: - echo $MY_VAR # -> 'hello' ``` #### Multi-line Command The simplest way to share Okteto Variables between commands is to use a multi-line command, example: okteto.yaml ``` deploy: commands: - | export MY_VAR=hello echo $MY_VAR # -> 'hello' ``` #### $OKTETO\_ENV We understand that projects of a certain size and maturity often need to automate such steps, and often that require sharing values between steps. For such scenario we recommend using the special variable called `$OKTETO_ENV`. okteto.yaml ``` test: integration: commands: # 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 make the following var available to other steps - echo SERVICE_ENDPOINT=$(cat tfout.json | jq -r '.service_endpoint') >> $OKTETO_ENV # the following step will have access to SERVICE_ENDPOINT - echo "Running tests against ${SERVICE_ENDPOINT}..." ``` Another example for the same functionality, can be for example, creating the infrastructure, generating a `.env` file, and then deploy the application. okteto.yaml ``` deploy: commands: - name: Create AWS infrastructure command: | set -e bucketName="${OKTETO_NAMESPACE}-okteto-tacos-shop" terraform apply -input=false -var "bucket_name=$bucketName" -auto-approve echo "S3_BUCKET_NAME=$bucketName" >> "$OKTETO_ENV" - name: Create .env command: | set -e echo "S3_BUCKET_NAME=$S3_BUCKET_NAME" > .env - name: Deploy the app command: | set -e make deploy ``` note Here are some highlights, and clarifications on the example above: 1. The first step makes the variable `S3_BUCKET_NAME` available to the rest of the deployment steps. Both the step "Create .env" and "Deploy the app" will have access to `S3_BUCKET_NAME`. 2. Also, it's important to remember that the variables in `$OKTETO_ENV` are not shared across `deploy`, `test`, and `destroy` sections. They are only shared within the same section. 3. If you are wondering where the variable `OKTETO_NAMESPACE` comes from, check the section Okteto Variables [Built-in by Okteto](#built-in-by-okteto). ### Configuring dynamic endpoints In this example, we show how `$OKTETO_ENV` can be used to configure dynamic endpoints for [External Resources](/docs/core/okteto-manifest.md#external) within your dev environment. External Resources are defined in the Okteto manifest and have a name and a URL. Often, the resource URL is generated dynamically when the infrastructure is provisioned, in this example we show how to dynamically set the URL of an SQS queue. okteto.yaml ``` 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 # I configure the external resource URL echo OKTETO_EXTERNAL_SQS_ENDPOINTS_QUEUE_URL=$(cat tfout.json | jq -r '.queue_url') >> $OKTETO_ENV external: sqs: icon: aws endpoints: - name: queue ``` ## Built-in by Okteto ### Runtime Environment Variables (Injected into Pods) 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_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. * **`OKTETO_GIT_COMMIT`**: The SHA1 hash of the last commit of the branch * **`OKTETO_IS_PREVIEW_ENVIRONMENT`**: Set to `true` when the environment is [a preview environment](/docs/previews.md). ### Built-in Environment Variables for Images in Okteto Registry Reference images defined in the `build` section of the Okteto manifest using the following environment variables: * **`OKTETO_BUILD_(IMAGE)_IMAGE`**: Full image reference. * **`OKTETO_BUILD_(IMAGE)_REGISTRY`**: Registry URL where the image was pushed. * **`OKTETO_BUILD_(IMAGE)_REPOSITORY`**: Name of the image that was pushed. * **`OKTETO_BUILD_(IMAGE)_SHA`**: Latest tag and SHA of the image. For instance, with a build section like: okteto.yaml ``` build: hello-world: context: . ``` Okteto will generate environment variables such as: * **`OKTETO_BUILD_HELLO_WORLD_IMAGE`**: registry.okteto.example.com/cindy/hello-world\@sha256 :xxx * **`OKTETO_BUILD_HELLO_WORLD_REGISTRY`**: registry.okteto.example.com * **`OKTETO_BUILD_HELLO_WORLD_REPOSITORY`**: cindy/hello-world * **`OKTETO_BUILD_HELLO_WORLD_SHA`**: f56119a37b\@sha256 :xxx note If an `image` name includes '-', it will be replaced by '\_' in the corresponding environment variables. ### Reserved Variables Certain variable names are reserved for use by the Okteto Platform only. These reserved variables can be used within the supported [environment variable settings](/docs/core/credentials/environment-variables.md) but should not be used outside of them. This applies to: * Admin Variables * User Variables * Catalog Variables * Variables defined at deployment time The reserved variable names are: * `OKTETO_NAMESPACE` * `OKTETO_CONTEXT` * `OKTETO_TOKEN` * `OKTETO_URL` ## Setting Okteto Variables This section will show a brief example of how to set each type of Okteto Variable. ### Deployment Variables Variables defined at deployment time are those set with the `--var` flag. They are used to specify ad-hoc variables when running a command like [deploy](/docs/reference/okteto-cli.md#deploy) or [preview deploy](/docs/reference/okteto-cli.md#deploy-2) Example: ``` okteto deploy --var PORT=4000 ``` okteto.yaml ``` deploy: image: "node:${TAG}" commands: - name: deploy command: NODE_ENV=${ENV} make deploy ``` ### Catalog Variables When you deploy an application from the Okteto UI or if your organization uses the Okteto Catalog, you can define variables specific for your development environment. See [Catalog Variables](/docs/admin/catalog.md#add-environment-variables) for more information. ### Local Environment Variables Similar to the `--var` flag, local environment variables are useful when you need to specify ad-hoc variables when running a command like [deploy](/docs/reference/okteto-cli.md#deploy) or [preview deploy](/docs/reference/okteto-cli.md#deploy-2) Example: ``` PORT=4000 okteto deploy ``` ### The .env file You can set default values for any environment variables referenced in the Okteto Manifest in an environment file named `.env`. The `.env` should be placed in the same folder of the Okteto Manifest. The Okteto Manifest can also be stored in a special folder called `.okteto`. In that case, the `.env` should not be placed inside it, but in the parent directory. For example: ``` # .env PORT=4000 ``` okteto.yaml ``` deploy: commands: - name: deploy command: echo $PORT # -> 4000 ``` tip The `.env` integration also supports parameter expansion to set default values and allowing other developers to override them. Example: ``` # .env PORT=${PORT:-4000} ``` When running `PORT=5000 okteto deploy` the value of `PORT` will be `5000`. ### User Variables User variables are defined and managed by each user from the Okteto dashboard. They are useful for storing user-specific configuration values that are not shared with the rest of the team. To create or delete User Variables go to the `Variables` section in the `Settings` page of the Okteto dashboard: ![Settings page with the Variables tab selected, showing a user variable with a masked value and a Remove button](/docs/assets/images/variables-user+1.32-512f1ed38a59751bf5174e436ee0619d.png) To create a new variable, click on the **Add Variable** button, and provide a name and a value. The value will be masked once the variable is created. ![Add Variable dialog with Name and Value input fields](/docs/assets/images/variables-add-d15877db39a5e55e54b47a059bd43634.png) 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. ![Variables table showing a user variable with a masked value and a Remove button](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABE8AAADDCAIAAAD8/ajwAAAXVUlEQVR4Aezdg5IlWQLH4X2Wsdq2bY0KY9u2bdu2bds232L3v3NiMyrqDqo7emrvqfk6vug4eTOHN05H/jJPZv1r3Y1HAQAADDxqBwAAUDsAAABqBwAAQO0AAACoHQAAALUDAACoHQAAALUDAACgdgAAANQOAACA2gEAAFA7AACA2gEAAFA7AAAAagcAAEDtAAAAqJ21BgAAUDsAAABqBwAAQO0AAACoHQAAALUDAACoHQAAALUDAACgdgAAANQOAACA2gEAAFA7AACA2gEAAFA7AAAAamezkTNHT105flbH+FmdAADAP1JHoiBpMHBqZ4NB40dOXjZ8wuKNh07OJgAA8I+VKEgaJBCSCQOhdvJfMmj07DIGAABIICQTqq+d3KVKumXQAAAASCYkFuqunSzLs4ANAADoJZmQWKi7dvIcUhkAAAC0xELdtdNZBgAAAC2xoHYqAAAAqB0AAAC1UzsAAEDt1A8AAFA7AAAAagcAAKiH2gEAAFA7AABAPdQOAACA2gEAAOqhdgAAANQOAABQDbUDAACgdgAAgAqoHQAAALXDrMXblwEAAAwcakfnnHrpE7c99WvsfMA5+QQAAKqndkjeJHKKgRY8AACgdqROGTSbVrXB2jJtQfeUuVtnAADUVztqZ4/DLk4e3PT4j2OnLe+165zrXr7hkW/beQFb0zbRDAQP9HLMOfdmUkyYuap1V/ceJ2bXVjsdVTZbXXbnB/mjIAMAoNbaUTtx2uVPr7fJ6Ipqp+e6taZ2mnGe5Mk4gEVb7p1Jkcneuuvsa1+68dEfNh0+dcDWDgCoHbWTE5rfru8eXUvtNEvXMu5VO2Wv4GnABpuNu+b+Ly6/68NeVzTGTVuRmXL4abdnPGBrBwDUjtpZ2rHfdQ99fd2DXw8bO6eW2okMWmun9QBg36Ov/O8cWbJDxo3dD7kwH85ZttNArh0AUDtqZ9r8rtzYyeDos+/5o9rp2OWY8298/YZHvrvw5jd3O+SCjQZPKJ8fduqtexx20fyVu51x1XNX3fvZ0WfdM2T0zM1GTDvijDuuuOeTS257t2u343NYY8sdjzz7mhevf/ib/N69+4nlYvMaa62dVkDeNJA5ctCJN2RcZOpddueHkcGfTPCetXPc+Q9kVwbFpFlbnHjRowu32KtsDh83L7P+qns/vfyuj/LnwOjJi/MhAKB22qJ2csZz6mVPZrxoi71aa2f7fU7LrgtueiPHn3b5UxkffNJNzcnQ1fd9lpOko866O39JdiV78jDApXe8nxC6/uFv88nyrgPLwXsfeVk2T73sqf2OvTrrajI+8Pjr+qF2gMzf3L/dMBnTY9bsetB5fznBm9q56bEfTrjw4QyKOUt3ypGdux6f8ciJC6994Ms44Phrj7/goVue+Dlzf8zUpdn1/wcAakftZDx68pIbH/0+12U3GTalV+1cfOs7V9z9cVb/l80zr3r+5id+KpvlmZ8ZC7fNOHJNN5tnXPns+puOyebYqcuyedx5D5Sry7c+9cv+x13TXFrOq6LySV4V9XfXDlCSZunW+5XN3OfJZu7A/MkE73vtZI4nb8rfLSbN3jK7cgUkYwCgLWJB7cS2e52Szf2PvbpX7SRdho6dk99HTVo8f9Xu593wWg4bPn5eORnKYpieC9WaE6AiN3lyzTiDXQ48N7u22P6IPDxQ7LT/2eXgv7t2gKw0u/XJX449976Mc4cnj+rlNs6fT/A+1k666ObHf8p7HZupHVnFes0DX+YwAKBdYkHt5HTnrGtezP2W/EjBnrUzZsrSXLvNm2pzcNaoZN1aBiPGzy8nQ2dd/UIGxYrug5rrx0UeBrjw5rcyOPKMO7OrVZa39UPtAHnMJlkyaOT0ZZ37Z8psvt1hfz7B+1g75RZuqyjvtgYA2iIW1E5kXVnOh3I3JkrtrL/p2Etufy8r/vMmg7yyNtdxswZmDWpnryMuza7pC7cZOXFBT5uNmN4PtQOs6D44M2XrnY9J22R2bzx0Ul8meFM7yaGTLn60jGPBqt1L7WTta1m3luncS3kFAgDQLrGgdmKXg87Nh1FqJ48aZ3zIyTc1z9skYNagdvKe6+zKYrlmV572Of/G12Yu3q4fagfYaMjEvA4xky6P5ZQZ3ZcJ3tTORbe+nef6yiN5sc9RV5TaKa9AyDsYyyN/RZbMHXzSjRkAAO0VC2onF3dz7tLUTi4A5+0FV97zSV7XNn1B92Gn3Za1Ltk7YsKC1aqdnEVlZX9uHOWnfMxbseuO+5+VM6f80MMho2f1T+0AKZBMlihXGfoywZva2fPwS/J53rWYN85nnHDKZnnFfH5oT8Y5Mi9gzHWN3OfJ5q4Hn59dAEB7xYLaianzO/NAc6mdyCr/cmYTeVF1eZF0Fr2sVu3EoFEzci6VA4qcG02ctUW/vYEaKJMlrxAoa8z6MsGb2tlk2OQsgWtu/OauTgZ51VvZu3irfXJ7p+zNmrfdDj7/z5exAQBqp43kRCcJtFZ+gEYeXM7fKm9/KidDagcqmuBZ4TZ5ztYbDhrfuiszOi88mDK3I3+3bAIAq0/tUHftAACA2kHtAACA2qGC1AEAALUDAACgduoBAACoHQAAALVTDwAAQO0AAAConXoAAABqBwAAQO3UAwAAUDsAAABqpx4AAIDaAQAAUDv1AAAA1A4AAIDaqQcAAKB2AAAA1E49AAAAtQMAAKB26gEAAKgdAAAAtVMxAABA7dQPAABQOwAAAK3c26kAAABgJRsAAIDaqQAAAKB2AAAA1E41AAAAtQMAAKB26gEAAKgdAAAAtVMPAABA7QAAAKidegAAAGoHAABA7dQDAABQOwAAAGqnHgAAgNoBAABQO7UCAADUDgAAgNqpHwAAg0fPGT115fhZHTk5pM105KvJF6R21A4AAKtng0Hjf+uczpGTl8eQMfNoN/le8gXla8qXpXb6Su0AAFBSZ+OhUzKmbaV5SvConb5SOwAAFrDlbDBn0hnT5lKk+bL6eUmb2gEAoOIbO1kllQFVyJfVz7d31A4AALXKE/Bu7NRVO/nK1I7aAQDgr9W4jM3TO2qnUDsAAKgdtaN2AABQO6gdtQMAgNpB7agdAADUDmpH7fQTAADUjtpROwAAqB3UjtoBAEDtbL3NrvHq62+dd+HlkXE+RO2oHQAAKq6dFM6///erGZdfyZ4cgNpROwAAVFY7uYHTRE7GvXYldTSP2lE7AADUVztpmKZz/vIwwaN2Bn7tLF31H/bOwUtytYnDf8w117Zt27Zt27ZtG2NrbdvevXy+W2fr5Ex6tnfy9Vx0V5/nzHnfSnWSi6TzS+Ftlnb6HKxet/kTbgWKVkhNO4vb3v1HmGbPWyImNpFpz75D3c7NWnVmU1RMQrbcxdXo5svv8x47EYln3YatfTr8kKNwQlIaDkVKVlFjkVJVsMCEybN87lO2Ksmpp3ftOThq3NTvsxfCwTAMwzAMI/jUjgcNI84eKnn2HThy9+59J2fOnt+ybXfdRq1N7XjA1E7WgtK4/+AR3Lv/qHiZ6hm5TZ42V9yiYxPF0n/waKYXL1/Lka+k0/PbnwsmJqexqc+AEX6PPmXGfDxXrN7oc2vHbv3YevREhNM4adocjHDh0lWO5VY7svXGzTvXb96Gu/ceiCU+ISVX/lL4BCWGYRiGYZjaEamT2dqezB4lNi7xD1+f3377bcr0uaZ2/qViwdQOzJ6/1KcPURFUTTq189UP+U6Gx2CZu2CZ03nEmMkYj5+M/OqHvH6PXqp8LZyv37j9Y86i7q279x1maw9H+OjrH/OfPXfx9p37YRExbOrQpW9Gakc1GIMefYYQ4VFZFXwYhmEYhmFqR2I1Hip80Dze1M6hI8e3bt+zb//h5y9eqOCp3aClqZ1/nVgwtUOchL9Xr938OXcxtw/pauqjagcq12h07/5DgidlK9URS74i5a9dv4WlYrUGYvELoRt227n7AHfuHDsnOOM8pZZtu+G8eetudA6D/QeP+VU7QvfegzGyN9FgQYZhGIZhGKZ23IEdpm4LCsdjeMeldvQJ8JufCpDeJsbVazdh+XdhasfUDpJj34GjDAYOHev2oUSHTROnzlG1o8xbuBwj35XpytUbmc6et0Qd/NKr3zC+smff4XT24aMnYV+2cr3TuGP3AYzNW3f5Lluhy1euMy5RtrpftSOFRmIvWKwiU8MITQjJ8pKiW6/BXPjUxfn04Zrq2LUvV1nugmUC50COa4G8hcvlLVRWLZr7ij1XgdIy5dLm3Lr2HFivcZuc+Uo5PbPlKYEn/nKImnWbi90wDMPUjkZp+JthGY9r6vqid7UDzVp3FiNb1Vi0VNWhI8avWb9l5pxFnbr1J0nHWebduXv/5m26fP1jPt5Kr1qzkbqJmvVayFYCRBQvrFi9of+gUe7KhXyFy/XuP2zp8rWLlq7q0WewliqULFeTfUKNOs2c/pyn2MtUrO3nxIJY7Zja4dGEASU36aIfDZq2w56UfKpqrSZutcPzx9nzl7C3at+jWu2mFP+cPnNBozF+kT3cvHWXMA7BHKc9Nj6Z3daq31IthYpXwo3Dyf+RZNDhMG3mgs9RO8SOMN65+4B3D0wNIwRBIZBiqpmr9PCo36St04Erl2xPdeDCHDRsbKAckC63bt/FSP4qU2X8pFkY5y9aKb+4nBVTgWDsgCFj1JPfJIxtOvTc+ddbD8LIYjcMwzC1405jcwset9RRAqJ20Cqa3iaWYaMmvnn7Fot+Tp85p185d/4ilps3bzurgH7//fd+A0eOHDOZgRovXLycLU9xPRA659nzF87dPnr8hLdsomrEwm55JsQiHDsRLvbqdZr6ObEgVjumdhA5SBqJnDgdtu/cJzGfStUbutUOSFJZStqZk+HRDNp27IUxU8hDDMEctVSp2RhLfGKq040mbBinz1oo0wpV6zM9f+Ey74w/oXZ4/EKy09sN49r1W7GEIIYhHQ5VSGgzjxLlaqgPjRnTOUiWaaAcJPbLz6HzguXWgZHLuVjpapTwkQe7cs2m9p37zJq7ROK33KP0RiG3Bf7eunMvMjoeo2EYxqcxtQN+F9ghmQ08qJ2efYbQh40oDWEWLd0ZMnwcPp269ZPp48dP9h88mpySJlNEDsEcVTvy+fXX35ytDj4af1Uj+5dDt+nYU43v3r3/8OGDyqT6jdvgEB0TLxZ9o0eigezqzLkLfk8smNWOqR3GSBrG0mNa4EmIcM2VazfQDG61o5CHxibgnauHc5DwEfly6RLkaHjgzMAhaoSxdIVaapReBe069XarHc758tX/QUsD7a9AWRE+IYhhECRx6xDQ1vPlq9Tz6XDm7MVAOdSo20xiShpAlvvPibAoxkNGjGeM1GEsjBo7VcM+qnYIENHv0Rm8NQzDMLWjisWb2pFNHtSO+4N+II+G3LOHjx4zvXT5as6Pd+yxE6eLD8EZp9rZvnMvCT6EVpJTT4nl7dt3qBre0w0cOkZjL5LtzFOdaBs0Fck+HGvilFnic/XaDZ4DyYWW6cYtO+S4Q0dOEMuI0ZP8nliQqx1TO0gaGhUwLVOxjlN1zJyzmPEn1I60VgPpYZ1ZePSR9BUOIfn9tIDjFa9TnEiiXURUHBU4CnJI5Jlb7RDzIedNMmdoyMaj3k+5iuIQkhiG76iLJKk6m5H4pGDxSgFxAJbhYqrv2yjMc/ZdxE0Le7j8CeSydfuu/U61M2f+MsZuDMMwrG7HQyZbANXO06fPuvQYoI2sxLhj137kh0AFjhipxnGqnWJlqn1c3WSUWPbsOyQWuHnrDpYXL14yJg/t4273MXUnqhUvWx39I3rm1avXUqGakJjC9P3795T3+D2xIFc7pnaABgNMFy1dLRU1JJZQKsOCnp9WO7SoZhN4roqhEE1bYLdq153x1h17nQ7bduzD6BOiT+TAuDPZtFzn3IXLUkoUshjG0hXrfF4+MXFJzto2n5ADEBAH6DdoFFNS2hj/mKMItTe8YdEG9Lwu4SYQHhnLnQc3jRg71U7XnoMYG4ZheMa6FOATqC4F6IQ+A4bL+MHDR9zYtbQGS0af4ycjVO0gQpx9C9wxqNj4JJEujFWWDB42jqkyaepssXfo0ofpvAXLZEoDA6SUjOXXxP+JmdoJerWDbEA8kM1PSbEklmzaugt7Vqsd6qclIMMeWIuXMc2mdSuN1BBd5KTRuiAdFy5ewXnK9HlutSNTWRSIZUyZGkbIgkjwqUMWLF4pDkVLV+UqczvEJSQHygGy5S5O7wFZYkvU0cIlq/QOQ1cDLIeOnCCqQ6Ro2MiJbrUjdwbDMAxTO25k5Rx3v2m/lv+zA/WRoydlSlKZOLTp0EMs4ZExy1etTwepZd7UjpbcjJs4Qx2c8qZx8w5/Pc1WleKfsPBoVjuVTU1adPzMEzO1E+RqBwiqYBk1bmpq2lkGdADMarUjHD4axh5oQYiqIRrj3NXYiTP0fXA6aFPLJpLW8HerHf0HJKVNIlSGEbK9p48eD0+nQ3hZ4GwSPXXmfHfglEssgA6weNka7GQO0Lle81dhw6YdcudxLpNlascwDFM7mSrdkSiN91V6PKkdmktJCzVapVFogKVwicrisHnrLueSA3MXLCWFh+dGb2qHBtPikJp2RjsKUMxz5ep1set6BpLbhua5feeuo0Wb/xMLCbVjaoeUeixS3E8bALVntdrp0WcIe5AMFmm8pk9pUtVD0w+xKCJvklNOs7V1hx5utSNIsIhnKcaGEbLwC7Rq7Wbkh1wjR46FaUM2vdZGjplCgEVbVDdu3jGwDpLMLXcSzoRGjmonpCNNR7ScD4upHcMwTO14D+947eTmoQP1gUPHxDJn/lKxREXHi4UicNx4vKQaRyzU53hTO0BMRnzCIqLbd+5N3934hGSx7N1/WHw0hqOfqTPmid3viYWE2jG1AzyIuHrLZrnaobSGDDrZj7PxWpOWnaTTgIhyN7wMxmH33kNutaOd5VhpR1fvMYxQhguNpbG0GYAb2oRwsVNCw9WURQ6SXwqkq6lxzPjpIpDoPkJbkWMnIinpkUvb1I5hGKZ2MlG989mxGnffAs9qp2K1BhLeef36jfzEkE728uUrd21MYlIqsRTPaofdPn323L3b+w8eynH17RtRHW1vzZqNYvd7YqGidkzt0CIJ49lzF3lq+dvUDtB8lp2Qb6MWjcyM1QRNF3QtpIEb74mLlKziVjsCfZww8owlrW//QQzDkDsMLQqkU6JqJG0cJw0YybF23p1M7RiGYWonUBoGUUQIyO3mWe2ARkiWrVwnlqKlqkpGma6fs3Hzjhx55QnNo9qRBz8WMHUsy/MbWQCaw6ZoxQ7noEb/J2ZqJ6jUTtYjK+RkBGsdqqdhGIY0oWYBrnKV63r5umEYhqkd1wI7CBufOkcrfLIaVATrflIHLuvbBAq63bDPmnWb02b6HzsxUzumduYvWrF2/daMYK10u6n92b4daEYMhFEYfZtStIoIgrQQBSAKTN7/OfrbEFhk17ByOetgAZELPjMBAPqonZPm2X9H5Nx/20NS7agdAADUznGYU9lTqnDqf8l/S2pH7QAAoHZQO2oHAAC1g9pRO/0AAFA7akftAACgdlA7agcAALWD2lE7AACoHdSO2gEAQO2gdtQOAEA3tdOGeY16ZrXT1I7aAQDg3Pjzp3aC1Fg1mdpROwAAnPscf6dle//6Tnlg19hqMrWjdgAAePR4x9c711dFWjO9+GBH7QAAkO3tY9qDZ5jXah6upnYpe+rUWGpH7QAA8PSVtlvztGnZuJhW0/RfYFM7AAAAagcAAEikdgAAANQOAACQQ+0AAACoHQAAIIfaAQAAUDsAAEAOtQMAAKB2AACAHGoHAABA7QAAADnUDgAAgNoBAAByqB0AAAC1AwAA5FA7AAAAagcAAMimdgAAgHxqBwAAQO0AAAA51A4AAIDaAQAAcqgdAAAAtQMAAORQOwAAAGoHAADIoXYAAADUDgAAkEHtAAAAqB0AACCA2gEAAFA7/QAAALXzD6T540hHUKnvAAAAAElFTkSuQmCC) ### Admin Variables Admin variables are defined and managed by the Okteto administrators from the Okteto dashboard. They are useful for storing configuration values that are shared with all users of the Okteto installation. To create or delete Admin Variables navigate to the **Admin -> Admin Variables** underneath the Settings section of the Okteto Admin Dashboard: ![Admin Dashboard showing the Admin Variables page with a table of variables and Remove buttons](/docs/assets/images/variables-admin+1.32-2e6fb21d011af91e9a1599e96503b937.png) To create a new variable, click on the **Add Variable** button, and provide a name and a value. The value will be masked once the variable is created. ![Add Variable dialog with Name and Value input fields](/docs/assets/images/variables-add-d15877db39a5e55e54b47a059bd43634.png) 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. ![Admin variables table showing variables with masked values and Remove buttons](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABE8AAADDCAIAAAD8/ajwAAAXVUlEQVR4Aezdg5IlWQLH4X2Wsdq2bY0KY9u2bdu2bds232L3v3NiMyrqDqo7emrvqfk6vug4eTOHN05H/jJPZv1r3Y1HAQAADDxqBwAAUDsAAABqBwAAQO0AAACoHQAAALUDAACoHQAAALUDAACgdgAAANQOAACA2gEAAFA7AACA2gEAAFA7AAAAagcAAEDtAAAAqJ21BgAAUDsAAABqBwAAQO0AAACoHQAAALUDAACoHQAAALUDAACgdgAAANQOAACA2gEAAFA7AACA2gEAAFA7AAAAamezkTNHT105flbH+FmdAADAP1JHoiBpMHBqZ4NB40dOXjZ8wuKNh07OJgAA8I+VKEgaJBCSCQOhdvJfMmj07DIGAABIICQTqq+d3KVKumXQAAAASCYkFuqunSzLs4ANAADoJZmQWKi7dvIcUhkAAAC0xELdtdNZBgAAAC2xoHYqAAAAqB0AAAC1UzsAAEDt1A8AAFA7AAAAagcAAKiH2gEAAFA7AABAPdQOAACA2gEAAOqhdgAAANQOAABQDbUDAACgdgAAgAqoHQAAALXDrMXblwEAAAwcakfnnHrpE7c99WvsfMA5+QQAAKqndkjeJHKKgRY8AACgdqROGTSbVrXB2jJtQfeUuVtnAADUVztqZ4/DLk4e3PT4j2OnLe+165zrXr7hkW/beQFb0zbRDAQP9HLMOfdmUkyYuap1V/ceJ2bXVjsdVTZbXXbnB/mjIAMAoNbaUTtx2uVPr7fJ6Ipqp+e6taZ2mnGe5Mk4gEVb7p1Jkcneuuvsa1+68dEfNh0+dcDWDgCoHbWTE5rfru8eXUvtNEvXMu5VO2Wv4GnABpuNu+b+Ly6/68NeVzTGTVuRmXL4abdnPGBrBwDUjtpZ2rHfdQ99fd2DXw8bO6eW2okMWmun9QBg36Ov/O8cWbJDxo3dD7kwH85ZttNArh0AUDtqZ9r8rtzYyeDos+/5o9rp2OWY8298/YZHvrvw5jd3O+SCjQZPKJ8fduqtexx20fyVu51x1XNX3fvZ0WfdM2T0zM1GTDvijDuuuOeTS257t2u343NYY8sdjzz7mhevf/ib/N69+4nlYvMaa62dVkDeNJA5ctCJN2RcZOpddueHkcGfTPCetXPc+Q9kVwbFpFlbnHjRowu32KtsDh83L7P+qns/vfyuj/LnwOjJi/MhAKB22qJ2csZz6mVPZrxoi71aa2f7fU7LrgtueiPHn3b5UxkffNJNzcnQ1fd9lpOko866O39JdiV78jDApXe8nxC6/uFv88nyrgPLwXsfeVk2T73sqf2OvTrrajI+8Pjr+qF2gMzf3L/dMBnTY9bsetB5fznBm9q56bEfTrjw4QyKOUt3ypGdux6f8ciJC6994Ms44Phrj7/goVue+Dlzf8zUpdn1/wcAakftZDx68pIbH/0+12U3GTalV+1cfOs7V9z9cVb/l80zr3r+5id+KpvlmZ8ZC7fNOHJNN5tnXPns+puOyebYqcuyedx5D5Sry7c+9cv+x13TXFrOq6LySV4V9XfXDlCSZunW+5XN3OfJZu7A/MkE73vtZI4nb8rfLSbN3jK7cgUkYwCgLWJB7cS2e52Szf2PvbpX7SRdho6dk99HTVo8f9Xu593wWg4bPn5eORnKYpieC9WaE6AiN3lyzTiDXQ48N7u22P6IPDxQ7LT/2eXgv7t2gKw0u/XJX449976Mc4cnj+rlNs6fT/A+1k666ObHf8p7HZupHVnFes0DX+YwAKBdYkHt5HTnrGtezP2W/EjBnrUzZsrSXLvNm2pzcNaoZN1aBiPGzy8nQ2dd/UIGxYrug5rrx0UeBrjw5rcyOPKMO7OrVZa39UPtAHnMJlkyaOT0ZZ37Z8psvt1hfz7B+1g75RZuqyjvtgYA2iIW1E5kXVnOh3I3JkrtrL/p2Etufy8r/vMmg7yyNtdxswZmDWpnryMuza7pC7cZOXFBT5uNmN4PtQOs6D44M2XrnY9J22R2bzx0Ul8meFM7yaGTLn60jGPBqt1L7WTta1m3luncS3kFAgDQLrGgdmKXg87Nh1FqJ48aZ3zIyTc1z9skYNagdvKe6+zKYrlmV572Of/G12Yu3q4fagfYaMjEvA4xky6P5ZQZ3ZcJ3tTORbe+nef6yiN5sc9RV5TaKa9AyDsYyyN/RZbMHXzSjRkAAO0VC2onF3dz7tLUTi4A5+0FV97zSV7XNn1B92Gn3Za1Ltk7YsKC1aqdnEVlZX9uHOWnfMxbseuO+5+VM6f80MMho2f1T+0AKZBMlihXGfoywZva2fPwS/J53rWYN85nnHDKZnnFfH5oT8Y5Mi9gzHWN3OfJ5q4Hn59dAEB7xYLaianzO/NAc6mdyCr/cmYTeVF1eZF0Fr2sVu3EoFEzci6VA4qcG02ctUW/vYEaKJMlrxAoa8z6MsGb2tlk2OQsgWtu/OauTgZ51VvZu3irfXJ7p+zNmrfdDj7/z5exAQBqp43kRCcJtFZ+gEYeXM7fKm9/KidDagcqmuBZ4TZ5ztYbDhrfuiszOi88mDK3I3+3bAIAq0/tUHftAACA2kHtAACA2qGC1AEAALUDAACgduoBAACoHQAAALVTDwAAQO0AAAConXoAAABqBwAAQO3UAwAAUDsAAABqpx4AAIDaAQAAUDv1AAAA1A4AAIDaqQcAAKB2AAAA1E49AAAAtQMAAKB26gEAAKgdAAAAtVMxAABA7dQPAABQOwAAAK3c26kAAABgJRsAAIDaqQAAAKB2AAAA1E41AAAAtQMAAKB26gEAAKgdAAAAtVMPAABA7QAAAKidegAAAGoHAABA7dQDAABQOwAAAGqnHgAAgNoBAABQO7UCAADUDgAAgNqpHwAAg0fPGT115fhZHTk5pM105KvJF6R21A4AAKtng0Hjf+uczpGTl8eQMfNoN/le8gXla8qXpXb6Su0AAFBSZ+OhUzKmbaV5SvConb5SOwAAFrDlbDBn0hnT5lKk+bL6eUmb2gEAoOIbO1kllQFVyJfVz7d31A4AALXKE/Bu7NRVO/nK1I7aAQDgr9W4jM3TO2qnUDsAAKgdtaN2AABQO6gdtQMAgNpB7agdAADUDmpH7fQTAADUjtpROwAAqB3UjtoBAEDtbL3NrvHq62+dd+HlkXE+RO2oHQAAKq6dFM6///erGZdfyZ4cgNpROwAAVFY7uYHTRE7GvXYldTSP2lE7AADUVztpmKZz/vIwwaN2Bn7tLF31H/bOwUtytYnDf8w117Zt27Zt27ZtG2NrbdvevXy+W2fr5Ex6tnfy9Vx0V5/nzHnfSnWSi6TzS+Ftlnb6HKxet/kTbgWKVkhNO4vb3v1HmGbPWyImNpFpz75D3c7NWnVmU1RMQrbcxdXo5svv8x47EYln3YatfTr8kKNwQlIaDkVKVlFjkVJVsMCEybN87lO2Ksmpp3ftOThq3NTvsxfCwTAMwzAMI/jUjgcNI84eKnn2HThy9+59J2fOnt+ybXfdRq1N7XjA1E7WgtK4/+AR3Lv/qHiZ6hm5TZ42V9yiYxPF0n/waKYXL1/Lka+k0/PbnwsmJqexqc+AEX6PPmXGfDxXrN7oc2vHbv3YevREhNM4adocjHDh0lWO5VY7svXGzTvXb96Gu/ceiCU+ISVX/lL4BCWGYRiGYZjaEamT2dqezB4lNi7xD1+f3377bcr0uaZ2/qViwdQOzJ6/1KcPURFUTTq189UP+U6Gx2CZu2CZ03nEmMkYj5+M/OqHvH6PXqp8LZyv37j9Y86i7q279x1maw9H+OjrH/OfPXfx9p37YRExbOrQpW9Gakc1GIMefYYQ4VFZFXwYhmEYhmFqR2I1Hip80Dze1M6hI8e3bt+zb//h5y9eqOCp3aClqZ1/nVgwtUOchL9Xr938OXcxtw/pauqjagcq12h07/5DgidlK9URS74i5a9dv4WlYrUGYvELoRt227n7AHfuHDsnOOM8pZZtu+G8eetudA6D/QeP+VU7QvfegzGyN9FgQYZhGIZhGKZ23IEdpm4LCsdjeMeldvQJ8JufCpDeJsbVazdh+XdhasfUDpJj34GjDAYOHev2oUSHTROnzlG1o8xbuBwj35XpytUbmc6et0Qd/NKr3zC+smff4XT24aMnYV+2cr3TuGP3AYzNW3f5Lluhy1euMy5RtrpftSOFRmIvWKwiU8MITQjJ8pKiW6/BXPjUxfn04Zrq2LUvV1nugmUC50COa4G8hcvlLVRWLZr7ij1XgdIy5dLm3Lr2HFivcZuc+Uo5PbPlKYEn/nKImnWbi90wDMPUjkZp+JthGY9r6vqid7UDzVp3FiNb1Vi0VNWhI8avWb9l5pxFnbr1J0nHWebduXv/5m26fP1jPt5Kr1qzkbqJmvVayFYCRBQvrFi9of+gUe7KhXyFy/XuP2zp8rWLlq7q0WewliqULFeTfUKNOs2c/pyn2MtUrO3nxIJY7Zja4dGEASU36aIfDZq2w56UfKpqrSZutcPzx9nzl7C3at+jWu2mFP+cPnNBozF+kT3cvHWXMA7BHKc9Nj6Z3daq31IthYpXwo3Dyf+RZNDhMG3mgs9RO8SOMN65+4B3D0wNIwRBIZBiqpmr9PCo36St04Erl2xPdeDCHDRsbKAckC63bt/FSP4qU2X8pFkY5y9aKb+4nBVTgWDsgCFj1JPfJIxtOvTc+ddbD8LIYjcMwzC1405jcwset9RRAqJ20Cqa3iaWYaMmvnn7Fot+Tp85p185d/4ilps3bzurgH7//fd+A0eOHDOZgRovXLycLU9xPRA659nzF87dPnr8hLdsomrEwm55JsQiHDsRLvbqdZr6ObEgVjumdhA5SBqJnDgdtu/cJzGfStUbutUOSFJZStqZk+HRDNp27IUxU8hDDMEctVSp2RhLfGKq040mbBinz1oo0wpV6zM9f+Ey74w/oXZ4/EKy09sN49r1W7GEIIYhHQ5VSGgzjxLlaqgPjRnTOUiWaaAcJPbLz6HzguXWgZHLuVjpapTwkQe7cs2m9p37zJq7ROK33KP0RiG3Bf7eunMvMjoeo2EYxqcxtQN+F9ghmQ08qJ2efYbQh40oDWEWLd0ZMnwcPp269ZPp48dP9h88mpySJlNEDsEcVTvy+fXX35ytDj4af1Uj+5dDt+nYU43v3r3/8OGDyqT6jdvgEB0TLxZ9o0eigezqzLkLfk8smNWOqR3GSBrG0mNa4EmIcM2VazfQDG61o5CHxibgnauHc5DwEfly6RLkaHjgzMAhaoSxdIVaapReBe069XarHc758tX/QUsD7a9AWRE+IYhhECRx6xDQ1vPlq9Tz6XDm7MVAOdSo20xiShpAlvvPibAoxkNGjGeM1GEsjBo7VcM+qnYIENHv0Rm8NQzDMLWjisWb2pFNHtSO+4N+II+G3LOHjx4zvXT5as6Pd+yxE6eLD8EZp9rZvnMvCT6EVpJTT4nl7dt3qBre0w0cOkZjL5LtzFOdaBs0Fck+HGvilFnic/XaDZ4DyYWW6cYtO+S4Q0dOEMuI0ZP8nliQqx1TO0gaGhUwLVOxjlN1zJyzmPEn1I60VgPpYZ1ZePSR9BUOIfn9tIDjFa9TnEiiXURUHBU4CnJI5Jlb7RDzIedNMmdoyMaj3k+5iuIQkhiG76iLJKk6m5H4pGDxSgFxAJbhYqrv2yjMc/ZdxE0Le7j8CeSydfuu/U61M2f+MsZuDMMwrG7HQyZbANXO06fPuvQYoI2sxLhj137kh0AFjhipxnGqnWJlqn1c3WSUWPbsOyQWuHnrDpYXL14yJg/t4273MXUnqhUvWx39I3rm1avXUqGakJjC9P3795T3+D2xIFc7pnaABgNMFy1dLRU1JJZQKsOCnp9WO7SoZhN4roqhEE1bYLdq153x1h17nQ7bduzD6BOiT+TAuDPZtFzn3IXLUkoUshjG0hXrfF4+MXFJzto2n5ADEBAH6DdoFFNS2hj/mKMItTe8YdEG9Lwu4SYQHhnLnQc3jRg71U7XnoMYG4ZheMa6FOATqC4F6IQ+A4bL+MHDR9zYtbQGS0af4ycjVO0gQpx9C9wxqNj4JJEujFWWDB42jqkyaepssXfo0ofpvAXLZEoDA6SUjOXXxP+JmdoJerWDbEA8kM1PSbEklmzaugt7Vqsd6qclIMMeWIuXMc2mdSuN1BBd5KTRuiAdFy5ewXnK9HlutSNTWRSIZUyZGkbIgkjwqUMWLF4pDkVLV+UqczvEJSQHygGy5S5O7wFZYkvU0cIlq/QOQ1cDLIeOnCCqQ6Ro2MiJbrUjdwbDMAxTO25k5Rx3v2m/lv+zA/WRoydlSlKZOLTp0EMs4ZExy1etTwepZd7UjpbcjJs4Qx2c8qZx8w5/Pc1WleKfsPBoVjuVTU1adPzMEzO1E+RqBwiqYBk1bmpq2lkGdADMarUjHD4axh5oQYiqIRrj3NXYiTP0fXA6aFPLJpLW8HerHf0HJKVNIlSGEbK9p48eD0+nQ3hZ4GwSPXXmfHfglEssgA6weNka7GQO0Lle81dhw6YdcudxLpNlascwDFM7mSrdkSiN91V6PKkdmktJCzVapVFogKVwicrisHnrLueSA3MXLCWFh+dGb2qHBtPikJp2RjsKUMxz5ep1set6BpLbhua5feeuo0Wb/xMLCbVjaoeUeixS3E8bALVntdrp0WcIe5AMFmm8pk9pUtVD0w+xKCJvklNOs7V1hx5utSNIsIhnKcaGEbLwC7Rq7Wbkh1wjR46FaUM2vdZGjplCgEVbVDdu3jGwDpLMLXcSzoRGjmonpCNNR7ScD4upHcMwTO14D+947eTmoQP1gUPHxDJn/lKxREXHi4UicNx4vKQaRyzU53hTO0BMRnzCIqLbd+5N3934hGSx7N1/WHw0hqOfqTPmid3viYWE2jG1AzyIuHrLZrnaobSGDDrZj7PxWpOWnaTTgIhyN7wMxmH33kNutaOd5VhpR1fvMYxQhguNpbG0GYAb2oRwsVNCw9WURQ6SXwqkq6lxzPjpIpDoPkJbkWMnIinpkUvb1I5hGKZ2MlG989mxGnffAs9qp2K1BhLeef36jfzEkE728uUrd21MYlIqsRTPaofdPn323L3b+w8eynH17RtRHW1vzZqNYvd7YqGidkzt0CIJ49lzF3lq+dvUDtB8lp2Qb6MWjcyM1QRNF3QtpIEb74mLlKziVjsCfZww8owlrW//QQzDkDsMLQqkU6JqJG0cJw0YybF23p1M7RiGYWonUBoGUUQIyO3mWe2ARkiWrVwnlqKlqkpGma6fs3Hzjhx55QnNo9qRBz8WMHUsy/MbWQCaw6ZoxQ7noEb/J2ZqJ6jUTtYjK+RkBGsdqqdhGIY0oWYBrnKV63r5umEYhqkd1wI7CBufOkcrfLIaVATrflIHLuvbBAq63bDPmnWb02b6HzsxUzumduYvWrF2/daMYK10u6n92b4daEYMhFEYfZtStIoIgrQQBSAKTN7/OfrbEFhk17ByOetgAZELPjMBAPqonZPm2X9H5Nx/20NS7agdAADUznGYU9lTqnDqf8l/S2pH7QAAoHZQO2oHAAC1g9pRO/0AAFA7akftAACgdlA7agcAALWD2lE7AACoHdSO2gEAQO2gdtQOAEA3tdOGeY16ZrXT1I7aAQDg3Pjzp3aC1Fg1mdpROwAAnPscf6dle//6Tnlg19hqMrWjdgAAePR4x9c711dFWjO9+GBH7QAAkO3tY9qDZ5jXah6upnYpe+rUWGpH7QAA8PSVtlvztGnZuJhW0/RfYFM7AAAAagcAAEikdgAAANQOAACQQ+0AAACoHQAAIIfaAQAAUDsAAEAOtQMAAKB2AACAHGoHAABA7QAAADnUDgAAgNoBAAByqB0AAAC1AwAA5FA7AAAAagcAAMimdgAAgHxqBwAAQO0AAAA51A4AAIDaAQAAcqgdAAAAtQMAAORQOwAAAGoHAADIoXYAAADUDgAAkEHtAAAAqB0AACCA2gEAAFA7/QAAALXzD6T540hHUKnvAAAAAElFTkSuQmCC) ## Feature flag variables Some features in Okteto are controlled by feature flags. These flags can be enabled or disabled using Okteto Variables and they have an impact on the behavior of the Okteto CLI. For a list of available feature flags, see [Feature Flags](/docs/reference/feature-flags.md). ## Security Okteto Variables longer than 5 characters are masked in the logs. This is to prevent sensitive information from being exposed, without compromising the developer experience when inspecting logs you will be able to see values that not sensitive such as boolean options (`true` / `false`). --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Remote Execution The Okteto Manifest allows you to define a list of `commands` to [deploy](/docs/core/okteto-manifest.md#deploy), [test](/docs/core/okteto-manifest.md#test) and [destroy](/docs/core/okteto-manifest.md#deploy) your application. By default, your commands run locally in your machine, but we recommend that you enable remote execution. ## Enable Remote Execution You can enable remote execution by default for all applications or on a per application basis. ### 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`. Navigate to **Admin -> Command Line (CLI)** under the Settings section to enable it. ![Remote Execution Settings](/docs/assets/images/remote-execution-setting+1.32-5ece30d508c2c70aca09dd28390ccae4.png) warning Okteto recommends that you enable remote execution for your deploy/destroy commands ### Enable Remote Execution per Application To use remote execution per application, you can enable it by setting the `remote` field to `true` in the deploy/destroy section of your Okteto Manifest: okteto.yaml ``` deploy: remote: true commands: - helm upgrade --install movies chart ``` note Remote execution is always enabled for `okteto test` By default, your commands will run in a remote container using our [default container image](https://github.com/okteto/pipeline-runner) in the workdir `/okteto/src`. The default container image is a Debian Linux container with the following tools preinstalled: * `bash` * `curl` * `envsubst` * `git` * `helm` * `kubectl` * `kustomize` * `make` * `okteto` * `openssh` * `wait-for-it` Remote execution means you don't have to worry about installing tools like `helm`, `kubectl`, and others on your local machine. ### Defining Your Own Image If you need custom tooling or advanced logic, you can use your own image for remote execution. For example, if you want to use the image `runner:1.0` as the runtime of your remote execution, configure your Okteto Manifest like this: okteto.yaml ``` deploy: image: runner:1.0 commands: - helm upgrade --install movies chart ``` You can use your own image to force specific versions of your deployment tools and ensure that your team has a consistent experience when working with Okteto. ## How Remote Execution Works When running on remote, Okteto will automatically synchronize your local folder to a container running inside Buildkit: ![Remote Execution flow showing okteto deploy syncing local files to a BuildKit container that runs commands](/docs/assets/images/remote-execution-3725c2b86f501c2d43898807d75c29bd.png) Okteto mounts the [Okteto SSH Key](/docs/admin/private-repositories/ssh-key.md) within the container running inside Buildkit. This allows you to clone any private git repository as part of your commands execution as long as the [Okteto SSH Key](/docs/admin/private-repositories/ssh-key.md) has the appropriate access privileges. info Remote executions also honor organization-wide [SSH Known Hosts](/docs/admin/ssh-known-hosts.md). ## Ignoring Files By default, Okteto synchronizes all files in the folder where the Okteto Manifest is located to the container running inside Buildkit. You can also configure the folder to be synchronized using the `context` field: okteto.yaml ``` deploy: image: runner:1.0 context: . commands: - helm upgrade --install movies chart ``` You can optimize which files are synchronized to the container running inside Buildkit by using a `.oktetoignore` file, located in the folder specified by the `context` field. If this file exists, the CLI will exclude from synchronization any files and directories that match patterns in it. This helps avoid unnecessarily synchronizing large or sensitive files and directories that are not used by the commands defined in your Okteto Manifest. An example `.oktetoignore` file would be the following: ``` # applied to all commands docs # applied to deploy commands only [deploy] integration/* # applied to destroy commands only [destroy] app # applied to all test commands [test] app # applied to unit test command only [test.unit] integration ``` This `.oktetoignore` expands to the following rules: * For deploys, ignores `docs` and `integration/**`. * For destroys, ignores `docs` and `app`. * For any test, ignores `docs` and `app`. * For the unit test specifically, ignores `docs`, `app` and `integration`. Each command group in `.oktetoignore` uses the same format as [.dockerignore files](https://docs.docker.com/engine/reference/builder/#dockerignore-file). note For remote `deploy` and `destroy` operations, Okteto also reads the legacy `.oktetodeployignore` file but it will be deprecated in future versions. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Volume Snapshots in Development Environments Okteto Volume Snapshots allow you to initialize Persistent Volume Claims (PVCs) with data from a previously created snapshot. 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 1. Your application uses a Persistent Volume Claim (PVC) to store data (e.g., a PostgreSQL or MySQL database) 2. You create a snapshot of this volume, capturing the data at that moment 3. When deploying a new Development Environment, you can restore the PVC from the snapshot, ensuring your app starts with the same dataset This allows you to spin up new environments with fresh, realistic data every time. ## Requirements * Self-Hosted * BYOC 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. Follow [this guide](/docs/self-hosted/install/volume-snapshots.md) to install a compatible CSI driver, create the `VolumeSnapshotClass`, and enable Volume Snapshots in your cluster. 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. ## 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 can contain database backups, large files, images, or a copy of your staging data. To use Volume Snapshots with your Development Environment, follow these steps: * [1. Create the source persistent volume](/docs/core/use-volume-snapshots.md#1-create-the-source-persistent-volume-pvc) * [2. Create a volume snapshot of the source persistent volume](/docs/core/use-volume-snapshots.md#2-create-a-snapshot-of-the-pvc) * [3. Consume the volume snapshot in a new persistent volume](/docs/core/use-volume-snapshots.md#3-restore-a-pvc-from-a-snapshot) ### 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, 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](/docs/core/use-volume-snapshots.md#requirements) section to learn more about the available storage classes in Okteto. * Kubernetes * Compose ``` apiVersion: v1 kind: PersistentVolumeClaim metadata: name: mysql-pvc spec: storageClassName: csi-okteto accessModes: - ReadWriteOnce resources: requests: storage: 10Gi --- apiVersion: v1 kind: Pod metadata: name: mysql spec: containers: - name: mysql image: mysql volumeMounts: - name: data mountPath: /var/lib/mysql volumes: - name: data persistentVolumeClaim: claimName: mysql-pvc ``` ``` services: mysql: image: mysql volumes: - mysql-pvc:/var/lib/mysql volumes: mysql-pvc: driver_opts: class: csi-okteto ``` note 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 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. This step is independent of whether you created your persistent volume with Kubernetes manifests or a Docker Compose file: The following manifest creates a volume snapshot from the `mysql-pvc` persistent volume claim: ``` apiVersion: snapshot.storage.k8s.io/v1 kind: VolumeSnapshot metadata: name: mysql-snapshot spec: volumeSnapshotClassName: okteto-snapshot-class source: persistentVolumeClaimName: mysql-pvc ``` ### 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: * Kubernetes * Compose ``` apiVersion: v1 kind: PersistentVolumeClaim metadata: annotations: dev.okteto.com/from-snapshot-name: mysql-snapshot dev.okteto.com/from-snapshot-namespace: staging name: pvc-from-snapshot spec: accessModes: - ReadWriteOnce resources: requests: storage: 10Gi ``` ``` services: mongodb: image: mysql volumes: - data:/var/lib/mysql volumes: data: labels: dev.okteto.com/from-snapshot-name: mysql-snapshot dev.okteto.com/from-snapshot-namespace: staging ``` 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. ## Automating snapshot creation in deployments You can integrate snapshot creation into your Okteto Manifest so every deployment includes an updated snapshot: ``` deploy: - create snapshot - deploy app ``` --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # User Roles and Permissions in Okteto The Okteto platform offers a robust Role-Based Access Control (RBAC) system to manage and control access to different environments within the platform. This page outlines the roles, permissions, and key features available to Admins and Developers in Okteto. ## User Roles In Okteto, there are two primary roles: **Admins** and **Developers**. ### Admins Admins have extensive control and oversight capabilities across the Okteto platform. Key features include: #### Admin Access to Any Environment Admins can perform all operations on any Namespace or Preview Environment, including: * Deleting, sharing, waking, sleeping, and marking Namespaces or Preview Environments as persistent * Deploying or deleting applications using both Okteto and `kubectl` * Accessing all resources and sub-resources within any Development Environment * [Transferring Namespace ownership](/docs/core/namespaces.md#transfer-namespace-ownership) between developers * Fine tuning Developer access to Namespaces and Preview Environments by configuring [the `serviceAccounts` section within the Okteto Helm configuration](/docs/self-hosted/helm-configuration.md#serviceaccounts). **Benefits**: This level of access allows admins to manage and troubleshoot environments, even if the original owner is unavailable. #### Access to the Okteto Admin Dashboard Admins can manage their instance through the [Okteto Admin Dashboard](/docs/admin/dashboard.md), including: * [Managing all users](/docs/admin/dashboard.md#users) within their Okteto instance * Having an overview of [Kubernetes Node utilization](/docs/admin/dashboard.md#nodes) * Seeing and managing all [Namespaces and Preview Environments](/docs/admin/dashboard.md#namespaces) within their Okteto instance * Setting cluster-wide variables in the [Admin Variables section](/docs/admin/dashboard.md#admin-variables) * Configuring [Admin Access Tokens](/docs/admin/dashboard.md#admin-access-tokens) for shared automations * Creating a library of ready-to-use Environments in the [Catalog](/docs/admin/catalog.md) ### Developers Developers have permissions primarily focused on creating and managing their own environments. Key features include: #### Creating and Managing Environments Developers can: * Create Namespaces and Personal/Global Preview Environments * Delete Namespaces and Preview Environments they own * Share Namespaces and Preview Environments they own * Deploy applications using both Okteto and `kubectl` within their own or shared Namespaces and Previews Environments * Wake and sleep Namespaces and Preview Environments they own or have access to #### Access to Global Preview Environments Developers have read access to Global Preview Environments, enabling them to troubleshoot issues effectively using `kubectl`. **Benefits**: This feature allows developers to monitor and debug shared environments without requiring elevated permissions. ## Permission Model ### Namespace Operations | Action | Admin | Developer-Owner | Developer-Member | Developer without direct access | | ----------------------------------- | ----- | --------------- | ---------------- | ------------------------------- | | Create | ✅ | ✅ | - | - | | Read | ✅ | ✅ | ✅ | ❌ | | Delete | ✅ | ✅ | ❌ | ❌ | | Share | ✅ | ✅ | ❌ | ❌ | | Deploy dev environment | ✅ | ✅ | ✅ | ❌ | | Redeploy dev environment | ✅ | ✅ | ✅ | ❌ | | Destroy dev environment | ✅ | ✅ | ✅ | ❌ | | Destroy all | ✅ | ✅ | ✅ | ❌ | | Wake | ✅ | ✅ | ✅ | ❌ | | Sleep | ✅ | ✅ | ✅ | ❌ | | Transfer Ownership | ✅ | ❌ | ❌ | ❌ | | Make Persistent | ✅ | ❌ | ❌ | ❌ | | Undo Make Persistent | ✅ | ❌ | ❌ | ❌ | | Start Development over sub-resource | ✅ | ✅ | ✅ | ❌ | | Restart sub-resource | ✅ | ✅ | ✅ | ❌ | | Destroy sub-resource | ✅ | ✅ | ✅ | ❌ | | Stop development over sub-resource | ✅ | ✅ | ✅ | ❌ | | 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 ### Operations within Previews #### Personal Previews | Action | Admin | Developer-Owner | Developer-Member | Developer without direct access | | ----------------------------------- | ----- | --------------- | ---------------- | ------------------------------- | | Create | ✅ | ✅ | - | - | | Read | ✅ | ✅ | ✅ | ❌ | | Delete | ✅ | ✅ | ❌ | ❌ | | Share | ✅ | ✅ | ❌ | ❌ | | Deploy dev environment | ✅ | ✅ | ✅ | ❌ | | Redeploy dev environment | ✅ | ✅ | ✅ | ❌ | | Destroy dev environment | ✅ | ✅ | ✅ | ❌ | | Destroy all | - | - | - | - | | Wake | ✅ | ✅ | ✅ | ❌ | | Sleep | ✅ | ✅ | ✅ | ❌ | | Transfer Ownership | - | - | - | - | | Make Persistent | ✅ | ❌ | ❌ | ❌ | | Undo Make Persistent | ✅ | ❌ | ❌ | ❌ | | Start Development over sub-resource | - | - | - | - | | Restart sub-resource | - | - | - | - | | Destroy sub-resource | - | - | - | - | | Stop development over sub-resource | - | - | - | - | | 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 #### Global Previews | Action | Admin | Developer-Owner | Developer-Member | Developer without direct access | | ----------------------------------- | ----- | --------------- | ---------------- | ------------------------------- | | Create | ✅ | ✅ | - | - | | Read | ✅ | ✅ | - | ✅ | | Delete | ✅ | ✅ | - | ❌ | | Share | - | - | - | - | | Deploy dev environment | ✅ | ✅ | - | ❌ | | Redeploy dev environment | ✅ | ✅ | - | ❌ | | Destroy dev environment | ✅ | ✅ | - | ❌ | | Destroy all | - | - | - | - | | Wake | ✅ | ✅ | - | ❌ | | Sleep | ✅ | ✅ | - | ❌ | | Transfer Ownership | - | - | - | - | | Make Persistent | ✅ | ❌ | - | ❌ | | Undo Make Persistent | ✅ | ❌ | - | ❌ | | Start Development over sub-resource | - | - | - | - | | Restart sub-resource | - | - | - | - | | Destroy sub-resource | - | - | - | - | | Stop development over sub-resource | - | - | - | - | | 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 ## 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`](/docs/self-hosted/helm-configuration.md#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](/docs/self-hosted/helm-configuration.md#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`](/docs/self-hosted/helm-configuration.md#serviceaccounts) Helm configuration value. For example, to use a more restrictive role: ``` 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`](/docs/self-hosted/helm-configuration.md#serviceaccounts) (defaults to `view`). --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Development Environments on Kubernetes 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](/docs/core/okteto-manifest.md). This way developers spend less time troubleshooting your development environment and more time coding cool features for their users 😎 * [Okteto CLI](/docs/development/using-okteto-cli.md) usage and commands * [Divert](/docs/development/using-divert.md) for lightweight Development Environments with shared services * [Development Containers](/docs/development/containers.md) for hot reload and debugging on Okteto * [Development images](/docs/development/images.md) for customizing your container setup * [Deploying](/docs/development/deploy.md) Development Environments --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Development Containers Okteto makes it easier to develop on Kubernetes by using Development Containers. Development Containers allow you to hot reload and debug your Development Environments **as fast as you write code** 🚀 Development Containers support two different modes: * [File Sync development mode](/docs/development/containers/file-sync.md): syncs your local changes to your remote Development Container (default mode) * [Hybrid development mode](/docs/development/containers/hybrid.md): runs your service locally and simulates your laptop belonging to the cluster network by using ssh tunnels The [mode](/docs/reference/okteto-manifest.md#mode-string-optional) is configured in your Okteto Manifest and affects the behavior of [`okteto up`](/docs/reference/okteto-cli.md#up). --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # File Sync Mode File Sync is the default development mode. Using File Sync means your code changes are synchronized to the remote Development Container. ![File sync development architecture](/docs/assets/images/sync-development-arch-abb345d5b944188a34cb7f2b5216977a.png) When you run `okteto up`, Okteto replaces the **api** Kubernetes Deployment with a development copy Deployment called **api-okteto** with the following development-time improvements: * Okteto overrides the container-level configuration of the **api-okteto** Kubernetes Deployment with the values defined in your [Development Container](/docs/reference/okteto-manifest.md#dev-object-optional). A typical example of this is to replace the production container image with one that contains your development runtime * A bidirectional file [synchronization service](/docs/reference/file-synchronization.md) is started to keep your changes up to date between your local filesystem and your Development Container * Automatic port forwarding using [SSH](/docs/reference/ssh-server.md). This allows you to do things like access your cluster services via `localhost` It's worth noting that your Development Container inherits the original **api** Kubernetes Deployment manifest. Therefore, the Development Container uses the same service account, environment variables, secrets, volumes, sidecars as the original **api** Kubernetes Deployment, providing a fully production-like development experience. File Sync works for applications of all shapes and forms. We have getting started guides for the following languages: * [ASP.NET](/docs/development/containers/file-sync/aspnetcore.md) * [Go](/docs/development/containers/file-sync/golang.md) * [Java](/docs/development/containers/file-sync/java.md) * [Node.js](/docs/development/containers/file-sync/node.md) * [PHP](/docs/development/containers/file-sync/php.md) * [Python](/docs/development/containers/file-sync/python.md) * [Ruby](/docs/development/containers/file-sync/ruby.md) Take a look at [our samples repository](https://github.com/okteto/samples) to see more examples of how to build, deploy and develop applications on Okteto with different programming languages, frameworks, and deployment tools. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Getting Started with Okteto and ASP.NET Okteto is a platform that simplifies the process of launching cloud development environments without requiring the expertise to do this yourself. This enables developers to automatically spin up fully-managed development environments that emulate production as closely as possible. Okteto eliminates the friction of local development environments, the many deviations that can exist for the same engineering organization, and the troubleshooting that comes with them. This tutorial will show you how to develop and debug an ASP.NET application using Okteto. ## Prerequisites Install the latest version of the Okteto CLI and configure it to access Okteto. [Follow our installation guide](/docs/get-started/install-okteto-cli.md) if you haven't done it yet. ## Step 1: Deploy the ASP.NET Sample App Get a local version of the ASP.NET Sample App by executing the following commands: ``` $ git clone https://github.com/okteto/aspnetcore-getting-started $ cd aspnetcore-getting-started ``` At the root of the directory, you'll find the `okteto.yml` file. This file describes how to [deploy](/docs/reference/okteto-manifest.md#deploy-string-optional) the ASP.NET Sample App. okteto.yml ``` deploy: - kubectl apply -f k8s.yml ``` Deploy your development environment by executing: ``` $ okteto deploy ``` ``` i Using cindy @ okteto.example.com as context i Running kubectl apply -f k8s.yml deployment.apps/hello-world created service/hello-world created ingress.networking.k8s.io/hello-world created ✓ Development environment 'aspnet-getting-started' successfully deployed i Run 'okteto up' to activate your development container ``` Open your browser and go to the URL of the application. You can get the URL by logging into your Okteto instance (e.g ) and clicking on the application's endpoint: ![Okteto dashboard showing the hello-world deployment running with endpoints and logs](/docs/assets/images/okteto-ui+1.32-53025faf6ca9fdbb5361923f92c90704.png) Did you notice that you're accessing your application through an HTTPs endpoint? This is because Okteto will [automatically create them](/docs/core/endpoints/automatic-ssl.md) for you when you deploy your application. Cool no 😎? ## Step 2: Activate your development container The [dev](/docs/reference/okteto-manifest.md#dev-object-optional) section defines how to activate a development container for the ASP.NET Sample App: okteto.yml ``` dev: hello-world: image: ghcr.io/okteto/aspnetcore-getting-started:dev command: bash environment: - ASPNETCORE_ENVIRONMENT=Development remote: 2222 sync: - hello-world:/src ``` The `hello-world` key matches the name of the hello world Deployment. The meaning of the rest of fields is: * `image`: the image used by the development container (built from this [Dockerfile](https://github.com/okteto/aspnetcore-getting-started/blob/main/Dockerfile)). * `command`: the start command of the development container. * `environment`: the environment variables added or overwritten in your development container. * `remote`: the local port to use for SSH communication with your development environment. * `sync`: the folders that will be synchronized between your local machine and the development container. Also, note that there is a `.stignore` file under the `sync` folder to indicate which files shouldn't be synchronized to your development container. This is useful to avoid synchronizing binaries, build artifacts, or git metadata. Next, execute the following command to activate your development container: ``` $ okteto up ``` ``` ✓ Persistent volume successfully attached ✓ Images successfully pulled ✓ Files synchronized Namespace: cindy Name: hello-world Welcome to your development container. Happy coding! cindy:hello-world src> ``` Working in your development container is the same as working on your local machine. Start the application by running the following command: ``` cindy:hello-world src> dotnet watch run ``` ``` dotnet watch ⌚ Polling file watcher is enabled dotnet watch 🔥 Hot reload enabled. For a list of supported edits, see https://aka.ms/dotnet/hot-reload. 💡 Press "Ctrl + R" to restart. dotnet watch 🔧 Building... Determining projects to restore... All projects are up-to-date for restore. helloworld -> /src/bin/Debug/netcoreapp8.0/helloworld.dll dotnet watch 🚀 Started warn: Microsoft.AspNetCore.Server.Kestrel[0] Overriding address(es) 'https://localhost:5001, http://localhost:5000'. Binding to endpoints defined via IConfiguration and/or UseKestrel() instead. info: Microsoft.Hosting.Lifetime[14] Now listening on: http://0.0.0.0:5000 dotnet watch 🌐 Unable to launch the browser. Navigate to http://0.0.0.0:5000 info: Microsoft.Hosting.Lifetime[0] Application started. Press Ctrl+C to shut down. info: Microsoft.Hosting.Lifetime[0] Hosting environment: Development info: Microsoft.Hosting.Lifetime[0] Content root path: /src ``` Go back to the browser and reload the page to test that your application is running. ## Step 3: Remote Development with Okteto Open the file `hello-world/Controllers/HelloWorldController.cs` in your favorite local IDE and modify the response message on line 25 to be *Hello world from Okteto!*. Save your changes. ``` [HttpGet] public string Get() { return "Hello world from Okteto!"; } ``` Take a look at the development container shell and notice how the changes are detected by `dotnet watch run` and automatically built and reloaded. ``` info: Microsoft.Hosting.Lifetime[0] Application is shutting down... watch : Exited watch : File changed: /src/Controllers/HelloWorldController.cs watch : Started info: Microsoft.Hosting.Lifetime[0] Now listening on: http://0.0.0.0:5000 info: Microsoft.Hosting.Lifetime[0] Application started. Press Ctrl+C to shut down. info: Microsoft.Hosting.Lifetime[0] Hosting environment: Development info: Microsoft.Hosting.Lifetime[0] Content root path: /src ``` Go back to the browser and reload the page. Your code changes were instantly applied. No commit, build, or push required 😎! ## Step 4: Remote debugging with Okteto Okteto enables you to debug your applications directly from your favorite IDE. Let's take a look at how that works in VS Code using the VS dotnet debugger. For this step, we're going to use the `C#` extension for VS Code. If you don't have it, you can [install it here](https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp#review-details). You might need to restart your VS Code instance. Open `HelloWorldController.cs` in VS Code, set a breakpoint on line `26` and press `F5`. VS Code will connect to your development container via SSH and give you a list of processes you can attach to. Scroll through the list and select the `helloworld` process, as shown below (you can also type `helloworld` in the search bar directly). ![ASP.NET processes to attach to](/docs/assets/images/aspnetcore-attach-22f181f019eadf050888915a5dcaa4c0.png) Once you select the process, VS Code will switch to debug view, launch the debugger, and attach it to the process you just selected. You'll know it's finished when the status bar at the bottom turns orange. ![ASP.NET connection status bar](/docs/assets/images/aspnetcore-connected-031ebcf3ef107780ee808db8fcbcf21c.png) Go back to the browser and reload the page. As soon as the service receives the request, the execution will halt at your breakpoint and VS Code will jump to the front of the screen. You can then inspect the request, the available variables, etc. ![ASP.NET core debug](/docs/assets/images/aspnetcore-debug-6d325006873489975c6dec9f5ee481c4.png) Your code is executing in Okteto, but you can debug it from your local machine without any extra services or tools. Pretty cool no? 😉 ## Next steps Congratulations, you just developed **your first application in Okteto** 🚀. Okteto lets you develop your applications directly on Kubernetes. This way you can: * Eliminate integration issues by developing in a realistic environment * Test your application end to end as fast as you type code * No more CPU cycles wasted in your machine. Develop at the speed of the cloud! Find more advanced samples with Okteto in [this repository](https://github.com/okteto/samples) or [join our community](https://community.okteto.com) to ask questions and share your feedback. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Getting Started with Okteto and Go Okteto is a platform that simplifies the process of launching cloud development environments without requiring the expertise to do this yourself. This enables developers to automatically spin up fully-managed development environments that emulate production as closely as possible. Okteto eliminates the friction of local development environments, the many deviations that can exist for the same engineering organization, and the troubleshooting that comes with them. This tutorial will show you how to develop and debug a Go application using Okteto. ## Prerequisites Install the latest version of the Okteto CLI and configure it to access Okteto. [Follow our installation guide](/docs/get-started/install-okteto-cli.md) if you haven't done it yet. ## Step 1: Deploy the Go Sample App Get a local version of the Go Sample App by executing the following commands: ``` $ git clone https://github.com/okteto/go-getting-started $ cd go-getting-started ``` At the root of the directory, you'll find the `okteto.yml` file. This file describes how to [deploy](/docs/reference/okteto-manifest.md#deploy-string-optional) the Go Sample App. okteto.yml ``` deploy: - kubectl apply -f k8s.yml ``` Deploy your development environment by executing: ``` $ okteto deploy ``` ``` i Using cindy @ okteto.example.com as context i Running kubectl apply -f k8s.yml deployment.apps/hello-world created service/hello-world created ingress.networking.k8s.io/hello-world created ✓ Development environment 'go-getting-started' successfully deployed i Run 'okteto up' to activate your development container ``` Log into your Okteto instance and click on the URL of the application: ![Okteto dashboard showing the hello-world deployment running with endpoints and logs](/docs/assets/images/okteto-ui+1.32-53025faf6ca9fdbb5361923f92c90704.png) Did you notice that you're accessing your application through an HTTPs endpoint? This is because Okteto will [automatically create them](/docs/core/endpoints/automatic-ssl.md) for you when you deploy your application. Cool no 😎? ## Step 2: Activate your development container The [dev](/docs/reference/okteto-manifest.md#dev-object-optional) section defines how to activate a development container for the Go Sample App: okteto.yml ``` dev: hello-world: image: ghcr.io/okteto/golang:1 command: bash sync: - .:/usr/src/app volumes: - /go - /root/.cache securityContext: capabilities: add: - SYS_PTRACE forward: - 2345:2345 ``` The `hello-world` key matches the name of the hello world Deployment. The meaning of the rest of fields is: * `image`: the image used by the development container. * `command`: the start command of the development container. * `sync`: the folders that will be synchronized between your local machine and the development container. * `volumes`: a list of paths in your development container to be mounted as persistent volumes. For example, this can be used to persist the Go cache. * `securityContext`: `SYS_PTRACE` is a capability required by the Go debugger. * `forward`: a list of ports to forward from your development container to localhost in your machine. This is needed to configure the Go remote debugger. Also, note that there is a `.stignore` file to indicate which files shouldn't be synchronized to your development container. This is useful to avoid synchronizing binaries, build artifacts, git metadata, or dependencies like the `vendor` folder. Next, execute the following command to activate your development container: ``` $ okteto up ``` ``` i Using cindy @ okteto.example.com as context i Development environment 'go-getting-started' already deployed. ✓ Images successfully pulled ✓ Files synchronized Context: okteto.example.com Namespace: cindy Name: hello-world Forward: 2345 -> 2345 Welcome to your development container. Happy coding! cindy:hello-world app> ``` Working in your development container is the same as working on your local machine. Start the application by running the following command: ``` cindy:hello-world app> go run main.go ``` ``` Starting hello-world server... ``` Go back to the browser, and reload the page to test that your application is running. ## Step 4: Remote Development with Okteto Open the file `main.go` in your favorite local IDE and modify the response message on line 17 to be *Hello world from Okteto!*. Save your changes. ``` func helloServer(w http.ResponseWriter, r *http.Request) { fmt.Fprint(w, "Hello world from Okteto!") } ``` Okteto will synchronize your changes to your development container. Cancel the execution of `go run main.go` from the development container shell by pressing `ctrl + c`. Rerun your application: ``` cindy:hello-world app> go run main.go ``` ``` Starting hello-world server... ``` Go back to the browser and reload the page. Your code changes were instantly applied. No commit, build, or push required 😎! ## Step 5: Remote debugging with Okteto Okteto enables you to debug your applications directly from your favorite IDE. Let's take a look at how that works in VS Code, one of the most popular IDEs for Go development. If you haven't done it yet, install the [Go extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go) available from Visual Studio marketplace. Cancel the execution of `go run main.go` from the development container shell by pressing `ctrl + c`. Rerun your application in debug mode: ``` cindy:hello-world app> dlv debug --headless --listen=:2345 --log --api-version=2 ``` ``` API server listening at: [::]:2345 2019-10-17T14:39:24Z info layer=debugger launching process with args: [/usr/src/app/__debug_bin] ``` In your local machine, open VS Code, and install the [Go extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go). The sample application is already configured for remote debugging. Open the *Debug* view in VS Code and run the *Connect to okteto* debug configuration (or just press the F5 shortcut) to start the remote debugger: ``` { "version": "0.2.0", "configurations": [ { "name": "Connect to okteto", "type": "go", "request": "attach", "mode": "remote", "remotePath": "/usr/src/app", "port": 2345, "host": "127.0.0.1" } ] } ``` note You should be replacing the value of `remotePath` with wherever your application code is. Add a breakpoint on `main.go`, line 17. Go back to the browser, and reload the page. The execution will halt at your breakpoint. You can then inspect the request, the available variables, etc... ![VS Code editor with main.go open and a line highlighted in the helloServer function](/docs/assets/images/golang-debug-16fca653461c4fb26fd6e3824788028f.png) Your code is executing in Okteto, but you can debug it from your local machine without any extra services or tools. Pretty cool no? 😉 ## Next steps Congratulations, you just developed **your first application in Okteto** 🚀. Okteto lets you develop your applications directly on Kubernetes. This way you can: * Eliminate integration issues by developing in a realistic environment * Test your application end to end as fast as you type code * No more CPU cycles wasted in your machine. Develop at the speed of the cloud! Find more advanced samples with Okteto in [this repository](https://github.com/okteto/samples) or [join our community](https://community.okteto.com) to ask questions and share your feedback. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Getting Started with Okteto and Java Okteto is a platform that simplifies the process of launching cloud development environments without requiring the expertise to do this yourself. This enables developers to automatically spin up fully-managed development environments that emulate production as closely as possible. Okteto eliminates the friction of local development environments, the many deviations that can exist for the same engineering organization, and the troubleshooting that comes with them. This tutorial will show you how to develop and debug a Java application using Okteto. ## Prerequisites Install the latest version of the Okteto CLI and configure it to access Okteto. [Follow our installation guide](/docs/get-started/install-okteto-cli.md) if you haven't done it yet. ## Step 1: Deploy the Java Sample Maven or Gradle App Get a local version of the Java Sample App by executing the following commands: #### Maven ``` $ git clone https://github.com/okteto/java-maven-getting-started $ cd java-maven-getting-started ``` #### Gradle ``` $ git clone https://github.com/okteto/java-gradle-getting-started $ cd java-gradle-getting-started ``` At the root of the directory, you'll find the `okteto.yml` file. This file describes how to [deploy](/docs/reference/okteto-manifest.md#deploy-string-optional), and [develop](/docs/reference/okteto-manifest.md#dev-object-optional) the Java Sample App. #### Maven okteto.yml ``` deploy: - kubectl apply -f k8s.yml ``` #### Gradle okteto.yml ``` deploy: - kubectl apply -f k8s.yml ``` Deploy your development environment by executing: ``` $ okteto deploy ``` The output should look like this: #### Maven ``` i Using cindy @ okteto.example.com as context i Running kubectl apply -f k8s.yml deployment.apps/hello-world created service/hello-world created ingress.networking.k8s.io/hello-world created ✓ Development environment 'java-maven-getting-started' successfully deployed i Run 'okteto up' to activate your development container ``` #### Gradle ``` i Using cindy @ okteto.example.com as context i Running kubectl apply -f k8s.yml deployment.apps/hello-world created service/hello-world created ingress.networking.k8s.io/hello-world created ✓ Development environment 'java-gradle-getting-started' successfully deployed i Run 'okteto up' to activate your development container ``` Log into your Okteto instance and click on the endpoint URL for the application: ![Okteto dashboard showing the hello-world deployment running with endpoints and logs](/docs/assets/images/okteto-ui+1.32-53025faf6ca9fdbb5361923f92c90704.png) Notice that you're accessing your application through an HTTPS endpoint? This is because Okteto will [automatically create them](/docs/core/endpoints/automatic-ssl.md) for you when you deploy your application. Cool, no 😎? ## Step 2: Activate your development container The [dev](/docs/reference/okteto-manifest.md#dev-object-optional) section defines how to activate a development container for the Java Sample App. #### Maven okteto.yml ``` dev: hello-world: image: ghcr.io/okteto/maven:3 command: bash sync: - .:/usr/src/app forward: - 5005:5005 volumes: - /root/.m2 ``` #### Gradle okteto.yml ``` dev: hello-world: image: ghcr.io/okteto/gradle:6.5 command: bash sync: - .:/usr/src/app forward: - 5005:5005 volumes: - /home/gradle/.gradle ``` The `hello-world` key matches the name of the hello world Deployment. The other fields represent: * `image`: the image used by the development container. * `command`: the start command of the development container. * `sync`: the folders synchronized between your local machine and the development container. * `forward`: a list of ports to forward from your development container. This is needed to configure the Java remote debugger. * `volumes`: a list of paths in your development container to be mounted as persistent volumes. This is useful to persist the maven/gradle caches. In the project root, there is an .stignore file to indicate which files shouldn't be synchronized to your development container. This is useful to avoid synchronizing binaries, build artifacts, or git metadata. ## Step 3: Activate your development container Next, execute the following command to activate your development container: ``` $ okteto up ``` ``` ✓ Persistent volume successfully attached ✓ Images successfully pulled ✓ Files synchronized Namespace: cindy Name: hello-world Forward: 5005 -> 5005 Welcome to your development container. Happy coding! cindy:hello-world app> ``` Working in your development container is the same as working on your local machine. Start the application by running the following command: #### Maven app> ``` mvn spring-boot:run ``` #### Gradle app> ``` app> gradle bootRun ``` The first time you run the application, Maven/Gradle will compile your application. Wait for this process to finish. Go back to the browser and reload the page to test that your application is running. ## Step 4: Remote Development with Okteto Open `src/main/java/com/okteto/helloworld/RestHelloWorld.java` in your favorite local IDE and modify the response message on line 11 to be *Hello world from Okteto!*. Save your changes. ``` package com.okteto.helloworld; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @RestController public class RestHelloWorld { @GetMapping("/") public String sayHello() { return "Hello world from Okteto!"; } } ``` Your IDE will auto compile only the necessary `*.class` files which will be synchronized by Okteto to your remote environment. Take a look at the development container shell and notice how the changes are detected by Spring Boot and automatically hot reloaded. tip The `spring-boot-devtools` dependency is already included to automatically restart your Java application whenever a file is changed. When using your own spring application don't forget to include spring-boot-devtools to enable hot reloading. Go back to the browser and reload the page. Your code changes were instantly applied. No commit, build, or push required 😎! ## Step 5: Remote debugging with Okteto Okteto enables you to debug your applications directly from your favorite IDE. Let's take a look at how that works in IntelliJ, one of the most popular IDEs for Java development. > Add the following JVM arguments in the Gradle/Maven configuration files to enable remote debugging in your Java application: > > `-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005` ### Create the debug configuration on IntelliJ 1. From the main menu, select Run | Edit Configurations. 2. In the Run/Debug Configuration dialog, click + on the toolbar or press `⌘ N`. The list shows the run/debug configuration templates. Select Remote JVM Debug. 3. Specify the run/debug configuration name in the Name field. This name will be shown in the list of the available run/debug configurations. 4. In the Configuration section, specify the parameters listed below: * Debugger Mode: `Attach to remote JVM` * Host: `localhost` * Port: `5005` (this should match the port forward on your Okteto manifest file) * Command line arguments for remote JVM: `-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005` 5. Apply the changes and close the dialog. ![debugging in Okteto with Java](/docs/assets/images/java-debug-401cfa9cd8d0fce555981031d21ff584.png) ### Start the remote debugging session Select the debug action you just added, and click on the debug button to start the remote debugging session. Add a breakpoint on `src/main/java/es/okteto/helloworld/RestHelloWorld.java`, line 11. Go back to the browser and reload the page. The execution will halt at your breakpoint. You can then inspect the request, the available variables, etc... ![breakpoint in Java](/docs/assets/images/java-halt-582d67f018b47fd6ad5c8baf4bc4787c.png) Your code is executing in your remote development environment, but you can debug it from your local machine without any extra services or tools! ## Next steps Congratulations, you just developed **your first application in Okteto** 🚀. Okteto lets you develop your applications directly on Kubernetes. This way you can: * Eliminate integration issues by developing in a realistic environment * Test your application end to end as fast as you type code * Avoid wasting CPU cycles on your machine and develop at the speed of the cloud! Find more advanced samples with Okteto in [this repository](https://github.com/okteto/samples) or [join our community](https://community.okteto.com) to ask questions and share your feedback. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Getting Started with Okteto and Node.js Okteto is a platform that simplifies the process of launching cloud development environments without requiring the expertise to do this yourself. This enables developers to automatically spin up fully-managed development environments that emulate production as closely as possible. Okteto eliminates the friction of local development environments, the many deviations that can exist for the same engineering organization, and the troubleshooting that comes with them. This tutorial will show you how to develop and debug a Node.js application using Okteto. ## Prerequisites Install the latest version of the Okteto CLI and configure it to access Okteto. [Follow our installation guide](/docs/get-started/install-okteto-cli.md) if you haven't done it yet. ## Step 1: Deploy the Node.js Sample App Get a local version of the Node.js Sample App by executing the following commands: ``` $ git clone https://github.com/okteto/node-getting-started $ cd node-getting-started ``` At the root of the directory, you'll find the `okteto.yml` file. This file describes how to [deploy](/docs/reference/okteto-manifest.md#deploy-string-optional) the Node Sample App. okteto.yml ``` deploy: - kubectl apply -f k8s.yml ``` Deploy your development environment by executing: ``` $ okteto deploy ``` ``` i Using cindy @ okteto.example.com as context i Running kubectl apply -f k8s.yml deployment.apps/hello-world created service/hello-world created ingress.networking.k8s.io/hello-world created ✓ Development environment 'node-getting-started' successfully deployed i Run 'okteto up' to activate your development container ``` Log into your Okteto instance and click on the URL of the application: ![Okteto dashboard showing the hello-world deployment running with endpoints and logs](/docs/assets/images/okteto-ui+1.32-53025faf6ca9fdbb5361923f92c90704.png) Did you notice that you're accessing your application through an HTTPs endpoint? This is because Okteto will [automatically create them](/docs/core/endpoints/automatic-ssl.md) for you when you deploy your application. Cool no 😎? ## Step 2: Activate your development container The [dev](/docs/reference/okteto-manifest.md#dev-object-optional) section defines how to activate a development container for the Node Sample App: okteto.yml ``` dev: hello-world: command: bash sync: - .:/usr/src/app forward: - 9229:9229 ``` The `hello-world` key matches the name of the hello world Deployment. The meaning of the rest of fields is: * `command`: the start command of the development container. * `sync`: the folders that will be synchronized between your local machine and the development container. * `forward`: a list of ports to forward from your development container to localhost in your machine. This is needed to configure the Node remote debugger. Also, note that there is a `.stignore` file to indicate which files shouldn't be synchronized to your development container. This is useful to avoid synchronizing binaries, build artifacts, git metadata, or dependencies like the `node_modules` folder. Next, execute the following command to activate your development container: ``` $ okteto up ``` ``` ✓ Persistent volume successfully attached ✓ Images successfully pulled ✓ Files synchronized Namespace: cindy Name: hello-world Forward: 9229 -> 9229 Welcome to your development container. Happy coding! cindy:hello-world app> ``` Working in your development container is the same as working on your local machine. Start the application in hot-reload mode by running the following command: ``` cindy:hello-world app> npm run start ``` ``` > node-getting-started@1.0.0 start /usr/src/app > nodemon index.js [nodemon] 2.0.18 [nodemon] to restart at any time, enter `rs` [nodemon] watching path(s): *.* [nodemon] watching extensions: js,mjs,json [nodemon] starting `node index.js` Starting hello-world server... ``` Go back to the browser and reload the page to test that your application is running. ## Step 3: Remote Development with Okteto Open the `index.js` file in your favorite local IDE and modify the response message on line 5 to be *Hello world from Okteto!*. Save your changes. ``` res.send("Hello world from Okteto!"); ``` Okteto will synchronize your changes to your development container. Take a look at the development container shell and notice how the changes are detected by `nodemon` and automatically hot reloaded. ``` [nodemon] restarting due to changes... [nodemon] starting `node index.js` Starting hello-world server... ``` Go back to the browser and reload the page. Your code changes were instantly applied. No commit, build, or push required 😎! ## Step 4: Remote debugging with Okteto Okteto enables you to debug your applications directly from your favorite IDE. Let's take a look at how that works in VS Code, one of the most popular IDEs for Node development. If you haven't done it yet, install the Node.js extension available from Visual Studio marketplace. Cancel the execution of `nodemon index.js` from the development container shell by pressing `ctrl + c`. Rerun your application in debug mode: ``` cindy:hello-world app> npm run debug ``` ``` Debugger listening on ws://0.0.0.0:9229/73d8d793-b0c3-4310-86ee-3a42938a5df1 For help, see: https://nodejs.org/en/docs/inspector ``` Open the *Debug* extension and run the *Connect to okteto* debug configuration (or press the F5 shortcut): ``` { "version": "0.2.0", "configurations": [ { "name": "Connect to okteto", "type": "node", "request": "attach", "address": "localhost", "port": 9229, "localRoot": "${workspaceFolder}", "remoteRoot": "/usr/src/app", "skipFiles": ["/**"] } ] } ``` note You should be replacing the value of `remoteRoot` with wherever your application code is. Add a breakpoint on `index.js`, line 5. Go back to the browser and reload the page. The execution will halt at your breakpoint. You can then inspect the request, the available variables, etc... ![breakpoint in Node.js](/docs/assets/images/node-halt-b43927a977e7522243e158103c0ffa09.png) Your code is running in Okteto, but you can debug it from your local machine without any extra services or tools. Pretty cool no? 😉 ## Next steps Congratulations, you just developed **your first application in Okteto** 🚀. Okteto lets you develop your applications directly on Kubernetes. This way you can: * Eliminate integration issues by developing in a realistic environment * Test your application end to end as fast as you type code * No more CPU cycles wasted in your machine. Develop at the speed of the cloud! Find more advanced samples with Okteto in [this repository](https://github.com/okteto/samples) or [join our community](https://community.okteto.com) to ask questions and share your feedback. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Getting Started with Okteto and PHP Okteto is a platform that simplifies the process of launching cloud development environments without requiring the expertise to do this yourself. This enables developers to automatically spin up fully-managed development environments that emulate production as closely as possible. Okteto eliminates the friction of local development environments, the many deviations that can exist for the same engineering organization, and the troubleshooting that comes with them. This tutorial will show you how to develop and debug a PHP application using Okteto. ## Prerequisites Install the latest version of the Okteto CLI and configure it to access Okteto. [Follow our installation guide](/docs/get-started/install-okteto-cli.md) if you haven't done it yet. ## Step 1: Deploy the PHP Sample App Get a local version of the PHP Sample App by executing the following commands: ``` $ git clone https://github.com/okteto/php-getting-started $ cd php-getting-started ``` At the root of the directory, you'll find the `okteto.yml` file. This file describes how to [deploy](/docs/reference/okteto-manifest.md#deploy-string-optional) the Php Sample App. okteto.yml ``` deploy: - kubectl apply -f k8s.yml ``` Deploy your development environment by executing: ``` $ okteto deploy ``` ``` i Using cindy @ okteto.example.com as context i Running kubectl apply -f k8s.yml deployment.apps/hello-world created service/hello-world created ingress.networking.k8s.io/hello-world created ✓ Development environment 'php-getting-started' successfully deployed i Run 'okteto up' to activate your development container ``` Open your browser and go to the URL of the application. You can get the URL by logging into your Okteto instance (eg. ) and clicking on the application's endpoint: ![Okteto dashboard showing the hello-world deployment running with endpoints and logs](/docs/assets/images/okteto-ui+1.32-53025faf6ca9fdbb5361923f92c90704.png) Did you notice that you're accessing your application through an HTTPS endpoint? This is because Okteto will [automatically create them](/docs/core/endpoints/automatic-ssl.md) for you when you deploy your application. Cool no 😎? ## Step 2: Activate your development container The [dev](/docs/reference/okteto-manifest.md#dev-object-optional) section defines how to activate a development container for the Php Sample App: okteto.yml ``` dev: hello-world: image: ghcr.io/okteto/php-getting-started:dev command: bash sync: - .:/app reverse: - 9000:9000 volumes: - /root/.composer/cache ``` The `hello-world` key matches the name of the hello world Deployment. The meaning of the rest of fields is: * `image`: the image used by the development container (built from this [Dockerfile](https://github.com/okteto/php-getting-started/blob/main/Dockerfile)). * `command`: the start command of the development container. * `sync`: the folders that will be synchronized between your local machine and the development container. * `reverse`: a list of ports to reverse forward from your development container to your local machine. This is needed to configure the PHP remote debugger. * `volumes`: a list of paths in your development container to be mounted as persistent volumes. For example, this is useful to persist the Composer cache. Also, note that there is a `.stignore` file to indicate which files shouldn't be synchronized to your development container. This is useful to avoid synchronizing binaries, build artifacts, or git metadata. Next, execute the following command to activate your development container: ``` $ okteto up ``` ``` ✓ Persistent volume successfully attached ✓ Images successfully pulled ✓ Files synchronized Namespace: cindy Name: hello-world Reverse: 9000 <- 9000 Welcome to your development container. Happy coding! cindy:hello-world app> ``` Working in your development container is the same as working on your local machine. Start the application by running the following command: ``` cindy:hello-world app> php -S 0.0.0.0:8080 ``` ``` [Tue Jul 5 21:04:55 2022] PHP 8.2.0 Development Server (http://0.0.0.0:8080) started ``` Go back to the browser, and reload the page to test that your application is running. ## Step 3: Remote Development with Okteto Open the `index.php` file in your favorite local IDE and modify the response message on line 2 to be *Hello world from Okteto!*. Save your changes. ``` **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Getting Started with Okteto and Python Okteto is a platform that simplifies the process of launching cloud development environments without requiring the expertise to do this yourself. This enables developers to automatically spin up fully-managed development environments that emulate production as closely as possible. Okteto eliminates the friction of local development environments, the many deviations that can exist for the same engineering organization, and the troubleshooting that comes with them. This tutorial will show you how to develop and debug a Python application using Okteto. ## Prerequisites Install the latest version of the Okteto CLI and configure it to access Okteto. [Follow our installation guide](/docs/get-started/install-okteto-cli.md) if you haven't done it yet. ## Step 1: Deploy the Python Sample App Get a local version of the Python Sample App by executing the following commands: ``` $ git clone https://github.com/okteto/python-getting-started $ cd python-getting-started ``` At the root of the directory, you'll find the `okteto.yml` file. This file describes how to [deploy](/docs/reference/okteto-manifest.md#deploy-string-optional) the Python Sample App. okteto.yml ``` deploy: - kubectl apply -f k8s.yml ``` Deploy your development environment by executing: ``` $ okteto deploy ``` ``` i Using cindy @ okteto.example.com as context i Running kubectl apply -f k8s.yml deployment.apps/hello-world created service/hello-world created ingress.networking.k8s.io/hello-world created ✓ Development environment 'python-getting-started' successfully deployed i Run 'okteto up' to activate your development container ``` Log into your Okteto instance and click on the URL of the application: ![Okteto dashboard showing the hello-world deployment running with endpoints and logs](/docs/assets/images/okteto-ui+1.32-53025faf6ca9fdbb5361923f92c90704.png) Did you notice that you're accessing your application through an HTTPs endpoint? This is because Okteto will [automatically create them](/docs/core/endpoints/automatic-ssl.md) for you when you deploy your application. Cool no 😎? ## Step 2: Activate your development container The [dev](/docs/reference/okteto-manifest.md#dev-object-optional) section defines how to activate a development container for the Python Sample App: okteto.yml ``` dev: hello-world: command: bash environment: - FLASK_ENV=development sync: - .:/usr/src/app reverse: - 9000:9000 volumes: - /root/.cache/pip ``` The `hello-world` key matches the name of the hello world Deployment. The meaning of the rest of fields is: * `command`: the start command of the development container. * `sync`: the folders that will be synchronized between your local machine and the development container. * `reverse`: a list of ports to reverse forward from your development container to your local machine. This is needed to configure the Python remote debugger. * `volumes`: a list of paths in your development container to be mounted as persistent volumes. This is useful to persist the pip cache. Also, note that there is a `.stignore` file to indicate which files shouldn't be synchronized to your development container. This is useful to avoid virtual environments, build artifacts, or git metadata. Next, execute the following command to activate your development container: ``` $ okteto up ``` ``` ✓ Persistent volume successfully attached ✓ Images successfully pulled ✓ Files synchronized Namespace: cindy Name: hello-world Reverse: 9000 <- 9000 Welcome to your development container. Happy coding! cindy:hello-world app> ``` Working in your development container is the same as working on your local machine. Start the application in development mode by running the following command: ``` cindy:hello-world app> python app.py ``` ``` Starting hello-world server... * Serving Flask app "app" (lazy loading) * Environment: development * Debug mode: on * Running on http://0.0.0.0:8080/ (Press CTRL+C to quit) ``` Go back to the browser and reload the page to test that your application is running. ## Step 3: Remote Development with Okteto Open the `app.py` file in your favorite local IDE and modify the response message on line 7 to be *Hello world from Okteto!*. Save your changes. ``` @app.route('/') def hello_world(): return 'Hello World from Okteto!' ``` Okteto will synchronize your changes to your development container. Flask's auto-reloader will detect the changes automatically and restart the application with the new code. ``` * Detected change in '/usr/src/app/app.py', reloading * Restarting with stat Starting hello-world server... * Debugger is active! * Debugger PIN: 308-916-374 ``` Go back to the browser and reload the page. Your code changes were instantly applied. No commit, build, or push required 😎! ## Step 4: Remote debugging with Okteto Okteto enables you to debug your applications directly from your favorite IDE. Let's take a look at how that works in one of python's most popular IDE's, [PyCharm](https://www.jetbrains.com/pycharm/). note For VS Code users, this [document](https://code.visualstudio.com/docs/python/debugging#_debugging-by-attaching-over-a-network-connection) explains how to configure the debugger with `debugpy`. First, open the project in PyCharm and remove the comments on `app.py` line `20`. ``` if __name__ == '__main__': print('Starting hello-world server...') # comment out to use Pycharm's remote debugger attach() app.run(host='0.0.0.0', port=8080) ``` Second, launch the [Remote Debug Server](https://www.jetbrains.com/help/pycharm/remote-debugging-with-product.html) by clicking on the Debug button on the top right. Ensure that the Debug Tool Window shows the `Waiting for process connection...` message. This message will be shown until you launch your app on the development container shell and it connects to the Debug Server. ``` Starting hello-world server... * Serving Flask app "app" (lazy loading) * Environment: development * Debug mode: on * Running on http://0.0.0.0:8080/ (Press CTRL+C to quit) * Restarting with stat Starting hello-world server... Connecting to debugger... ``` On your local machine, switch to the Debug Tool Window. Once the app connects it will show the connection to the pydev debugger. Press the `resume` button to let the execution continue. ![PyCharm Debug console showing a successful connection to the pydev remote debugger on port 9000](/docs/assets/images/python-connected-90a2a5d5a2bb5478e09e763a6d77c3c1.png) Add a breakpoint on `app.py`, line 10. Go back to the browser and reload the page. The execution will halt at your breakpoint. You can then inspect the request, the available variables, etc. ![PyCharm IDE paused at a breakpoint on line 10 of app.py, showing the call stack and variable inspector](/docs/assets/images/python-debug-bbd96a93e546f018be4754ef07245409.png) Your code is executing in Okteto, but you can debug it from your local machine without any extra services or tools. Pretty cool no? 😉 ## Next steps Congratulations, you just developed **your first application in Okteto** 🚀. Okteto lets you develop your applications directly on Kubernetes. This way you can: * Eliminate integration issues by developing in a realistic environment * Test your application end to end as fast as you type code * No more CPU cycles wasted in your machine. Develop at the speed of the cloud! Find more advanced samples with Okteto in [this repository](https://github.com/okteto/samples) or [join our community](https://community.okteto.com) to ask questions and share your feedback. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Getting Started with Okteto and Ruby Okteto is a platform that simplifies the process of launching cloud development environments without requiring the expertise to do this yourself. This enables developers to automatically spin up fully-managed development environments that emulate production as closely as possible. Okteto eliminates the friction of local development environments, the many deviations that can exist for the same engineering organization, and the troubleshooting that comes with them. This tutorial will show you how to develop and debug a Ruby application using Okteto. ## Prerequisites Install the latest version of the Okteto CLI and configure it to access Okteto. [Follow our installation guide](/docs/get-started/install-okteto-cli.md) if you haven't done it yet. ## Step 1: Deploy the Ruby Sample App Get a local version of the Ruby Sample App by executing the following commands: ``` $ 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](/docs/reference/okteto-manifest.md#deploy-string-optional) the Ruby Sample App. okteto.yml ``` deploy: - kubectl apply -f k8s.yml ``` Deploy your development environment by executing: ``` $ okteto deploy ``` ``` i Using cindy @ okteto.example.com as context i Running kubectl apply -f k8s.yml deployment.apps/hello-world created service/hello-world created ingress.networking.k8s.io/hello-world created ✓ Development environment 'ruby-getting-started' successfully deployed i Run 'okteto up' to activate your development container ``` Log into your Okteto instance and click on the URL of the application: ![Okteto dashboard showing the hello-world deployment running with endpoints and logs](/docs/assets/images/okteto-ui+1.32-53025faf6ca9fdbb5361923f92c90704.png) Did you notice that you're accessing your application through an HTTPs endpoint? This is because Okteto will [automatically create them](/docs/core/endpoints/automatic-ssl.md) for you when you deploy your application. Cool no 😎? ## Step 2: Activate your development container The [dev](/docs/reference/okteto-manifest.md#dev-object-optional) section defines how to activate a development container for the Ruby Sample App: okteto.yml ``` dev: hello-world: command: bash sync: - .:/opt/app/ forward: - 1234:1234 volumes: - /usr/local/bundle/cache ``` The `hello-world` key matches the name of the hello world Deployment. The meaning of the rest of fields is: * `command`: the start command of the development container. * `sync`: the folders that will be synchronized between your local machine and the development container. * `forward`: a list of ports to forward from your development container to localhost in your machine. This is needed to configure the Ruby remote debugger. * `volumes`: a list of paths in your development container to be mounted as persistent volumes. For example, this is useful to persist the bundle cache. Also, note that there is a `.stignore` file to indicate which files shouldn't be synchronized to your development container. This is useful to avoid synchronizing binaries, build artifacts or git metadata. Next, execute the following command to activate your development container: ``` $ okteto up ``` ``` ✓ Persistent volume successfully attached ✓ Images successfully pulled ✓ Files synchronized Namespace: cindy Name: hello-world Forward: 1234 -> 1234 Welcome to your development container. Happy coding! cindy:hello-world app> ``` Working in your development container is the same as working on your local machine. Start the application in hot-reload mode by running the following command: ``` cindy:hello-world app> ruby app.rb ``` ``` [2022-07-04 16:50:53] INFO WEBrick 1.6.1 [2022-07-04 16:50:53] INFO ruby 2.7.6 (2022-04-12) [x86_64-linux] == Sinatra (v2.0.8.1) has taken the stage on 8080 for production with backup from WEBrick [2022-07-04 16:50:53] INFO WEBrick::HTTPServer#start: pid=79 port=8080 ``` Go back to the browser and reload the page to test that your application is running. ## Step 3: Remote Development with Okteto Open the `app.rb` file in your favorite local IDE and modify the response message on line 7 to be *Hello world from Okteto!*. Save your changes. ``` get "/" do message = "Hello world from Okteto!" message end ``` Okteto will synchronize your changes to your development container in Kubernetes and Sinatra automatically detects them and reloads your application. Go back to the browser and reload the page. Your code changes were instantly applied. No commit, build, or push required 😎! ## Step 4: Remote debugging with Okteto Okteto enables you to debug your applications directly from your favorite IDE. Let's take a look at how that works in VS Code, one of the most popular IDEs for Ruby development. If you haven't done it yet, install the [Ruby extension](https://marketplace.visualstudio.com/items?itemName=rebornix.Ruby) available from Visual Studio marketplace. This extension comes with debug definitions covering the default `ruby-debug-ide` client setup. Now, cancel the execution of `ruby app.rb` from the development container shell by pressing `ctrl + c`. Rerun your application in debug mode: ``` cindy:hello-world app> rdebug-ide --host 0.0.0.0 app.rb ``` ``` Fast Debugger (ruby-debug-ide 0.7.0, debase 0.2.4.1, file filtering is supported) listens on 0.0.0.0:1234 ``` Open the *Run* view in VS Code and run the *Connect to okteto* debug configuration (or press the F5 shortcut): ``` { "version": "0.2.0", "configurations": [ { "name": "Connect to okteto", "type": "Ruby", "request": "attach", "remotePort": "1234", "remoteHost": "localhost", "remoteWorkspaceRoot": "/opt/app", "cwd": "${workspaceRoot}" } ] } ``` note You should be replacing the value of `remoteWorkspaceRoot` with wherever your application code is. Add a breakpoint on `app.rb`, line 8. Go back to the browser and reload the page. The execution will halt at your breakpoint. You can then inspect the request, the available variables, etc... ![debugging in Okteto with Ruby](/docs/assets/images/ruby-halt-94dee99b79284ad882241abed1f6b384.png) Your code is executing in Okteto, but you can debug it from your local machine without any extra services or tools. Pretty cool no? 😉 ## Next steps Congratulations, you just developed **your first application in Okteto** 🚀. Okteto lets you develop your applications directly on Kubernetes. This way you can: * Eliminate integration issues by developing in a realistic environment * Test your application end to end as fast as you type code * No more CPU cycles wasted in your machine. Develop at the speed of the cloud! Find more advanced samples with Okteto in [this repository](https://github.com/okteto/samples) or [join our community](https://community.okteto.com) to ask questions and share your feedback. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Hybrid Development Mode There are situations when running a service locally is faster than synchronizing code with a remote Development Container. For example, when doing frontend-only development or when working in an IDE-heavy context (e.g. Java/Spring) where the IDE may be pre-configured to run tests, start services, and connect debuggers. Hybrid development mode enables you to run the service in development locally while keeping the rest of your application components on Okteto. note Using hybrid development mode might increase latency when accessing the rest of the services in the cluster. To allow communication to and from the cluster and your local machine, an SSH server is deployed in the remote Development Container. You can expose the local service to the services running in the cluster using the [`reverse`](/docs/reference/okteto-manifest.md#reverse-string-optional) configuration for the Development Container. If you want to forward a service running in the cluster to your local machine you can use the [`forward`](/docs/reference/okteto-manifest.md#forward-string-optional) configuration. ![Hybrid development architecture](/docs/assets/images/hybrid-development-arch-c68df3e044228158a94603aab9d77e70.png) When using Hybrid development mode the [command](/docs/reference/okteto-manifest.md#command-string-optional) in your Okteto Manifest runs locally with the same environment variables as the original service running in the cluster. To achieve this, the following environment variables are added to the local process. This list is ordered from highest to lowest prevalence: * Environment variables defined in the [environment](/docs/reference/okteto-manifest.md#environment-string-optional) of the development container * Environment variables defined in the original [container spec](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/) * Environment variables coming from [configmaps](https://kubernetes.io/es/docs/concepts/configuration/configmap/#configmaps-y-pods) defined in the original container spec * Environment variables coming from [secrets](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#define-container-environment-variables-using-secret-data) defined in the original container spec * Environment variables defined in the [container image](https://kubernetes.io/docs/concepts/containers/#container-images) To enable `hybrid` mode you need to configure the necessary ports to expose the local service to the cluster network. This allows the components running in the cluster to communicate with the local service as if it was running directly in the cluster. To do this you can make use of the [reverse](/docs/reference/okteto-manifest.md#reverse-string-optional) field in your Okteto Manifest, which will expose the configured port of your local machine to the desired port on the Development Container. We have getting started guides for the following use cases: * [Frontend development](/docs/development/containers/hybrid/hybrid-frontend.md) * [Java development](/docs/development/containers/hybrid/hybrid-java.md) --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Getting Started with Hybrid Mode for Frontend Development This tutorial will show you how to develop a sample Frontend application using Okteto Hybrid Mode. ## Prerequisites Install the latest version of the Okteto CLI and configure it to access Okteto. [Follow our installation guide](/docs/get-started/install-okteto-cli.md) if you haven't done so yet. ## Step 1: Deploy the Sample App Get a local version of the Sample App by executing the following commands: ``` git clone https://github.com/okteto/movies-with-helm cd movies-with-helm ``` Checkout the branch with the Hybrid Mode configuration: ``` git checkout hybrid ``` At the root of the directory, you'll find the `okteto.yml` file. This file describes how to deploy the Sample App. okteto.yml ``` deploy: - helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE} ``` The Sample App consists of the following services: * A *React* based front-end, using [webpack](https://webpack.js.org) as bundler and *hot-reload server* for development. * A very simple Node.js API using [Express](https://expressjs.com). * A [MongoDB](https://www.mongodb.com) database. Deploy the Sample App by executing: ``` okteto deploy ``` ``` i Using cindy @ okteto.example.com as context i Running 'helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE}' ... ✓ Development environment 'movies-with-helm' successfully deployed i Endpoints available: - https://movies-cindy.okteto.example.dev - https://movies-cindy.okteto.example.dev/api ``` ## Step 2: Activate your Development Container The [dev](/docs/reference/okteto-manifest.md#dev-object-optional) section defines how to activate a Development Container for the Sample App: okteto.yml ``` dev: frontend: mode: hybrid workdir: frontend command: bash reverse: - 80:80 ``` The `frontend` key matches the name of the **frontend** Deployment. The definition of the rest of fields are: * `mode`: to configure Hybrid development mode * `workdir`: the working dir of the command * `command`: the command to start the frontend service locally * `reverse`: to expose the local port 80 in the Development Container port 80 using a reverse tunnel Next, execute the following command to activate your Development Container: ``` okteto up frontend ``` ``` i Using cindy @ okteto.example.com as context i Development environment 'microservices-demo' already deployed. ✓ Reverse tunnel configured Context: okteto.example.com Namespace: cindy Name: frontend Reverse: 80 <- 80 bash-3.2$ ``` You can run `yarn install` + `yarn start` to start the **frontend** service locally. Your local process will be still available from its okteto endpoint because the local port `80` is accessible via a reverse tunnel to the cluster. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Getting Started with Hybrid Mode for Java Development This tutorial will show you how to develop and debug a sample Java application using Okteto Hybrid Mode. ## Prerequisites Install the latest version of the Okteto CLI and configure it to access Okteto. [Follow our installation guide](/docs/get-started/install-okteto-cli.md) if you haven't done it yet. ## Step 1: Deploy the Sample App Get a local version of the Sample App by executing the following commands: ``` git clone https://github.com/okteto/microservices-demo cd microservices-demo ``` Checkout the branch with the Hybrid Mode configuration: ``` git checkout hybrid ``` At the root of the directory, you'll find the `okteto.yml` file. This file describes how to deploy the Sample App. okteto.yml ``` deploy: - helm upgrade --install postgresql postgresql/postgresql-11.6.2.tgz -f postgresql/values.yml - helm upgrade --install kafka kafka/kafka-17.1.0.tgz -f kafka/values.yml - helm upgrade --install vote vote/chart --set image=${OKTETO_BUILD_VOTE_IMAGE} - helm upgrade --install result result/chart --set image=${OKTETO_BUILD_RESULT_IMAGE} - helm upgrade --install worker worker/chart --set image=${OKTETO_BUILD_WORKER_IMAGE} ``` The Sample App consists of the following services: * A front-end web app in Java which lets you vote between Tacos and Burritos * A [Kafka](https://bitnami.com/stack/kafka/helm) queue which collects new votes * A Golang worker which consumes votes from Kafka and stores them in PostgresQL * A [PostgresQL](https://bitnami.com/stack/postgresql/helm) database * A Node.js webapp which shows the results of the voting in real time Deploy the Sample App by executing: ``` okteto deploy ``` ``` i Using cindy @ okteto.example.com as context i Running 'helm upgrade --install postgresql postgresql/postgresql-11.6.2.tgz -f postgresql/values.yml' ... i Running 'helm upgrade --install kafka kafka/kafka-17.1.0.tgz -f kafka/values.yml' ... i Running 'helm upgrade --install vote vote/chart --set image=${OKTETO_BUILD_VOTE_IMAGE}' ... i Running 'helm upgrade --install result result/chart --set image=${OKTETO_BUILD_RESULT_IMAGE}' ... i Running 'helm upgrade --install worker worker/chart --set image=${OKTETO_BUILD_WORKER_IMAGE}' ... ✓ Development environment 'microservices-demo' successfully deployed i Endpoints available: - https://vote-cindy.okteto.example.dev - https://result-cindy.okteto.example.dev ``` ## Step 2: Activate your Development Container The [dev](/docs/reference/okteto-manifest.md#dev-object-optional) section defines how to activate a Development Container for the Sample App: okteto.yml ``` dev: vote: mode: hybrid command: bash # mvn spring-boot:run workdir: vote reverse: - 8080:8080 forward: - 9092:kafka:9092 ``` The `vote` key matches the name of the **hello world** Deployment. The definition of the rest of fields are: * `mode`: to configure Hybrid development mode * `command`: the command to start the java service locally * `workdir`: the working dir of the command * `reverse`: to expose the local port 8080 in the Development Container port 8080 using a reverse tunnel * `forward`: to expose the kafka port 9092 on localhost to access kafka from your local machine Next, execute the following command to activate your Development Container: ``` okteto up vote ``` ``` i Using cindy @ okteto.example.com as context i Development environment 'microservices-demo' already deployed. ✓ Reverse tunnel configured Context: okteto.example.com Namespace: cindy Name: vote Forward: 9092 -> kafka:9092 Reverse: 8080 <- 8080 bash-3.2$ ``` You can run `mvn spring-boot:run` to start the **vote** service locally. Your local maven process will be still available from its okteto endpoint because the local port `8080` is accessible via a reverse tunnel to the cluster. The *vote* needs to connect to Kafka. You can change the code of the *vote* service to connect to kafka on `localhost`, or add the following entries to your `/etc/hosts` file: ``` 127.0.0.1 kafka 127.0.0.1 kafka-0.kafka-headless.<>.svc.cluster.local ``` --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Deploy your Development Environments In this section, we'll learn different ways to deploy your Development Environment in Okteto. You can use the Okteto CLI [deploy](/docs/reference/okteto-cli.md#deploy) command to deploy your Development Environment from your local machine. But you can also deploy your Development Environment using these methods: * [From the Catalog](/docs/development/deploy/deploy-from-catalog.md) * [From Git Repositories](/docs/development/deploy/deploy-from-git.md) * [From the GitHub integration](/docs/development/deploy/from-private-repositories.md) * [Develop on Okteto button](/docs/development/deploy/develop-on-okteto-button.md) --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Deploy Development Environments from your CatalogScaleEnterpriseSelf-Hosted The Catalog contains a list of pre-configured applications ready for deployment. With the Catalog, you don't have to worry about selecting the right Okteto manifest or configuring the necessary environment variables. Just pick the application you want to deploy, and click `Deploy`. ## Prerequisites Your administrator needs to enable this feature and add at least one item to the catalog for this option to be available to you. More information on this [is available here](/docs/admin/catalog.md). ## Deploy a Development Environment from your Catalog In order to deploy a pre-configured application using the Catalog, navigate to `Namespaces` → `Deploy Dev Environment` → `Catalog`. 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`. [](/docs/assets/medias/deploy-dialog-e6d014354ed6dd5c8a82aa52d75729f0.webm) 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. tip Check the [Okteto Manifest](/docs/reference/okteto-manifest.md) to learn more about how to configure your development environment deployment with an `okteto.yaml` file. As soon as your application is deployed, you'll see its state in the UI. The UI will be automatically updated as the different components are created. Your application will be ready to go once it reaches the `Success` state. ## Customize your Development Environment Before clicking the `Deploy` button, you are able to modify any of the pre-configured values of the application. Use this if you want to deploy a different branch, set different values for the pre-configured variables, or use a different Okteto manifest. ## Redeploy your Development Environment Click the **Redeploy** button on the right of your development environment. A dialog will open where you can modify the branch, variables, and path to the Okteto manifest used to deploy the application: ![Redeploy from the catalog](/docs/assets/images/redeploy-catalog+1.42-dbe78670d3f1dfc74f1b635d4e0ada3a.png) Click the `Redeploy` button to rebuild and redeploy your application. ## Destroy your Development Environment To destroy your development environment, go to the extended menu of your development environment and click the `Destroy` button. A confirmation dialog will pop up. Click the `Destroy` button to delete your environment and all its resources: ![Destroy application](/docs/assets/images/destroy-catalog+1.42-0a1a31e2631163c723540eadd6043ea9.png) You won't be able to recover resources after the development environment has been destroyed, so back up any sensitive data before running this action. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Deploy your Development Environments from your Git Repositories ## Prerequisites Please make sure to configure your Git repositories with the [appropriate manifests](/docs/core/okteto-manifest.md) before using them to deploy Dev Environments. ## Deploy Log in to your Okteto instance (e.g. `https://okteto.example.com`), and click on the **Deploy Dev Environment** button on the top left. A dialog will open asking for a Git repository to deploy. Make sure that "**Git URL**" is selected as the source. Type the URL for the Movies App repo (), pick a branch, and click **Deploy**: ![Deploy Dev Environment dialog with GitHub source selected and a repository URL entered](/docs/assets/images/deploy-git+1.42-3d28a7322b1a46d5fcdea01cdedf81d1.png) 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 Check the [Okteto Manifest](/docs/reference/okteto-manifest.md) to learn more about how to configure your development environment deployment with an `okteto.yaml` file. As soon as your development environment is deployed, you'll see its state in the UI. The UI will be automatically updated as the different components are created. Your development environment will be ready to go once it reaches the `Success` state. ![Okteto UI showing the deployed Movies app with its components and endpoints](/docs/assets/images/ui-movies-git+1.32-c42fe7a8bee8f6fd20fb5d912e8fd43b.png) ## Redeploy Click the **Redeploy** button on the right of your development environment. A dialog will open where you can modify the branch to redeploy and configure advanced options: ![Redeploy from git with dependencies](/docs/assets/images/redeploy-catalog+1.42-dbe78670d3f1dfc74f1b635d4e0ada3a.png) If your application has declared dependencies, you'll see a checkbox to **Include all direct dependencies**. When selected, Okteto will also redeploy the services listed as direct dependencies of your development environment. Click **Redeploy** and your environment will be updated with the latest source code and configuration. ## Destroy You can also destroy your development environment with a single click. Go back to the extended menu of your development environment and click the **Destroy** button. A confirmation dialog will pop up. Click on **Destroy** and your development environment and all of the resources created for it will be gone: If your application has dependencies, you’ll also see an option to destroy its direct dependencies. This ensures all related services are cleaned up together, helping to prevent orphaned resources. ![Destroy application](/docs/assets/images/destroy-catalog+1.42-0a1a31e2631163c723540eadd6043ea9.png) You won't be able to recover resources after the development environment has been destroyed, so back up any sensitive data before running this action. ## Variables When you deploy from Git, you can add Variables that will be available as environment variables during the deployment of your development environment. ## Adding a Develop on Okteto Button The **Develop on Okteto** button is a shortcut to deploy your development environments with a single click. The button is designed to be used in GitHub README files, documentation sites, or pretty much anywhere that renders an HTML file. Use this instead of writing a never-ending list of manual steps on how to deploy your development environments. Here's an example button that shows you how to deploy [the Movies App](https://github.com/okteto/movies) on an Okteto instance: [![Develop on Okteto](https://okteto.com/develop-okteto.svg)](https://okteto.example.com/deploy?repository=https://github.com/okteto/movies) ### Adding the Develop on Okteto button There are two ways of referencing the source code repository: * Resolve it implicitly. This is useful in GitHub `README.` files. If you don't specify the repository, Okteto will infer it using the `referrer` header. This only works on public repositories hosted in . * Using the `repository` and `branch` parameters. This is useful for buttons hosted outside of , in blog posts, or documentation. #### Using an implicit repository If you're embedding the button in a public GitHub repository's `README` file, Okteto will automatically infer the repository and the branch using the referrer header when someone clicks on the button. Here's an example: ``` [![Develop on Okteto](https://okteto.com/develop-okteto.svg)](https://okteto.example.com/deploy) ``` And here's the equivalent content as HTML if you prefer that: ``` Develop on Okteto ``` A `develop-okteto.png` is also available. #### Adding explicit parameters Use the following Markdown snippet as a template, changing the `repository` and `branch` query parameters to match your repository. The `branch` query parameter is optional. ``` [![Develop on Okteto](https://okteto.com/develop-okteto.svg)](https://okteto.example.com/deploy?repository=https://github.com/okteto/movies&branch=main) ``` And here's the equivalent content as HTML if you prefer that: ``` Develop on Okteto ``` ### Parameters You can parametrize your development environment deployment using the following parameters: * `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 available on your deployment: `THEME=dark` and `LANG=en`. It has to be URL encoded. * `filename`: The location of the [Okteto Manifest](/docs/reference/okteto-manifest.md) relative to the root of the repository. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Develop On Okteto Button The **Develop on Okteto** button is a shortcut to deploy your development environments with a single click. The button is designed to be used in Git `README` files, documentation sites, or pretty much anywhere that renders an html file. Use this instead of writing a never-ending list of manual steps on how to deploy your development environments. Here's an example button that deploys [the Movies App](https://github.com/okteto/movies) using Okteto: [![Develop on Okteto](https://okteto.com/develop-okteto.svg)](https://okteto.example.com/deploy?repository=https://github.com/okteto/movies) ### Requirements The basic requirements for creating the button are that your application can be deployed in Okteto, and that the application's source code is hosted in a public Git repository. The easiest way to validate this is to follow the instructions in the [Deploy from Git](/docs/development/deploy/deploy-from-git.md) document. ### Adding the Develop on Okteto button There are two ways of referencing the source code repository: * Resolve it implicitly. This is useful in GitHub `README.` files. If you don't specify the repository, Okteto will infer it using the `referrer` header. This only works on public repositories hosted in . * Using the `repository` and `branch` parameters. This is useful for buttons hosted outside of , in blog posts or documentation. #### Using an implicit repository If you're embedding the button in a public GitHub repository's `README` file, Okteto will automatically infer the repository and the branch using the referrer header when someone clicks on the button. Here's an example: ``` [![Develop on Okteto](https://okteto.com/develop-okteto.svg)](https://okteto.example.com/deploy) ``` And here's the equivalent content as HTML if you prefer that: ``` Develop on Okteto ``` A `develop-okteto.png` is also available. #### Adding explicit parameters Use the following Markdown snippet as a template, changing the `repository` and `branch` query parameters to match your repository. The `branch` query parameter is optional. ``` [![Develop on Okteto](https://okteto.com/develop-okteto.svg)](https://okteto.example.com/deploy?repository=https://github.com/okteto/movies&branch=main) ``` And here's the equivalent content as HTML if you prefer that: ``` Develop on Okteto ``` ### Parameters You can parametrize your deployment using the following parameters: * `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 that are available on your deployment: `THEME=dark` and `LANG=en`. It has to be URL encoded. * `filename`: The location of the [Okteto manifest](/docs/core/okteto-manifest.md) relative to the root of the repository. If not set, one of the [deployment related manifests](/docs/core/okteto-manifest.md) will be used. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # From private repositories ## GitHub Private Repositories 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. 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](/docs/admin/private-repositories/github-app.md). ### Connect your GitHub account This is a one-time setup. Once complete, Okteto will remember your GitHub permissions across sessions. 1. Log into your Okteto instance 2. Click on the "**Deploy Dev Environment**" button on the top 3. Make sure "**GitHub**" is the selected source 4. Click on the **Configure GitHub** or **+ Add repositories** 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. ![GitHub dialog to install the Okteto App on your accounts and organizations](/docs/assets/images/private-repositories-enable-ad71f1f7579e327643595f4584e7e40c.png) 5. Finally click on the **Install & Authorize** button to proceed. If you're not the administrator of the organization, GitHub will send an email notification to your administrator and wait for their authorization to complete the installation and grant you access. ![install and authorize repositories](/docs/assets/images/private-repositories-authorize-1103312658b46b9cc600569b209c60cd.png) Once you or your administrator grants permission, Okteto will automatically list your private and public repositories in the **Deploy** dialog. Private repositories will be identified by a "lock" icon on right side. ![list of private repositories](/docs/assets/images/private-repositories-list+1.42-84aa7c2a951ea60d7ebc4f98abcdd12f.png) ### Deploy from a Private GitHub Repository After connecting your GitHub account, you'll be able to deploy from any of your public or private repositories [using an Okteto Manifest](/docs/reference/okteto-cli.md#deploy). ## Other Private Repositories You can also use `SSH` authentication to deploy a private repository. To do this, use the `SSH` url of your git repository. This applies both when using the [`Deploy`](/docs/development/deploy/deploy-from-git.md) dialog in the Okteto UI and the [`okteto pipeline deploy`](/docs/reference/okteto-cli.md#deploy) command from your terminal. ![Deploy Dev Environment dialog with Git URL source selected and an SSH repository URL entered](/docs/assets/images/private-repository+1.42-d15c070abb9f2a2fb15d85ea480b7a89.png) [This document](/docs/admin/private-repositories/ssh-key.md) has more information on how to configure access to the private repository in your source code provider. note Using SSH with any Git provider (GitHub, GitLab, Bitbucket, Azure DevOps, or self-hosted)? Your Okteto admin can centrally manage trusted hosts via [SSH Known Hosts](/docs/admin/ssh-known-hosts.md). This helps avoid host key verification failures during remote deploys and submodule operations. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Development images Development images allow you to configure the runtime of your Development Containers. Instead of having to keep a wiki with a never-ending list of tools, dependencies, and scripts to install and run, you can pack all of it in the development images of your Development Containers. ## Overview At a high level, a development image is a Docker container image that contains: * One or more language runtimes (e.g python, ruby, node) * SDKs for your language runtime (e.g JDK, python-dev) * Binary dependencies (e.g. openssl, git) * Tools to manage and install dependencies (e.g. pip, bundler, yarn) * Tools to run your tests and analyze your code (e.g nosetest, pylint) * Your source code Out of the box, Okteto maintains pre-configured development images in this [GitHub repository](https://github.com/okteto/devenv) for the following languages: * dotnetcore * golang * java * node * php * python * ruby * rust ## Create your own The default development images are a great way to start. They use the latest official docker images for your language runtime and include the most common developer tools and a custom bash prompt. But they might not have everything you need. Your team might need to support a very specific version of your runtime, or you might need some extra tooling available. Do the following to create your own development image: 1. Create a Dockerfile 2. Pick a base image 3. Add your extra dependencies, tools, and files 4. Build your image in the [build](/docs/core/okteto-manifest.md#build) section of the Okteto manifest 5. Update the `image` key in your `okteto.yaml` with your new image using the [OKTETO\_BUILD\_XXX](/docs/core/okteto-variables.md#built-in-environment-variables-for-images-in-okteto-registry) variables Besides following [Docker's best practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/), we also recommend the following: * Pin all your dependencies, so there aren't any surprises * Keep the Dockerfile in your repository, next to your code * When using [multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/), use your builder stage to build your development image --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # 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) ``` 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 | 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: ``` 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](/docs/reference/okteto-manifest.md#divert). ## Project Structure Patterns ### Single Service Development For working on a single service, create a dedicated manifest: ``` # 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: ``` # 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: ``` 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) ``` 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 ``` 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 ``` @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) ``` 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: ``` # 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: ``` 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: ``` 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: ``` // 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: ``` // 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: ``` // 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: ``` # 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: ``` // 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: ``` 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](/docs/core/divert.md)** - Understanding Divert architecture * **[Divert Tutorial](/docs/tutorials/divert.md)** - Step-by-step getting started guide * **[Manifest Reference](/docs/reference/okteto-manifest.md#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 --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Using the Okteto CLI 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](/docs/get-started/install-okteto-cli.md). The Okteto CLI requires one of the following manifests to know how to deploy your application: 1. [Okteto manifest](/docs/core/okteto-manifest.md): if there is an `okteto.yml` or `.okteto/okteto.yml` file in your folder, Okteto will use this file to deploy your application 2. [Docker Compose](/docs/reference/docker-compose.md): if there is an `okteto-compose.yaml`, `docker-compose.yaml` or `compose.yaml` file, Okteto will use this file to deploy your application note You can use the `-f` flag on any Okteto CLI command to explicitly define the location of an Okteto Manifest. If you do not yet have an Okteto Manifest, we recommend to follow this tutorial to [create your first Okteto Manifest](/docs/get-started/deploy-your-app.md). If you have a Docker Compose file, the Okteto CLI can directly deploy your application without generating an Okteto Manifest. However, you can still choose to create an Okteto Manifest [referring to your Docker Compose file](/docs/reference/okteto-manifest.md#deploy-with-compose) if you want more control over the configuration of your Development Environment. You can find our full [CLI reference guide here ->](/docs/reference/okteto-cli.md) Now that you know more about the Okteto CLI, let's introduce the concept of [Development Containers](/docs/development/containers.md) 😎 --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Advanced Commands & Concepts for Developers ## Advanced CLI Commands | Command | Description | | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [`okteto namespace`](/docs/reference/okteto-cli.md#namespace) | Allows you to manage namespaces by using commands like `create`, `delete`, `use`, and more | | [`okteto exec`](/docs/reference/okteto-cli.md#exec) | Allows you to execute a command in your development container. `okteto exec [devName] -- COMMAND` | | [`okteto destroy`](/docs/reference/okteto-cli.md#destroy) | Destroys a currently deployed Development Environment. Note that this does not destroy persistent volumes that were created for that Development Environment, to do so, pass the `-v` flag | | [`okteto logs`](/docs/reference/okteto-cli.md#logs) | Used to view the logs of a Development Environment | | [`okteto endpoints`](/docs/reference/okteto-cli.md#endpoints) | Used to view your application’s HTTPS URLs automatically generated by Okteto | | [`okteto doctor`](/docs/reference/okteto-cli.md#doctor) | Generates a `doctor file` with the okteto logs for a given Development Container. This file can be useful when asking Okteto support for help | | [`okteto status`](/docs/reference/okteto-cli.md#status) | Shows the status of the file synchronization process for a given Development Container | A list of all available CLI commands is in our full [CLI reference guide here ->](/docs/reference/okteto-cli.md) ### Commonly Used CLI Flags * **`okteto deploy --dependencies`**: Re-deploys dependencies defined in your okteto manifest * **`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, excluding resources annotated with `dev.okteto.com/policy: keep` ## Concepts to Understand ### Namespaces Namespaces in Okteto are where Development Environments get deployed. Each developer starts with a personal Namespace which has the same name as their account but can create as many different Namespaces as they need. A Namespace can be used for varying durations depending on your needs—ranging from a few weeks for developing a feature to just a couple of days for fixing a bug. Namespaces provide a dedicated environment for isolated development, and they can also be [shared among team members](/docs/core/namespaces.md#sharing-and-collaboration-with-namespaces) to collaborate on work before pushing changes to Git. However, many developers prefer to use a single namespace as a replacement for their local environment. In this workflow, instead of creating a new namespace for each feature or bug fix, they switch branches within the same namespace to work on different tasks. This approach mirrors the traditional local development process and eliminates the need to reinitialize data for each new namespace. When switching branches, it's important to ensure your environment is up-to-date. If your changes involve only code, running `okteto up` is sufficient to sync your changes. However, if the branches include changes to manifest files, you'll need to run `okteto deploy` to fully apply the updates. This flexibility allows you to choose the workflow that best fits your development process, whether it's using separate namespaces for isolation or a single namespace for continuity and efficiency. [Read the full Namespace documentation here ->](/docs/core/namespaces.md) ### Development Environments Development Environments enable developers to create applications in the cloud without having to worry about Kubernetes. Everything is pre-configured in the [Okteto Manifest](/docs/core/okteto-manifest.md). This way developers spend less time troubleshooting their Development Environment and more time coding cool features. [Read the full Development Environment documentation here ->](/docs/development.md) ### Development Containers Okteto makes it easier to develop on Kubernetes by using Development Containers. They allow you to hot reload and debug your Development Environments as fast as you write code 🚀 Development Containers can be run in two different modes: * [**File Sync Development Mode**](/docs/development/containers/file-sync.md): Syncs your local changes to your remote development container (default mode). * [**Hybrid Development Mode**](/docs/development/containers/hybrid.md): Runs your service locally and simulates your laptop belonging to the cluster network by using SSH tunnels. This may be helpful if you work with large file sizes in part of your application. Okteto Code Sync does not run while using hybrid mode since the changes are built locally. [Read the full Development Container documentation here ->](/docs/development/containers.md) ### Development Images Development images define the runtime your application runs in during development, ensuring consistency and reproducibility across different stages of your workflow, developers, and different local machines. [Read the full Development Image documentation here ->](/docs/development/images.md) ### Variables Environment variables are useful for storing user-specific configuration values that are not shared with the rest of the team. They can also be useful when you need to specify ad-hoc variables at [the time of deployment](/docs/core/okteto-variables.md#deployment-variables). [Read the full Okteto Variables documentation here ->](/docs/core/okteto-variables.md#user-variables) ### Okteto Preview Environments Okteto's Preview Environments automatically generate a unique, shareable version of your application for each pull request, making code reviews, automated end-to-end testing, and stakeholder feedback a breeze. Your platform team will need to set up Preview Environments if they are not already configured. [Read the full Preview Environment documentation here ->](/docs/previews.md) ## FAQ **When does `okteto deploy` look at the Git repo vs my own code?** * `okteto deploy` uses the code from your Git repository to deploy the application. After running `okteto up`, Okteto’s file sync will update your changes remotely **What’s the difference between `okteto up` and `okteto up --deploy`?** * `okteto up` creates the Development Environment of a service based on its previously deployed version. * `okteto up --deploy` runs the `okteto deploy` section first, picking up any new changes from the repository, and then connects to the Development Environment. **What does `okteto deploy --no-build` do?** * This command skips the re-build of the images in your okteto manifest. By default, `okteto deploy` rebuilds all images to make sure your development environment incorporates all your local changes. ## Additional Support and Help Getting Started * Follow this [tutorial to write your first Okteto Manifest](/docs/get-started/deploy-your-app.md) * 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 --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Deploy Your Application to Okteto This guide explains how to write your first Okteto Manifest and deploy your app to Okteto. ## Requirements Before you start this tutorial, make sure you fulfill the following requirements: * You have access to an Okteto instance. Otherwise, follow our [installation guide](/docs/get-started/install.md) * You have [installed the Okteto CLI](/docs/get-started/install-okteto-cli.md) and configured the Okteto Context with your Okteto instance ## What you will be building This tutorial will guide you on how to deploy the [Movies app](https://github.com/okteto/getting-started) to Okteto. The Movies app consists of: * a React frontend * a Node.js backend API * a MongoDB database This is a representation of the Movies app running in a Development Environment: ![Movies app architecture](/docs/assets/images/deploy-movies-app-1fd90c893dce8909ba942f53206b1293.png) In order to deploy the Movies app, you will create your first [Okteto Manifest](/docs/core/okteto-manifest.md). This is what your Okteto Manifest will look like at the end of the tutorial: okteto.yaml ``` build: api: context: api frontend: context: frontend dependencies: mongodb: repository: https://github.com/okteto/mongodb wait: true variables: MONGODB_PASSWORD: password deploy: - name: Helm Install command: | helm upgrade --install movies chart \ --set api.image=${OKTETO_BUILD_API_IMAGE} \ --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE} ``` This guide will take you through the following sections: * `deploy`: Configure a list of commands to deploy your application * `dependencies`: Configure a list of git repositories to deploy as part of your application * `build`: Configure a list of images to build for your application Now that you know what your are building, [start the tutorial](/docs/get-started/deploy-your-app/deploy.md) and deploy your app to Okteto 😎 --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Build your container images with Okteto The Movies app is using pre-built images to deploy your Development Environment. In this step you will use Okteto to build these images on demand in order to deploy the latest bits of your application. To instruct Okteto to build your images, add the following content to the `okteto.yaml` file: okteto.yaml ``` build: api: context: api frontend: context: frontend ``` The build context for the `api` image is in the `api` folder and Okteto will build the `api` image using the `api/Dockerfile`. The `frontend` images work in a similar way. Now you can build your images with `okteto build`: ``` okteto build ``` ``` i Using cindy @ okteto.example.com as context i Building 'api/Dockerfile' in tcp://buildkit.okteto.example.com:443... ... ✓ Image 'registry.okteto.example.com/cindy/movies-with-helm-api:okteto' successfully pushed i Building 'frontend/Dockerfile' in tcp://buildkit.okteto.example.com:443... ... ✓ Image 'registry.okteto.example.com/cindy/movies-with-helm-frontend:okteto' successfully pushed ``` Finally, update your `deploy` section in your `okteto.yaml` file to use these images in the helm installation. To do that, use the `OKTETO_BUILD_<>_IMAGE` environment variables to access to the dynamic tag generated by Okteto for your container images: note Read more about Okteto's [built-in environment variables](/docs/core/okteto-variables.md#built-in-environment-variables-for-images-in-okteto-registry) for images okteto.yaml ``` deploy: - name: Helm Install command: | helm upgrade --install movies chart \ --set api.image=${OKTETO_BUILD_API_IMAGE} \ --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE} ``` Deploy the Movies app to apply the changes: ``` okteto deploy ``` ``` i Using cindy @ okteto.example.com as context i Deploying dependency 'mongodb' ✓ Skipping repository 'mongodb' because it's already deployed i Okteto Smart Builds is skipping build of 'api' because it's already built from cache. i Okteto Smart Builds is skipping build of 'frontend' because it's already built from cache. i Okteto recommends that you enable remote execution for your deploy commands. i Running 'Helm Install' Release "movies" does not exist. Installing it now. NAME: movies LAST DEPLOYED: Fri Jan 19 23:54:00 2024 NAMESPACE: cindy STATUS: deployed REVISION: 2 TEST SUITE: None NOTES: Success! Your application will be available shortly. i Endpoints available: - https://movies-cindy.okteto.example.com - https://movies-cindy.okteto.example.com/api ✓ Development environment 'movies' successfully deployed ``` ## Next Steps Congratulations! You successfully deployed your first application to Okteto 🚀 Now, here’s what you can explore next: * Discover about [Development Environments](/docs/development.md) to use Okteto for a joyful development experience * Configure [Preview Environments](/docs/previews.md) to automatically share, test and validate your changes on every pull/merge request * Check out our [Developers Quickstart](/docs/get-started/dev-quickstart.md) guide to see how developers can make the most of Okteto --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Add a database as a dependency The Movies app requires an instance of MongoDB to be running in your Development Environment. You could deploy MongoDB as part of your `deploy` section in the `okteto.yaml` file, but in this case, you are going to use the repo as a dependency. This repo is already pre-configured with a Docker Compose file to deploy MongoDB in Okteto. To instruct Okteto to deploy this repository in your Development Environment, add the following section to your `okteto.yaml` file: okteto.yaml ``` dependencies: mongodb: repository: https://github.com/okteto/mongodb wait: true variables: MONGODB_PASSWORD: password ``` The `wait` flag instructs Okteto to wait until MongoDB is ready before running the deploy commands. 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 different ways to define [Okteto Variables here](/docs/core/okteto-variables.md) 😎 Deploy the Movies app to apply the changes: ``` okteto deploy ``` ``` i Using cindy @ okteto.example.com as context i Deploying dependency 'mongodb' ... ✓ Repository 'mongodb' successfully deployed i Running 'Helm Install' Release "movies" does not exist. Installing it now. NAME: movies LAST DEPLOYED: Fri Jan 19 23:54:00 2024 NAMESPACE: cindy STATUS: deployed REVISION: 2 TEST SUITE: None NOTES: Success! Your application will be available shortly. i Endpoints available: - https://movies-cindy.okteto.example.com - https://movies-cindy.okteto.example.com/api ✓ Development environment 'movies' successfully deployed ``` You can see that MongoDB is now running from the Okteto UI: ![Movies Onboard MongoDB](/docs/assets/images/movies-mongodb-ui+1.32-96bbab9e116cc13259c7df17ee50bd80.png) And the `seed` job has now successfully initialized the MongoDB data. note Running seed data scripts can be slow with real world databases. For those scenarios, you can use our [Volume Snapshots](/docs/core/use-volume-snapshots.md) feature to clone this data from an existing database in seconds 🚀 ## Next Steps But the Okteto CLI is informing us that `There are no available endpoints for 'movies'`... Let's [create endpoints for your app](/docs/get-started/deploy-your-app/endpoints.md) in the next step of this guide 😎 --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Deploy your application For this tutorial, you will be using our getting started sample app. Start by cloning the following repo: ``` git clone https://github.com/okteto/getting-started cd getting-started ``` The Movies app comes with a Helm chart to deploy the application on Kubernetes. To instruct Okteto to deploy the Movies app, create an `okteto.yaml` file at the root of the repo with the following content: okteto.yaml ``` deploy: - name: Helm Install command: helm upgrade --install movies chart ``` The meaning of these fields is: * `deploy`: it's a list of commands to deploy your application. Every command has the following fields: * `name`: a name to label your command * `command`: the command to be executed Now deploy the Movies app by running the following command: ``` okteto deploy ``` ``` i Using cindy @ okteto.example.com as context i Running 'Helm Install' Release "movies" does not exist. Installing it now. NAME: movies LAST DEPLOYED: Fri Jan 19 23:54:00 2024 NAMESPACE: cindy STATUS: deployed REVISION: 2 TEST SUITE: None NOTES: Success! Your application will be available shortly. i There are no available endpoints for 'movies'. Follow this link to know more about how to create public endpoints for your application: https://www.okteto.com/docs/core/ingress/automatic-ssl ✓ Development environment 'movies' successfully deployed ``` Confirm that the Movies app is up and running by logging into the Okteto UI: ![Movies Onboard Deploy](/docs/assets/images/movies-deploy-ui+1.32-4e9b25c0412fd226e6d57a7f80e6f016.png) Or by configuring your Kubernetes credentials to access your Development Environment: ``` okteto kubeconfig ``` ``` Updated kubernetes context 'okteto_example_com/cindy' in '[/Users/cindy/.kube/config]' ``` And using `kubectl` to visualize how your Development Environment looks in Kubernetes: ``` kubectl get all ``` ``` NAME READY STATUS RESTARTS AGE pod/api-689448db78-flf7j 1/1 Running 0 2m12s pod/frontend-d564c895-tvg65 1/1 Running 0 2m12s pod/seed-djt25 1/1 Running 0 2m11s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/api ClusterIP 10.7.255.99 8080/TCP 2m13s service/frontend ClusterIP 10.7.246.60 80/TCP 2m13s NAME READY UP-TO-DATE AVAILABLE AGE deployment.apps/api 1/1 1 1 2m13s deployment.apps/frontend 1/1 1 1 2m13s NAME DESIRED CURRENT READY AGE replicaset.apps/api-689448db78 1 1 1 2m13s replicaset.apps/frontend-d564c895 1 1 1 2m13s NAME COMPLETIONS DURATION AGE job.batch/seed 0/1 2m13s 2m13s ``` ## Next Steps Awesome, you have deployed the Movies app to Okteto 🚀 Looks like there is still an issue with the Movies app. The `seed` job keeps processing, and if you check the logs of the **api** Kubernetes Deployment: ``` okteto logs api ``` ``` i Using cindy @ okteto.example.com as context api-646fdf88d6-267sn › api api-646fdf88d6-267sn api yarn run v1.22.19 api-646fdf88d6-267sn api $ nodemon server.js api-646fdf88d6-267sn api [nodemon] 2.0.4 api-646fdf88d6-267sn api [nodemon] to restart at any time, enter `rs` api-646fdf88d6-267sn api [nodemon] watching path(s): *.* api-646fdf88d6-267sn api [nodemon] watching extensions: js,mjs,json api-646fdf88d6-267sn api [nodemon] starting `node server.js` api-646fdf88d6-267sn api Error connecting, retrying in 1 sec: MongoServerSelectionError: getaddrinfo ENOTFOUND mongodb api-646fdf88d6-267sn api Error connecting, retrying in 1 sec: MongoServerSelectionError: getaddrinfo ENOTFOUND mongodb ... ``` Or from the Okteto UI, you can see that the **api** is failing to connect to MongoDB... This is expected because you didn't deploy a MongoDB instance yet, let's [configure the MongoDB dependency](/docs/get-started/deploy-your-app/dependencies.md) in the next step of this guide 😎 --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Expose your application on a public endpoint In this step you will learn how to expose your application using Okteto Endpoints. In order to create endpoints for your application, you need to add the following annotation to your [Ingress](https://github.com/okteto/getting-started/blob/main/chart/templates/ingress.yaml) resource: ingress.yaml ``` annotations: dev.okteto.com/generate-host: "true" ``` The Ingress object, located in the file `chart/templates/ingress.yaml`, will look like this after this change: ingress.yaml ``` apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: movies annotations: dev.okteto.com/generate-host: "true" spec: rules: - http: paths: - path: / pathType: Prefix backend: service: name: frontend port: number: 80 - path: /api pathType: Prefix backend: service: name: api port: number: 8080 ``` This instructs Okteto to create an endpoint in the [Okteto Subdomain](/docs/self-hosted/helm-configuration.md#subdomain). For example, if your Ingress name is `movies` in the `cindy` namespace, your app will be accessible at if your Okteto domain is okteto.example.com. Deploy the Movies app to apply the changes: ``` okteto deploy ``` ``` i Using cindy @ okteto.example.com as context i Deploying dependency 'mongodb' ✓ Skipping repository 'mongodb' because it's already deployed i Running 'Helm Install' Release "movies" does not exist. Installing it now. NAME: movies LAST DEPLOYED: Fri Jan 19 23:54:00 2024 NAMESPACE: cindy STATUS: deployed REVISION: 2 TEST SUITE: None NOTES: Success! Your application will be available shortly. i Endpoints available: - https://movies-cindy.okteto.example.com - https://movies-cindy.okteto.example.com/api ✓ Development environment 'movies' successfully deployed ``` Notice how the endpoints are now shown by the Okteto CLI. You can also see the endpoints within the Okteto UI. Endpoints will only be present when a service reaches the "running" stage. ![Movies Onboard Endpoints](/docs/assets/images/movies-endpoints-ui+1.32-19374d43f02c8a30b882e459fc56e483.png) note Learn more about [how to configure Okteto Endpoints](/docs/core/endpoints/automatic-ssl.md) Finally, you can access the endpoint of the Movies app to see something like this: ![UI showing the movies app](/docs/assets/images/next-ui-movies-c2141cc02c5df37615f75a870206f797.png) ## Using Endpoints with Docker Compose If you're using Docker Compose instead of Kubernetes manifests, you can expose your application using the `endpoints` section directly in your `docker-compose.yml` file: docker-compose.yml ``` services: frontend: build: ./frontend ports: - 3000:3000 api: build: ./api ports: - 8080:8080 endpoints: - path: / service: frontend port: 3000 - path: /api service: api port: 8080 ``` When you run `okteto deploy`, your application will be accessible at URLs like `https://movies-cindy.okteto.example.com`. note Learn more about [configuring endpoints with Docker Compose](/docs/reference/docker-compose.md#endpoints-object-optional) ## Next Steps The Movies app is using pre-built images to deploy your Development Environment... This is not ideal since you won't be able to deploy your local changes, let's [build the images of the Movies app](/docs/get-started/deploy-your-app/build.md) in next step of this guide 😎 --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Using Okteto as a Developer ## Introduction Welcome to the Okteto Quick Start Guide! This guide will help you, as a developer, get started with Okteto in a few steps. Once your platform team has set up Okteto and configured your account, you can follow this guide to deploy your Development Environments and start coding in no time. [Okteto Developer Quickstart Guide](https://www.youtube.com/embed/eEJWJObxM2I?si=Q8MV1MEQ1WZa93YQ) ## Step 1: Sign In to Okteto 1. Open your web browser and navigate to your Okteto instance URL. It should look something like `https://okteto.example.com` 2. Sign in using the authentication method configured by your organization (e.g., GitHub, SSO). ## Step 2: Explore Your Namespace * After logging in, you will see your personal Namespace. This Namespace is automatically created by Okteto and is named after your account name or email. * Namespaces in Okteto are used to deploy your Development Environments. You can create as many Namespaces as you need by clicking on the “New Namespace” button that appears when you click on the Namespace dropdown in the top left corner. ## Step 3: Deploy a Development Environment 1. Click the **Deploy Dev Environment** button in the Okteto UI. 2. The Okteto Catalog will appear. This catalog contains a list of pre-configured applications provided by your organization’s platform team. A dev environment in Okteto is a version of your application deployed to a Namespace which syncs your local code with the code running on the cloud. 3. From the Okteto Catalog, select the application you want to develop. Okteto will begin deploying the chosen application. 4. Once the application is deployed, your dev environment is ready. Okteto will create endpoints for all the microservices and external resources (if configured by the platform team) as part of your application and give you the links view them. ## Step 4: Install the Okteto CLI 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](/docs/get-started/install-okteto-cli.md) before continuing this guide. ## Step 5: Configure the Okteto CLI The first thing you need to do before using the Okteto CLI is to set the Okteto CLI context with your Okteto instance. Open a terminal and point the Okteto CLI to your Okteto instance by running (replace `https://okteto.example.com` with your Okteto instance URL): ``` okteto context use https://okteto.example.com ``` You’ll be taken to the browser and asked to authenticate. Once that is done, Okteto CLI is configured and ready to be used with your development environments. ## Step 6: Start Your Development Container 1. Clone the repository of the application you deployed in step 3 to your local machine. 2. Open the cloned repository in your favorite code editor (Okteto supports any code editor and other tools you prefer). 3. In the terminal, navigate to the application’s directory. 4. Start the development container by running: ``` okteto up ``` 5. You will be prompted to select the microservice you want to work on. Choose the appropriate service to proceed. 6. If you need to work on multiple services simultaneously, you can launch another `okteto up` session in a different terminal window. ## Step 7: Begin Development 1. Once the Development Container is up, you will have terminal access inside of the Development Container. 2. From the terminal, execute the appropriate command to start your application. For instance, if you're working on the frontend service of a React-based application: ``` yarn start ``` ## Step 8: Sync Code, Debug and View Changes * The Development Container syncs all your local code changes with your application running on Okteto. * Your code is executing in Okteto, but you can debug it and add breakpoints from your favorite IDE without any extra tools * Any changes you make locally will be reflected in the endpoints shown in the Okteto UI, allowing you to see your changes in a production-like environment instantly. ## Benefits of Using Okteto * **No Configuration Required**: You can start writing code immediately using the pre-configured applications in the Okteto catalog. * **Resource Efficiency**: You are not limited by your local machine’s resources when running resource-intensive services and applications. * **Immediate Feedback**: You can see your changes running in a production-like environment as soon as you write code, without waiting for CI, staging, or test environments. ## Next Steps Dive into learning about Okteto by following our [CLI and Dashboard guide here](/docs/get-started/using-okteto-cli-and-dashboard.md). If your application doesn't have an Okteto Manifest yet, follow this [tutorial to deploy your first app to Okteto](/docs/get-started/deploy-your-app.md). Happy coding! --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Install the Okteto CLI 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. ## Installing the Okteto CLI Install the Okteto CLI following these steps: ### MacOS / Linux ``` curl https://get.okteto.com -sSfL | sh ``` If you need a specific version you can set the OKTETO\_VERSION environment variable: ``` curl https://get.okteto.com -sSfL | OKTETO_VERSION=3.21.0 sh ``` You can also install it via [brew](https://brew.sh/) by running: ``` brew install okteto ``` ### Windows Download and add it to your `$PATH`. You can also install it via [scoop](https://scoop.sh/) by running: ``` scoop install okteto ``` tip For updating okteto with scoop, you might need to `scoop unhold okteto & scoop update okteto` or `scoop uninstall okteto & scoop install okteto` ### GitHub Alternatively, you can directly download the binary [from GitHub](https://github.com/okteto/okteto/releases) or build it directly from the source code. ## Next Steps In this section you installed the Okteto CLI on your machine 🚀 If you are a developer and Okteto is already installed in your cluster, jump to the [Developers Quickstart](/docs/get-started/dev-quickstart.md) guide. If you are a platform engineer looking to install Okteto in your cluster, jump to our [Okteto SH installation](/docs/get-started/install.md) guides. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Installation Overview info If you are using Okteto's Bring Your Own Cloud (BYOC) offering, you can ignore this page and jump into the [Developers Quickstart guide](/docs/get-started/dev-quickstart.md). To start using the Okteto Platform you’ll need to install the Okteto Helm Chart in your Kubernetes cluster. These cloud-specific guides will walk you through deploying the Okteto Helm chart with default values and a basic configuration: * [Install Okteto in Amazon Elastic Kubernetes Service](/docs/get-started/install/amazon-eks.md) * [Install Okteto in Civo](/docs/get-started/install/civo.md) * [Install Okteto in DigitalOcean Kubernetes](/docs/get-started/install/digitalocean-doks.md) * [Install Okteto in Google Kubernetes Engine](/docs/get-started/install/google-gke.md) * [Install Okteto in Microsoft Azure Kubernetes Service](/docs/get-started/install/microsoft-aks.md) * [Install Okteto in Red Hat OpenShift](/docs/get-started/install/openshift.md) ## Video Tutorials If you need help installing Okteto on your Kubernetes cluster, we have a playlist of videos guiding you through each of the installation steps. Check them out here: [YouTube video player](https://www.youtube.com/embed/videoseries?list=PLVcXGaCKg-Y0XGujg_G7vCIGd_JEAQ4Sq) ## Supported Browsers The Okteto Dashboard is optimized for the following browsers: * **Google Chrome**: Last 8 versions * **Mozilla Firefox**: Last 8 versions * **Microsoft Edge**: Last 8 versions * **Safari**: Last 2 major versions (macOS only) **Note:** The Okteto UI is designed for desktop only and doesn't support mobile browsers. For users installing Okteto in air-gapped environments, ensure that all users have one of the supported browser versions to avoid compatibility issues. ## Troubleshooting We've done our best to make Okteto easy to install and operate. [The troubleshooting page](/docs/self-hosted/manage/troubleshooting.md) has tips and tricks to help troubleshoot common issues. You can also [reach out to support](https://okteto.com/support) if you need assistance. ## Uninstalling Okteto To delete an existing release use: ``` helm uninstall okteto ``` This will delete Okteto, but not the resources created when using it (e.g. namespaces, accounts, deployments, etc...). --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Amazon Elastic Kubernetes Service (EKS) This guide will walk you through the process of installing Okteto in Amazon Elastic Kubernetes Service (EKS). ## Installation Requirements Before you start, make sure you have the following CLIs installed in your machine: * `okteto` >= 3.21.0 ([okteto installation guides](/docs/get-started/install-okteto-cli.md)) * `eksctl` >= 0.201 ([eksctl installation guides](https://eksctl.io/installation/)) * `aws` >= 2.15 ([aws installation guides](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions)) * `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 * A Kubernetes cluster warning **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](/docs/self-hosted/helm-configuration.md#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](/docs/self-hosted/manage/troubleshooting.md#daemon-fails-with-open-etchosts-permission-denied) for more details. ## 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](/docs/self-hosted/helm-configuration.md#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. This guide assumes your domain is registered in [Amazon Route53](https://aws.amazon.com/route53/) service. You can use any DNS service you prefer, but this guide focuses specifically on Amazon Route53. ## Deploy a Kubernetes cluster Our installation guides assume Okteto will be running in a new dedicated cluster. note If you plan on installing Okteto in an existing cluster with other workloads, we recommend to read this section to make sure your cluster satisfies the requirements to install Okteto ### Setting up environment variables We recommend configuring the following environment variables to help you scripting the cluster creation: Your Kubernetes cluster version: ``` export K8S_VERSION="1.35" ``` note Okteto supports Kubernetes versions 1.33 through 1.35. Your Kubernetes cluster name: ``` export CLUSTER_NAME="okteto" ``` Your AWS Account ID: ``` export AWS_ACCOUNT_ID="$(aws sts get-caller-identity --query "Account" --output text)" ``` Your AWS Region: ``` export AWS_REGION="$(aws configure get region)" ``` Disable AWS CLI pagination (optional): ``` export AWS_PAGER="" ``` ### Create the Cluster For initial evaluation, we recommend a Kubernetes cluster with a pool of 3 `m5.xlarge` nodes with 250 GB each: 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](/docs/self-hosted/manage/arm-support.md) for full details and requirements. ``` eksctl create cluster -f - < ``` eksctl create cluster -h | grep 'Kubernetes version' ``` * Check the [available versions](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html) for AWS EKS service. * Verify the [supported K8s versions](/docs/release-notes.md) for the Okteto Helm chart version you plan to install. Follow Amazon's [cluster creation guide](https://docs.aws.amazon.com/eks/latest/userguide/create-cluster.html) for more details. ### Create EBS CSI Addon IAM Role Okteto requires the EBS CSI Addon to be able to create persistent volumes. Okteto uses persistent volumes to persist the cache of the [Okteto Build](/docs/core/build-service.md) service (buildkit). The default installation also uses persistent volumes to store your container images in the [Okteto Registry](/docs/core/container-registry.md). To install the EBS CSI Addon in your Kubernetes cluster, you need to create the EBS CSI Addon's IAM Role first: ``` eksctl create iamserviceaccount \ --region="${AWS_REGION}" \ --name="ebs-csi-controller-sa" \ --namespace="kube-system" \ --cluster="${CLUSTER_NAME}" \ --role-name="${CLUSTER_NAME}-ebs-csi-driver-role" \ --role-only \ --attach-policy-arn="arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy" \ --approve ``` Refer to the [AWS official documentation](https://docs.aws.amazon.com/eks/latest/userguide/csi-iam-role.html) for more details. ### Deploy EBS CSI Addon Once you have the EBS CSI IAM Role created, deploy the EBS CSI Addon with the following command: ``` eksctl create addon \ --region="${AWS_REGION}" \ --name="aws-ebs-csi-driver" \ --cluster="${CLUSTER_NAME}" \ --service-account-role-arn="arn:aws:iam::${AWS_ACCOUNT_ID}:role/${CLUSTER_NAME}-ebs-csi-driver-role" \ --force ``` Refer to the [AWS official documentation](https://docs.aws.amazon.com/eks/latest/userguide/managing-ebs-csi.html#adding-ebs-csi-eks-add-on) for more details. ### Create a Storage Class for the EBS CSI Addon Create a Storage Class for the EBS CSI Addon: ``` cat < **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Civo This guide will walk you through the process of installing Okteto in Civo's Kubernetes Service. ## Installation Requirements Before you start, make sure you have the following CLIs installed in your machine: * `okteto` >= 3.21.0 ([okteto installation guides](/docs/get-started/install-okteto-cli.md)) * `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 * A Kubernetes cluster ## 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](/docs/self-hosted/helm-configuration.md#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. This guide assumes your domain is registered in [Civo DNS](https://www.civo.com/account/dns). You can use any DNS service you prefer, but this guide focuses specifically on Civo DNS. ## Deploy a Kubernetes cluster If you are not familiar with this step, we recommend that you follow Civo's [cluster creation guide](https://www.civo.com/learn/kubernetes-cluster-administration-using-civo-cli). Okteto supports Kubernetes versions 1.33 through 1.35. To get started with Okteto, we recommend that you create a Kubernetes cluster with the following configuration: * Kubernetes v 1.35 * 3 large nodes * Default network * Without Traefik (you'll need to remove it from the default apps) ## Installing Okteto 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: ``` 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 initialize your Helm configuration file with these settings: config.yaml ``` license: "REPLACE ME WITH YOUR OKTETO LICENSE" subdomain: "REPLACE ME WITH YOUR OKTETO DOMAIN" ``` *Note: This is the minimum configuration. Check our [Helm configuration](/docs/self-hosted/helm-configuration.md) docs to learn more* ### 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=1.46.0 ``` After a few seconds, all the resources will be created. The output will look something like this: ``` 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 IP address You can use `kubectl` to fetch the address that has been dynamically allocated by Civo to the NGINX Ingress you've just installed and configured as a part of Okteto: ``` 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.245.147.23 91.211.154.196 80:30087/TCP,443:31799/TCP,1234:31412/TC 2m ``` You'll need to create a wildcard DNS record for this IP. To do that, log in to your Civo account, click on the "Manage" option on the left part of the dashboard, and click on "DNS". Select the domain you're using for your Okteto instance, and click on the "DNS Records" option. ![Screenshot of the CIVO app and the DNS Records settings](/docs/assets/images/civo-dns-records-81392566918e964849cc470926c12a80.png) Click on the "Add a Record" button and use the following values: * Type: A * Name: \* * Value: Your EXTERNAL-IP ![Screenshot of the CIVO app and the New Domain Record component](/docs/assets/images/civo-add-a-new-domain-record-08601767836014dd424bc0745c8cca63.png) Click on the "Add Record" button to create the DNS record. ### Sign in to your Okteto instance warning **Important**: The default installation is not recommended for production use. We highly advise configuring a [wildcard certificate](/docs/self-hosted/install/certificates.md) after finishing your evaluation and giving your team access to your Okteto instance. 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](/docs/get-started/install-okteto-cli.md) 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`: ``` okteto context use https://okteto.SUBDOMAIN ``` Once your Okteto instance is up and running, you are going to [deploy your first app](/docs/get-started/deploy-your-app.md) to Okteto 😎 --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # DigitalOcean Kubernetes (DOKS) This guide will walk you through the process of installing Okteto in DigitalOcean Kubernetes. ## Installation Requirements Before you start, make sure you have the following CLIs installed in your machine: * `okteto` >= 3.21.0 ([okteto installation guides](/docs/get-started/install-okteto-cli.md)) * `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 * A Kubernetes cluster ## 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](/docs/self-hosted/helm-configuration.md#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. This guide assumes your domain is registered in [DigitalOcean Domains](https://cloud.digitalocean.com/networking/domains). You can use any DNS service you prefer, but this guide focuses specifically on DigitalOcean Domains. ## Deploy a Kubernetes cluster If you are not familiar with this step, we recommend that you follow DigitalOcean's [cluster creation guide](https://www.digitalocean.com/docs/kubernetes/how-to/create-clusters/). Okteto supports Kubernetes versions 1.33 through 1.35. To get started with Okteto, we recommend that you create a Kubernetes cluster with the following configuration: * Kubernetes v 1.35 * A pool with at least 3 nodes (4CPUs and 16GBs each) * 250 GB per disk ## Installing Okteto 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: ``` 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 initialize your Helm configuration file with these settings: config.yaml ``` license: "REPLACE ME WITH YOUR OKTETO LICENSE" subdomain: "REPLACE ME WITH YOUR OKTETO DOMAIN" registry: storage: filesystem: persistence: enabled: true ``` *Note: This is the minimum configuration. Check our [Helm configuration](/docs/self-hosted/helm-configuration.md) docs to learn more* ### 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=1.46.0 ``` After a few seconds, all the resources will be created. The output will look something like this: ``` 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 IP address You can use `kubectl` to fetch the address that has been dynamically allocated by DigitalOcean to the NGINX Ingress you've just installed and configured as a part of Okteto: ``` 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.245.147.23 64.225.83.163 80:30087/TCP,443:31799/TCP,1234:31412/TC 2m ``` You'll need to take the `EXTERNAL-IP` address, and add it to your DNS for the domain you have chosen to use. This is done by creating an `A` record with the name `*`. ### Sign in to your Okteto instance warning **Important**: The default installation is not recommended for production use. We highly advise configuring a [wildcard certificate](/docs/self-hosted/install/certificates.md) and [Okteto Registry storage with DigitalOcean Spaces](/docs/self-hosted/install/okteto-registry-storage/digitalocean-spaces.md) after finishing your evaluation and giving your team access to your Okteto instance. 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](/docs/get-started/install-okteto-cli.md) 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`: ``` 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](/docs/get-started/deploy-your-app.md) to Okteto 😎 --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Google Kubernetes Engine (GKE) This guide will walk you through the process of installing Okteto in Google Kubernetes Engine (GKE). ## Installation Requirements Before you start, make sure you have the following CLIs installed in your machine: * `okteto` >= 3.21.0 ([okteto installation guides](/docs/get-started/install-okteto-cli.md)) * `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 * A Kubernetes cluster ## 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](/docs/self-hosted/helm-configuration.md#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. This guide assumes your domain is registered in [Google Cloud DNS](https://cloud.google.com/dns) service. You can use any DNS service you prefer, but this guide focuses specifically on Google Cloud DNS. ## Deploy a Kubernetes cluster We recommend that you follow Google's [GKE cluster creation guide](https://cloud.google.com/kubernetes-engine/docs/how-to/creating-a-cluster). Okteto supports Kubernetes versions 1.33 through 1.35. To get started with Okteto, we recommend that you create a Kubernetes cluster with the following configuration: * Kubernetes v 1.35 * A pool with at least 3 `n2-standard-4` nodes * 250 GB per disk ## Installing Okteto 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: ``` 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 initialize your Helm configuration file with these settings: config.yaml ``` license: "REPLACE ME WITH YOUR OKTETO LICENSE" subdomain: "REPLACE ME WITH YOUR OKTETO DOMAIN" registry: storage: filesystem: persistence: enabled: true ``` ARM Node Groups If you are using ARM-based node groups in your GKE cluster, you must add tolerations to your Helm configuration because GKE automatically applies taints to ARM nodes. Add the following tolerations to your `config.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 cluster configuration recommendations, supported instance types (Tau T2A), and known limitations, see the [ARM Support guide](/docs/self-hosted/manage/arm-support.md). *Note: This is the minimum configuration. Check our [Helm configuration](/docs/self-hosted/helm-configuration.md) docs to learn more* ### 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=1.46.0 ``` After a few seconds, all the resources will be created. The output will look something like this: ``` 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 IP address You can use `kubectl` to fetch the address that has been dynamically allocated by GKE to the NGINX Ingress we've just installed and configured as a part of Okteto: ``` 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 34.68.230.234 80:30795/TCP,443:32481/TCP,1234:30885/TCP 5m ``` You'll need to take the `EXTERNAL-IP` address, and add it to your DNS for the domain you have chosen to use. In Google Cloud DNS, this is done by creating an `A` record with the name `*`. We also suggest you set the TTL to 1 minute. ### Sign in to your Okteto instance warning **Important**: The default installation is not recommended for production use. We highly advise configuring a [wildcard certificate](/docs/self-hosted/install/certificates.md) and [Okteto Registry storage with Google Cloud Storage](/docs/self-hosted/install/okteto-registry-storage/google-cloud-storage.md) after finishing your evaluation and giving your team access to your Okteto instance. 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](/docs/get-started/install-okteto-cli.md) 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`: ``` 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](/docs/get-started/deploy-your-app.md) to Okteto 😎 ## Optional: Configure access to your Google Artifact Registry Optionally, you can configure Okteto to have [access to your Google Artifact Registry](/docs/admin/registry-credentials/google-artifact-registry.md). This will allow you to use your private images in your Dockerfiles and avoid using pull secrets everywhere to deploy your applications. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Azure Kubernetes Service (AKS) This guide will walk you through the process of installing Okteto in Azure Kubernetes Service (AKS). ## Installation Requirements Before you start, make sure you have the following CLIs installed in your machine: * `okteto` >= 3.21.0 ([okteto installation guides](/docs/get-started/install-okteto-cli.md)) * `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 * A Kubernetes cluster ## 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 [domain](/docs/self-hosted/helm-configuration.md#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. This guide assumes your domain is registered in [Azure DNS](https://docs.microsoft.com/en-us/azure/dns/dns-overview). You can use any DNS service you prefer, but this guide focuses specifically on Azure DNS. ## Deploy a Kubernetes cluster We recommend that you follow Azure's [cluster creation guide](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough). Okteto supports Kubernetes versions 1.33 through 1.35. To get started with Okteto, we recommend that you create a Kubernetes cluster with the following configuration: * Kubernetes v 1.35 * A pool with at least 3 `Standard D4` nodes * 250 GB per Standard SSD Managed Disk ## Installing Okteto 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: ``` 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 initialize your Helm configuration file with these settings: config.yaml ``` license: "REPLACE ME WITH YOUR OKTETO LICENSE" subdomain: "REPLACE ME WITH YOUR OKTETO DOMAIN" registry: storage: filesystem: persistence: enabled: true ``` *Note: This is the minimum configuration. Check our [Helm configuration](/docs/self-hosted/helm-configuration.md) docs to learn more* ### 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=1.46.0 ``` After a few seconds, all the resources will be created. The output will look something like this: ``` 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 IP address You can use `kubectl` to fetch the address that has been dynamically allocated by AKS to the NGINX Ingress we've just installed and configured as a part of Okteto: ``` 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 a519c8b3b27f94...aks.microsoft.com 80:30795/TCP,443:32481/TCP,1234:30885/TCP 5m ``` You'll need to take the `EXTERNAL-IP` address and add it to your DNS for the domain you have chosen to use. In AzureDNS, this is done by creating an `A` record with the name `*`, pointing to the IP of the Load Balancer. ### Sign in to your Okteto instance warning **Important**: The default installation is not recommended for production use. We highly advise configuring a [wildcard certificate](/docs/self-hosted/install/certificates.md) and [Okteto Registry storage with Azure Storage Container](/docs/self-hosted/install/okteto-registry-storage/azure-storage-container.md) after finishing your evaluation and giving your team access to your Okteto instance. 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](/docs/get-started/install-okteto-cli.md) if you haven't done so yet and set the Okteto CLI context with your Okteto instance. To do this, run the command below replacing `SUBDOMAIN`: ``` 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](/docs/get-started/deploy-your-app.md) to Okteto 😎 ## Optional: Configure access to your Azure Container Registry Optionally, you can configure Okteto to have [access to your Azure Container Registry](/docs/admin/registry-credentials/azure-acr.md). This will allow you to use your private images in your Dockerfiles and avoid using pull secrets everywhere to deploy your applications. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Red Hat OpenShiftEnterpriseSelf-Hosted This guide will walk you through the process of installing Okteto on a Red Hat OpenShift cluster. Red Hat OpenShift enhances the functionality and security of applications running on Kubernetes but may introduce additional steps when installing applications like Okteto. This guide has been crafted to help you overcome these hurdles, but we encourage you to [talk to us](https://www.okteto.com/get-demo/) to guide you during the installation. ## Installation Requirements Before you begin, make sure you have the following command-line interfaces (CLIs) installed on your machine: * `okteto` >= 3.21.0 ([okteto installation guides](/docs/get-started/install-okteto-cli.md)) * `helm` >= 3.14 ([helm installation guides](https://helm.sh/docs/intro/install/)) * `oc` >= 4.0.0 You'll also need: * An Okteto License * A Kubernetes cluster with Red Hat OpenShift (≥ 4.0.0) installed For this guide, you will need to obtain the following values: * ``: for example, `okteto.r9yz.p2.openshiftapps.com` * ``: for example, `okteto` ## 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). ## Preparing your cluster for Okteto installation Before installing Okteto, prepare your Red Hat OpenShift cluster by following these steps. ### Create the `okteto` namespace Run the following command to create the `okteto` namespace: ``` oc create namespace okteto ``` ### Allow containers as `root` in the `okteto` namespace By default, running containers as `root` is not allowed in Red Hat OpenShift. Currently, some components of the Okteto Control Plane require `root` privileges (this is something we will fix soon!). To allow `root` containers for the Okteto Control Plane components, run the following commands: ``` oc adm policy add-scc-to-user anyuid -z default -n okteto oc adm policy add-scc-to-user anyuid -z okteto -n okteto oc adm policy add-scc-to-user anyuid -z okteto-buildkit -n okteto oc adm policy add-scc-to-user anyuid -z okteto-registry -n okteto ``` These commands grant the `anyuid` Security Context Constraint (SCC) to the specified service accounts in the `okteto` namespace, allowing them to run containers as `root`. ### Grant access to the "privileged" SCC for the Okteto Build service account By default, running privileged containers is not allowed in Red Hat OpenShift. This restriction affects the [Okteto Build](/docs/core/build-service.md) service. To grant privileged access to the Okteto Build service account, run: ``` oc adm policy add-scc-to-user privileged -z okteto-buildkit -n okteto ``` This command grants the `privileged` SCC to the `okteto-buildkit` service account in the `okteto` namespace. ### 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 [Okteto Daemon](/docs/self-hosted/helm-configuration.md#daemonset) service. To grant the necessary permissions to the Okteto Daemon, run: ``` oc adm policy add-scc-to-user hostaccess -z okteto -n okteto ``` This command grants the `hostaccess` SCC to the `okteto` service account in the `okteto` namespace. ### Copy Red Hat OpenShift wildcard certificate to the `okteto` namespace Red Hat OpenShift requires a wildcard certificate for the wildcard domain `*.apps.`. We recommend reusing it when installing Okteto to [expose secure and unique endpoints](/docs/self-hosted/helm-configuration.md#subdomain) for your development environments. By default, Red Hat OpenShift creates the wildcard certificate in the secret `-primary-cert-bundle-secret` in the `openshift-ingress`. In this case, copy the certificate to the `okteto` namespace by running: ``` kubectl get secret -primary-cert-bundle-secret -n openshift-ingress -o yaml | sed 's/namespace: openshift-ingress/namespace: okteto/' | kubectl apply -f - ``` If you installed OpenShift with a custom certificate, copy the certificate's secret (and CA if needed) to the `okteto` namespace. This guide explains [how to configure a custom certificate and CA](/docs/self-hosted/install/certificates/bring-your-own-certificate.md) in Okteto. ### Retrieve the Red Hat OpenShift Ingress Controller IP We recommend installing Okteto behind the Red Hat Openshift Ingress Controller. Obtain the IP address of your Red Hat OpenShift Ingress Controller by running: ``` kubectl get svc router-default -n openshift-ingress -o jsonpath='{.status.loadBalancer.ingress[0].ip}' ``` Store this value as ``; you'll use it in the Okteto Helm configuration. ## Installing Okteto Okteto is installed using a Helm chart. Follow these steps to install it. ### Add the Okteto Helm repository Add the Okteto Helm repository and update it: ``` helm repo add okteto https://charts.okteto.com helm repo update ``` ### Create the Helm configuration file Create a configuration file named `config.yaml` with the following content. Replace ``, ``, ``, and `` with your actual values: ``` license: openshift: enabled: true subdomain: apps. wildcardCertificate: create: false name: -primary-cert-bundle-secret ingress-nginx: enabled: false okteto-nginx: enabled: false ingress: oktetoIngressClass: openshift-default class: openshift-default forceIngressClass: true ip: cluster: endpoint: https://api.:6443 user: extraRoleBindings: enabled: true roleBindings: okteto: - system:openshift:scc:anyuid ``` 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](/docs/self-hosted/helm-configuration.md) to learn more ### Installing the Okteto Helm chart Install the latest version of Okteto by running: ``` helm upgrade --install okteto okteto/okteto -f config.yaml --namespace=okteto --version=1.46.0 ``` This command installs Okteto in the `okteto` namespace using the configuration specified in `config.yaml`. After a few seconds, all the resources will be created. You should see output similar to: ``` Release "okteto" has been installed. Happy Helming! NAME: okteto LAST DEPLOYED: Thu Mar 26 18:07:55 2020 NAMESPACE: okteto STATUS: deployed ``` ### Sign in to your Okteto instance After a successful installation, you can access your Okteto instance at `https://okteto.apps.`. 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](/docs/get-started/install-okteto-cli.md) if you haven't done so yet and set the Okteto CLI context with your Okteto instance. To do this, run the command below replacing `SUBDOMAIN`: ``` 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](/docs/get-started/deploy-your-app.md) to Okteto 😎 --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Using the Okteto CLI and Dashboard ## Introduction to the Okteto Manifest The Okteto Manifest (`okteto.yaml`) is the configuration file that defines the behavior of your Development Environment in Okteto. It allows you to easily manage the entire lifecycle of your application, from building and deploying to testing and ongoing development. The manifest also allows you to customize your development workflow by specifying the dependencies, environment variables, services, and commands required for your application. With the Okteto Manifest, you can: * Automate Your Development Setup: Automatically deploy your application configuration and set up the Development Environment with a single command * Customize Your Environment: Tailor the configuration to match the needs of your application, such as setting environment variables or running specific startup scripts For a deeper dive into how the Okteto Manifest works, check out our [Okteto Manifest Overview](/docs/core/okteto-manifest.md). ## Essential Okteto CLI Commands 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](/docs/get-started/install-okteto-cli.md). 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. | Essential CLI Commands | Description | | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`okteto context`](/docs/reference/okteto-cli.md#context) | Connect to your Okteto instance | | [`okteto deploy`](/docs/reference/okteto-cli.md#deploy) | Deploy your Development Environment described by the `okteto.yaml` in your current directory. If you don't want to re-build the images used in the Development Environment, pass the `--no-build` flag. You can also use `--dependencies` to force the redeployment of app’s dependencies | | [`okteto build`](/docs/reference/okteto-cli.md#build) | Build a new image for your Development Environment. This will build and push the images defined in the build section of your [Okteto Manifest](/docs/core/okteto-manifest.md). Cache-less builds can be performed with the `--no-cache` flag | | [`okteto up`](/docs/reference/okteto-cli.md#up) | Start your Development Environment and connect your terminal window to the cloud environment. Note that if the Development Environment is already running, this will not redeploy it. If you want to force a redeploy pass the `--deploy` flag. When you exit the terminal session, you can automatically shut down the remote dev container by enabling the `OKTETO_AUTO_DOWN_ENABLED` [feature flag](/docs/reference/feature-flags.md) | | [`okteto down`](/docs/reference/okteto-cli.md#down) | Stops your Development Environment. Note that this does not destroy persistent volumes that were created for that Development Environment, to do so, pass the `-v` flag | You can find a list of all available CLI commands in our full [CLI reference guide ->](/docs/reference/okteto-cli.md) ## Overview of the Okteto Dashboard ### 1. **Your Personal Namespace** Automatically generated for each user, this Personal Namespace is uniquely named after your username or email, ensuring a personalized environment. These cannot be deleted, but their resources can be destroyed allowing the Personal Namespace to be reused. ![Okteto Namespace Landing Page](/docs/assets/images/namespace-landing+1.32-620f832f9197cc849ca2c8cb0f0d9b62.png) ### 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 Dev Environment” button. ![deploying an environment from the Okteto catalog](/docs/assets/images/catalog-deployment+1.32-7744da2c97a6cf8f3cb14fa654765819.png) 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 ### 3. **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. ![new namespace dialog](/docs/assets/images/new-namespace+1.32-bad8858049f5961e3a6f9958fb63d52c.png) Namespaces can also be created with by using the [`okteto namespace create` CLI Command](/docs/reference/okteto-cli.md#create) * **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** * 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). ![sharing a namespace with another user](/docs/assets/images/sharing-a-namespace+1.32-f0615a91ac9c991fbf871aca1c180c72.png) Read more about [sharing a Namespace here](/docs/core/namespaces.md#sharing-and-collaboration-with-namespaces) ### 5. **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 * **Persistent**: Admins can choose to prevent Namespaces from deletion and automatically sleeping so that they are always accessible ### 6. **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 ![preview environments in the Okteto dashboard](/docs/assets/images/preview-environments+1.32-b4fffabc003ad379c4c44b431ba11ef2.png) Read more about [Preview Environments here](/docs/previews.md) ### 7. **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](/docs/get-started/advanced-commands-and-concepts.md) 😎 --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto AI Okteto AI lets you launch AI-powered development agents directly from the Okteto Dashboard. Each agent runs in its own isolated Kubernetes namespace, where it can write code, install dependencies, run tests, and debug — all without any local setup on your machine. You describe a task in natural language, and the agent handles the rest: cloning your repo, setting up the environment, writing and validating code, and producing a pull request when it's done. You can monitor progress in real time through the Dashboard and review changes in an embedded editor. ## How it works 1. **Open the Agents tab** in the Okteto Dashboard 2. **Choose a repository** or start a new project from scratch 3. **Describe your task** — the agent clones, builds, codes, and tests in a sandboxed environment 4. **Review the results** — preview live endpoints, inspect code changes, and check test output 5. **Create a PR** when you're satisfied with the changes Each agent gets its own namespace with dedicated compute, filesystem, and network access. Agents don't share state unless you explicitly configure them to. ## What agents can do * **Build features** — new endpoints, services, UI components, or full applications from a description * **Fix bugs** — investigate issues with full access to logs, databases, and runtime state * **Write tests** — generate unit, integration, or end-to-end tests for existing code * **Refactor code** — modernize patterns, improve performance, or migrate to new frameworks * **Generate documentation** — READMEs, API specs, and inline docs based on the actual codebase ## Why Okteto AI **No local setup required.** Agents run entirely in the cloud. You don't need Docker, Kubernetes, or any CLI tooling installed on your machine. **Full isolation.** Each agent operates in its own Kubernetes namespace. One agent can't affect another, and none of them touch your production environment. **Production-like environments.** Agents have access to the same runtime, secrets, and configuration as your real development setup, so what works in the agent's environment works everywhere else. **Parallel execution.** Run multiple agents simultaneously on different tasks — one adding a feature, another writing tests, a third fixing a bug — without conflicts. **Built-in observability.** Full logs, metrics, and traces for every agent action. You can see exactly what the agent did and why. ## 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"* ## Getting started ### For administrators Before team members can use Okteto AI, an administrator must enable and configure it. See the [Admin Configuration Guide](/docs/okteto-ai/okteto-ai-admin-config.md) for setup instructions. ### For developers See the [Getting Started Guide](/docs/okteto-ai/ai-getting-started.md) to launch your first agent. ## FAQs **Can I run multiple agents at once?** Yes. Each agent runs in its own namespace and works independently. **Do I need to install anything locally?** No. Everything runs in the cloud through the Okteto Dashboard. **Can I bring my own LLM key?** Yes. You can provide your own Anthropic API key in the agent settings to use your own quota. **Do you plan to support additional LLM providers?** Yes. We plan to add support for additional models based on feedback in a coming release. ## Using your own agent tooling Okteto AI is a fully managed experience in the Dashboard. If you prefer to use your own AI agent tooling — such as Claude Code in your IDE or agents triggered by CI pipelines — see [Agentic Workflows](/docs/agentic.md) for how to connect agents to Okteto environments using the CLI. *** ## 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. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto AI - Getting Started This guide walks you through launching your first AI agent from the Okteto Dashboard. ## Prerequisites Before you begin: * Your administrator has [enabled Okteto AI](/docs/okteto-ai/okteto-ai-admin-config.md) 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. ## Launch your first agent ### Step 1: Open the Agents tab Navigate to the **Agents** tab in your Okteto Dashboard. ### Step 2: Choose your starting point **Work with an existing repository** — paste your repository URL (e.g., `https://github.com/yourorg/yourrepo`). The agent will clone and analyze your codebase. Use this for adding features, fixing bugs, or refactoring. **Start fresh** — select **Start a new project** and 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, and runs tests 3. Click **Open Editor** to view an embedded Visual Studio Code where you can monitor and audit all code changes ### Step 5: Review and deploy Once the agent completes its work: * **Preview**: Click any generated endpoints to see your application live * **Review**: Check the code changes and test results * **Accept**: Ask the agent to create a pull request ## Writing effective prompts Good prompts are specific about what you want, where it should go, and what constraints apply. **Specific prompt:** ``` 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 ``` **Vague prompt:** ``` Add image upload ``` Include these details when relevant: * **What**: The specific feature or fix needed * **Where**: Relevant files, endpoints, or services * **How**: Technical requirements or constraints * **Why**: Business logic or user needs ## Common first tasks 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 ``` ## Best practices **Start small.** Begin with well-defined tasks and build confidence before tackling complex features. **Run agents in parallel.** Multiple agents can work simultaneously on different tasks — one adding a feature, another writing tests, a third optimizing queries. **Review before merging.** Always check the preview environment, test results, and code changes before accepting a PR. **Iterate.** If the first result isn't right, provide specific feedback and let the agent adjust. ## Good use cases * CRUD operations and API endpoints * Data transformations and migrations * Test writing and coverage improvements * Bug fixes with clear symptoms * Documentation updates * Boilerplate and scaffolding ## Use with caution * Core authentication or authorization logic * Payment processing * Complex architectural decisions * Performance-critical algorithms Always review agent-generated code for security-sensitive features before merging. ## Agent capabilities Agents can: * Read and understand your entire codebase * Install packages and dependencies * Create, modify, and delete files * Run commands, scripts, and tests * Access [Okteto environment variables](/docs/core/okteto-variables.md) and configs * Interact with databases and external APIs Agents cannot: * Access production environments * Bypass your CI/CD pipeline * Merge code without your approval * Access secrets not provided to the environment * Modify Okteto platform settings ## Troubleshooting **Agent is taking too long** — break complex tasks into smaller steps and provide more specific instructions. Check if your environment is running low on resources. **Agent doesn't understand your codebase** — make sure the repository is accessible, provide context about your architecture, and reference specific files or patterns. **Tests are failing** — specify test requirements clearly, provide example test cases, and verify that environment dependencies are available. **Can't see the preview environment** — wait for deployment to complete, check service health endpoints, and verify port configurations. ## Get help * **Documentation**: [Okteto AI overview](/docs/okteto-ai.md) * **Support**: * **Community**: [Okteto Community](https://community.okteto.com/) ## Prompt guide For advanced prompting techniques, download the [Okteto AI Prompt Guide (PDF)](https://okteto.link/4mTWk1e). --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto AI - Admin Configuration Guide 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](/docs/assets/images/admin_ai_agent_fleets-9902c3503f1245102f1ebe0101542acb.png) ### 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 3: 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](/docs/assets/images/admin_ai_llm_provider_config_anthropic-33b51454088deb8aaa5ce436c275c791.png) 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](/docs/assets/images/admin_ai_llm_provider_config_bedrock-57c091b4e5179cc0a6306d7ed19962d5.png) 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 4: Configure LLM Model The LLM Model section shows which Claude model is being used: * Currently, agents use Claude Sonnet 4.6, 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 5: 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 6: 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 * 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](/docs/admin/dashboard.md#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 --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Preview Environments 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](/docs/assets/images/preview-environments+1.38-606d1f9e19f901ccc0f361576bc4c25d.png) 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](/docs/core/okteto-manifest.md), 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](/docs/reference/okteto-cli.md#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](/docs/previews/using-github-actions.md) - Set up Preview Environments with GitHub * [GitLab CI/CD](/docs/previews/using-gitlab-cicd.md) - Integrate with GitLab pipelines * Bitbucket Pipelines (coming soon!) * Azure DevOps (coming soon!) ### Prerequisites Preview Environments deploy the code in a pull request to [Okteto](/docs.md). You can configure the way your code gets deployed using the [Okteto manifest](/docs/core/okteto-manifest.md)'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](/docs/core/okteto-variables.md). ## 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](/docs/admin/previews.md). --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Preview environments using GitHub Actions This section will show you how to automatically create a preview environment for your applications using Okteto and GitHub Actions. ## Pre-Requisites * An Okteto account * A [GitHub account](https://github.com) For this tutorial, we'll be using our sample [movies rental application](https://github.com/okteto/movies). If you're using your own application to follow along, please ensure you have your [Okteto Manifest](/docs/reference/okteto-manifest.md) configured. ## Step 1: Create the GitHub Workflow To create the preview environments, we will use our [GitHub Actions for Okteto](https://github.com/okteto/actions). A preview environment follows the lifecycle of a Pull Request. The GitHub action we create will make sure that whenever a Pull Request is created: 1. A preview environment is deployed in Okteto with the code in the PR 2. The PR is updated with the URL of the preview environment The sample repository has been configured to use [the workflow described above](https://github.com/okteto/movies/blob/main/.github/workflows/preview.yaml). If you want to use this on for your repositories, all you need to do is to create a `.github/workflows` folder in the root of your repo, and save your workflow file in it. The workflow file to create the preview environments looks like this: ``` # file: .github/workflows/preview.yaml on: pull_request: branches: - main 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 steps: - name: Context uses: okteto/context@latest with: url: ${{secrets.OKTETO_CONTEXT}} token: ${{ secrets.OKTETO_TOKEN }} - name: Deploy preview environment uses: okteto/deploy-preview@latest env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: name: pr-${{ github.event.number }} timeout: 15m ``` warning **Important:** Always set `cancel-in-progress: false` for preview environment workflows. Setting to `true` will cancel **in-progress deployments**, which can lead to: * Incomplete deployments leaving your preview environment in an inconsistent state * Resource leaks in your Okteto cluster * Failed cleanup operations **Recommended approach:** * For preview deployments: Set `cancel-in-progress: false` (as shown above) * To manage queued workflows: Use GitHub's UI to manually cancel queued (not in-progress) workflows, or configure your CI/CD pipeline to handle this at the queue level rather than during execution The concurrency group configuration above ensures that workflows are properly queued per pull request, preventing concurrent deployments to the same preview environment. ## Step 2: Configure your secrets If you noticed, the workflow uses the `secrets.OKTETO_TOKEN` and `secrets.OKTETO_CONTEXT`. We do this, so we don't have to commit these values into our repo. Before you run this workflow you need to create the following secrets in your repository: * `OKTETO_TOKEN` with an Okteto [Admin Access Token](/docs/admin/dashboard.md#admin-access-tokens) * `OKTETO_CONTEXT` with the URL of your Okteto instance (e.g. `https://okteto.example.com`). See [Using secrets in GitHub Actions](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) for adding these to your Github repository. The workflow also uses `secrets.GITHUB_TOKEN`, but this gets populated automatically by GitHub. ## Step 3: Open a Pull Request Once your changes are in your repository, go ahead and open a new pull request. GitHub will receive the event, and it will start your workflow. You can see the workflow's status and logs in the `checks` section of the pull request. ![checks section of pull request](/docs/assets/images/preview-check-3c8094bb375496944293cb854413b18a.png) ## Step 4: See your changes live After a few seconds, the workflow will update the pull request with the URL of your preview environment. Click on it to see the changes in real-time. ![preview environment message with URL](/docs/assets/images/preview-message-d189a4e011774512e0d7e79e2de5ee60.png) Every time the branch is updated, the same workflow will run, automatically updating the preview environment. ## Step 5: Cleanup The sample repo also includes a workflow [to cleanup the preview environments](https://github.com/okteto/movies/blob/main/.github/workflows/preview-closed.yaml) once the pull request is closed. We recommend you follow this pattern to remove the preview environment after merging a pull request automatically. ``` # file: .github/workflows/preview-closed.yaml on: pull_request: types: - closed jobs: closed: runs-on: ubuntu-latest steps: - name: Context uses: okteto/context@latest with: url: ${{secrets.OKTETO_CONTEXT}} token: ${{ secrets.OKTETO_TOKEN }} - name: Destroy preview environment uses: okteto/destroy-preview@latest with: name: pr-${{ github.event.number }} ``` ## Resources * [How To Set Up Preview Environments With Okteto](https://youtu.be/kgX5qUkJGDA) - A video walking through the process of setting up Preview environments. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Preview environments using GitLab CI/CD Okteto integrates with GitLab review apps to automatically create a Preview Environment for your applications on every merge request. ## Prerequisites * An Okteto account * A [GitLab account](https://gitlab.com) 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](/docs/reference/okteto-manifest.md) is configured. ## Step 1: Configure your Okteto API token To deploy a Preview Environment with Okteto, you need to define the following environment variables: 1. `OKTETO_TOKEN`: an Okteto [access token](/docs/admin/dashboard.md#admin-access-tokens) 2. `OKTETO_CONTEXT`: specify the URL of your Okteto instance (e.g., ) To add the environment variables: 1. Navigate to your GitLab repository. 2. Go to the **Settings** menu on the left, and click on the **CI/CD** entry: ![GitLab settings, CI/CD](/docs/assets/images/gitlab-settings-cicd-c2be338d2068843de86ad035ba1e5db0.jpg) 3. Expand the **Variables** section, and click on the **Add Variable** button under the "Project variables" section. note 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. 4. Add `OKTETO_TOKEN` as the key and your access token as the value, then click the **Add Variable** button: ![update variable with Okteto Token](/docs/assets/images/gitlab-settings-cicd-add-variables-okteto-token-8a76f39b2f73651aa9ce62942be86be1.png) 5. Repeat the same process to add the `OKTETO_CONTEXT` variable (optional): ![environment variables added](/docs/assets/images/gitlab-settings-cicd-add-variables-added-25ffcb287cf88402c2c818dfa23254ca.png) ## Step 2: Configure the Preview Environment on 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. 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: 1. Create a dedicated Namespace for the Preview Environment 2. Build and deploy the application using the [Okteto preview](/docs/previews.md) defined in the repository. 3. Add the URL of the Preview Environment to the Merge Request. The flow to delete a Preview Environment looks like this: 1. Destroy the application deployed with [Okteto preview](/docs/previews.md) The `.gitlab-ci.yml` looks like this: ``` # file: .gitlab-ci.yml image: ghcr.io/okteto/okteto:latest stages: - review review: stage: review variables: APP: review-$CI_COMMIT_REF_SLUG script: - okteto preview deploy review-$CI_COMMIT_REF_SLUG --branch $CI_COMMIT_REF_NAME --repository $CI_PROJECT_URL environment: name: review/$CI_COMMIT_REF_SLUG url: https://movies-review-$CI_COMMIT_REF_SLUG.okteto.example.com on_stop: stop-review only: - branches except: - master stop-review: stage: review when: manual environment: name: review/$CI_COMMIT_REF_SLUG action: stop script: - okteto preview destroy review-$CI_COMMIT_REF_SLUG variables: GIT_STRATEGY: none only: - branches except: - master ``` A few recommendations when creating your Preview Environment: * 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 See the [Okteto CLI reference](/docs/reference/okteto-cli.md) for the full list of available commands and flags. ## 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 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](/docs/assets/images/gitlab-merge-request-2c9a9e1a0ad88d191e0d838d91603e61.png) ## Step 4: Cleanup 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. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # References [](/docs/reference/okteto-cli.md) Okteto CLI The Okteto Command Line Interface is a unified tool to manage your development environments [](/docs/reference/okteto-manifest.md) Okteto Manifest Reference Okteto's Manifest for describing development environments [](/docs/reference/docker-compose.md) Docker Compose Okteto allows you to develop applications using docker-compose files [](/docs/reference/supported-github-actions.md) GitHub Actions Automate your development workflows using GitHub Actions and Okteto [](/docs/reference/file-synchronization.md) File Synchronization Okteto keeps your local files synchronized with your development environment [](/docs/reference/feature-flags.md) Feature Flags Okteto's feature flags on the CLI [](/docs/reference/ssh-server.md) SSH Server Okteto runs an SSH server in your development container --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Docker Compose Reference Docker Compose are for developers who don't want to deal with the complexities of Kubernetes manifests. Okteto implements and extends the [Compose Specification](https://github.com/compose-spec/compose-spec) to make it easy to develop Docker Compose applications in Kubernetes. ## Example ``` services: vote: build: vote scale: 2 environment: - FLASK_ENV=development command: python app.py ports: - 8080:8080 volumes: - ./vote:/src redis: image: redis ports: - 6379 volumes: - redis:/data volumes: redis: ``` The equivalent Kubernetes manifests would have more than 300 lines of yaml! ## Schema reference ### services (\[object], optional) Define the services that make up your Docker Compose application. ``` services: vote: build: vote scale: 2 ports: - 8080:8080 redis: image: redis ports: - 6379 volumes: - redis:/data ``` Each service supports the fields in the [Compose Specification](https://github.com/compose-spec/compose-spec). 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`. The value is the path to the build context: ``` build: vote ``` It can also be an object with these fields: * `context`: the build context. When the value supplied is a relative path, it is interpreted as relative to the location of the Docker Compose file (default: `.`) * `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. ``` build: context: . dockerfile: Dockerfile target: prod args: - ENV1=prod - ENV2=$VALUE secrets: - npm_token ``` `okteto deploy` builds a new docker image, pushes it to the registry and redeploys your containers. #### cap\_add (\[string], optional) Add container capabilities. See `man 7 capabilities` for a full list. ``` cap_add: - ALL ``` #### cap\_drop (\[string], optional) Drop container capabilities. See `man 7 capabilities` for a full list. ``` cap_drop: - NET_ADMIN - SYS_ADMIN ``` #### command (string, optional) Override the default command of the container image `CMD`. ``` command: --debug ``` `command` can also be a list of strings: ``` command: ["-p", "3000"] ``` #### depends\_on (\[string]|object, optional) Specify the conditions that the declared services must meet in order for the service to start. The condition must be one of the following: * `service_started`: Wait until the service is running. * `service_healthy`: Wait for one of the ports of the dependent service to be available, or for its healthcheck test commands to complete successfully. * `service_completed_successfully`: Wait until the dependent service has been successfully completed. ``` depends_on: app: condition: service_started db: condition: service_healthy initialization-svc: condition: service_completed_successfully ``` You can also express dependencies as a list of services. In this case it will be the same as setting the condition to `service_started`. ``` depends_on: - app - db - initialization-svc ``` info 💡 To enforce `depends_on` ordering during environment wake-up, enable the [`OKTETO_COMPOSE_DEPENDS_ON_ENABLED` feature flag](/docs/reference/feature-flags.md). #### 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. ``` 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. * `vip` (default): Creates a virtual IP endpoint that maps to a standard Kubernetes ClusterIP service, providing load balancing across service replicas. * `dnsrr`: Creates a DNS round-robin endpoint that maps to a Kubernetes headless service (ClusterIP: None), where DNS queries return all pod IPs directly without load balancing. ``` deploy: endpoint_mode: dnsrr ``` warning When `endpoint_mode` is set to `dnsrr`, [Okteto Divert](/docs/reference/okteto-manifest.md#divert) will not work. info More information here: #### entrypoint (string, optional) Override the default entrypoint of the container image `ENTRYPOINT`. ``` entrypoint: yarn start ``` The entrypoint can also be a list of strings: ``` entrypoint: ["yarn", "start"] ``` #### env\_file (string, optional) Add environment variables from a file to the containers of a service. Environment variables declared in the [environment section](/docs/reference/docker-compose.md#environment-string-optional) override these values. This also holds true if those values are empty or undefined. ``` env_file: .env ``` `env_file` also accepts a list of files: ``` env_file: - .env.frontend - .env.api ``` #### environment (\[string], optional) Add environment variables: ``` environment: DEV_MODE: yes DB_HOST: postgres://${DB_HOST:-db}:${DB_PASSWORD}@postgres:5432/postgres ``` #### healthcheck (object, optional) healthcheck declares a check that's run to determine whether or not containers for a service are "healthy". * `start_period` (duration): Time between the start of the container and the initiation of the healthcheck. * `interval` (duration): Time between a healthcheck and a subsequent new try. * `timeout` (duration): Number of seconds after which the healthcheck times out. * `retries` (int): Number of retries before healthcheck fails. * `test` (string): Defines the command that will be run to check the container's health. It can be 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. 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`). ``` healthcheck: interval: 10s timeout: 10m retries: 5 start_period: 30s http: path: / port: 8080 ``` Healthchecks can also test a command as follows: ``` healthcheck: interval: 10s timeout: 10m retries: 5 start_period: 30s test: echo 'db.runCommand({serverStatus:1}).ok' | mongo admin -u $MONGO_INITDB_ROOT_USERNAME -p $MONGO_INITDB_ROOT_PASSWORD --quiet | grep 1 ``` #### image (string, optional) The container image of each service. ``` image: ghcr.io/okteto/vote:compose ``` If [`build`](/docs/reference/docker-compose.md#build-stringobject-optional) is defined, `image` is optional. Otherwise, it's required. #### labels (\[string], optional) Specify labels for the service. They translates to Kubernetes annotations. ``` labels: app: sample ``` You can set the update policy of a service by setting the label `dev.okteto.com/update`. Depending on the kind of resource the acceptance values are different: * rolling: Will deploy a service with zero downtime. Only allowed for deployments and stateful sets. * recreate: Will wait until the current pod is deleted to start creating the new one. Only allowed on deployments. * on-delete: Will wait until the current pod is deleted to start creating the new one. Only allowed on stateful sets. ``` services: deployment: image: python:alpine labels: "dev.okteto.com/update": rolling entrypoint: python -m http.server 8080 ports: - 8080:8080 sfs: image: python:alpine labels: "dev.okteto.com/update": on-delete entrypoint: python -m http.server 8080 ports: - 8080:8080 volumes: - /usr/src ``` info Remember that Docker Compose labels are translated into Kubernetes annotations. #### ports (\[int], optional) Ports exposed by each service. By default, they're only accessible from the cluster private network. ``` ports: - 8080 ``` To make the port public, use the following notation: ``` ports: - 8080:8080 ``` If you need to configure HTTPS routes, use [endpoints](/docs/reference/docker-compose.md#endpoints-object-optional) instead of configuring an NGINX container in your Docker Compose file. The following ports are never made public: | Protocol | Port | | --------------- | ----------------------- | | MySQL | 3306 | | OracleDB | 1521,1830 | | PostgreSQL | 5432 | | SQL Server | 1433,1434 | | MaxDB | 7210 | | Neo4j | 7473 | | ArangoDB | 8529 | | Cassandra | 7000,7001,9042 | | InfluxDB | 8086 | | Elasticsearch | 9200,9300 | | CouchDB | 5984 | | MongoDB | 27017,27018,27019,28017 | | Redis | 6379 | | Riak | 8087,8088 | | RethinkDB | 828015,29015,28015 | | Solr | 7574,8983 | | Golang debugger | 2345 | | Node debugger | 5858,9229 | | Java debugger | 5005 | | Ruby debugger | 1234 | | Python debugger | 4444,5678 | If you need make these ports public, you can use [endpoints](/docs/reference/docker-compose.md#endpoints-object-optional). #### resources (object, optional) 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`. ``` resources: requests: cpu: 300m memory: 500Mi limits: cpu: 500m memory: 800Mi ``` Or with the [docker-compose v3 configuration](https://docs.docker.com/compose/compose-file/compose-file-v3/#resources). ``` deploy: resources: reservations: cpus: 500m memory: 800Mi limits: cpus: 300m memory: 500Mi ``` #### restart (string, optional) Defines the policy that the platform applies on container termination. * `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. ``` restart: on-failure ``` 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) Specify the number of containers running for each service (default: `1`). ``` scale: 2 ``` #### stop\_grace\_period (duration|int, optional) Specify how long to wait when attempting to stop a container before sending SIGKILL. If no unit of time is given, the system will interpret the number in seconds. `stop_grace_period` translates to the `terminationGracePeriod` setting in the pod. ``` stop_grace_period: 10s ``` #### volumes (\[string], optional) Define volumes accessible by the containers of a service at a given path. ``` volumes: - redis:/data ``` The volume `redis` must be defined in the [volumes section](/docs/reference/docker-compose.md#volumes-object-optional). The following notation is also accepted: ``` volumes: - /data ``` Finally, host volumes are also supported: ``` volumes: - .:/usr/app/src ``` Host volumes are ignored at deployment time if the service defines a `build` section. Otherwise, they are added to the content of the `image` defined by the service. `okteto up` uses host volumes to infer the [sync paths](/docs/reference/okteto-manifest.md#sync-string-required) between your local filesystem and your remote development container. By default, services mounting the same volume will be placed on the same node using Kubernetes's pod affinity. If you wish to disable this behavior, set the environment variable `OKTETO_COMPOSE_VOLUME_AFFINITY_ENABLED` to `false` when deploying. You can also optionally configure this variable from the Okteto UI to make it available to all development environments in your namespace. #### working\_dir (string, optional) Override the default working directory of the container image `WORKDIR`. ``` working_dir: "/app/code" ``` #### x-node-selector (map\[string]string, optional) List of labels that the node must have to include the service containers on it. ``` x-node-selector: disktype: ssd ``` More information about Kubernetes node selectors is [available here](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector). #### 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. ``` 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`: ``` 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`: ``` { "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. Volumes are mounted on the containers of a given service by referring the volume from the [volumes field](/docs/reference/docker-compose.md#volumes-string-optional) of the service. ``` volumes: redis: driver_opts: size: 1Gi ``` Each volume has the following properties: #### driver\_opts.class (string, optional) Specify the storage class of the volume. ``` driver_opts: class: standard ``` #### driver\_opts.size (string, optional) Specify the size of the volume. Defaults to 1Gi. ``` driver_opts: size: 1Gi ``` #### labels (string, optional) Specify labels for the volume. They will translate to Kubernetes annotations. ``` 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. ``` 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: ``` 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. This section should help you find the information you need. ### Environment variable substitution It’s possible to use environment variables in your shell to populate values inside your Docker Compose file: ``` services: web: image: "app:${TAG}" ``` If you have multiple environment variables, you can substitute them by adding them to a file named `.env`. ### The .env file You can set default values for any environment variables referenced in your Docker Compose file in an environment file named `.env`. The `.env` file is placed at the same folder than the Docker Compose file. For example: ``` $ cat .env TAG=v1.5 ``` ``` $ cat docker-compose.yml services: web: image: "app:${TAG}" ``` When you run `okteto deploy` the `web` container uses the image `app:v1.5`. note Values in the shell take precedence over those specified in the `.env` file. ### extensions (object, optional) Specifies a configuration that can be used in other services using anchors. Every top-level field starting with the prefix 'x-' will be interpreted as an extension. ``` x-function: &environment environment: DEV_MODE: yes DB_HOST: postgres://${DB_HOST:-db}:${DB_PASSWORD}@postgres:5432/postgres services: app: <<: *environment image: okteto.dev/example ``` ### Okteto Variables You can also use your [Okteto Variables](/docs/core/okteto-variables.md) in your Docker Compose file. For example, if your have an Okteto Variable named `PASSWORD` whose value is `change-me!`, the following Docker Compose file: ``` services: mysql: image: mysql environment: - MYSQL_ROOT_PASSWORD=${PASSWORD} ``` will use `change-me!` for the value of the `MYSQL_ROOT_PASSWORD` environment variable of the `mysql` service when you run `okteto deploy`. note Values in the shell and/or the `.env` file take precedence over those specified as Okteto Variables. ## Okteto makes Docker Compose even more powerful! Okteto extends the Compose Specification to make it even easier for you and your team to build cloud-native applications. ### endpoints (\[object], optional) Endpoints expose HTTPS routes from outside the cluster to services within the cluster. Use this instead of having to run a NGINX proxy in your Docker Compose file. ``` endpoints: - path: / service: frontend port: 80 - path: /api service: api port: 8080 ``` The endpoint uses the name of the development environment to generate a URL with the following format: . Each endpoint has the following properties: #### path (string, required) The request path that will handle this route. #### service (string, required) The service that will receive the request. #### port (int, required) The port that will receive the request. If more than one endpoint is needed, you can declare multiple endpoints by using a map with the name of the endpoint and its specification: ``` endpoints: landing: - path: / service: nginx port: 80 web: - path: / service: frontend port: 80 - path: /api service: api port: 8080 ``` In this case, the URLs `landing-NAMESPACE.okteto.example.com` and `web-NAMESPACE.okteto.example.com` are created. `endpoints` also accepts an extended notation to specify labels for each endpoint: ``` endpoints: labels: kubernetes.io/ingress.class: nginx rules: - path: / service: frontend port: 3000 - path: /api service: backend port: 8080 ``` ## Compatibility Guide Okteto supports a large subset of the Docker Compose specification and introduces a few useful extensions to simplify Kubernetes development. The table below outlines the compatibility between standard Compose keys and Okteto's implementation, helping you understand which features are fully supported, partially supported with warnings, silently ignored, or unique to Okteto. ### Legend | **Emoji** | **Meaning** | | --------- | -------------------------------------------------------------------------------- | | ✅ | Fully supported by Okteto – it is unmarshalled into a regular Go type | | ⚠️ | Recognized but *unsupported* – Okteto will recognize it but will throw a warning | | ⛔️ | The key is **missing** from Okteto’s structs, therefore *silently ignored* | | 🆕 | Key exists in Okteto but **is not part of the Compose Spec** (Okteto-specific) | *** ### Top-level Keys | **Key** | **Compose Spec** | **Okteto** | **Notes** | | -------------------- | ---------------- | ---------- | ------------------------------------------------------------------------------------------ | | name | yes | ✅ | | | services | yes | ✅ | | | volumes | yes | ✅ | | | networks | yes | ⚠️ | Warning shown to the user | | configs | 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 extension for defining HTTPS routes | ### Service Spec #### ✅ Supported ``` annotations 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 env_file environment healthcheck image labels mem_limit mem_reservation cpu_count / cpus ports / expose restart stop_grace_period user volumes volumes.sub_path working_dir scale (short syntax) ``` #### ⚠️ Recognized but Unsupported (Warning Shown) ``` blkio_config cgroup_parent configs container_name cpu_percent cpu_period cpu_quota cpu_rt_period cpu_rt_runtime cpu_shares cpuset credential_spec deploy.restart_policy.delay deploy.restart_policy.window device_cgroup_rules devices dns dns_opt dns_search domainname driver_opts extends external_links extra_hosts group_add hostname init ipc isolation links logging mac_address mem_swappiness memswap_limit network_mode networks oom_kill_disable oom_score_adj pid pids_limit platform privileged profiles pull_policy read_only runtime security_opt shm_size stdin_open stop_signal storage_opts sysctls tmpfs tty ulimits userns_mode volumes_from ``` #### ⛔️ Silently Ignored ``` attach cgroup develop gpus interface_name label_file link_local_ips post_start pre_stop provider.* uts ``` *** ### 🆕 Okteto-Specific Extras | **Key** | **Purpose** | | ----------------------- | ----------------------------------------------------------------------------- | | endpoints | Define HTTPS routes for services | | public: true | Auto-generate a Kubernetes Ingress | | x-node-selector | Pod scheduling hint | | 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`) | *** ### Volume Section | **Attribute** | **Compose Spec** | **Okteto** | **Notes** | | ------------------------------ | ---------------- | ---------- | -------------------------------- | | labels | yes | ✅ | | | driver, driver\_opts, external | yes | ⚠️ | Warning then ignored | | size, class | — | 🆕 | PVC size & storage-class helpers | *** ### Networks & Configs Blocks Both blocks are **parsed only to raise a warning**; every sub-field therefore falls under ⚠️. ### Secrets Block Top-level `secrets` definitions with `file` or `environment` fields are ✅ supported for use with `build.secrets`. Runtime secrets (`services..secrets`) remain ⚠️ unsupported. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Frequently Asked Questions (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: ``` annotations: fluxcd.io/ignore: "true" ``` tip Please see our [ArgoCD Configuration Guide](/docs/self-hosted/manage/argocd.md) 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](/docs/admin/registry-credentials.md) feature. ## Why are my [Endpoints](/docs/core/endpoints/automatic-ssl.md) 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](/docs/reference/docker-compose.md#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`](/docs/reference/okteto-cli.md#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](/docs/admin/cleanup.md#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](/docs/get-started/install-okteto-cli.md) 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](/docs/get-started/install-okteto-cli.md). 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`](/docs/reference/okteto-cli.md#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: ``` okteto build -f Dockerfile -t myapp:latest --platform linux/amd64 ``` 2. Building the image for ARMv7 architecture: ``` okteto build -f Dockerfile -t myapp:latest --platform linux/arm/v7 ``` 3. Building a multiarchitectural image: ``` 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. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Feature Flags Setting any feature flag variable as an [Admin Variable](/docs/admin/dashboard.md#admin-variables) will enable that feature flag for all operations within the cluster. Admin variables are equivalent to defining that variable on every developer's machine. Below is a list of those variables that you can use to leverage these newer and experimental features: | Environment Variable | Description | Default Value | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- | | 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 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\_QUEUE\_ENABLED | Enables the [Build Queue System](/docs/core/build-service.md#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` | | OKTETO\_DEV\_PERSISTENT\_VOLUME\_SIZE | Override the default [persistent volume](/docs/reference/okteto-manifest.md#persistentvolume-object-optional) size for Development Containers. Set in [binary SI units](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) (e.g. 2Gi) | N/A | | OKTETO\_DISABLE\_SPINNER | If set, disables the spinner rotation | `false` | | OKTETO\_INHERIT\_KUBERNETES\_RESOURCES | When enabled, development container inherits CPU and memory requests/limits from the original resource (deployment or statefulset) if they are not already defined in the Okteto Manifest | `false` | | OKTETO\_INHERIT\_KUBERNETES\_NODESELECTOR | When enabled, development container inherits the node selector from the original resource (deployment or statefulset) if it is not already defined in the Okteto Manifest | `false` | | OKTETO\_FOLDER | Defines the path where the Okteto folder is located | `$OKTETO_HOME/.okteto` | | OKTETO\_KUBERNETES\_TIMEOUT | Specifies the timeout while deploying | `0` | | OKTETO\_LOCAL\_REGISTRY\_STORE\_PRIORITY\_ENABLED | Gives more priority to the local registry credentials than the Okteto Registry Credentials | `false` | | OKTETO\_PARALLEL\_WAKE\_UPS\_FOR\_DEVENVS | Specifies if the dev environments within a namespace should wake up in parallel or not | `false` | | OKTETO\_SERVICES\_UP\_WAIT | If set, waits for file synchronization to complete before starting the services defined in the [`services` section](/docs/reference/okteto-manifest.md#services-object-optional) | `false` | | OKTETO\_SMART\_BUILDS\_ENABLED | Enables the [Smart Builds feature](/docs/core/build-service.md#smart-builds) that uses a hash of the build context to determine if an image needs to be rebuilt or can be pulled from the registry. This can accelerate build times | `true` | | OKTETO\_SMART\_BUILDS\_IGNORE\_FILES\_ENABLED | When enabled, files listed in `.dockerignore` will be excluded from the smart build context calculation | `false` | | OKTETO\_SUPPORT\_STACKS\_ENABLED | Support Okteto Stacks syntax | `false` | | OKTETO\_SYNCTHING\_VERSION | Specifies the Syncthing version the CLI must use | N/A | | OKTETO\_USE\_STATIC\_KUBETOKEN | Use a fixed token rather than a dynamic token for interactions with the Kubernetes API | `false` | --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # File Synchronization When you run `okteto up`, an instance of [Syncthing](https://syncthing.net/), a file synchronization service, will be automatically started to keep your local files synchronized with your development container. 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`: ``` $ okteto status --info ``` ``` i Local syncthing url: http://localhost:60539 i Remote syncthing url: http://localhost:60538 i Syncthing username: okteto i Syncthing password: ac0ee34a-b1aa-4a41-bc67-cec3128b6cfd ✓ Synchronization status: 100.00% ``` ### Ignoring files If some files should not be synchronized between your local machine and your development environment, a file called `.stignore` can be created containing file patterns to ignore. The `.stignore` file must be placed in the root of the folder. info 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`. The `.stignore` file contains a list of files or path patterns. The *first pattern* that matches will decide the fate of a given file. The patterns follow the same syntax that `.gitignore` and `.dockerignore`. More information on this [is available here](https://docs.syncthing.net/users/ignoring.html). ``` # default .stignore for a go-based project okteto.yaml .git *.exe *.exe~ *.dll *.so *.dylib # Test binary, built with go test -c *.test # Output of the go coverage tool, specifically when used with LiteIDE *.out ``` --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # 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: ``` $ 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: ``` 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: ``` 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](/docs/core/container-registry.md) or another registry your cluster can reach, and reference it with the [`image`](/docs/reference/okteto-manifest.md#image-string-optional) field in your Okteto Manifest. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Migrating to Okteto CLI 2.0 The launch of [Okteto CLI 2.0](https://www.okteto.com/blog/announcing-the-launch-of-okteto-cli-2-0/) provides support for [Okteto Manifest v2](/docs/reference/okteto-manifest.md). The Okteto CLI 2.0 was introduced in [Okteto 0.11.0](/docs/archived-release-notes.md#0110). Older versions of Okteto are not able to support version 2.0 of the CLI. The goal of the new manifest format is to have a single for defining the build, deployment, and development of your application. The v2 manifest also consolidates the various actions possible with previous versions into one command, the improved `okteto up` command. Previously, developers would have to run a series of commands, such as `okteto pipeline deploy` or `okteto stack deploy` and then `okteto up`. The choice between using either the `pipeline` or `stack` commands was often a tripping point for our users and introduced needless complexity. After a user figured this out, they were still not in setup to start active development. The user still needed to run the `okteto up` command. With v2, a single run of `okteto up` will build images, deploy your application, and activate your development container. Note that there are still commands for all the intermediary operations to use when desired: * `okteto build`: builds the images defined in the okteto manifest. * `okteto deploy`: builds any pending images and deploys your dev environment. * `okteto deploy --no-build`: deploys your dev environment without re-building the defined images. * `okteto up`: activates your dev container. * `okteto up --deploy`: forces a redeploy of your development environment before activating your dev container. To facilitate the migration of a v1 okteto manifest to v2 we will cover the following scenarios: * *Scenario 1* Developers with a docker-compose and a v1 manifest * *Scenario 2* Developers with an okteto pipeline file and a v1 manifest * *Scenario 3* Developers with a compose file, pipeline file and a v1 manifest ## Scenario 1: Compose and v1 Manifest This scenario provides an example of transitioning to a v2 manifest using a compose file and a v1 dev manifest. You will continue to use your compose file, providing slight modifications by indexing the services and adding a deploy section. ### v1 manifest #### okteto.yaml ``` name: frontend image: ghcr.io/okteto/node:16 command: bash sync: - .:/app ``` ### v2 manifest #### okteto.yaml ``` deploy: compose: docker-compose.yml dev: frontend: image: ghcr.io/okteto/node:16 command: bash sync: - .:/app ``` ## Scenario 2: Pipeline and Multiple v1 Manifests The following scenario demonstrates converting from an okteto pipeline and v1 manifest to a single v2 manifest. The example files are for a project that uses a pipeline to deploy a 3rd party PostgreSQL helm chart, build your app, and then deploy with a local helm chart. The conversion is performed as follows: * Move the `deploy` section of the pipeline into a new `okteto.yaml` v2 manifest. * Take any `okteto build` commands from that `deploy` section and create a new and separate `build` section in the v2 manifest. * Add all the v1 manifest instructions into indexed sections of the `dev` portion of the v2 manifest. The files used with okteto v1 are: * `okteto-pipeline.yml` -> The pipeline manifest. * `frontend/okteto.yaml` -> The v1 okteto manifest for the frontend service. * `api/okteto.yaml` -> The v1 okteto manifest for the api service. The migration to v2 would result in a single `okteto.yaml` at the root of your project. The example files are as follows: ### v1 manifests #### okteto-pipeline.yml ``` deploy: - helm repo add bitnami https://charts.bitnami.com/bitnami - helm upgrade --install postgresql bitnami/postgresql - okteto build -t okteto.dev/frontend:${OKTETO_GIT_COMMIT} frontend - okteto build -t okteto.dev/api:${OKTETO_GIT_COMMIT} api - helm upgrade --install frontend frontend/chart --set image=okteto.dev/frontend:${OKTETO_GIT_COMMIT} - helm upgrade --install api api/chart --set image=okteto.dev/api:${OKTETO_GIT_COMMIT} ``` #### frontend/okteto.yaml ``` name: frontend image: ghcr.io/okteto/node:16 command: bash sync: - .:/app ``` #### api/okteto.yaml ``` name: api image: ghcr.io/okteto/golang:1 command: bash sync: - .:/app ``` ### v2 manifest The following variables are available within your v2 manifest to refer to the latest build of the images defined in the build section. * `${OKTETO_BUILD__IMAGE}`: the full image reference * `${OKTETO_BUILD__REGISTRY}`: the registry URL where the image was pushed * `${OKTETO_BUILD__REPOSITORY}`: the name of the image that was pushed * `${OKTETO_BUILD__SHA}`: the latest tag and the SHA of the image For example, for the image `registry.okteto.example.com/cindy/hello-world:okteto`, you would have the following values: * `OKTETO_BUILD_HELLO_WORLD_IMAGE`: registry.okteto.example.com/cindy/hello-world\@sha256 :xxx * `OKTETO_BUILD_HELLO_WORLD_REGISTRY`: registry.okteto.example.com * `OKTETO_BUILD_HELLO_WORLD_REPOSITORY`: cindy/hello-world * `OKTETO_BUILD_HELLO_WORLD_SHA`: okteto\@sha256 :xxx ### okteto.yaml ``` build: frontend: context: frontend api: context: api deploy: - helm repo add bitnami https://charts.bitnami.com/bitnami - helm upgrade --install postgresql bitnami/postgresql - helm upgrade --install frontend frontend/chart --set image=${OKTETO_BUILD_FRONTEND_IMAGE} - helm upgrade --install api api/chart --set image=${OKTETO_BUILD_API_IMAGE} dev: frontend: image: ghcr.io/okteto/node:16 command: bash sync: - frontend:/app api: image: ghcr.io/okteto/golang:1 command: bash sync: - api:/app ``` ## Scenario 3: Pipeline, Compose and Multiple v1 Manifests Scenario 3 is similar to Scenario 2, except we are no longer using a 3rd party helm chart to deploy PostgreSQL. Now we are using a separate docker compose file called `db-compose.yml`. ### v1 manifests We start with a similar v1 manifest and pipeline as in scenario 2 except the pipeline is using the deprecated `okteto stack` command to deploy `db-compose.yml` #### okteto-pipeline.yml ``` deploy: - okteto stack deploy -f db-compose.yml - okteto build -t okteto.dev/frontend:${OKTETO_GIT_COMMIT} frontend - okteto build -t okteto.dev/api:${OKTETO_GIT_COMMIT} api - helm upgrade --install frontend frontend/chart --set image=okteto.dev/frontend:${OKTETO_GIT_COMMIT} - helm upgrade --install api api/chart --set image=okteto.dev/api:${OKTETO_GIT_COMMIT} ``` #### frontend/okteto.yaml ``` name: frontend image: ghcr.io/okteto/node:16 command: bash sync: - .:/app ``` #### api/okteto.yaml ``` name: api image: ghcr.io/okteto/golang:1 command: bash sync: - .:/app ``` ### v2 manifest The resulting v2 okteto manifest is again similar to that of scenario 2. However, we have used extended notation in the `deploy` section to launch our PostgreSQL dependency from `db-compose.yml`. The following variables are available within your v2 manifest in order to refer to the latest build of the images defined in the build section. * `${OKTETO_BUILD__IMAGE}`: the full image reference * `${OKTETO_BUILD__REGISTRY}`: the registry URL where the image was pushed * `${OKTETO_BUILD__REPOSITORY}`: the name of the image that was pushed * `${OKTETO_BUILD__SHA}`: the latest tag and the SHA of the image For example, for the image `registry.okteto.example.com/cindy/hello-world:okteto`, you would have the following values: * `OKTETO_BUILD_HELLO_WORLD_IMAGE`: registry.okteto.example.com/cindy/hello-world\@sha256 :xxx * `OKTETO_BUILD_HELLO_WORLD_REGISTRY`: registry.okteto.example.com * `OKTETO_BUILD_HELLO_WORLD_REPOSITORY`: cindy/hello-world * `OKTETO_BUILD_HELLO_WORLD_SHA`: okteto\@sha256 :xxx ### okteto.yaml ``` build: frontend: context: frontend api: context: api deploy: compose: db-compose.yml commands: - helm upgrade --install frontend frontend/chart --set image=${OKTETO_BUILD_FRONTEND_IMAGE} - helm upgrade --install api api/chart --set image=${OKTETO_BUILD_API_IMAGE} dev: frontend: image: ghcr.io/okteto/node:16 command: bash sync: - frontend:/app api: image: ghcr.io/okteto/golang:1 command: bash sync: - api:/app ``` Happy coding! --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto CLI The Okteto Command Line Interface (CLI) is a unified tool to manage your applications in Okteto directly from your terminal. Follow this [guide to download and install the CLI](/docs/get-started/install-okteto-cli.md) if you don't already have it. The CLI is an [open-source](https://github.com/okteto/okteto) tool that can be used independently or integrated with the Okteto Platform. * Commands labeled `Platform` are available exclusively on the Okteto platform and require the [Okteto Helm Chart to be installed](/docs/get-started/install.md) in your Kubernetes cluster * Commands labeled `Open-Source` are available to users of the Okteto open-source CLI For a complete comparison of features, refer to the [open-source README](https://github.com/okteto/okteto/?tab=readme-ov-file#okteto-open-source-cli-features) ## Synopsis ``` $ 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. ## Global Flags | Options | Type | Description | Default | | ------------------- | -------------------------- | ---------------------------- | ------- | | **--help** | bool | Show help info | | | **-l, --log-level** | *debug, info, warn, error* | Amount of information output | warn | | **--log-output** | *tty, plain, json* | Output format for logs | tty | ## Available commands ### analyticsPlatformOpen-Source Enable / Disable analytics collection. Analytics are enabled by default. If [telemetry](/docs/self-hosted/helm-configuration.md#telemetry) is disabled, analytics are disabled for all developers. ``` $ okteto analytics [parameters] ``` | Options | Description | | ----------------- | --------------------------- | | **-d, --disable** | Disable analytic collection | Okteto only collects information to help us understand how our users interact with the product. We don't collect any personally identifiable information. When you use the okteto CLI, the following information is collected: * The name of the action * A timestamp of when it was run * Your version of the CLI * Your OS * An anonymous machine ID (we use for this) * A user ID if you are currently logged in to Okteto * An action ID (to correlate multiple actions performed during a command's execution) Please reach [out to us](mailto://hello@okteto.com) if you have any questions or concerns about the information collected. ### buildPlatform Build and push the images defined in the `build` section using the [Okteto Build Service](/docs/core/build-service.md). ``` $ okteto build [image...] ``` tip To save you time, `okteto build` will only build the image if your build context hasn't been built before. You can always force a build by using the `--no-cache` flag. Learn more about [Okteto Smart Builds here](/docs/core/build-service.md#smart-builds). The following command flags are available: | Options | Type | Description | Default | | ------------------- | ------ | ---------------------------------------- | ------------ | | **-f, --file** | string | The path to the Okteto Manifest | `okteto.yml` | | **-n, --namespace** | string | Overwrite the current Okteto Namespace | | | **--no-cache** | bool | Do not use cache when building the image | `false` | | **--progress** | string | Show plain/tty build output | `tty` | You can also use the `-f` to point to a Dockerfile instead of an Okteto Manifest. In this mode, `okteto build` will build an image using the Dockerfile. This is useful to build images that are not defined on your [Okteto manifest](/docs/reference/okteto-manifest.md). In "Dockerfile" mode, the following additional flags can be used (very similar to `docker build`): | Options | Type | Description | Default | | ------------------ | ------ | ---------------------------------------------------------------------------------------------------------- | ------- | | **--build-arg** | list | Set build-time variables (optional) | | | **--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` or `id=mysecret,env=MY_ENV_VAR` | | | **-t, --tag** | string | Tag name to be pushed (optional) | | | **--target** | string | Target build stage to build (optional) | | tip 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.dev` and `dev.Dockerfile.dockerignore` ### contextPlatformOpen-Source 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. ``` $ okteto context ``` tip `okteto ctx` is an alias of `okteto context`. This will prompt you to select one of your existing Okteto Contexts or to create a new one: ``` A context defines the default cluster/namespace for any Okteto CLI command. Select the context you want to use: Use the arrow keys to navigate: ↓ ↑ → ← ▸ https://okteto.example.com * minikube Create new context ``` | Options | Type | Description | Default | | ---------------------------- | ------ | --------------------------------------------------------------------------------------------------------------- | ------- | | *--insecure-skip-tls-verify* | bool | Skip validation of server's certificates | `false` | | **-n, --namespace** | string | Overwrite the current Okteto Namespace | | | **--token** | string | API token for authentication. Use this when scripting or if you don't want to use browser-based authentication. | | When you run `okteto context`, the Okteto CLI will exchange an authorization token with the Okteto Platform and save your API token and Okteto certificates information under `$HOME/.okteto/`. tip In your CI/CD you should use environment variables to specify your Okteto Context, Namespace and token. Check out [Environment Variables](/docs/core/credentials/environment-variables.md) to know more. Available subcommands: #### delete Delete one or more Okteto Contexts. For example, to delete the Okteto Context "", run: ``` $ okteto context delete https://okteto.example.com ``` #### list List available Okteto Contexts. ``` $ okteto context list ``` ``` Name Namespace Builder Registry https://okteto.example.com * cindy tcp://buildkit.okteto.example.com:1234 registry.okteto.example.com minikube default docker - ``` | Options | Type | Description | Default | | ---------------- | ------ | ------------------------------------- | ------- | | **-o, --output** | string | Output format. One of: `json`, `yaml` | `json` | #### show Print the current Okteto Context. ``` $ okteto context show ``` | Options | Type | Description | Default | | ------------------- | ------ | ------------------------------------- | ------- | | **--include-token** | bool | Include the token in the output | `false` | | **-o, --output** | string | Output format. One of: `json`, `yaml` | `json` | ``` { "name": "https://okteto.example.com", "token": "REDACTED", # only printed using flag: --include-token "namespace": "cindy", "builder": "tcp://buildkit.okteto.example.com:1234", "registry": "registry.okteto.example.com", "isOkteto": true } ``` #### use Set the default Okteto Context. `okteto context use` is an alias of `okteto context`. ### deployPlatform Deploy your Development Environment by running the commands specified in the `deploy` section of your Okteto Manifest. ``` $ okteto deploy ``` If there are pending changes in the images defined in your Okteto Manifest, `okteto deploy` automatically builds and pushes all them. This way, `okteto deploy` enforce all your local changes are pushed to your Development Environment. If the repositories in the `dependencies` section haven't been deployed yet, `okteto deploy` deploys these dependencies automatically. The command is executed relative to the path where the Okteto Manifest is located. This means, that if the Okteto Manifest is at any subfolder, the command will use the context of the subfolder where the Okteto Manifest is defined. ##### Options | Options | Type | Description | Default | | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | *--dependencies* | bool | Force deployment of repositories in the `dependencies` section | Set by cluster config | | **-f, --file** | string | The path to the Okteto Manifest | `okteto.yml` | | **--name** | string | The name of the Development Environment | The repo/folder name | | **-n, --namespace** | string | Overwrite the current Okteto Namespace | | | **--no-bash** | bool | Execute the command using the container's default shell instead of bash | `false` | | **--no-build** | bool | Skips the re-build of images in the `build` section | `false` | | **--remote** | bool | Run the deploy commands using [Remote Execution](/docs/core/remote-execution.md) | `false` | | **-t, --timeout** | duration | The duration to wait until all pods are healthy. Requires `--wait`. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h | 5m0s | | **-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`](/docs/reference/okteto-cli.md#deploy-1), and [`okteto preview deploy`](/docs/reference/okteto-cli.md#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](/docs/development.md) | | `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](/docs/development.md) | | `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](/docs/previews.md) 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](/docs/core/remote-execution.md). * 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](/docs/previews.md) for a branch or pull request in its own Namespace. ### destroyPlatform Destroy your Development Environment. It automatically destroys all the Kubernetes resources created by [okteto deploy](/docs/reference/okteto-cli.md#deploy). If you need to destroy external resources (like s3 buckets or other Cloud resources), use the [destroy](/docs/reference/okteto-manifest.md#destroy-string-optional) section of the Okteto Manifest. ``` $ 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](/docs/reference/okteto-manifest.md#name-string-optional), or with the `--name` flag. In a monorepo scenario, where you might have several Okteto Manifests, you need to specify the correct Okteto Manifest to destroy the specific Development Environment. This ensures that the appropriate destroy commands, as defined in your Okteto Manifest, are executed within a particular scope. This way, executing the `okteto destroy` command on one Development Environment will not delete the other. For example, if you have two Development Environments, `dev1` and `dev2`, and you run `okteto destroy` for `dev1`, it will only destroy the resources for `dev1` and leave `dev2` intact. You can use `okteto destroy --all` to delete all Development Environments in an Okteto Namespace. ##### Options | 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 | | **-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 | | **-n, --namespace** | string | Overwrite the current Okteto Namespace | | | **--no-bash** | bool | Execute the command using the container's default shell instead of bash | `false` | | **--remote** | bool | Run the destroy commands using [Remote Execution](/docs/core/remote-execution.md) | `false` | | **-v, --volumes** | bool | Destroy the persistent volumes created by the Development Environment | `false` | > Resources annotated with `dev.okteto.com/policy: keep` will not be affected by the destroy action. ### doctorPlatformOpen-Source 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. ``` $ okteto doctor [devContainer] ``` The `doctor` command should be run from the folder where you ran `okteto up`. The doctor file contains: * The `okteto.log` * The syncthing logs of your Development Container * A summary of your Development Container manifest * A metadata file with information about your host machine's OS and architecture The following command flags are available: | Options | Type | Description | Default | | ------------------- | ------ | -------------------------------------- | ------------ | | **-f, --file** | string | The path to the Okteto Manifest | `okteto.yml` | | **-n, --namespace** | string | Overwrite the current Okteto Namespace | | ### downPlatformOpen-Source Deactivate your Development Container, stops the file synchronization service, and restores your previous deployment configuration. ``` $ okteto down [devContainer] ``` The `down` command should be run from the same location as `okteto up`. | Options | Type | Description | Default | | ------------------- | ------ | --------------------------------------------------------------------- | ------------ | | **-A, --all** | bool | Deactivate all running Development Containers | `false` | | **-f, --file** | string | The path to the Okteto Manifest | `okteto.yml` | | **-n, --namespace** | string | Overwrite the current Okteto Namespace | | | **-v, --volumes** | bool | Remove persistent volumes where your local folder is synced on remote | `false` | tip Stopping Your Development Container Automatically You can automatically disable your Development Container by setting the `OKTETO_AUTO_DOWN_ENABLED` feature flag to `true`, [this is set as an environment variable](/docs/reference/feature-flags.md). When enabled, `okteto down` will automatically run when you exit the terminal session, provided all commands completed successfully. This helps keep your development environment clean without manual intervention. Learn more about this and other [feature flags](/docs/reference/feature-flags.md). ### endpointsPlatform List the public endpoints of your Development Environment. ``` $ okteto endpoints ``` | Options | Type | Description | | ------------------- | ------ | --------------------------------------- | | **-f, --file** | string | The path to the Okteto Manifest | | **--name** | string | The name of the Development Environment | | **-n, --namespace** | string | Overwrite the current Okteto Namespace | | **-o, --output** | string | Output format. One of: \['json', 'md'] | ### execPlatformOpen-Source The `exec` command allows you to execute a `COMMAND` inside your Development Container, created by an `okteto up` session which is already running. It is important to note that `okteto exec` can only be used with a container that is in development mode. If there is no active Development Container corresponding to the current folder, the command will fail. 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. ``` $ okteto exec [devContainer] -- COMMAND ``` Make sure to run the `exec` command from the same directory where you ran `okteto up`. | Options | Type | Description | Default | | ------------------- | ------ | -------------------------------------- | ------------ | | **-f, --file** | string | The path to the Okteto Manifest | `okteto.yml` | | **-n, --namespace** | string | Overwrite the current Okteto Namespace | | ### helpPlatformOpen-Source Displays the full help. ``` $ okteto help ``` ### kubeconfigPlatformOpen-Source Download credentials for the Kubernetes cluster selected via `okteto context`. ``` $ okteto kubeconfig ``` ``` i Updated kubernetes context 'okteto_example_com/cindy' in '/Users/cindy/.kube/config' ``` ### logsPlatform Fetch the logs of your Development Environment. ``` $ 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. For example, `okteto logs api` fetches the logs of any container starting with `api`. | Options | Type | Description | Default | | -------------------- | -------- | ------------------------------------------------------------- | -------------------- | | **-a, --all** | bool | Fetch logs from the whole namespace | `false` | | **-e, --exclude** | string | Exclude by container name (regular expression) | | | **-f, --file** | string | The path to the Okteto Manifest | `okteto.yml` | | **--name** | string | The name of the Development Environment | The repo/folder name | | **-n, --namespace** | string | Overwrite the current Okteto Namespace | | | **-s, --since** | duration | Return logs newer than a relative duration like 5s, 2m, or 3h | 48h0m0s | | **--tail** | int | The number of lines from the end of the logs to show | 100 | | **-t, --timestamps** | bool | Print timestamps | `false` | ### namespacePlatform Configure the default namespace of the Okteto Context. ``` $ okteto namespace ``` tip `okteto ns` is an alias of `okteto namespace`. This will prompt you to select one of your existing namespaces: ``` Select the namespace you want to use: Use the arrow keys to navigate: ↓ ↑ → ← ▸ cindy Create new namespace ``` ``` ✓ Using context cindy @ okteto.example.com ``` | Options | Type | Description | Default | | -------------- | ---- | ----------------------- | ------- | | **--personal** | bool | Load personal namespace | `false` | #### create 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. ``` $ okteto namespace create test-cindy ``` ``` ✓ Namespace 'test-cindy' created ✓ Using context test-cindy @ okteto.example.com ``` #### delete 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. ``` $ okteto namespace delete test-cindy ``` ``` ✓ Namespace 'test-cindy' deleted ``` #### list List your Okteto Namespaces. ``` $ okteto namespace list ``` ``` Namespace Status demos-cindy Active cindy * Active ``` | Options | Type | Description | Default | | ---------------- | ------ | ------------------------------------- | ------- | | **-o, --output** | string | Output format. One of: `json`, `yaml` | `json` | #### use Configure the default namespace of the Okteto Context. `okteto namespace use` is an alias of `okteto namespace`. #### sleep Sleeps an Okteto Namespace. By default, it sleeps the default namespace in the Okteto Context. ``` $ okteto namespace sleep [name] ``` ``` i Using test-cindy @ okteto.example.com as context ✓ Namespace 'test-cindy' is sleeping ``` If you'd like to sleep an Okteto Namespace other than the default one, you can provide its name as an argument to the command. #### wake Wakes an Okteto Namespace. By default, it wakes the default namespace in the Okteto Context. ``` $ okteto namespace wake [name] ``` ``` i Using test-cindy @ okteto.example.com as context ✓ Namespace 'test-cindy' is awake now ``` If you'd like to wake an Okteto Namespace other than the default one, you can provide its name as an argument to the command. ### pipelinePlatform [Development Environments](/docs/development.md) management commands. ``` $ okteto pipeline [command] ``` Available subcommands: #### deploy Runs a job in the cluster that clones a repository and executes [okteto deploy](/docs/reference/okteto-cli.md#deploy) on it. This is equivalent to clicking the **Deploy Dev Environment** button on the Okteto UI and selecting a git repository. ``` $ okteto pipeline deploy ``` ##### Options | Options | Type | Description | Default | | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------- | | **-b, --branch** | string | The branch to deploy | Your current branch | | *--dependencies* | bool | Force deployment of repositories in the `dependencies` section | Set by cluster config | | **-f, --file** | string | The path to the Okteto Manifest | `okteto.yml` | | **--label** | list | Tag and organize Development Environments using labels (multiple *--label* flags accepted) | | | **--name** | string | The name of the Development Environment | The repo/folder name | | **-n, --namespace** | string | Overwrite the current Okteto Namespace | | | **-r, --repository** | string | The HTTPS url of the repository to deploy (e.g. ) | Your current repository | | **--reuse-params** | bool | If the Development Environment exists, reuse same parameters to redeploy | | | **--skip-if-exists** | bool | Skip the deployment if the Development Environment already exists in the Okteto Namespace | `false` | | **-t, --timeout** | duration | The duration to wait for the deployment to complete. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h | 5m0s | | **-v, --var** | list | Set a variable to be injected in the deploy commands (can be set more than once) | | | **-w, --wait** | bool | Wait until the deployment finishes | `true` | #### destroy Runs a job in the cluster that clones a repository and executes [okteto destroy](/docs/reference/okteto-cli.md#destroy) on it. This is equivalent to clicking the **Destroy** button on the Okteto UI. ``` $ okteto pipeline destroy ``` ##### Options | Options | Type | Description | Default | | ------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | **--dependencies** | bool | Force destroy repositories in the `dependencies` section | Set by cluster config | | **--name** | string | The name of the Development Environment | The repo/folder name | | **-n, --namespace** | string | Overwrite the current Okteto Namespace | | | **-t, --timeout** | string | The duration to wait for the Development Environment to be destroyed. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h | 5m0s | | **-v, --volumes** | bool | Destroy the persistent volumes created by the Development Environment | `false` | | **-w, --wait** | bool | Wait until the Development Environment is destroyed | `true` | #### list List all your Development Environments in the current Okteto Namespace. ``` $ okteto pipeline list ``` Run `okteto pipeline list` to get the status and info of your Development Environments. | Options | Type | Description | Default | | ------------------- | ------ | ------------------------------------------------------------------------------------------ | ------- | | **--label** | list | Tag and organize Development Environments using labels (multiple *--label* flags accepted) | | | **-n, --namespace** | string | Overwrite the current Okteto Namespace | | | **-o, --output** | string | Output format. One of: \['json', 'yaml'] | `json` | ### previewPlatform [Preview environment](/docs/previews.md) management commands. ``` $ okteto preview [command] ``` #### deploy Deploy a Preview Environment. ``` $ okteto preview deploy [name] ``` Run `okteto preview deploy` to automatically deploy a Preview Environment for your branch. | Options | Type | Description | Default | | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | **-b, --branch** | string | The branch to deploy | Your current branch | | **--dependencies** | bool | Force deployment of repositories in the `dependencies` section | Set by cluster config | | **-f, --file** | string | The path to the Okteto Manifest | `okteto.yml` | | **--label** | list | Tag and organize Preview Environments using labels (multiple *--label* flags accepted) | | | *--repository* | string | The url of the repository to deploy (e.g. ) | Your current repo | | **-s, --scope** | string | The scope of Preview Environment to create: `personal` or `global`. A personal Preview Environment can only be accessed by its creator, while in a global Preview Environment all cluster users can access it. | `global` | | **--sourceUrl** |  string | The HTTPS url of the pull/merge request to deploy. | | | **-t, --timeout** | duration | The duration to wait for the deployment to complete. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h | 5m0s | | **-v, --var** | list | Set a variable to be injected in the deploy commands (can be set more than once) | | | **-w, --wait** | bool | Wait until the deployment finishes | `true` | #### destroy Destroy a Preview Environment. ``` $ okteto preview destroy [name] ``` Run `okteto preview destroy` to destroy a Preview Environment by name. If the Okteto Manifest includes `destroy` commands, they will be executed as part of this command. | Options | Type | Description | Default | | -------------- | ---- | ------------------------------------------------------- | ------- | | **-w, --wait** | bool | Wait until the Preview Environment destruction finishes | `true` | #### endpoints List the endpoints of a Preview Environment. ``` $ okteto preview endpoints [name] ``` | Options | Type | Description | Default | | ---------------- | ------ | -------------------------------------- | ------- | | **-o, --output** | string | Output format. One of: \[`json`, `md`] | `json` | Output flag can be used to parse the endpoints and add them to your PR with a custom layout. #### list List all your Preview Environments. ``` $ okteto preview list ``` Run `okteto preview list` to get the status and scope of your Preview Environments. | Options | Type | Description | Default | | ------------------- | ------ | -------------------------------------------------------------------------------------- | ------- | | **--label** | list | Tag and organize Preview Environments using labels (multiple *--label* flags accepted) | | | **-n, --namespace** | string | Overwrite the current Okteto Namespace | | | **-o, --output** | string | Output format. One of: \[`json`, `yaml`] | `json` | #### sleep Sleep an Preview Environment. Only users with admin access or who own the Preview Environment can take this action. ``` $ okteto preview sleep [name] ``` More on sleeping resources [here](/docs/admin/cleanup.md#manually-sleeping-resources). #### wake Wake a Preview Environment. You must provide the name of a Preview Environment as an argument for this command. ``` $ okteto preview wake [name] ``` ### restartPlatformOpen-Source Restarts the containers corresponding to the `services` section for a given Development Container. This is useful to reload configurations that cannot be hot-reloaded. ``` $ okteto restart [devContainer] ``` The `restart` command should be run from the same location than `okteto up`. | Options | Type | Description | Default | | ------------------- | ------ | -------------------------------------- | ------------ | | **-f, --file** | string | The path to the Okteto Manifest | `okteto.yml` | | **-n, --namespace** | string | Overwrite the current Okteto Namespace | | ### statusPlatformOpen-Source Status of the file synchronization process for a given Development Container. ``` $ okteto status [devContainer] --info ``` ``` i Local syncthing url: http://localhost:60539 i Remote syncthing url: http://localhost:60538 i Syncthing username: okteto i Syncthing password: ac0ee34a-b1aa-4a41-bc67-cec3128b6cfd ✓ Synchronization status: 100.00% ``` The `status` command should be run from the same location than `okteto up`. | Options | Type | Description | Default | | ------------------- | ------ | -------------------------------------------------------------------- | ------------ | | **-f, --file** | string | The path to the Okteto Manifest | `okteto.yml` | | **--info** | bool | Show syncthing links for troubleshooting the synchronization service | | | **-n, --namespace** | string | Overwrite the current Okteto Namespace | | | **-w, --watch** | bool | Watch for changes | | ### testPlatform Run tests using [Remote Execution](/docs/core/remote-execution.md#how-remote-execution-works). ``` $ 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](/docs/core/okteto-variables.md#configuring-dynamic-endpoints) are also available within the test commands. 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 | | ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------- | | **--deploy** | bool | Force execution of the commands in the `deploy` section | `false` | | **-f, --file** | string | The path to the Okteto Manifest | `okteto.yml` | | **-n, --namespace** | string | Overwrite the current Okteto Namespace | | | **--name** | string | The name of the Development Environment | The repo/folder name | | **--no-cache** | bool | By default, the `caches` of a Test Container are reused between executions | `false` | | **-t, --timeout** | duration | The duration to wait for the Test Container to run. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h | 5m0s | | **-v, --var** | list | Set a variable to be injected in the test commands (can be set more than once) | | ### upPlatformOpen-Source Activate a Development Container. If needed, `okteto up` builds the images and runs the deploy commands defined in your [Okteto Manifest](/docs/reference/okteto-manifest.md). ``` $ okteto up [devContainer] ``` 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](/docs/reference/okteto-manifest.md). A typical example of this is to replace the production container image with one that contains your development runtime. * A bidirectional file [synchronization service](/docs/reference/file-synchronization.md) is started to keep your changes up to date between your local filesystem and your development container. * Automatic local and remote port forwarding using [SSH](/docs/reference/ssh-server.md). This allows you to do things like access your cluster services via `localhost` or connect a remote debugger. * A watcher service to keep the definition of the mirror deployment up to date with original deployment. It's worth noting that your Development Container inherits the original deployment manifest definition. Therefore, the Development Container uses the same service account, environment variables, secrets, volumes, sidecars, ... than the original deployment, providing a fully integrated development environment. `okteto up` also creates a persistent volume for your Development Container, shown as **Dev Volume** in the [Okteto Dashboard](/docs/get-started/using-okteto-cli-and-dashboard.md#overview-of-the-okteto-dashboard). It persists the synchronized files and any configured caches between `okteto up` sessions. Configure it with the [`persistentVolume`](/docs/reference/okteto-manifest.md#persistentvolume-object-optional) field in your Okteto Manifest. While a service is in development mode, the Okteto Dashboard marks it with an Okteto icon. > Run [`okteto down`](#down) to restore your original deployment. Stopping Your Development Container Automatically You can automatically disable your Development Container by setting the `OKTETO_AUTO_DOWN_ENABLED` feature flag to `true`, [this is set as an environment variable](/docs/reference/feature-flags.md). When enabled, `okteto down` will automatically run when you exit the terminal session, provided all commands completed successfully. This helps keep your development environment clean without manual intervention. Learn more about this and other [feature flags](/docs/reference/feature-flags.md). | Options | Type | Description | Default | | ------------------- | ------ | ------------------------------------------------------------------------------------------------- | ------------ | | **-d, --deploy** | bool | Force the redeployment of your Development Environment | `false` | | **-e, --env** | list | Set environment variable in the Development Container | | | **-f, --file** | string | The path to the Okteto Manifest | `okteto.yml` | | **-n, --namespace** | string | Overwrite the current Okteto Namespace | | | **-r, --remote** | int | Exposes the SSH server in a given port | | | **--reset** | bool | Resets the file synchronization service. Use it if the file synchronization service stops working | `false` | You can also overwrite the start [command](/docs/reference/okteto-manifest.md#command-string-optional) in your Development Container with the syntax `okteto up -- COMMAND [args...]`. ### validatePlatformOpen-Source This command helps you catch configuration errors, typos or invalid syntax in your Okteto Manifest. When authoring a new manifest or updating an existing one, you can use this command to quickly validate the changes you've made. By default, it will use the Okteto Manifest in the current directory, alternatively you can specify a different path using the `--file` flag. ``` $ okteto validate ``` The following command flags are available: | Options | Type | Description | Default | | -------------- | ------ | ------------------------------- | ------------ | | **-f, --file** | string | The path to the Okteto Manifest | `okteto.yml` | ### versionPlatformOpen-Source Show the current installed Okteto CLI binary version ``` $ okteto version ``` Available subcommands: #### update Show information about how to update the Okteto CLI binary. ``` $ okteto version update ``` ``` You can update okteto with the following: # Using installation script: curl https://get.okteto.com -sSfL | sh # Using brew: brew upgrade okteto ``` ## Dynamic Environment Variables Okteto automatically creates dynamic environment variables for build dependencies so you can easily reference outputs from dependency builds in your own builds or pipelines. The format is: ``` OKTETO_DEPENDENCY_${DEPENDENCY_NAME}_BUILD_${BUILD_SVC}_${BUILD_ENVVAR} ``` Where: * `${DEPENDENCY_NAME}` is the name of the dependency (as defined in your manifest’s dependencies section) * `${BUILD_SVC}` is the service being built within that dependency * `${BUILD_ENVVAR}` is the name of the environment variable you wish to reference from the build **Example** - Suppose you have the following in your manifest: ``` deploy: - name: Deploy Application command: | helm upgrade --install hello-world ./hello-world \ --set helloworld.image.repository=${OKTETO_DEPENDENCY_HELLO_WORLD_NOCHART_BUILD_HELLO_WORLD_IMAGE} \ --set holamundo.image.repository=${OKTETO_DEPENDENCY_HOLA_MUNDO_NOCHART_BUILD_HOLA_MUNDO_IMAGE} \ --values values-okteto.yaml ``` * `OKTETO_DEPENDENCY_HELLO_WORLD_NOCHART_BUILD_HELLO_WORLD_IMAGE` will be resolved by Okteto to the image repository produced by the `hello-world` service build of the `hello-world-nocharts` dependency. * `OKTETO_DEPENDENCY_HOLA_MUNDO_NOCHART_BUILD_HOLA_MUNDO_IMAGE` will be resolved by Okteto to the image repository produced by the `hola-mundo` service build of the `hola-mundo-nocharts` dependency. This mechanism enables advanced automation and chaining of build artifacts or secrets between dependencies and services. tip Use these variables in your build args, deploy steps, or pipeline commands wherever you need to consume data produced by dependency builds. ## Troubleshooting ### Kubernetes authentication After you've ran `okteto kubeconfig` you should be able to communicate with the cluster through tools like `kubectl` and `helm`. If you are getting errors when trying to do so, you can use the `okteto kubetoken` command to troubleshoot the issue. This command is used internally as your [authentication plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins) against the cluster. When running ``` $ okteto kubetoken # example: okteto kubetoken https://okteto.example.com cindy ``` You should see a message like this: ``` { "apiVersion": "client.authentication.k8s.io/v1", "metadata": { "creationTimestamp": null, "managedFields": [ { "manager": "backend", "operation": "Update", "apiVersion": "authentication.k8s.io/v1", "time": "2023-03-01T13:18:48Z", "fieldsType": "FieldsV1", "fieldsV1": { "f:spec": { "f:expirationSeconds": {} } }, "subresource": "token" } ] }, "spec": { "audiences": [""], "expirationSeconds": 1800, "boundObjectRef": null }, "status": { "token": "", "expirationTimestamp": "2023-03-01T13:48:48Z" } } ``` If you are getting something else, you should be receiving an error message with guidance on how to follow up. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto Manifest Reference `okteto.yaml` is a manifest format for describing development environments. The Okteto Manifest has four main sections: `build`, `deploy`, `test` and `dev`, to define how to build, deploy, test, and develop your development environment. The open-source version of Okteto supports features within the `dev` section of the Okteto Manifest. For a complete comparison of features, refer to the [open-source README](https://github.com/okteto/okteto/?tab=readme-ov-file#okteto-open-source-cli-features). ## Example ``` build: api: context: api frontend: context: frontend deploy: - helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE} dev: api: command: ["bash"] forward: - 8080:8080 - 9229:9229 sync: - api:/usr/src/app frontend: command: yarn start sync: - frontend:/usr/src/app test: unit: image: ghcr.io/okteto/golang:1 commands: - "go test ." ``` ## Validating and Autocompleting the Okteto Manifest in 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: ``` { "yaml.schemas": { "https://raw.githubusercontent.com/okteto/okteto/master/schema.json": [ "okteto.yml", "okteto.yaml" ] } } ``` For **JetBrains IDEs**, you can use the built-in [JSON Schema feature](https://www.jetbrains.com/help/idea/json.html) specifying the following params: * Schema URL as `https://raw.githubusercontent.com/okteto/okteto/master/schema.json` * Schema version as `2020.12` * Files: `okteto.yml` and `okteto.yaml` ## Schema reference ### build (object, optional) A list of images to build as part of your development environment. ``` build: base: context: . api: context: api frontend: context: frontend dockerfile: Dockerfile target: dev depends_on: base args: 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: * `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. * `context`: the build context. Relative paths are relative to the location of the Okteto Manifest (default: `.`) * `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](/docs/core/container-registry.md) is used). * `secrets`: list of secrets exposed to the build. Each secret can be defined in one of three forms: **Shorthand (file path):** ``` secrets: my_secret: /path/to/secret/file ``` **Explicit file key:** ``` secrets: my_secret: file: /path/to/secret/file ``` **Environment variable:** ``` 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: ``` 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. tip 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` For a list of [environment variables](/docs/core/okteto-variables.md#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. ### dependencies (\[string], optional) A list of repositories you want to deploy as part of your development environment. Dev environments with declared dependencies will surface additional options during redeploy and destroy actions in the Okteto UI ``` dependencies: - https://github.com/okteto/movies-frontend ``` tip Use `okteto deploy --dependencies` to force the redeployment of your dependencies. There is also an extended notation to configure how to deploy your dependencies: ``` dependencies: frontend: repository: https://github.com/okteto/movies-frontend manifest: okteto.yaml branch: main variables: ENVIRONMENT: development DEBUG: true wait: true timeout: 15m ``` Each dependency supports the following fields: * `repository`: the URL of the git repository containing the dependency * `manifest`: the path to the Okteto Manifest within the repository. Defaults to `okteto.yaml` in the root of the repository * `branch`: the branch or tag to deploy. If not specified, it uses the default branch of the repository * `variables`: environment variables to set during the dependency deployment. These are passed to the dependency's deploy commands * `wait`: if `true`, Okteto waits for the dependency deployment to complete before continuing with the main deployment. If `false`, the dependency deploys asynchronously (default: `false`) * `timeout`: maximum time to wait for the dependency deployment to complete when `wait` is `true`. Uses duration format like `5m`, `1h`, etc. (default: `5m`) ### deploy (\[string], optional) A list of commands to deploy your development environment. It's usually a combination of `helm`, `kubectl`, and `okteto` commands. #### Deploy with Commands For example, deploy a Helm chart using a command to invoke the `helm` CLI: ``` deploy: - helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE} ``` You can name your commands with the following syntax: ``` deploy: - name: Deploy Movies App with Helm command: helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE} ``` You can share environment variables between steps by adding them to `$OKTETO_ENV`: ``` deploy: - name: Set env value command: echo "OKTETO_FOLDER=/app" >> $OKTETO_ENV - name: Get env value command: echo "$OKTETO_FOLDER" # Prints /app ``` See the [environment variables](/docs/core/okteto-variables.md#runtime-environment-variables-injected-into-pods) available in your deploy commands. #### Deploy remotely (recommended) If you define an image in your `deploy` section, `okteto deploy` will run in remote mode: ``` deploy: 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} ``` The `context` field specifies the working directory for running the deploy commands. If left empty, it defaults to the directory containing the Okteto Manifest. If you don't define an image, you can run in remote mode adding the `remote` field to your manifest: ``` deploy: remote: true commands: - helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE} ``` See [Remote Execution](/docs/core/remote-execution.md) for details on how remote mode works. #### Deploy with Compose Deploy a Docker Compose file using the following notation: ``` deploy: compose: docker-compose.yml ``` note Images specified in the `build` section of the Okteto Manifest overrides the image associated with services sharing the same name in your Docker Compose files. If you want to deploy only a subset of the services in the Docker compose file, you can use the `services` field. By default, all services are deployed. ``` deploy: compose: file: docker-compose.yml services: - frontend ``` There is an extended notation to deploy several Docker Compose files and [endpoints](/docs/reference/docker-compose.md#endpoints-object-optional). Only the `volumes` and `endpoints` of the services specified in the `services` field are deployed: ``` deploy: compose: - file: docker-compose.yml services: - frontend - file: docker-compose.dev.yml services: - api endpoints: - path: / service: frontend port: 80 - path: /api service: api port: 8080 ``` You can combine deploy commands with Docker Compose files: ``` deploy: commands: - helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE} compose: docker-compose.yml ``` 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 reduces infrastructure costs and complexity in large microservices architectures. Okteto supports two different drivers: `nginx` (default) and `istio`. * Nginx * Istio Use the `nginx` driver if your applications rely on Okteto-generated endpoints for service-to-service communication. To deploy a `diverted` development environment, add the `divert.namespace` key under the `deploy` section of your Okteto Manifest. This configuration tells Okteto where to redirect requests for services not deployed in your current development environment. ``` deploy: commands: - helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE} divert: driver: nginx namespace: staging ``` * `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. **Environment Variable Support:** The `namespace` field supports environment variable substitution: ``` divert: namespace: ${OKTETO_SHARED_NAMESPACE:-staging} ``` **Behavior:** When you run `okteto deploy` with a `divert` configuration: 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. Beyond request routing, this header can also be used to: * Route messages to different queues or topics * Redirect requests to services in other namespaces * Dynamically select the correct database instance for read/write operations Check out [Using Divert](/docs/development/using-divert.md#header-propagation) for language-specific examples of header propagation. **Additional Examples:** With local database: ``` 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: ``` 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 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: ``` deploy: commands: - helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE} divert: driver: istio virtualServices: - name: vs1 namespace: staging routes: - route1 - route2 hosts: - virtualService: frontend namespace: staging ``` * `driver`: Specifies the backend to divert requests. Use `istio` to use the Istio driver. * `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](/docs/core/divert.md)** - Understanding Divert architecture and traffic routing * **[Using Divert](/docs/development/using-divert.md)** - Implementation guide with header propagation examples * **[Divert Tutorial](/docs/tutorials/divert.md)** - Step-by-step getting started guide * **[Self-Hosted Configuration](/docs/self-hosted/install/divert.md)** - Admin setup for Divert drivers ### destroy (\[string], optional) A list of commands to destroy external resources created by your development environment. `okteto destroy` automatically takes care of destroying all the Kubernetes resources created by `okteto deploy` in your namespace. Use the `destroy` section if you create resources outside of your namespace, like clusterroles, or out of the scope of Kubernetes, like s3 buckets or RDS databases. ``` destroy: - helm uninstall movies ``` You can name your commands with the following syntax: ``` destroy: - name: Uninstall Movies App command: helm uninstall movies ``` See the [environment variables](/docs/core/okteto-variables.md#runtime-environment-variables-injected-into-pods) available in your destroy commands. #### Destroy remotely (recommended) If you define an image in your `destroy` section, `okteto destroy` will run in remote mode: ``` destroy: image: ghcr.io/okteto/tfenv-ci:1.4 context: . commands: - terraform destroy --auto-approve ``` The `context` field specifies the working directory for running the destroy commands. If left empty, it defaults to the directory containing the Okteto Manifest. If you don't define an image, you can run in remote mode adding the `remote` field to your manifest: ``` destroy: remote: true commands: - helm uninstall movies ``` See [Remote Execution](/docs/core/remote-execution.md) for details on how remote mode works. ### dev (object, optional) A list of development containers to define the behavior of [okteto up](/docs/reference/okteto-cli.md#up) and synchronize your code in your development environment. ``` dev: api: command: ["bash"] forward: - 8080:8080 - 9229:9229 sync: - api:/usr/src/app frontend: command: yarn start sync: - frontend:/usr/src/app ``` The `name` of each development container must match the name of the Kubernetes Deployment or Statefulset that you want to put on development mode. If the name of your Deployment or Statefulset is dynamically generated, use the [selector](/docs/reference/okteto-manifest.md#selector-mapstringstring-optional) field to match the Deployment or Statefulset by labels. 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. 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. ``` affinity: podAffinity: requiredDuringSchedulingIgnoredDuringExecution: - labelSelector: matchExpressions: - key: role operator: In values: - web-server topologyKey: kubernetes.io/hostname ``` #### autocreate (bool, optional) If set to true, `okteto up` creates a deployment if `name` doesn't match any existing deployment in the current namespace (default: `false`). #### command (string, optional) Sets the command of your development container. If empty, it defaults to `sh`: ``` command: bundle exec thin -p 3000 ``` The command can also be a list: ``` command: ["bundle", "exec", "thin", "-p", "3000"] ``` #### container (string, optional) The name of the container in your deployment you want to put on development mode. By default, it takes the first one. #### environment (\[string], optional) Add environment variables to your development container. If a variable already exists on your deployment, it will be overridden with the value specified on the manifest. Environment variables with only a key, or with a value with a `$` sign resolve to their values on the machine Okteto is running on, which can be helpful for secret or machine-specific values. ``` 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 DBPASSWORD: ## will be given the value of $DBPASSWORD if it exists ``` They can also be defined as a list, for example: ``` 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 - DBPASSWORD ``` #### envFiles Add environment variables to your development container from a file. ``` envFiles: - .env1 - .env2 ``` Environment variables declared in the environment section override these values. #### externalVolumes (\[string], optional) A list of persistent volume claims (not managed by Okteto) that you want to mount in your development container. This is useful to share cache information between different development containers. For example, to share the go cache between different development containers, you could define: ``` externalVolumes: - go-cache:/root/.cache/go-build/ ``` on different Okteto Manifests. You can also mount a relative subpath of a given persistent volume claim: ``` externalVolumes: - pvc-name:subpath:/var/lib/mysql ``` #### forward (\[string], optional) A list of ports to forward from your development container. The list should follow the `localPort:remotePort` notation and each element should be unique. You can also access other services running in your namespace by using the notation `localPort:remoteService:remotePort`. ``` forward: - 8080:80 - 5432:postgres:5432 ``` You can also use the extended notation below to configure the service to be exposed using a label selector or its name. ``` forward: - localPort: 8080 remotePort: 80 name: app - localPort: 5432 remotePort: 5432 labels: app: db ``` Once your development container is up and running, you will be able to access the port directly by using `localhost:localPort`. > Common uses of port forwarding are: > > 1. Access a service via `localhost` instead of via an ingress > 2. Remote debugging > 3. Connect to a hot reloader via a websocket If Okteto can't forward a port (typically because they are already taken), the `okteto up` command will fail with an error. #### initContainer (object, optional) Allows you to override the okteto init container configuration of your development container. ``` initContainer: image: ghcr.io/okteto/okteto:3.14.0 resources: requests: cpu: 30m memory: 30Mi limits: cpu: 30m memory: 30Mi ``` #### interface (string, optional) Port forwards and reverse tunnels will be bound to this address. Defaults to `localhost`. ``` interface: 0.0.0.0 ``` #### image (string, optional) Sets the docker image of your development container. Defaults to the image specified in your deployment. > See the [development images](/docs/development/images.md) documentation for more details. You can use an environment variable to replace the image, or any part of it: ``` image: ghcr.io/okteto/dev:$USER ``` > See [how to use private images](/docs/reference/faqs.md#how-to-use-private-images) for your Development Container. #### imagePullPolicy (string, optional) The image pull policy of your development environment (default: `Always`) #### lifecycle (boolean, optional) Configures lifecycle hooks for your development container. Lifecycle hooks allow you to execute commands when your container starts or stops, enabling you to automate setup or cleanup tasks. If set to true, both postStart and preStop lifecycle events are enabled when running `okteto up` inheriting the lifecycle from the original container (default: false). For more information about Kubernetes lifecycle hooks, see the official [Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/attach-handler-lifecycle-event/). ``` lifecycle: true ``` This enables both postStart and preStop events to use the default commands defined in your Kubernetes deployment. For more granular control, you can enable or disable specific lifecycle events and define custom commands to run during those events. ``` lifecycle: postStart: enabled: true command: "echo 'Container has started'" preStop: enabled: true command: "echo 'Container is stopping'" ``` * postStart: * enabled (boolean): Set to true to enable the postStart event (default: false). * command (string): The command to execute when the container starts. * preStop: * enabled (boolean): Set to true to enable the preStop event (default: false). * command (string): The command to execute just before the container stops. #### metadata (object, optional) The metadata field allows to inject labels and annotations into your development container. ``` metadata: annotations: fluxcd.io/ignore: "true" labels: custom.label/dev: "true" ``` #### mode (string, optional) The development mode used for a development environment. There are two options available for this field: * `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 See [development modes](/docs/development/containers.md) for details. #### nodeSelector (map\[string]string, optional) List of labels that the node must have to include the development container on it. See the Kubernetes documentation on [node selectors](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) for details. ``` nodeSelector: disktype: ssd ``` #### persistentVolume (object, optional) `okteto up` creates a persistent volume for your Development Container, shown as **Dev Volume** in the [Okteto Dashboard](/docs/get-started/using-okteto-cli-and-dashboard.md#overview-of-the-okteto-dashboard). It persists the synchronized files and any configured caches between `okteto up` sessions. Allows you to configure the Okteto persistent volume: * `enabled`: enable/disable the use of persistent volumes (default: `true`) * `accessMode`: the Okteto persistent volume [access mode](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) (default: `ReadWriteOnce`) * `annotations`: add annotations to the Okteto persistent volume * `labels`: add labels to the Okteto persistent volume * `size`: the size of the Okteto persistent volume (default: `5Gi`) * `storageClass`: the storage class of the Okteto persistent volume (default: the `default` storage class in your cluster) * `volumeMode`: the Okteto persistent volume [mode](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#volume-mode) (default: `Filesystem`) ``` persistentVolume: enabled: true storageClass: standard size: 30Gi ``` Note the following limitations: * `persistentVolume.enabled` must be `true` if you use [services](/docs/reference/okteto-manifest.md#services-object-optional). * `persistentVolume.enabled` must be `true` if you use [volumes](/docs/reference/okteto-manifest.md#volumes-string-optional). * `persistentVolume.enabled` must be `true` if you want to share command history across development containers between different `okteto up` sessions. #### priorityClassName (string, optional) This field allows you to optionally override the priorityClassName of your development container. By default, this is not set, but you can specify a custom value as shown below: ``` priorityClassName: okteto ``` This value will also apply to the `priorityClassName` of the pods defined in your [services](/docs/reference/okteto-manifest.md#services-object-optional). #### probes (boolean, optional) If set to true, liveness, readiness, and start probes are enabled when running `okteto up` (default: `false`). 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: ``` probes: liveness: true readiness: true startup: true ``` * `liveness`: specifies if liveness probes are enabled when running `okteto up` (default: `false`). * `readiness`: specifies if readiness probes are enabled when running `okteto up` (default: `false`). * `startup`: specifies if startup probes are enabled when running `okteto up` (default: `false`). #### resources (object, optional) Allows you to override the resources configuration of your development container. It follows the [same syntax used in Kubernetes](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container). By default, `requests`, `limits` and `ephemeral-storage` are unset. ``` resources: requests: cpu: "250m" memory: "64Mi" ephemeral-storage: "64Mi" limits: cpu: "500m" memory: "1Gi" ephemeral-storage: "1Gi" ``` #### remote (integer, optional) The local port to use for SSH communication with your development environment. Defaults to a random value. ``` remote: 2222 ``` > Setting this value in the manifest is equivalent to starting your development container with the `okteto up --remote=2222` command. #### reverse (\[string], optional) A list of ports to reverse forward from your development container to your local machine. The list should follow the `remotePort:localPort` notation and each element should be unique. ``` reverse: - 9000:9001 - 8080:8080 ``` Once your development container is up and running, any requests to `0.0.0.0:remotePort` in the development container will be directed to `localhost:localPort` > Common uses of reverse forwarding are: > > 1. Remote debugging > 2. Send events or logs to your local machine If Okteto can't reverse forward a port (typically because they're already taken), the `okteto up` command will fail with an error. #### secrets (\[string], optional) A list of secrets that will be injected into your development container. The format of a secret is `LOCAL_PATH:REMOTE_PATH:MODE`. `LOCAL_PATH` must exist, `REMOTE_PATH` must be an absolute path, and `MODE` is the remote file permissions in Base-8 (optional: defaults to `644`). ``` secrets: - $HOME/.token:/root/.token:400 ``` #### securityContext (object, optional) 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/). ``` securityContext: runAsUser: 1000 runAsGroup: 2000 fsGroup: 3000 runAsNonRoot: false allowPrivilegeEscalation: false readOnlyRootFilesystem: false capabilities: add: - SYS_PTRACE ``` > Non-root Containers: > > If you're using a non-root container, and the runAsUser and runAsGroup values are not specified in your Kubernetes manifest, you need to set these values in your Okteto manifest. Remember to use the numeric ID in all cases, not the human readable name. #### selector (map\[string]string, optional) The labels of the Kubernetes deployment/statefulset you want to put on development mode. They must identify a single Kubernetes deployment/statefulset. ``` selector: app.kubernetes.io/name: vote ``` #### serviceAccount (string, optional) Allows you to override the [serviceAccount](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) of your development container. ``` serviceAccount: default ``` #### services (\[object], optional) A list of services that you want to put on developer mode along your development container. 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. ``` dev: web: command: ["python", "manage.py", "runserver", "0.0.0.0:8080"] sync: - .:/app services: - name: worker replicas: 2 command: ["celery", "worker", "-A", "myproject.celeryconf", "-Q", "default", "-n", "default@%h"] sync: - .:/app ``` and both deployments, `web` and `worker` will mount your local folder `.` into the path `/app`. The supported keys for containers defined in this section are: 1. `annotations` 2. `command` 3. `container` 4. `environment` 5. `image` 6. `labels` 7. `name` 8. `resources` 9. `sync` 10. `tolerations` 11. `workdir` 12. `replicas` They work the same as for the main container, except for the `command` and `name` keys. For `services`, `command` defaults to the command specified in your deployment, instead of `sh`. `labels` and `name` are mutually exclusive (for the main container, `name` is mandatory). `replicas` specifies the number of replicas for service dev containers. If `replicas` is not specified, it defaults to the original deployment replicas. #### sync (\[string], required) Specifies local folders that must be synchronized to the development container. ``` sync: - .:/code ``` `sync` supports relative paths and environment variable expansion: ``` sync: - .:/code - config:/etc/config - $HOME/.ssh:/root/.ssh ``` > Use the `.stignore` file on each local folder to avoid synchronizing build artifacts, dependencies, or git metadata. See the [file synchronization reference](/docs/reference/file-synchronization.md) 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](/docs/reference/okteto-manifest.md#secrets-string-optional) to synchronize a single file instead of a folder There is also an extended `sync` notation to fine tune the file synchronization service: ``` sync: folders: - .:/code verbose: false compression: true rescanInterval: 100 ``` * `folders`: list of local folders that must be synchronized to the development container * `verbose`: enable verbose logging for syncthing (default: `true`) * `compression`: compress files before synchronizing them (default: `false`) * `rescanInterval`: the synchronization service [rescan internal](https://docs.syncthing.net/users/syncing.html?highlight=rescan#scanning) in seconds. It can be set to zero to disable rescans (default: `300`) #### timeout (time, optional) Maximum time to be waiting for creating a development container until an error is returned. ``` timeout: 5m ``` You can also use the extended notation below to specify max time to be waiting for resources. ``` timeout: default: 3m resources: 5m ``` #### tolerations (\[object], optional) A list of tolerations that will be injected into your development container. See the Kubernetes documentation on [taints and tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) for details. ``` tolerations: - key: nvidia.com/gpu operator: Exists ``` #### volumes (\[string], optional) A list of paths in your development container that you want to associate to persistent volumes. This is useful to persist information between `okteto up` executions, like downloaded libraries or cache information. For example, to speed your go builds up, you could define: ``` volumes: - /go/pkg/ - /root/.cache/go-build/ ``` You can also mount a relative subpath of your local folder: ``` volumes: - data:/var/lib/mysql ``` #### workdir (string, optional) 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. ``` external: db: notes: docs/database.md icon: database endpoints: - name: db url: https://localhost:3306 functions: notes: docs/lambdas.md icon: function endpoints: - name: data-aggregator url: https://fake-id.lambda-url.us-east-1.on.aws.aggregator - name: data-processor url: https://fake-id.lambda-url.us-east-1.on.aws.processor ``` #### endpoints (\[object], required) Endpoints contain information on how to access the external resource. ##### name (string, required) The name of the endpoint. ##### url (string, optional) The url of the endpoint. ##### Use dynamic endpoints for an external URL The url value related to an external resource can be set during deployment stage by sharing `$OKTETO_EXTERNAL_{EXTERNAL_NAME}_ENDPOINTS_{ENDPOINT_NAME}_URL`. This allows a value to be generated dynamically at deployment time. ``` deploy: - name: Set endpoint URL dynamically command: echo "OKTETO_EXTERNAL_DB_ENDPOINTS_DB_URL=$(aws deploy db --name foo)" >> $OKTETO_ENV - name: Use dynamic value command: echo ${OKTETO_EXTERNAL_DB_ENDPOINTS_DB_URL} external: db: notes: docs/database.md icon: database endpoints: - name: db # url: is not set because it is dynamically generated in the deploy section. ``` If the url value is declared in both places, the one declared in the deploy section will prevail. #### 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`. | | | | | | | | :---------------------------------------------: | :---------------------------------------------------------------: | :------------------------------------------------------------------------: | :------------------------------------------------------------: | :---------------------------------------------------------: | :------------------------------------------------------------: | | `aws`
![AWS icon](/docs/img/icons/aws.svg) | `container`
![container icon](/docs/img/icons/container.svg) | `dashboard`
![dashboard icon](/docs/img/icons/dashboard.svg) | `database`
![database icon](/docs/img/icons/database.svg) | `default`
![default icon](/docs/img/icons/default.svg) | `function`
![function icon](/docs/img/icons/function.svg) | | `gcp`
![gcp icon](/docs/img/icons/gcp.svg) | `graph`
![graph icon](/docs/img/icons/graph.svg) | `launchdarkly`
![launchdarkly icon](/docs/img/icons/launchdarkly.svg) | `mongodb`
![mongodb icon](/docs/img/icons/mongodb.svg) | `okteto`
![okteto icon](/docs/img/icons/okteto.svg) | `storage`
![storage icon](/docs/img/icons/storage.svg) | #### notes (string, optional) A relative path to a markdown file. The contents of the file will be displayed in the Okteto UI. You can use this to describe the resource or share instructions on how to use it. [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/) is supported, which adds the following to standard [Markdown](https://www.markdownguide.org/): * Autolink literals (`www.x.com`) * Footnotes (`[^1]`) * Strikethrough (`~~stuff~~`) * Tables (`| cell |…`) * Tasklists (`* [x]`) Images are allowed, as long as they are referenced by `https://`. Images from unsupported protocol sources or relative paths will not render and will be replaced with a warning message pointing to this document. Inline HTML markup will be escaped and render as text. ### forward (\[string], optional) When declaring a global forward, Okteto will automatically handle port collision when two or more `okteto up` sessions are running simultaneously. If the `okteto up` session detects that the port is already in use, and said port is defined as global forward, `okteto up` will ignore the port collision and continue the `up` sequence. If the port is later available, `okteto up` session will automatically connect to it without interrupting the session. Global forward uses the same format than [forward](#forward-string-optional): ``` forward: - 5432:postgres:5432 - localPort: 8080 remotePort: 80 name: app ``` You can also indicate the service to expose using a label selector. ``` forward: - localPort: 5432 remotePort: 5432 labels: app: db ``` ### icon (string, optional) The icon associated to your development environment in the Okteto UI (optional). ### name (string, optional) The name of your development environment. It defaults to the name of your git repository. ### test (object, optional) A dictionary of Test Containers to run tests using [Remote Execution](/docs/core/remote-execution.md#how-remote-execution-works). ``` test: unit: image: ghcr.io/okteto/golang:1 artifacts: - coverage.out caches: - /go - /root/.cache commands: - "go test . -v" integration: depends_on: - unit image: ghcr.io/okteto/golang:1 context: integration commands: - make tests hosts: - "localhost:127.0.0.1" ``` Each key is the name of your Test Container, and it has the following fields: #### artifacts (\[string], optional) A list of files and/or folder to be exported after the execution of the tests. They will be added relative to root context of the tests. If you want to export coverage reports and test results this is where they should go. #### caches (\[string], optional) A list of cache mounts to be used as part of running the tests. This is used to speed up recurrent test executions where, for example, dependencies will not be reinstalled and will instead be mounted from the cache. #### commands (\[string], required) Provide a list of commands to run the tests. For the tests to be considered successful, each command must exit with a zero exit code. If any command returns a non-zero exit code, the Test Container will be marked as failed. #### context (string, optional) The folder to use as the root for running the tests. If this is empty, the location of the Okteto Manifest will be used (usually the root of the project). info If `context` is used, the `.oktetoignore` file must be place in the `context` folder #### depends\_on (\[string], optional) A list of Test Containers this test depends on. When a Test Container is executed, all its dependencies are executed first. The Test Containers defined in `depends_on` must exist in the current Okteto Manifest. #### hosts (\[string], optional) A list of hostnames and ips. For each pair, an entry is created in `/etc/hosts` during the test execution. The following extended notation is also supported: ``` hosts: - hostname: localhost ip: 127.0.0.1 ``` #### image (string, optional) The base image used to run your test. If it is not defined, Okteto uses the [pipeline-runner](https://github.com/okteto/pipeline-runner) image unless an Okteto Cluster admin has specifically changed it [here](/docs/self-hosted/helm-configuration.md#installer) with a [custom installer image](/docs/admin/custom-installer-image.md) ## Environment variables There are multiple parts of the Okteto Manifest that deal with environment variables in one sense or another. This section should help you find the information you need. ### Substitute environment variables It’s possible to use environment variables in your shell to populate values inside an Okteto Manifest: ``` image: "node:${TAG}" ``` If you have multiple environment variables, you can substitute them by adding them to a file named `.env`. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # SSH Server As part of enabling your development container, `okteto up` performs the following steps: * A [minimalist SSH server](https://github.com/okteto/remote) is injected into your development container * A port forward is created from a local port to port 22 of the development container * A host entry is added to your local `.ssh/config` file with the following values: ``` Host MANIFEST_NAME.okteto HostName localhost Port PORT StrictHostKeyChecking no UserKnownHostsFile /dev/null ``` > Use the [remote](/docs/reference/okteto-manifest.md#remote-integer-optional) field to configure the local port where the SSH server is exposed. The SSH server is used by `okteto up` to run remote commands and forward ports from/to your development containers. The SSH server makes it possible to integrate your development container with IDEs that support remote development, such as [VS Code](https://marketplace.visualstudio.com/items?itemName=okteto.remote-kubernetes), [PHPStorm](https://confluence.jetbrains.com/pages/viewpage.action?pageId=57294700) or [PyCharm](https://www.jetbrains.com/help/pycharm/remote-debugging-with-product.html). ### Connect using SSH Once the development container is up and running, you can SSH into it with the following command: ``` $ ssh -p PORT localhost ``` You can also SSH using the host entry added to your local SSH config: ``` $ ssh MANIFEST_NAME.okteto ``` ### Secure by default When you run `okteto up` the first time, Okteto will create a SSH key pair for you and save it at `$HOME/.okteto/id_rsa_okteto` and `$HOME/.okteto/id_rsa_okteto.pub`. The SSH server launched in your development container will be automatically configured to use these keys for authentication. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Supported GitHub Actions Automate your development workflows using GitHub Actions and Okteto. GitHub Actions gives you the flexibility to build automated software development workflows. With GitHub Actions for Okteto, you can create workflows to build, deploy, and update your applications in Okteto. ## Available Actions The GitHub Actions for Okteto are available directly from [the GitHub Marketplace](https://github.com/marketplace?type=actions\&query=okteto). * [Activate Namespace](https://github.com/marketplace/actions/activate-namespace) * [Build](https://github.com/marketplace/actions/okteto-build) * [Context](https://github.com/marketplace/actions/okteto-context) * [Create Namespace](https://github.com/marketplace/actions/create-namespace) * [Delete Namespace](https://github.com/marketplace/actions/delete-namespace) * [Deploy Pipeline](https://github.com/marketplace/actions/okteto-pipeline) * [Deploy Preview](https://github.com/marketplace/actions/deploy-preview-environment) * [Destroy Pipeline](https://github.com/marketplace/actions/destroy-okteto-pipeline) * [Destroy Preview](https://github.com/marketplace/actions/destroy-preview-environment) * [Test](https://github.com/marketplace/actions/okteto-test) Each GitHub Action supports the following tags: * `latest`: this is the version running the last stable Okteto CLI release * `v3`: this is the version running the last stable Okteto CLI 3.x release * `v2`: this is the version running the last stable Okteto CLI 2.x release * `main`: this is our development version. **Don't use this tag for production usage!** Finally, you can ping a specific Okteto CLI version in your GitHub Actions, for example, `okteto/context@2.31.0`. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Release notes ## 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 * **Workload identity for Docker Compose services**: Docker Compose services now support a per-service [`x-okteto-identity-token`](/docs/reference/docker-compose.md#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 * **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`](/docs/reference/feature-flags.md) 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 * [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 * **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 * 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 * **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 * **Environment Variables in `build.secrets`**: The Okteto Manifest and Docker Compose stacks now support environment variables in the [`build.secrets`](/docs/reference/okteto-manifest.md#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 * 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 * 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 * **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](/docs/self-hosted/manage/argocd.md) for the corrected configuration ### New Features * **Kubernetes 1.35 Support**: Added support for Kubernetes [1.35](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.35.md) - **[Agentic Workflows](/docs/agentic.md)**: 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 * 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 * 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 * ⚠️ 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 * **Build Queue Enabled by Default**: The [build queue system](/docs/core/build-service.md#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](/docs/admin/dashboard.md#admin-variables) ### Improvements * **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](/docs/core/namespaces.md#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 [](/docs/assets/medias/deploy-dialog-e6d014354ed6dd5c8a82aa52d75729f0.webm) ### Bug Fixes * 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 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 * **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 * **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](/docs/admin/dashboard.md#admin-variables). Learn more about the [Build Queue System](/docs/core/build-service.md#build-queue-system) ### Improvements * **Configurable Build Service Thresholds**: Administrators can now configure resource thresholds (CPU pressure, memory usage, and IOPS) directly from the [Build Service admin dashboard](/docs/admin/build-service.md) 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](/docs/admin/build-service.md#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 * **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 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 * **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](/docs/self-hosted/manage/upgrade.md#upgrading-to-okteto-140x--default-registry-change-to-github-container-registry) ### New Features * **Builds Dashboard**: Track and analyze your build performance with the new [Builds dashboard in Okteto Insights](/docs/core/okteto-insights-dashboards.md#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 * 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](/docs/admin/catalog.md) 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 * [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 * 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 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 * **Build Service Admin Dashboard**: Administrators can now monitor BuildKit performance and resource utilization through a new [Build Service dashboard](/docs/admin/build-service.md). 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 * 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 * 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 * **Upgrade Considerations for Self-Hosted Customers**: Internal certificates have been unified into a [single configuration](/docs/self-hosted/helm-configuration.md#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](/docs/self-hosted/manage/argocd.md). The certificate unification may require special attention during the ArgoCD sync process to avoid deployment interruptions. ### New Features * **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](/docs/self-hosted/manage/custom-resource-definitions.md#known-hosts), allowing admins to lock down SSH host key management and prevent accidental modifications ### Improvements * 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](/docs/core/build-service.md#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 * 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 * 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 * 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 * 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](/docs/self-hosted/helm-configuration.md#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**](/docs/self-hosted/helm-configuration.md#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 * Added a centralized [Known Hosts feature to the Admin UI](/docs/admin/ssh-known-hosts.md) (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 * 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](/docs/reference/docker-compose.md#endpoint_mode-string-optional)). ### Bug Fixes * 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)](/docs/okteto-ai.md) 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](/docs/okteto-ai/okteto-ai-admin-config.md): * 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 * Added a [new Public API endpoint to delete users](/docs/admin/okteto-api.md) * Added support for [configuring custom init containers](/docs/self-hosted/helm-configuration.md#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](/docs/self-hosted/helm-configuration.md#prepullimages) onto nodes. ### Improvements * 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`](/docs/reference/okteto-manifest.md#securitycontext-object-optional) property in the `securityContext` of dev containers defined in the Okteto Manifest ### Bug Fixes * 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 * 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](/docs/self-hosted/manage/upgrade.md#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 * [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 * 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 * 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 * [Okteto CLI 3.9.0](https://github.com/okteto/okteto/releases/tag/3.9.0): Added a [feature flag](/docs/reference/feature-flags.md) 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](/docs/reference/feature-flags.md) to make `dev..services` wait for file synchronization to finish before running their commands during `okteto up` execution ### Bug Fixes * 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 --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto Self-Hosted ## Introduction Okteto Self-Hosted allows you to run Okteto on your own infrastructure. Tailored for organizations that prioritize control, security, and customization, this version allows you to bring Okteto's platform into your private or on-premises infrastructure. You maintain complete oversight while empowering your developers with the tools they need to build faster and more effectively. Okteto Self-Hosted is distributed as a [Helm chart](https://artifacthub.io/packages/helm/okteto/okteto). This contains all the required components for the complete Okteto experience. Okteto components: * NGINX Ingress * Okteto/API * Okteto/Buildkit * Okteto/Frontend * Okteto/Migration * Okteto/Registry * Okteto/Validation Webhook ## Installation Guides If you haven't installed Okteto yet, these cloud-specific guides will walk you through deploying the Okteto Helm chart with default values and basic configuration: * [Install Okteto in Amazon Elastic Kubernetes Service](/docs/get-started/install/amazon-eks.md) * [Install Okteto in Civo](/docs/get-started/install/civo.md) * [Install Okteto in DigitalOcean Kubernetes](/docs/get-started/install/digitalocean-doks.md) * [Install Okteto in Google Kubernetes Engine](/docs/get-started/install/google-gke.md) * [Install Okteto in Microsoft Azure Kubernetes Service](/docs/get-started/install/microsoft-aks.md) ### The sub-pages in this section will help you to configure and manage your Okteto installation * [**Complete the installation**](/docs/self-hosted/install/certificates.md) - Includes guides for deploying Okteto through ArgoCD, setting up your own certificates, GitHub integration, Divert configuration, and more * [**Helm Configuration**](/docs/self-hosted/helm-configuration.md) - Configuration of your Okteto Helm chart including authentication, garbage collection, and much more * [**Manage Okteto**](/docs/self-hosted/manage/upgrade.md) - Details on how to maintain your Okteto installation long term * [**ARM Support**](/docs/self-hosted/manage/arm-support.md) - Install Okteto on ARM-based clusters (GCP Tau T2A GA, AWS Graviton Beta) ### Feature Configuration * [**Configure Divert**](/docs/self-hosted/install/divert.md) - Set up traffic routing for lightweight development environments with nginx or istio drivers ## Troubleshooting We've done our best to make Okteto easy to install and operate. [The troubleshooting page](/docs/self-hosted/manage/troubleshooting.md) has tips and tricks to help troubleshoot common issues. You can also [reach out to support](https://okteto.com/support) if you need assistance. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Getting started after deploying Okteto on DigitalOcean After you have downloaded your `kubeconfig` file and can successfully connect to your DigitalOcean Kubernetes cluster (see if you haven't connected to your cluster), follow the instructions below to start using Okteto. ## Initial Configuration The first step is to get your admin token. Run the following command in a terminal shell to retrieve it: ``` 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: ``` kubectl port-forward service/do-ingress-nginx-controller 8443:443 --namespace okteto ``` Third, open your browser and go to to load the admin screen. Use the admin token you retrieved on the first step to log in to the admin screen. Once you log in to the admin page, you'll need to provide the following values to complete Okteto's initial configuration. 1. A [dedicated subdomain](#subdomain) for your Okteto instance 2. Your Kubernetes cluster's [public endpoint](#cluster-public-endpoint) 3. Your [Okteto license](#license) (optional) 4. The Client ID and Client Secret of a [GitHub OAuth app](#authentication) 5. A list of the GitHub Usernames allowed to log into your Okteto instance (optional, leave it empty to allow everyone) 6. A DigitalOcean [personal access token](#digitalocean-personal-access-token) Press `Save` once you're ready to apply the new configuration. It'll take about 30 seconds for the configuration to be applied. Your Okteto instance is now fully configured. It will be available via (e.g. ). The [next section ](#dns-configuration)explains how to configure the DNS for this. ## DNS configuration Run the following command in a terminal shell to get the External IP address of the Load Balancer. ``` kubectl get svc -n=okteto -l="app=nginx-ingress,component=controller" ``` Create a [wildcard A record](https://cloud.digitalocean.com/networking/domains) for the entire subdomain and point it to the load balancer's external IP. ![Digital Ocean DNS](/docs/assets/images/dns-ddd49ac22ee71520df8ff8b1f79e3b7a.png) ## More information ### Subdomain Okteto can automatically create HTTPS endpoints for the applications you deploy in your cluster. We recommend that you give Okteto a dedicated subdomain to prevent endpoint clashes with other applications. The Okteto web UI will always be available at . The subdomain must be [registered with Digital Ocean](https://www.digitalocean.com/docs/networking/dns/how-to/add-domains/). ### Cluster Public Endpoint This is the fully qualified URL of your Kubernetes cluster's apiserver. You can get it from the `kubeconfig` file you downloaded from DigitalOcean: ``` apiVersion: v1 clusters: - cluster: certificate-authority-data: DATA+OMITTED server: https://0b84ec60-fe41-4994-8e76-b53e00859ef9.k8s.ondigitalocean.com name: do-sfo2-ramiro ... ``` ### License 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). No credit card required](https://www.okteto.com/free-trial/). ### Authentication Okteto uses GitHub OAuth as the authentication provider. You'll need to create a [GitHub OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/) with the following values: *Homepage URL:* *Authorization callback URL:* ### DigitalOcean Personal Access Token Okteto requires a DigitalOcean personal access token with read/write permissions to create DNS entries when responding to [ACME DNS-01 challenges](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge). The entries will be created in the subdomain you provided in the configuration. Create your [DigitalOcean personal access token here](https://cloud.digitalocean.com/account/api/tokens). ## Support If you get stuck or have any questions, feel free to reach out to us at , [Twitter](https://twitter.com/oktetohq), or [our community](https://community.okteto.com/). --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Helm Configuration ## General Settings ### license 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), no credit card required](https://www.okteto.com/free-trial/). ``` license: XXXXX ``` > You can also use a [secret](/docs/self-hosted/helm-configuration.md#store-sensitive-configuration-values-using-a-secret) to store the license. ### subdomain Okteto's [automatic SSL endpoints](/docs/core/endpoints/automatic-ssl.md) allows you to expose secure and unique public endpoints for your development environments. By default, all endpoints created by Okteto will use a combination of the name of the app, the namespace, and the `subdomain`. For example, if you have a development environment named `app` in the `cindy` namespace, it will be accessible at if `subdomain` is example.com. ``` subdomain: "example.com" ``` Okteto's frontend and API services will be also accessible via . Once Okteto is installed, you can use `kubectl` to retrieve the public address of the Okteto NGINX Ingress Controller: ``` 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 34.68.230.234 80:30795/TCP,443:32481/TCP,1234:30885/TCP 5m ``` You'll need to take the `EXTERNAL-IP` address to create a DNS entry for `*.$SUBDOMAIN`. You can overwrite Okteto's public URL using the [publicOverride](/docs/self-hosted/helm-configuration.md#publicoverride) field. ### publicOverride Use this property to override the Public URL where Okteto is available. This option replaces `okteto.$SUBDOMAIN` with your [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) of choice. ``` 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)): ``` kubectl get service -l=app.kubernetes.io/name=ingress-nginx,app.kubernetes.io/component=controller --namespace=okteto ``` **Important**: When using `publicOverride`, the certificate referred by [wildcardCertificate.name](/docs/self-hosted/helm-configuration.md#wildcardcertificate) must be valid for `publicOverride`, `registry.$SUBDOMAIN` and `buildkit.$SUBDOMAIN`. When `publicOverride` is set, an additional component is deployed for [Okteto Private Endpoints](/docs/core/endpoints/private-endpoints.md) feature. You can configure its settings using the [privateEndpoints](/docs/self-hosted/helm-configuration.md#privateendpoints) section. When setting your [auth provider](/docs/self-hosted/helm-configuration.md#auth), the authentication callback URL and origin URL will change to the following: **Callback URL**: ``` https://${publicOverride}/auth/callback https://private-endpoints.${subdomain}/auth/callback ``` **Origin URL**: ``` https://${publicOverride} https://private-endpoints.${subdomain} ``` ### auth Use the `auth` property to specify which users can access Okteto and the method they can use for logging in. Okteto provides OAuth2 integrations for the following auth providers: * [Azure Active Directory](/docs/self-hosted/install/auth/azure-ad.md) * [Bitbucket](/docs/self-hosted/install/auth/bitbucket.md) * [GitHub](/docs/self-hosted/install/auth/github.md) * [GitLab](/docs/self-hosted/install/auth/gitlab.md) * [Google](/docs/self-hosted/install/auth/google.md) * [Okta](/docs/self-hosted/install/auth/okta.md) * [OpenID Connect](/docs/self-hosted/install/auth/openid-connect.md) Additionally, Okteto provides a single user authentication method based on a [Token](/docs/self-hosted/install/auth/token.md) for initial evaluations. ### Theme Use this property to customize the logo and the colors of the sidebar to match your team's identity or your favorite colors. * `logo`: The logo displayed at the far top left of the Okteto UI. The value can be a url or a Base64 encoded image. * `primary`: The primary color of the sidebar. This is used for the color of the sidebar. The value can be a [HTML color name](https://en.wikipedia.org/wiki/Web_colors#HTML_color_names) (e.g. blue, red) or a hexadecimal code. * `secondary`: The secondary color of the sidebar. This is used for the icons and the text displayed in the sidebar. The value can be a [HTML color name](https://en.wikipedia.org/wiki/Web_colors#HTML_color_names) (e.g. blue, red) or a hexadecimal code. ``` theme: logo: http://example.com/icon.png primary: \#EFF3F2 secondary: black ``` ## Okteto Components ### api The API service. Account and Kubernetes credentials management, namespace creation, and sharing, deployment via the catalog, etc... * `annotations`: Annotations to add to the API pods. * `extraEnv`: Environment variables to be set on the API containers. * `labels`: Labels to add to the API pods. * `priorityClassName`: The priority class to be used by the API 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 API pods. It defaults to 2. * `resources`: The resources for the API pods. ``` api: extraEnv: - name: NO_PROXY value: ".example.com" replicaCount: 2 resources: requests: cpu: 100m memory: 128Mi ``` ### autoscaler (deprecated) 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. > **Requirements**: cluster autoscaler and metrics server must be installed in your cluster. * `annotations`: Annotations to add to the autoscaler pods. * `cpu.up`: Increase the cluster size when the CPU consumption is greater than or equal to this value. It defaults to 60 percent. * `cpu.down`: Decrease the cluster size when the CPU consumption is lesser than this value. It defaults to 40 percent. * `image`: image used by the autoscaler to deploy the autoscaler agent. It defaults to `busybox`. * `labels`: Labels to add to the autoscaler pods. * `memory.up`: Increase the cluster size when the Memory consumption is greater than or equal to this value. It defaults to 70 percent. * `memory.down`: Decrease the cluster size when the Memory consumption is lesser than this value. It defaults to 50 percent. * `nodes.increment`: The number of new nodes to request when all the current nodes are overloaded. e.g. if this value is 3, the autoscaler will request 3 new nodes when all the cluster nodes are overloaded. It defaults to 1. * `nodes.min`: Minimum number of nodes in the cluster. It defaults to 1. * `nodes.max`: Maximum number of nodes in the cluster. It defaults to 10. Zero means unlimited. * `nodes.poolLabel`: The node label that identifies the node pool of the node. For example, the value in GKE is `cloud.google.com/gke-nodepool`. In EKS the value is `eks.amazonaws.com/nodegroup`. If set, the autoscaler scales each node pool independently. * `pods.up`: Increase the cluster size when the Pods in a node vs the max pods per node is greater than or equal to this value. It defaults to 90 percent. * `pods.down`: Decrease the cluster size when the Pods in a node vs the max pods per node is lesser than this value. It defaults to 80 percent. * `priorityClassName`: The priority class to be used by the autoscaler pods. * `schedule`: How often, in seconds, the autoscaler analyzes if the cluster needs to be scaled. It defaults to 300. * `slackWebhook`: A slack webhook url to notify autoscaler events. * `volumes.up`: Increase the cluster size when the Volumes in a node vs the max volumes per node is greater than or equal to this value. It defaults to 90 percent. * `volumes.down`: Decrease the cluster size when the Volumes in a node vs the max volumes per node is lesser than this value. It defaults to 80 percent. ``` autoscaler: enabled: false image: busybox schedule: 300 cpu: up: 60 down: 40 memory: up: 70 down: 50 pods: up: 90 down: 80 volumes: up: 90 down: 80 nodes: increment: 1 min: 1 max: 10 podLabel: cloud.google.com/gke-nodepool slackWebhook: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX ``` ### buildkit The build service. It's used in combination with `okteto build` to build containers directly in the cluster. * `port`: Port used for the buildkit statefulset. Defaults to `443`. * `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. 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`. * `replicaCount`: The number of buildkit pods. It defaults to 1. * `resources`: The resources for the buildkit pods. * `serviceAccount.create`: create a service account for buildkit. True by default. * `serviceAccount.name`: Buildkit service account name. Defaults to `okteto-buildkit`. * `serviceAccount.annotations`: Annotations for the buildkit service account. * `serviceAccount.labels`: Labels for the buildkit service account. * `service.loadBalancerSourceRanges`: List of CIDR blocks allowed to access the BuildKit service when using a LoadBalancer. Defaults to `[]`. Ignored for other service types. * `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 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. * `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`](/docs/self-hosted/helm-configuration.md#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`](/docs/self-hosted/helm-configuration.md#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. ``` buildkit: port: 443 extraEnv: - name: NO_PROXY value: ".example.com" replicaCount: 1 persistence: enabled: true class: ssd size: 180Gi cacheRatio: 0.8 tolerations: - key: "okteto-buildkit" operator: "Equal" value: "buildkit" effect: "NoExecute" 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: * `OKTETO_KEEPALIVE_SERVER_TIME_MS`: After this duration of time, if the server doesn't see any activity it pings the client to see if the transport is still alive. If set below 1s, a minimum value of 1s will be used. The current default value is 2 hours. * `OKTETO_KEEPALIVE_SERVER_TIMEOUT_MS`: After having pinged for keepalive check, the server waits for a duration of Timeout and if no activity is seen, the connection is closed. The current default value is 20 seconds. * `OKTETO_KEEPALIVE_SERVER_MAX_CONN_IDLE_MS`: Duration for the amount of time after which an idle connection would be closed by sending a GOAWAY. Idleness duration is defined since the most recent time the number of outstanding RPCs became zero or the connection establishment. The current default value is infinity. * `OKTETO_KEEPALIVE_SERVER_MAX_CONN_AGE_MS`: Duration for the maximum amount of time a connection may exist before it will be closed by sending a GOAWAY. A random jitter of +/-10% will be added to the value to spread out connection storms. The current default value is infinity. * `OKTETO_KEEPALIVE_SERVER_MAX_CONN_AGE_GRACE_MS`: An additive period after `OKTETO_KEEPALIVE_SERVER_MAX_CONN_AGE_MS` after which the connection will be forcibly closed. The current default value is infinity. * `OKTETO_KEEPALIVE_SERVER_POLICY_MINTIME_MS`: Minimum amount of time a client should wait before sending a keepalive ping. The current default value is 5 minutes. * `OKTETO_KEEPALIVE_SERVER_POLICY_PERMIT_WITHOUT_STREAM`: If true, server allows keepalive pings even when there are no active streams(RPCs). If false, and client sends pings when there are no active streams, server will send GOAWAY and close the connection. False by default. If you're trying to configure Buildkit persistency for your Okteto installation, check out our video tutorial: [YouTube video player](https://www.youtube.com/embed/R0V_-lRVico) ### cli Settings for the Okteto CLI. The `cli` section allows you to configure the Docker image used by the Okteto CLI for cluster-wide operations. These settings can be customized to use your own Docker images if required. * `image`: Specifies the image settings for the Okteto CLI. * `registry`: The registry where the Okteto CLI image is hosted. Defaults to `docker.io`. * `repository`: The repository path for the Okteto CLI image. Defaults to `okteto/okteto`. ``` cli: image: registry: "my-custom-registry:5000" repository: "okteto/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 `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 ### daemonset The daemonset automatically configures every node of your cluster to work better with Okteto. * `enabled`: Control if the daemonset is installed. Defaults to `true`. * `annotations`: Annotations to add to the daemonset pods. * `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`. * `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: * [Overrides](/docs/self-hosted/helm-configuration.md#overrideregistryresolution) the Okteto Registry hostname resolution to use internal IPs. * [Overrides](/docs/self-hosted/helm-configuration.md#overridefilewatchers) the default kernel values for file watchers on every node. * Configures the kubelet with registry credentials for [private registries](/docs/self-hosted/helm-configuration.md#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`). You can restrict the nodes where the daemonset is deployed using `dev` [tolerations](/docs/self-hosted/helm-configuration.md#tolerations) and [nodeSelectors](/docs/self-hosted/helm-configuration.md#nodeselectors): ``` tolerations: devPool: dev ``` ### defaultBackend The defaultBackend receives errored requests from the ingress-controller and transform them returning them to the client. * `affinity`: Affinities to add to the defaultBackend pods. * `annotations`: Annotations to add to the defaultBackend pods. * `enabled`: Control if defaultBackend is deployed. Defaults to `true`. * `extraEnvs`: Environment variables to be set on the defaultBackend containers. * `labels`: Labels to add to the defaultBackend pods. * `nameOverride`: String to override the full name of the defaultBackend service. * `port`: Internal port used for the defaultBackend. Defaults to `8080`. * `priorityClassName`: The priority class to be used by the defaultBackend 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 defaultBackend pods. It defaults to 2. * `resources`: The resources for the defaultBackend pods. ``` defaultBackend: replicaCount: 3 resources: requests: cpu: 100m memory: 128Mi ``` The defaultBackend provides the following features: * **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. ``` tolerations: devPool: dev ``` ### frontend The frontend service serves the web application. * `annotations`: Annotations to add to the frontend pods. * `extraEnv`: Environment variables to be set on the frontend containers. * `labels`: Labels to add to the frontend pods. * `priorityClassName`: The priority class to be used by the frontend 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 frontend pods. It defaults to 2. * `resources`: The resources for the frontend pods. ``` frontend: extraEnv: - name: NO_PROXY value: ".example.com" replicaCount: 2 resources: requests: cpu: 100m memory: 128Mi ``` ### gc The Okteto Garbage Collector service automatically scales idle applications to zero and deletes unused namespaces for optimal cost savings and resource management. It is enabled by default. The Garbage Collector service can also be [configured in the Admin Dashboard](/docs/admin/cleanup.md) by navigating to **Admin -> Garbage Collector** underneath the Settings section. * `annotations`: Annotations to add to the gc pods. * `labels`: Labels to add to the gc pods. * `slackWebhook`: If set, the garbage collector will send a notification when it scales a resource to zero or when it deletes a namespace. * `upSessionByLastSyncedFile`: If true, `okteto up` sessions will be scaled to zero if no files have been synchronized in the scale to zero period. Default behavior is to check for an active connection (regardless of inactivity) * `priorityClassName`: The priority class to be used by the gc 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`. ``` gc: enabled: true upSessionByLastSyncedFile: false slackWebhook: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX ``` ### insights Configures the [Okteto Insights](/docs/admin/okteto-insights.md) component in your Okteto instance. * `enabled`: Whether to enable Okteto Insights. Defaults to `false`. * `bearerSecret.name`: Name of the secret where the token to access Okteto Insights metrics is stored. Defaults to `okteto-insights`. * `bearerSecret.key`: Name of the key within the secret where the token to access Okteto Insights metrics is stored. Defaults to `bearer`. ``` insights: enabled: false bearerSecret: name: okteto-insights key: bearer ``` If Okteto Insights is enabled, the Event Exporter component and the Insights Metrics cronjob are also installed. The Event Exporter receives Okteto CLI events via Kubernetes Events and injects them as Okteto Insights metrics. * `priorityClassName`: The priority class for pods created by the Event Exporter. 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`. * `podAnnotations`: Annotations to add to Event Exporter pods. * `podLabels`: Labels to add to the Event Exporter pods. * `resources`: The resources for the Event Exporter pods. ``` insights: eventsExporter: priorityClassName: podLabels: {} podAnnotations: {} resources: requests: cpu: 50m memory: 20Mi limits: memory: 100Mi ``` The Insight Metrics is a cronjob that pre-computes several metrics for the Okteto Insights `/metrics` endpoint. * `annotations`: Annotations to add to Insight Metrics pods. * `labels`: Labels to add to the Insight Metrics pods. * `priorityClassName`: The priority class for pods created by the Insight Metrics. 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`. * `resources`: The resources for the Insight Metrics pods. * `schedule`: Defines the frequency at which cronjob is executed, using the cron syntax. It defaults to run every 5 minutes (`*/5 * * * *`). ``` insights: metrics: annotations: {} labels: {} priorityClassName: resources: requests: cpu: 50m memory: 20Mi limits: memory: 100Mi schedule: "*/5 * * * *" ``` ### installer The jobs that deploy your [development environments from Git](/docs/development/deploy/deploy-from-git.md). * `annotations`: Annotations to add to the installer job pods. * `extraEnv`: Environment variables to be set on the installer job containers. * `labels`: Labels to add to the installer job pods. * `runner`: to configure your [custom installer image](/docs/admin/custom-installer-image.md). * `registry`: The registry where the installer image is hosted. Defaults to the helm configuration setting `globals.registry`. * `repository`: The repository path for the installer image. Defaults to `okteto/pipeline-runner` if not specified. * `tag`: The image tag to deploy. Defaults to `1.46.0` if not specified. * `activeDeadlineSeconds`: Maximum duration of the pipeline in seconds. * `gitSSHUser`: User to be used when cloning git repos using ssh. * `sshSecretName`: The name of the secret that contains the private key used when cloning git repos using ssh. If it doesn't exist, the key and the secret will be automatically generated by Okteto. * `resources`: The resources for pods created by the installer jobs. * `priorityClassName`: The priority class for pods created by the installer 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`. * `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: 1.46.0 extraEnv: - name: NO_PROXY value: ".example.com" activeDeadlineSeconds: 1800 gitSSHUser: git sshSecretName: "okteto-ssh" securityContext: allowPrivilegeEscalation: false resources: requests: cpu: 10m memory: 50Mi ``` ### oktetoAI The Okteto AI section configures the [Okteto AI](/docs/okteto-ai.md) feature in your cluster: * `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 1.46.0 . * `resources`: The resources for the Okteto AI Agent pods. ``` oktetoAI: enabled: true resources: requests: cpu: 50m memory: 400Mi ``` ### privateEndpoints When [publicOverride](/docs/self-hosted/helm-configuration.md#publicoverride) is set, Okteto Self Hosted deploys an additional component for [Okteto Private Endpoints](/docs/core/endpoints/private-endpoints.md) feature, which is responsible for authenticating and authorizing requests sent to Okteto Endpoints set to private mode. * `port`: Internal port used for the Private Endpoint component. Defaults to `8080`. * `resources`: The resources for the Private Endpoint component pods. * `replicaCount`: The number of Private Endpoint component pods. It defaults to 1. * `annotations`: Annotations to add to the Private Endpoint component pods. * `priorityClassName`: The priority class to be used by the Private Endpoints 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`. By default, the Private Endpoint component will inherit the configuration set at the \[`auth`] section, but you can override some values with the following properties: * `clientID`: Overrides `auth.*.clientID`. * `clientSecret`: Overrides `auth.*.clientSecret`. ### prepullImages The prepull images daemonset ensures that essential Okteto images are available on every node in your cluster. This improves startup times for jobs and operations by avoiding image pulls when containers are created. note The prepullImages feature assumes that cluster nodes have access to pull all Okteto images, either because the images are public or through appropriate IAM roles/permissions configured at the node level. This is the same assumption made for all images in the Okteto Control Plane. No additional image pull secrets or authentication configuration is provided by this feature. * `enabled`: When set to `true`, the prepull images daemonset is installed. It defaults to `true`. * `priorityClassName`: The priority class to be used by the prepull images 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`. ``` prepullImages: enabled: true priorityClassName: "high-priority" ``` The following images are prepulled on every node: * **ghcr.io/okteto/backend:1.46.0** * **ghcr.io/okteto/pipeline-runner:1.46.0** * **ghcr.io/okteto/okteto:3.21.0** ### regcredsManager The configuration for the controller manager of the Registry Credentials Operator. This controller manager is deployed as a deployment and is responsible for managing private registry credentials in the cluster. If `pullSecrets.enabled=true` all private registry credentials are copied to the `okteto-regcred` secret in user dev namespaces and previews. If `pullSecrets.enabled=false` these credentials are copied to all nodes through the Okteto Daemon if `daemonset.configurePrivateRegistriesInNodes.enabled=true`. * `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. * `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 * `replicas`: The number of controller manager pods. The controller is deployed as a deployment with leader election. It is recommended to have at least 2 replicas here. * `resources`: The resources for the controller manager pods. ``` regcredsManager: priorityClassName: pullSecrets: enabled: false podLabels: {} podAnnotations: {} webhookTimeout: 30 replicas: 2 resources: requests: cpu: 50m memory: 100Mi limits: memory: 800Mi ``` ### redis Use this section to configure Redis for the [Resource Manager](/docs/admin/resource-manager.md). Redis is only installed if the Resource Manager is enabled. * `annotations`: Annotations to add to the Redis pods. * `args`: Additional arguments for the Redis container command. * `extraEnv`: Environment variables to be set on the Redis containers. * `image.repository`: The repository path for the Redis image. Defaults to `okteto/redis`. * `image.tag`: The image tag for the Redis image. Defaults to 1.46.0 . * `labels`: Labels to add to the Redis pods. * `port`: Specifies the port on which Redis listens. The default value is `6379`. * `resources`: The resources for the Redis pods. ### resourceManager Use this section to configure the [Resource Manager](/docs/admin/resource-manager.md). * `annotations`: Annotations to add to the Resource Manager pods. * `deletePeriodDays`: Specifies the retention period for the recommendations. If a service is no longer deployed in your cluster, its recommendation will be deleted after the specified deletePeriod. It defaults to 15 days. * `enabled`: When set to `true`, the Resource Manager is installed. When Resource Manager is installed, Okteto creates a CronJob responsible for computing the cpu and memory recommendations for your pods. It defaults to `true`. * `labels`: Labels to add to the Resource Manager pods. * `priorityClassName`: The priority class to be used by the Resource 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`. * `recommendations.correction`: A floating-point multiplier used to adjust for over or under-provisioning of resources. The default is `1.1`, indicating a 10% over-provisioning. This value must be greater than 0. For example, setting it to 0.9 will result in a 10% under-provisioning compared to the average utilization. * `recommendations.min.cpu`: Specifies the minimum CPU requests configured when the Resource Manager applies recommendations. The minimum value will be used if a recommendation hasn't been calculated yet or is below this value. It defaults to `5m`. * `recommendations.min.memory`: Specifies the minimum memory requests configured when the Resource Manager applies recommendations. The minimum value will be used if a recommendation hasn't been calculated yet or is below this value. It defaults to `10Mi`. * `recommendations.weight`: A floating-point number between 0 and 1 used to stabilize CPU and memory recommendation calculations. A higher value (closer to 1) gives more weight to historical resource usage trends, making the Resource Manager less responsive to recent changes or spikes. A lower value (closer to 0) makes it more reactive to recent usage patterns, including spikes. The default value is `0.9`, which makes the Resource Manager conservative, favoring existing trends and attempting to ignore minor fluctuations. * `resources`: The resources for the Resource Manager pods. * `schedule`: Defines the frequency at which resource recommendations are calculated, using the cron syntax. It defaults to run every 5 minutes (`*/5 * * * *`). ``` resourceManager: enabled: true schedule: "*/5 * * * *" deletePeriodDays: 15 recommendations: weight: 0.9 correction: 1.1 min: cpu: 5m memory: 10Mi priorityClassName: labels: {} annotations: {} resources: {} ``` ### registry Use this section to configure the [Okteto Registry](/docs/core/container-registry.md). We have dedicated guides to [configure the Okteto Registry](/docs/self-hosted/install/okteto-registry-storage.md) to store your images in the storage driver of your choice. These are all the settings available to configure your Okteto Registry: * `annotations`: Annotations to add to the registry pods. * `extraEnv`: Environment variables to be set on the registry containers. * `ingress.annotations`: Annotations to add to the registry ingress. These annotations take precedence over the ones defined in the [ingress](/docs/self-hosted/helm-configuration.md#ingress) section. * `labels`: Labels to add to the registry pods. * `pullPolicy`: The security policy for image pulls. If set to `cluster`, any Okteto user can pull any image from the registry. When set to `namespace`, only users with access to the namespace can pull images from the namespace. It defaults to `namespace`. * `priorityClassName`: The priority class to be used by the registry 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 registry pods. It defaults to 1. * `resources`: The resources for the registry pods. * `serviceAccountName`: Alternative service account to be used by the registry. The service account must exist in the same namespace for the Okteto Helm release. Defaults to none. * `serviceAccount.annotations`: Annotations to add to the registry service account. * `secret.name`: when using external storage, the name of the secret with the values of your cloud provider credentials. * `secret.accessKey`: the key of the access key in the secret referenced by `secret.name` (defaults to `accessKey`). * `secret.secretKey`: the key of the secret key in the secret referenced by `secret.name` (defaults to `secretKey`). * `storage`: [the full configuration guide is available here](/docs/self-hosted/install/okteto-registry-storage.md) ### sshAgent The SSH Agent service. This service runs an SSH Agent with [Okteto's SSH Key](/docs/admin/private-repositories/ssh-key.md) to be used when cloning private repositories as part of the commands defined in your Okteto Manifest during [remote execution](/docs/core/remote-execution.md). * `annotations`: Adds custom annotations to the ssh-agent pods. * `extraEnv`: Environment variables to be set on the ssh-agent containers. * `labels`: Adds custom labels to the ssh-agent pods. * `port`: Specifies the internal port on which the ssh-agent listens. The default value is `3000`. * `priorityClassName`: The priority class to be used by the ssh-agent 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`: Specifies the number of ssh-agent pods to run. The default is `2`. * `resources`: Configures resource limits and requests for the ssh-agent pods. ``` sshAgent: annotations: {} extraEnv: [] labels: {} port: 3000 priorityClassName: replicaCount: 2 resources: requests: cpu: 10m memory: 10Mi ``` ### telemetry The telemetry job "phones home" once a day with the following information: * Number of managed users * Number of managed namespaces * Kubernetes Version and Platform * A unique install ID * Your license ID. * The name of the authentication provider * The name of the cloud provider Okteto uses the information to help us better understand how our customers use Okteto, as well as to help us prioritize fixes and features. We don't share your information with anyone else. * `enabled`: Enables or disables the telemetry job. Defaults to `true`. * `priorityClassName`: The priority class to be used by the telemetry 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`. ``` telemetry: enabled: true ``` If this configuration is disabled, Okteto CLI analytics are automatically disabled. ### webhook The webhook service. Ingress creation, generation of hostnames, enforcement of policies, etc... * `annotations`: Annotations to add to the webhook pods. * `extraEnv`: Environment variables to be set on the webhook containers. * `hostNetwork`: Enables or disables host networking for the webhook deployment. The default is false. * `labels`: Labels to add to the webhook pods. * `port`: Port sets the port used for the webhook deployment. The default is 443. * `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. ## Advanced Configuration ### affinity Apply default affinities to pods deployed in namespaces created by Okteto. * `devPool`: Affinities for pods created on namespaces managed by Okteto. * `oktetoPool`: Affinities for pods created during the Okteto installation. ``` affinity: devPool: preferredDuringSchedulingIgnoredDuringExecution: - preference: matchExpressions: - key: cloud.google.com/spot operator: In values: - "true" weight: 10 oktetoPool: preferredDuringSchedulingIgnoredDuringExecution: - preference: matchExpressions: - key: dev.okteto.com/overloaded operator: DoesNotExist weight: 50 ``` In this case, pods deployed in namespaces created by Okteto will have a preferred affinity to land on preemptive nodes. ### autowake When enabled, Okteto wakes up sleeping Namespaces upon receiving an incoming request to any of the Namespace's public endpoints (default: true). ``` autowake: enabled: true ``` ### convertLoadBalancedServices Converts services with type LoadBalancer into ClusterIP and automatically creates an ingress. Enabled by default. ``` convertLoadBalancedServices: enabled: true ``` ### crds Configures CRDs managed by Okteto. * `annotations`: The annotations to apply to the CRDs created during the Okteto installation. * `keep`: Keep CRDs on chart uninstall (defaults to `true`). * `install`: Install and upgrade CRDs on chart install (defaults to `true`). ``` crds: install: true keep: true annotations: {} ``` ### devStorageClass Uses the specified storage class for all persistent volume claims created when developers execute `okteto up`. This setting will override any storage class defined on the [Okteto manifest](/docs/reference/okteto-manifest.md#persistentvolume-object-optional). Disabled by default. * `storageClass`: The storage class enforced for persistent volume claims created by `okteto up`. ``` devStorageClass: enabled: true storageClass: ebs-sc ``` There is only one exception where this storage class is overwritten. In case of having [volume snapshots feature](/docs/self-hosted/install/volume-snapshots.md) configured, if a storage class is required for the snapshots that storage class will have preference. ### fullnameOverride The Okteto chart combines the release name and the chart name to create a prefix used for naming the Kubernetes resources created by the chart. Use this property to override the whole prefix. If you want to override only the chart name, you can use the [nameOverride](#nameoverride) setting. ``` fullnameOverride: custom-prefix ``` The maximum length for `fullnameOverride` is 34 characters. Check how to [extend the limit to 40 characters](#handling-a-long-release-name) if you need a longer prefix. ### globals Global settings applicable to all Okteto components. #### jobs Specifies global configuration for jobs created in the `okteto` namespace: * `ttlSecondsAfterFinished`: time in seconds to wait until a finished job is deleted (defaults to `86400` - 1 day). ``` globals: jobs: ttlSecondsAfterFinished: 86400 ``` #### nodeSelectors 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. ``` globals: nodeSelectors: okteto: okteto-node-label: okteto dev: okteto-node-label: dev region: east ``` 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. #### priorityClassName Defines the priority class to be used by all pods in the `okteto` namespace. The priority class must already exist in your cluster before using this setting. ``` globals: priorityClassName: okteto-priority ``` #### registry Defines the global registry applied for all the Okteto components (except for the CLI). For more information visit [our air-gapped installation guide](/docs/self-hosted/manage/air-gapped.md). ``` 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). ``` globals: tolerations: okteto: - key: "kubernetes.io/arch" operator: "Equal" value: "arm64" effect: "NoSchedule" dev: - key: "kubernetes.io/arch" operator: "Equal" value: "arm64dev" effect: "NoSchedule" ``` 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. ### ingress Configure default values for the ingress created by Okteto. * `annotations`: The annotations to apply to all the ingresses created during the Okteto installation. * `oktetoIngressClass`: The `ingressClassName` to apply to all the ingresses created during the Okteto installation (defaults to `okteto-controlplane-nginx`). * `class`: If specified, Okteto will set this as the `ingressClassName` of all ingresses managed by Okteto. This is useful if you have more than one ingress controller in your cluster. If not specified, it will fallback on the cluster's default ingress class. * `forceIngressClass`: If enabled, all ingresses deployed in namespaces managed by Okteto will have the ingress class defined in `ingress.class` (default: `false`). * `forceIngressSubdomain`: If enabled, the subdomain of the host of all ingresses deployed in namespaces managed by Okteto must match the Okteto wildcard subdomain (default: `false`). * `ip`: The internal IP of the ingress. Pods will call the Okteto API and the Okteto Registry using this IP. Required if the installation of the Okteto [NGINX Ingress Controller](/docs/self-hosted/helm-configuration.md#using-your-own-ingress-controller) is disabled. ``` ingress: annotations: {} oktetoIngressClass: nginx class: nginx forceIngressClass: false forceIngressSubdomain: true ip: "" ``` ### ingressLimits Configure ingress connections limits for each public endpoint. Disabled by default. * `connections`: Maximum parallel connections for each ingress. * `rps`: Maximum requests per second for each ingress. * `rpm`: Maximum requests per minute for each ingress. ``` ingressLimits: enabled: true connections: 40 rps: 40 rpm: 400 ``` ### injectDevelopmentBinaries Automatically inject `kubectl`, `helm`, and `okteto` binaries on every development container, and on the pipeline runner. If this is disabled, you'll need to provide your own image in `installer.image`. ``` 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 ``` internalCertificate: durationDays: 3650 annotations: {} ``` ### kubetoken * `lifetimeSeconds`: The lifetime in seconds of the tokens generated for the [Kubernetes credentials](/docs/core/credentials/kubernetes-credentials.md) provided by Okteto. This value has to be equal or greater than [`installer.activeDeadlineSeconds`](/docs/self-hosted/helm-configuration.md#installer) to make sure the tokens are valid during all installer execution. Defaults to 86400 seconds (1 day). > One important thing to bear in mind is that the maximum expiration time you can specify depends on the [Kubernetes apiserver's](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/) flag `--service-account-max-token-expiration`, so it might happen that the expiration time retrieved on your tokens is not the one specified here. If you specify a higher value, you will always get the maximum allowed by the apiserver. Be aware that not all Kubernetes service providers allow you to change this value and they enforce their own. ### nameOverride The Okteto chart combines the release name and the chart name to create a prefix used for naming the Kubernetes resources created by the chart. Use this property to override the chart name part of the prefix. You can override the whole prefix by using the [fullnameOverride](#fullnameoverride) setting. ``` nameOverride: custom-chart-name-override ``` Note that the maximum length for the entire prefix is 34 characters. Check how to [extend the limit to 40 characters](#handling-a-long-release-name) if you need a longer prefix. ### namespace Annotation and label customizations in namespaces created by Okteto. These annotations and labels are additional to the ones already applied by Okteto. * `annotations`: Annotations applied to each namespace created by Okteto. * `labels`: Labels applied to each namespace created by Okteto. * `ingress.annotations`: Annotations applied to ingresses in namespaces created by Okteto. * `ingress.labels`: Labels applied to ingresses in namespaces created by Okteto. * `autoRoleBinding.enabled`: Flag to automatically bind the default service account within namespaces managed by Okteto to the cluster role specified on [`serviceAccounts.roleBindings.namespaces`](/docs/self-hosted/helm-configuration.md#serviceaccounts). This will provide access to the Kubernetes API to all pods that do not have a custom service account. Defaults to `true`. ``` namespace: annotations: development: "true" labels: istio-injection: enabled ingress: annotations: cert-manager.io/issuer: "letsencrypt" labels: development: "true" ``` ### networkPolicies Configures [network policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) for each namespace to isolate network traffic. Disabled by default. * `ingress`: Ingress list of rules (NetworkPolicyIngressRule) to be applied on every namespace managed by Okteto. (optional). * `egress`: Egress list of rules (NetworkPolicyEgressRule) to be applied on every namespace managed by Okteto (optional). ``` networkPolicies: enabled: true ingress: - from: - ipBlock: cidr: 172.17.0.0/16 except: - 172.17.1.0/24 - namespaceSelector: matchLabels: project: myproject - podSelector: matchLabels: role: frontend ports: - protocol: TCP port: 6379 egress: - to: - ipBlock: cidr: 10.0.0.0/24 ports: - protocol: TCP port: 5978 ``` ### overrideFileWatchers Overrides the default kernel values for file watchers in every node. Recommended if you're running databases, or if you plan on using "okteto up" on the cluster. This requires permission to mount and modify /proc values. * `maxUserWatches`: The maximum number of allowed inotify watchers. * `maxMapCount`: The maximum number of memory map areas a process may have. * `aioMaxNR`: The maximum number of allowable concurrent IO requests. ``` overrideFileWatchers: enabled: true maxUserWatches: 10048576 maxMapCount: 262144 aioMaxNR: 1000000 ``` ### overrideRegistryResolution Overrides the registry hostname resolution to use internal IPs. This requires permission to mount and modify the cluster nodes' /etc/hosts file. ``` overrideRegistryResolution: enabled: true ``` ### oktetoBotUser Overrides the name of the user used for [admin access tokens](/docs/admin/dashboard.md#admin-access-tokens). Defaults to "okteto-bot". ### pullAlways Forces the `PullAlways` image pull policy in the cluster. Disabled by default. ``` pullAlways: enabled: true ``` ### quotas Enables [resource quotas](https://kubernetes.io/docs/concepts/policy/resource-quotas/) at the namespace level. The configuration applies to all Okteto-managed Namespaces, including development Namespaces and Preview Environments. * `resources`: Limits the number of resources that a user can create. * `maxNamespaces`: Maximum number of namespaces that a user can create. This does not apply to the `okteto-bot` user used for [admin access tokens](/docs/admin/dashboard.md#admin-access-tokens). * `maxPods`: Maximum number of pods per namespace. * `maxReplicationControllers`: Maximum number of replication controllers per namespace. * `maxSecrets`: Maximum number of secrets per namespace. * `maxServices`: Maximum number of services per namespace. * `maxJobs`: Maximum number of jobs per namespace. * `maxCronjobs`: Maximum number of cronjobs per namespace. * `maxLoadBalancers`: Maximum number of services of type `LoadBalancer` per namespace. * `maxNodePorts`: Maximum number of services of type `NodePort` per namespace. * `maxConfigMaps`: Maximum number of config maps per namespace. * `maxPVCs`: Maximum number of persistent volume claims per namespace. * `maxVolumeSnapshots`: Maximum number of volume snapshots per namespace. * `maxIngresses`: Maximum number of ingresses per namespace. * `bandwidth`: Limits the incoming/outgoing bandwidth per pod. Requires using the Okteto [NGINX Ingress Controller](/docs/self-hosted/helm-configuration.md#ingress-nginx). * `ingress`: Maximum ingress bandwidth. * `egress`: Maximum egress bandwidth. * `up`: Limits the incoming/outgoing bandwidth per development container. * `ingress`: Maximum ingress bandwidth for a development container * `egress`: Maximum egress bandwidth for a development container. * `requests`: Limits the maximum [resource requests](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits) per namespace. * `cpu`: Maximum CPU resource requests. * `memory`: Maximum memory resource requests. * `storage`: Maximum storage resource requests. * `limits`: Limits the maximum [resource limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits) per namespace. * `cpu`: Maximum CPU resource limits. * `memory`: Maximum memory resource limits. * `storage`: Maximum storage resource limits. * `limitranges`: Configures the [limit ranges](https://kubernetes.io/docs/concepts/policy/limit-range/) of each namespace. * `max`: Configures the maximum resources per container. * `cpu`: Maximum CPU resource limits. * `memory`: Maximum memory resource limits. * `requests`: Configures the default resource requests per container. * `cpu`: Default CPU resource requests. * `memory`: Default memory resource requests. * `limits`: Configures the default resource limits per container. * `cpu`: Default CPU resource limits. * `memory`: Default memory resource limits. The default configuration values are shown below. A value of "-1" indicates that no quota is enforced for that specific resource: ``` quotas: resources: enabled: false maxNamespaces: "3" maxPods: "-1" maxServices: "-1" maxLoadBalancers: "0" maxNodePorts: "0" maxReplicationControllers: "-1" maxSecrets: "-1" maxConfigMaps: "-1" maxPVCs: "-1" maxVolumeSnapshots: "-1" maxIngresses: "-1" maxJobs: "-1" maxCronjobs: "-1" bandwidth: enabled: false ingress: "800M" egress: "800M" up: enabled: false ingress: "800M" egress: "800M" requests: enabled: false cpu: "1" memory: "2Gi" storage: "20Gi" limits: enabled: false cpu: "4" memory: "8Gi" storage: "20Gi" limitranges: max: enabled: false cpu: "3" memory: "12Gi" requests: enabled: true cpu: "10m" memory: "50Mi" limits: enabled: true cpu: "2" memory: "8Gi" ``` ### secret Labels and annotations to include in the secret created by the chart. Useful if you want to integrate with Vault or similar secret stores. ``` secret: annotations: your.custom.annotation: "10" labels: your.custom.label: "20" ``` ### serviceAccounts Use the `serviceAccounts` section to configure labels, annotations and role bindings to be applied to each service account generated by Okteto for user accounts. * `annotations`: Annotations added to each service account generated by Okteto for user accounts. * `labels`: Labels added to each service account generated by Okteto for user accounts. * `roleBindings.namespaces`: Okteto assigns this cluster role to every admin, owner and member of a namespace via a namespace-scoped role binding on every namespace managed by Okteto. This cluster role is **not** created by Okteto, it must exist in the cluster. Default value is `cluster-admin`. * `roleBindings.previews`: Okteto assigns this cluster role to every Okteto user via a namespace-scoped role binding on every **global** preview environment. This cluster role is **not** created by Okteto, it must exist in the cluster. Default value is `view`. * `clusterRoleBinding`: Okteto assigns this cluster role to every user via a cluster role binding. By default, this behavior is disabled. This can be useful to give access to cluster level resources to every developer account, like accessing the Node API. This cluster role is **not** created by Okteto, it must exist in the cluster. * `extraRoleBindings`: Okteto assigns every cluster role specified there to every user via a namespace-scoped role binding on the namespace specified in the configuration. Okteto will not create the ClusterRoles nor the Namespaces and expects them to exist in the cluster. ``` serviceAccounts: annotations: custom.annotation/one: one custom.annotation/two: two labels: custom.label/one: one custom.label/two: two roleBindings: namespaces: cluster-admin previews: view clusterRoleBinding: "example-cluster-role" extraRoleBindings: namespace-name1: - cluster-role1 - cluster-role2 namespace-name2: - cluster-role3 ``` > In case you need to link more than one cluster role in any of the configuration settings, you should use [Cluster Role aggregation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles) to aggregate several Cluster Roles into one. ### store Configures how Okteto persists user data. * `personalAccessToken.max`: The maximum number of [Personal Access Tokens](/docs/core/credentials/personal-access-tokens.md) each user can create. Defaults to `5`. ``` store: personalAccessToken: max: 5 ``` note Okteto stores each Personal Access Token as a Kubernetes Secret. A cluster has a finite capacity for the total number of Secrets it can hold, so set `personalAccessToken.max` in proportion to the number of users on your instance. A high value multiplied across many users can exhaust the cluster's Secret capacity. ### userDefinedNamespaces Disable if you want to enforce using the `username` as a suffix on namespaces and ingress hosts. Enabled by default. ``` userDefinedNamespaces: false ``` ### userPodAffinity When enabled Okteto automatically adds a preferred affinity to every pod, which leans towards placing pods from the same namespace and in the same node (default: `true`). * `antiAffinity`: When enabled Okteto adds an anti-affinity to the pod to ensure that all pods in the same namespace are placed in the same node. Disabled by default ``` userPodAffinity: enabled: true antiAffinity: enabled: false ``` ### virtualServices When enabled, the Okteto UI will show the public endpoints associated with [Istio Virtual Services](https://istio.io/latest/docs/reference/config/networking/virtual-service/) (default: `false`). ``` virtualServices: enabled: false ``` ### volumes Allows you to specify different settings for volumes. * `validate`: Section to configure volume validation. * `enabled`: Enables volume validation. Disabled by default * `supportedStorageClasses`: List of supported storage classes. * `forceStorageClass`: Flag to specify if the storage class should be enforced in case of creating a volume with a non-supported storage class. If set, the first storage class specified on `supportedStorageClasses` will be the enforced value. * `supportedAccessModes`: List of supported access modes. ``` volumes: validate: enabled: true supportedStorageClasses: ["standard", "standard-rwo"] forceStorageClass: true supportedAccessModes: ["ReadWriteOnce"] ``` ### volumeSnapshots Enables users to initialize persistent volume claims with the contents of a preexisting volume snapshot. This feature requires having a CSI driver installed in your cluster. * `driver`: The name of the CSI driver used when creating snapshots. * `class`: The VolumeSnapshotClass of the volume snapshot. * `storageClass`: The storage class required by volumes initialized from snapshots (optional). * `enableNamespaceAccessValidation`: When enabled, only users that have access to the namespace where the volume snapshot is stored will be able to use it in their development environments. Default false. * `allowIDAnnotation`: Allow using your cloud provider's snapshot ID as the source of the data. Default true. ``` volumeSnapshots: enabled: true driver: ebs.csi.aws.com class: snapclass storageClass: ebs-sc ``` Add the `dev.okteto.com/from-snapshot-id` annotation to any persistent volume claim to tell Okteto to initialize your persistent volume claim, as shown below: ``` apiVersion: v1 kind: PersistentVolumeClaim metadata: annotations: dev.okteto.com/from-snapshot-id: snap-xxxxxxxx name: pvc-name spec: accessModes: - ReadWriteOnce resources: requests: storage: 10Gi ``` When a persistent volume claim resource is created, Okteto will import the snapshot in Kubernetes using a [VolumeSnapshotContent](https://kubernetes.io/docs/concepts/storage/volume-snapshots/) and will set the source of your persistent volume claim to this VolumeSnapshotContent. ### wildcardCertificate By default, Okteto configures a self-signed wildcard certificate for your instance to simplify your product evaluation. For a production-ready installation, follow our docs to [configure your wildcard certificate](/docs/self-hosted/install/certificates.md) and disable the default behavior. These are all the settings available to configure certificates: * `create`: If set to false, Okteto will not create a self-signed wildcard certificate * `duration`: The duration of the self-signed certificate. Ignored if `create` is set to `false` * `name`: The name of the secret where the certificate is stored * `privateCA.enabled`: Set to true when using a private certificate authority * `privateCA.secret.name`: The name of the secret that stores the private certificate authority's certificate * `privateCA.secret.key`: The key in the secret that stores the private certificate authority's certificate * `annotations`: Annotations to add to the self-signed certificate generated by Okteto ``` wildcardCertificate: create: true duration: 2160h0m0s name: default-ssl-certificate annotations: argocd.argoproj.io/compare-options: IgnoreExtraneous # if using a private CA, specify the name of the TLS secret that stores the certificate privateCA: enabled: false secret: name: "okteto-ca" key: "ca.crt" ``` ## 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). Each instance has an specific role: * `ingress-nginx`: ingress-controller that serves all the inbound traffic to the Okteto cluster, including Buildkit, Registry, Okteto API, Okteto Frontend and users' ingresses. * `okteto-nginx`: ingress-controller dedicated to serve users' ingresses inbound traffic. By default, it is deployed behind `ingress-nginx`. ### Okteto Ingress Controllers Okteto has two nginx-related keys you can define in your configuration file (e.g. `config.yaml` or any other config file where you specify these keys): `ingress-nginx` and `okteto-nginx`. These each serve a different function. #### ingress-nginx This key is used to specify ingress behavior for Okteto's platform components (e.g. api, buildkit, registry) and supports passthrough/proxy behavior to `okteto-nginx`. This configuration will serve through a `*.$subdomain` internal ingress pointing to `okteto-nginx`. This ingress controller resides within the control plane of the Okteto cluster. #### okteto-nginx This key is used to specify ingress behavior specifically for development environments. This configuration is used to parse and register developer ingresses. This ingress controller resides within the cluster and manages ingress to and between developer applications. A practical example of how these two ingress controllers interaction is: when a new user request arrives to Okteto it will be served by `ingress-nginx`, which will proxy it to `okteto-nginx`. Then `okteto-nginx` will proxy the request to the backend pod. #### Sample configuration One example of modifying the Okteto ingress controllers, to change the number of replicas in `ingress-nginx`, looks like this: ``` ingress-nginx: controller: replicaCount: 2 ``` The full list of values is [available here](https://github.com/kubernetes/ingress-nginx/blob/main/charts/ingress-nginx/values.yaml). #### 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: * `ingress-nginx`: ``` helm get values okteto/okteto --jsonpath '{.ingress-nginx}' ``` * `okteto-nginx`: ``` helm get values okteto/okteto --jsonpath '{.okteto-nginx}' ``` #### Using Your Own Ingress Controller Refer to this [community guide](https://community.okteto.com/t/how-do-i-configure-my-own-ingress-controller/887) for detailed instructions on disabling the Okteto Nginx Ingress Controller and exposing Okteto behind your own Ingress Controller. ### Reloader 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). ## 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: * `OKTETO_LICENSE`: use this instead of `.Values.license` in your helm configuration file. * `GOOGLE_CLIENTSECRET`: use this instead of `.Values.auth.google.clientSecret` in your helm configuration file. * `GITHUB_CLIENTSECRET`: use this instead of `.Values.auth.github.clientSecret` in your helm configuration file. * `BITBUCKET_CLIENTSECRET`: use this instead of `.Values.auth.bitbucket.clientSecret` in your helm configuration file. * `OPENID_CLIENTSECRET`: use this instead of `.Values.auth.openid.clientSecret` in your helm configuration file. * `GITHUB_INTEGRATION_CLIENTSECRET`: use this instead of `.Values.github.clientSecret` in your helm configuration file. * `GITHUB_APP_PRIVATE_KEY`: use this instead of `.Values.github.appPrivateKey` in your helm configuration file. ## Handling a Long Release Name The Okteto chart combines the release name and the chart name to create a prefix used for naming the Kubernetes resources created by the chart. In Kubernetes, there are strict limits on the maximum length of names for various resources. For example, CronJob names cannot exceed 52 characters, and Service names cannot be longer than 63 characters. Additionally, Helm enforces a maximum length of 53 characters for a release name. Since the Okteto chart creates multiple resources in Kubernetes, it employs specific strategies to avoid exceeding these length limits and to minimize the need for additional configuration. The maximum length for the Okteto prefix is 34 characters. This limit is derived from the maximum name length allowed by Kubernetes (63 characters), minus the length of the longest Okteto component suffix ("-ingress-nginx-defaultbackend"). The 34 characters are then divided into 27 characters for the release name and 7 characters for the chart name ("-okteto"). This limit can be extended to 40 characters by overriding the name of the defaultBackend component. To do this, set the `defaultBackend.nameOverride` value. If you need to use a release name longer than 40 characters, you can also use the [nameOverride](#nameoverride) or [fullnameOverride](#fullnameoverride) settings to make the prefix shorter. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Authentication There are numerous authentication methods available in Okteto to verify user identity. The authentication configuration dictates which users can access Okteto and the method they can use for logging in. Okteto supports the following auth providers: * [Azure Active Directory](/docs/self-hosted/install/auth/azure-ad.md) * [Bitbucket](/docs/self-hosted/install/auth/bitbucket.md) * [GitHub](/docs/self-hosted/install/auth/github.md) * [GitLab](/docs/self-hosted/install/auth/gitlab.md) * [Google](/docs/self-hosted/install/auth/google.md) * [Okta](/docs/self-hosted/install/auth/okta.md) * [OpenID Connect](/docs/self-hosted/install/auth/openid-connect.md) * [Token](/docs/self-hosted/install/auth/token.md) > Are we missing your favorite identity provider? Open a feature request in the [Okteto Community](https://community.okteto.com/t/about-the-feature-requests-category/28) and let us know! Additionally, Okteto provides a single user authentication method based on a [Token](/docs/self-hosted/install/auth/token.md) for initial evaluations. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Use Azure AD as your Authentication Provider This guide will walk you through the steps necessary to configure Azure Active Directory as the authentication provider for Okteto. Please refer to [Azure's official documentation](https://learn.microsoft.com/en-us/power-apps/maker/portals/configure/configure-openid-settings) on Open ID Connect for more information. ## Prerequisites * A working installation of [Okteto](/docs/get-started/install.md) * [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 register applications in Azure Active Directory ## Create an App Registration Create a [new app integration](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/CreateApplicationBlade/quickStartType~/null/isMSAApp~/false), using the values below: ![Create the new App Registration](/docs/assets/images/new-app-37555f40943994e9a36ba11ec0b1ada0.png) Then, fill in the following values on the “Register an application” window: 1. Name: The name of your application (e.g. `okteto`) 2. Accounts in this organizational directory only (Default Directory only - Single tenant) 3. Redirect URI: [https://okteto.{YOUR\_DOMAIN}/auth/callback](https://okteto.%7BYOUR_DOMAIN%7D/auth/callback) Once the application has been created, save the `Application (client) ID` value. You'll need it to configure your Okteto Instance. ![Copy the Tenant ID](/docs/assets/images/client-id-0ddb5be9f0db2f90c2beac9db8502a8b.png) Copy the `Directory (tenant) ID` value. You'll need it to configure your Okteto Instance. ![Copy the Tenant ID](/docs/assets/images/tenant-id-73774ad83abeb5a1758945b110f5ea5e.png) On the left menu, click on "Certificates & secrets". Create a "New client secret" and copy the `Value`. You'll need it to configure your Okteto Instance. ![Copy the Secret ID and Value](/docs/assets/images/azure-secrets-25a84da52d872c8e4eecfb507d4977fc.png) On the left menu, click on "API permissions" and grant the following permissions: ![Grant permissions](/docs/assets/images/permissions-11beed7ebc02bac3dd357336afc1e360.png) ## Configure Okteto Once you have the Okta application ready, update the `auth` section of your Okteto Helm configuration file with the values you obtained on the first step of this guide: config.yaml ``` auth: openid: enabled: true clientId: $CLIENT_ID clientSecret: $CLIENT_SECRET endpoints: issuer: https://sts.windows.net/$TENANT_ID/ authorization: https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/authorize mapping: externalIDKey: email ``` > You can also store the value of clientSecret [as a secret directly in Kubernetes](/docs/self-hosted/helm-configuration.md#store-sensitive-configuration-values-using-a-secret). [Upgrade your Okteto instance](/docs/self-hosted/manage/upgrade.md) 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. Once the upgrade has been completed, go to your instance and click on the **Log In** button to access your instance. If everything is configured correctly, Okteto will now use your Azure Active Directory for user authentication. ![Log in with Azure Active Directory](/docs/assets/images/with-azure-ad48e11e574b3053b34641733c3a2458.png) ## Customize the attributes that Okteto consumes By default, Okteto will use the following attributes below when creating a user: * `Name` as the display name of the user. * `Nickname` as the username of the user. * `Email` as the email. Addresses must contain only lowercase alphanumeric characters, '-', or '.' * `Picture URL` for the user's profile picture. If you are not using some of those values, or you want to customize which attributes get mapped, you can customize that by using the `mapping` field inside the `openid` key in your Helm configuration file. config.yaml ``` auth: openid: enabled: true clientId: $CLIENT_ID clientSecret: $CLIENT_SECRET endpoints: issuer: https://sts.windows.net/$TENANT_ID/ authorization: https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/authorize mapping: externalIDKey: nickname nameKey: name emailKey: email pictureKey: picture ``` The value of every key in the `mapping` section must match a `claim` in your Azure Active Directory + OpenID configuration, and it must contain a non-empty value. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Use Bitbucket as your Authentication Provider This guide will walk you through the steps necessary to configure Bitbucket as the authentication provider for Okteto. Please refer to [Bitbucket's official documentation](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/) on how to create an OAuth Consumer for more information. ## Prerequisites * A working installation of [Okteto](/docs/get-started/install.md) * [Helm](https://helm.sh/docs/intro/install/) 3.0+ installed in your local machine * Access to a [Bitbucket account](https://bitbucket.org/) with permissions to create an OAuth Consumer ## Create the OAuth Consumer When creating the OAuth Consumer, you will need to provide the following values: **Callback URL**: ``` https://okteto.DOMAIN/auth/callback ``` **URL**: ``` https://okteto.DOMAIN ``` **Permissions**: Account: Email Account: Read Copy the `OAuth Consumer Key` and `OAuth Consumer Secret` values. You'll need them to configure Okteto. ## Configure Okteto Once you have the Bitbucket OAuth Consumer ready, update the `auth` section of your Helm configuration file with the following values: config.yaml ``` auth: bitbucket: enabled: true clientId: "REPLACE_ME_WITH_YOUR_OAUTH_CONSUMER_KEY" clientSecret: "REPLACE_ME_WITH_YOUR_OAUTH_CONSUMER_SECRET" workspace: "REPLACE_ME_WITH_YOUR_BITBUCKET_WORKSPACE" ``` > You can also use a [secret](/docs/self-hosted/helm-configuration.md#store-sensitive-configuration-values-using-a-secret) to store the sensitive part of these credentials. [Upgrade your Okteto instance](/docs/self-hosted/manage/upgrade.md) 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. The `workspace` field is optional. Only members of the workspace will be allowed to login into Okteto. An empty `workspace` field permits any user to log in. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Use GitHub as your Authentication Provider This guide will walk you through the steps necessary to configure GitHub as the authentication provider for Okteto. Please refer to [GitHub's official documentation](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/) on how to create an OAuth App for more information. ## Prerequisites * A working installation of [Okteto](/docs/get-started/install.md) * [Helm](https://helm.sh/docs/intro/install/) 3.0+ installed in your local machine * Access to a [GitHub account](https://github.com/) with permissions to create an OAuth App > If you are planning on using our GitHub Integration for accessing private repositories, you should follow [the guide to configure our GitHub App](/docs/self-hosted/install/github-integration.md). You'll then use the same Github Application for the Integration as the one from Oauth. ## Create the OAuth App When creating the OAuth App, you will need to provide the following values: **Homepage URL**: ``` https://okteto.DOMAIN ``` **Authorization callback URL**: ``` https://okteto.DOMAIN/auth/callback ``` Copy the `Client ID` and `Client Secret` values. You'll need them to configure Okteto. ## Configure Okteto Once you have the GitHub OAuth App ready, update the `auth` section of your Helm configuration file with the following values: config.yaml ``` auth: github: enabled: true clientId: "REPLACE_ME_WITH_YOUR_OAUTH_APP_CLIEND_ID" clientSecret: "REPLACE_ME_WITH_YOUR_OAUTH_APP_CLIEND_SECRET" organization: "REPLACE_ME_WITH_YOUR_GITHUB_ORGANIZATION" ``` > You can also use a [secret](/docs/self-hosted/helm-configuration.md#store-sensitive-configuration-values-using-a-secret) to store the sensitive part of these credentials. [Upgrade your Okteto instance](/docs/self-hosted/manage/upgrade.md) 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. The `organization` field is optional. Only members of the organization will be allowed to log in into your Okteto instance. An empty `organization` field permits any user to log in. warning If your Okteto instance is publicly reachable, we highly recommend that you set up access restrictions. Leaving the organization field blank lets anyone with a GitHub account log in to your Okteto instance. If you want to provide access to users outside of your GitHub organization, you can additionally use the `allowList` key to list the GitHub accounts you want to allow. config.yaml ``` auth: github: enabled: true clientId: "REPLACE_ME_WITH_YOUR_OAUTH_APP_CLIEND_ID" clientSecret: "REPLACE_ME_WITH_YOUR_OAUTH_APP_CLIEND_SECRET" organization: "REPLACE_ME_WITH_YOUR_GITHUB_ORGANIZATION" allowList: ["acct1","acct2","acct3"] ``` We also have a video walking you through the steps on configuring GitHub as an authentication provider for your Okteto installation: [YouTube video player](https://www.youtube.com/embed/_IUUASuAjtg) --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Use Gitlab as your Authentication Provider This guide will walk you through the steps necessary to configure Gitlab as the authentication provider for your Okteto instance. Please refer to [GitLab's official documentation](https://docs.gitlab.com/ee/integration/openid_connect_provider.html) on Open ID Connect for more information. ## Prerequisites * A working installation of [Okteto](/docs/get-started/install.md) * [Helm](https://helm.sh/docs/intro/install/) 3.0+ installed in your local machine. * Access to a [Gitlab account](https://gitlab.com) with permissions to enable and configure OAuth and OpenID. This can either gitlab.com, or self-hosted GitLab. note This guide will use in the examples. If you're using GitLab self-hosted, replace `gitlab.com` with the URL of your GitLab instance. ## Create the GitLab Application Create a new OAuth application integration, using the values below: * Name: "okteto" * Redirect URI: "[https://okteto.${YOUR\_DOMAIN}.com/auth/callback](https://okteto.$%7BYOUR_DOMAIN%7D.com/auth/callback)" * Unselect the `Confidential` checkbox * Select the following scopes: * `openid` * `profile` * `email` ![Create the new GitLab App](/docs/assets/images/gitlab-new-app-5fe3f448355190bf5ca9b8169a1475eb.png) ![Set the OpenID Scopes for the GitLab App](/docs/assets/images/gitlab-new-app-scopes-d86432ac24e22853c124343304383d61.png) Once the application has been created, copy the values of the `Application ID` and the `Secret`. You'll need them to configure Okteto. ![Copy the Application ID and Secret from the success page](/docs/assets/images/gitlab-app-created-76eba456257e5e383d035be203bb7842.png) Finally, browse to , and copy the values of `issuer` and `authorization_endpoint`. You'll need them to configure Okteto. ![Copy the issuer and authorization\_endpoint from the openid configuration response](/docs/assets/images/gitlab-openid-configuration-b5c9efa4b935b8b652bdcbbd6d007d91.png) ## Configure Okteto Once you have the GitLab application ready, update the `auth` section of your Okteto Helm configuration file with the values you obtained on the first step of this guide: config.yaml ``` auth: openid: enabled: true clientId: $CLIENT_ID clientSecret: $CLIENT_SECRET endpoints: issuer: "https://gitlab.com" authorization: "https://gitlab.com/oauth/authorize" mapping: externalIDKey: email ``` > You can also store the value of clientSecret [as a secret directly in Kubernetes](/docs/self-hosted/helm-configuration.md#store-sensitive-configuration-values-using-a-secret). [Upgrade your Okteto instance](/docs/self-hosted/manage/upgrade.md) 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. Once the upgrade has been completed, go to your instance and click on the **Log In** button to access your instance. If everything is configured correctly, Okteto will now use Gitlab for user authentication. ![Log in with Gitlab](/docs/assets/images/with-azure-ad48e11e574b3053b34641733c3a2458.png) ## Customize the attributes that Okteto consumes By default, Okteto will use the following attributes below when creating a user: * `Name` as the display name of the user. * `Nickname` as the username of the user. * `Email` as the email. Addresses must contain only lowercase alphanumeric characters, '-', or '.' * `Picture URL` for the user's profile picture. If you are not using some of those values, or you want to customize which attributes get mapped, you can customize that by using the `mapping` field inside the `openid` key in your Helm configuration file. config.yaml ``` auth: openid: enabled: true clientId: $CLIENT_ID clientSecret: $CLIENT_SECRET endpoints: issuer: "https://gitlab.com" authorization: "https://gitlab.com/oauth/authorize" mapping: externalIDKey: nickname nameKey: name emailKey: email pictureKey: picture ``` The value of every key in the `mapping` section must match a `claim` in your Gitlab OpenID configuration, and it must contain a non-empty value. You can see the available claims in the `claims_supported` section of . --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Use Google as your Authentication Provider This guide will walk you through the steps necessary to configure Google as the authentication provider for Okteto. Please refer to [Google's official documentation](https://support.google.com/cloud/answer/6158849?hl=en) on how to create an OAuth 2.0 Client for more information. ## Prerequisites * A working installation of [Okteto](/docs/get-started/install.md) * [Helm](https://helm.sh/docs/intro/install/) 3.0+ installed in your local machine * Access to a [Google account](https://cloud.google.com/) with permissions to create an OAuth 2.0 Client ## Create the OAuth 2.0 Client When creating the OAUTH 2.0 Client, you will need to provide the following values: **Authorized javascript origin**: ``` https://okteto.DOMAIN ``` **Authorized redirect URIs**: ``` https://okteto.DOMAIN https://okteto.DOMAIN/auth/callback ``` Copy the `Client Secret` value. You'll need it to configure Okteto. ## Configure Okteto Once you have the Google OAuth 2.0 Client ready, update the `auth` section of your Helm configuration file with the following values: config.yaml ``` auth: google: enabled: true clientId: clientid.apps.googleusercontent.com clientSecret: "REPLACE_ME_WITH_YOUR_OAUTH_CLIENT_SECRET" allowDomains: - example.com ``` > You can also use a [secret](/docs/self-hosted/helm-configuration.md#store-sensitive-configuration-values-using-a-secret) to store the sensitive part of these credentials. [Upgrade your Okteto instance](/docs/self-hosted/manage/upgrade.md) 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. The `allowDomains` field is optional. Only users with Google Workspace accounts that match one of the domains on the list will be allowed to log into your Okteto instance. An empty `allowDomains` field permits any user with a valid Google Workspace account to log in. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Use Okta as your Authentication Provider This guide will walk you through the steps necessary to configure Okta as the authentication provider for your instance of Okteto. Please refer to [Okta's official documentation](https://developer.okta.com/docs/concepts/oauth-openid/) on Open ID Connect for more information. ## Prerequisites * A working installation of [Okteto](/docs/get-started/install.md) * [Helm](https://helm.sh/docs/intro/install/) 3.0+ installed in your local machine. * Access to an [Okta Workforce Identity Cloud account](https://www.okta.com) with permissions to create Applications. ## Create the Okta Application Create a new app integration, using the values below: ![Create the new app](/docs/assets/images/okta-new-app-62b0df6dffeed2787e3c7e0d913291be.png) Then, fill in the following values on the “New Web App Integration” window: 1. Name: The name of your app (e.g. Okteto) 2. Grant type: authorization code 3. Sign-in redirect URIs: `https://okteto.{YOUR_DOMAIN}`  & `https://okteto.{YOUR_DOMAIN}/auth/callback` 4. Assignments: We recommend you create a dedicated group for Okteto, so you can control who can access your instance from Okta. Leave all the other values empty, and press the save button. ![Create the new app integration](/docs/assets/images/new-web-app-integration-1b68dcdd449a96cc672ceb40af98c156.png) ![Create the new app integration](/docs/assets/images/new-web-app-integration-2-a3515d45927b666e07aece3d0fb1b563.png) Once the application has been created, copy the `ClientID` and the `Client Secret` values. You'll need them to configure Okteto. ![Copy the client ID and the Client Secret](/docs/assets/images/okta-secrets-12aeb4fa6a7a4cd88b6b208aa019bd48.png) Assign the users or groups that will have access to Okteto to the application that you just created. ![Assign the users to the application](/docs/assets/images/assignment-366f09939c2e389e8282eb90401f0c11.png) By default, Okteto will use the attributes below when creating a user. These will be synchronized when the account is created, and every time the user logs in. * `Name` as the display name of the user. * `Nickname` as the username of the user. * `Email` as the email. Addresses must contain only lowercase alphanumeric characters, '-', or '.' * `Picture URL` for the user's profile picture. Authentication will fail if the `Nickname` or `Email` property is missing or empty. Please refer to the [Customize the attributes that Okteto consumes](#customize-the-attributes-that-okteto-consumes) section below on how to change the attributes that Okteto will use during authentication and account creation. Finally, browse to `https://{YOUR_TENANT}.okta.com/.well-known/openid-configuration`, and copy the values of `issuer` and `authorization_endpoint`. You'll need them to configure Okteto. ![Get the URLs for authorization](/docs/assets/images/well-known-1ca5a2da3fe92e37a3f0146b3cb59ce0.png) ## Update your Users Profile for Okteto Okta will send the values set on the user profile as part of the authentication process. If you want to set specific values for Okteto, you can set an Application-specific override by going to Directory → People → `${User}` → Applications → Okteto → Edit). ![Update the profile in the application assignment](/docs/assets/images/profile-33474b1fac35548b03d5e69f9c7be019.png) ![Update the profile details in the application assignment](/docs/assets/images/profile-details-e1b58295f2d5bbdf94c05e7adef91559.png) > If you want to sync the profile picture from Okta, you'll need to set the Picture URL property in the dialog shown above. ## Configure Okteto Once you have the Okta application ready, , update the `auth` section of your Okteto Helm configuration file with the values you obtained on the first step of this guide: config.yaml ``` auth: openid: enabled: true clientId: $CLIENT_ID clientSecret: $CLIENT_SECRET endpoints: issuer: $ISSUER_URL authorization: $AUTHORIZATION_URL mapping: externalIDKey: email ``` You can read more about `mapping` [here](/docs/self-hosted/install/auth/okta.md#customize-the-attributes-that-okteto-consumes). In our sample instance, this looks like: config.yaml ``` auth: openid: enabled: true clientId: 0oa76rh0z5zgKG7XXXXX clientSecret: dTgsfHbYV9tt91Ng4dzvpULw6y7kjJaYxzfXXXXX endpoints: issuer: https://dev-6093102.okta.com authorization: https://dev-6093102.okta.com/oauth2/v1/authorize mapping: externalIDKey: email ``` > You can also store the value of clientSecret [as a secret directly in Kubernetes](/docs/self-hosted/helm-configuration.md#store-sensitive-configuration-values-using-a-secret). [Upgrade your Okteto instance](/docs/self-hosted/manage/upgrade.md) 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. Once the upgrade has been completed, go to your instance and click on the 'Log In' button to access your instance using Okta as the authentication provider. ![Log in with Okta](/docs/assets/images/with-okta-ad48e11e574b3053b34641733c3a2458.png) ## Customize the attributes that Okteto consumes By default, Okteto will use the following attributes below when creating a user: * `Name` as the display name of the user. * `Nickname` as the username of the user. * `Email` as the email. Addresses must contain only lowercase alphanumeric characters, '-', or '.' * `Picture URL` for the user's profile picture. If you are not using some of those values, or you want to customize which attributes get mapped, you can customize that by using the `mapping` field inside the `openid` key in your Helm configuration file. config.yaml ``` auth: openid: enabled: true clientId: $CLIENT_ID clientSecret: $CLIENT_SECRET endpoints: issuer: $ISSUER_URL authorization: $AUTHORIZATION_URL mapping: externalIDKey: nickname nameKey: name emailKey: email pictureKey: picture ``` The value of every key in the `mapping` section must match a `claim` in your Okta + OpenID configuration, and it must contain a non-empty value. For example, if you just want to use the `email` instead of the nickname for usernames, use the following configuration: ``` auth: openid: enabled: true clientId: 0oa76rh0z5zgKG7XXXXX clientSecret: dTgsfHbYV9tt91Ng4dzvpULw6y7kjJaYxzfXXXXX endpoints: issuer: https://dev-6093102.okta.com authorization: https://dev-6093102.okta.com/oauth2/v1/authorize mapping: externalIDKey: email ``` ## Configure Automatic User Deprovisioning [Follow this guide](/docs/admin/integrations/okta-user-deprovisioning.md) to set up the Okta event hook for user deprovisioning. ## Troubleshooting ### Log in fails with a 500 error This is most likely because the user was not added to the application. Make sure that the user (or group) is assigned to the application that you just created in Okta. To fix this, go to Application → Okteto → Assignments and add the required users or groups. ![Add user to the Okta application](/docs/assets/images/add-user-45e874b8936d4a42178ceca4da925529.png) --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Use OpenID Connect (OIDC) as your Authentication Provider This guide will walk you through the steps necessary to configure OpenID Connect (OIDC) as the authentication provider for Okteto. note If you are looking to configure Private Registry credentials from Amazon ECR, please [see our guide here](/docs/admin/registry-credentials/amazon-ecr.md#using-iam-roles-via-openid-connect-oidc-federation). Okteto supports any identity provider that implements the OpenID Connect standard. We have dedicated guides for the following providers: * [Azure Active Directory](/docs/self-hosted/install/auth/azure-ad.md) * [GitLab](/docs/self-hosted/install/auth/gitlab.md) * [Okta](/docs/self-hosted/install/auth/okta.md) For other providers, follow your OpenID Connect service provider's documentation on how to create the required application. note Your provider needs to support the [UserInfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) in order to be used with Okteto. This authentication option follows the OpenID standard, and it has been validated with Okta, PingIdentity, and GitLab. ## Prerequisites * A working installation of [Okteto](/docs/get-started/install.md) * [Helm](https://helm.sh/docs/intro/install/) 3.0+ installed in your local machine ## Create the OpenID Connect Application When creating the application, you'll need to provide the following values: * Start SSO URL: `https://okteto.DOMAIN` * Redirect URIs: `https://okteto.DOMAIN`, `https://okteto.DOMAIN/auth/callback` * Scopes: `openid`, `email`, `profile` * Response Type: `code` * Grant Type: `authorization code` ## Configure Okteto Once you have the OpenID Connect Application ready, update the `auth` section of your Helm configuration file with the following values: config.yaml ``` openid: enabled: true clientId: "REPLACE_ME_WITH_YOUR_APPLICATION_CLIENT_ID" clientSecret: "REPLACE_ME_WITH_YOUR_APPLICATION_CLIENT_SECRET" group: "REPLACE_ME_WITH_YOUR_GROUP" endpoints: issuer: "REPLACE_ME_WITH_YOUR_ISSUER_URL" authorization: "REPLACE_ME_WITH_YOUR_AUTHORIZATION_URL" mapping: externalIDKey: nickname nameKey: name emailKey: email pictureKey: picture groupsKey: groups ``` > You can also use a [secret](/docs/self-hosted/helm-configuration.md#store-sensitive-configuration-values-using-a-secret) to store the sensitive part of these credentials. [Upgrade your Okteto instance](/docs/self-hosted/manage/upgrade.md) 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. The `group` field is optional. Only members of the group will be allowed to log in into your Okteto instance. An empty `group` field permits any user to log in. 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. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Use Tokens as your Authentication Provider Okteto defaults to token-based authentication to simplify the installation and configuration of Okteto self-hosted. In this mode, Okteto automatically generates a token for an Admin user that you can use to log in to the Okteto UI and start exploring Okteto's features and functionality much faster than configuring other authentication methods. Once you've completed the product evaluation, we recommend switching to another authentication method for your final rollout. Token-based authentication is not ideal for production use of Okteto. To use token-based authentication, remove the [`auth` section of your Okteto Helm configuration](/docs/self-hosted/helm-configuration.md#auth) file and [upgrade your Okteto instance](/docs/self-hosted/manage/upgrade.md) 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. This option allows you to grant access to other users to continue your evaluation. ![generating an invitation link for a new user](/docs/assets/images/token-add-user+1.32-db42adac4618c9a25d2624ccfc8e62a2.png) 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 user has opened the invitation link, they can copy their Okteto token and see details on how to connect the Okteto CLI. ![accepting an invitation and retrieving the Okteto token](/docs/assets/images/token-accept-invite+1.32-10bef030cbdade111705e873f7e68638.png) After successful use, the invite link becomes invalid. If for any reason a user has not yet joined your Okteto instance and cannot find the invitation, the link can be viewed again by an administrator. To do so, click on the three dots related to the invited users name, then select "View Invite Link." ![viewing an existing invitation link from the admin panel](/docs/assets/images/token-resend-link+1.46-37abd91fbfeb7eb0be4773d3cd37333b.jpg) ## 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. 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. In the event of losing this token, the cluster admin can retrieve the token of a given `username` by executing the following command: ``` kubectl get sa -l=dev.okteto.com/external-id= -o=jsonpath='{.items[0].metadata.labels.dev\.okteto\.com/token}' ``` --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Configure the Okteto Wildcard Certificate By default, Okteto will create a self-signed wildcard certificate for your cluster. This certificate is used to secure communication to the Okteto UI, the build service, the registry service, and to all the applications that use [Automatic SSL Endpoints](/docs/core/endpoints/automatic-ssl.md). In a production environment, you should use your own certificates rather than let Okteto create a self-signed wildcard certificate for you. You can configure your wildcard certificate using any of the following approaches: * [Cert-manager and Let’s Encrypt](/docs/self-hosted/install/certificates/cert-manager.md) * [Amazon Certificate Manager](/docs/self-hosted/install/certificates/aws-acm.md) * [Bring your own certificate](/docs/self-hosted/install/certificates/bring-your-own-certificate.md) If you cannot use wildcard certificates, our community maintains a guide to explain [how to install Okteto without a wildcard certificate](https://community.okteto.com/t/how-do-i-install-okteto-without-a-wildcard-certificate/796). --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Setting up certificates with AWS ACM This guide will walk you through the process of setting certificates issued by or imported into Amazon Certificate Manager. ## Requirements Before you start, make sure you have the following CLI installed in your machine: * `aws` >= 2.15 ([aws installation guides](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions)) You'll also need to install the Load Balancer Controller in your Kubernetes cluster. If you haven't done it yet, follow our guide to [create the Load Balancer Controller IAM Role](/docs/get-started/install/amazon-eks.md#create-load-balancer-controller-iam-role) and [deploy the Load Balancer Controller](/docs/get-started/install/amazon-eks.md#deploy-load-balancer-controller) to your Kubernetes cluster. note If you don't install the Load Balancer Controller, you will need to setup the ALPN policy to HTTP2Preferred in the AWS NLB TLS listener at port 443. ## Setting up environment variables We recommend configuring the following environment variables to help you scripting the certificate configuration: The [Okteto Domain](/docs/get-started/install/amazon-eks.md#a-domain-and-the-ability-to-create-wildcard-dns-records-for-it) used in your Okteto installation: ``` export OKTETO_DOMAIN="<>" ``` Your AWS Region: ``` export AWS_REGION="$(aws configure get region)" ``` Disable AWS CLI pagination (optional): ``` export AWS_PAGER="" ``` ## Create an AWS Route 53 DNS Zone Okteto uses a DNS zone for both its internal endpoints (e.g., registry, kubernetes, buildkit) and also your application endpoints. Create a DNS zone with the following command: ``` aws route53 create-hosted-zone \ --name="${OKTETO_DOMAIN}" \ --caller-reference="$(date +%s)" ``` From the output, take note of the following properties: * `HostedZone.Id`, set it as the value of the following environment variable: ``` export HOSTED_ZONE_ID="<>" ``` * `DelegationSet.Nameservers[]`, use them to delegate the DNS zone from your domain nameservers. tip You can recover the nameservers of your DNS zone with the following command: ``` aws route53 get-hosted-zone --id="${HOSTED_ZONE_ID}" ``` ## Request a Certificate Using AWS ACM with DNS Validation Okteto requires a wildcard certificate that matches its DNS zone. Request a certificate with the following command: ``` aws acm request-certificate \ --domain-name="*.${OKTETO_DOMAIN}" \ --validation-method="DNS" \ --region="${AWS_REGION}" ``` From the output, take note of the following property: * `CertificateArn`, it identifies the certificate for usage in AWS integrated services. ``` export CERTIFICATE_ARN="<>" ``` ## Publish the Validation Records to the DNS Zone warning Before continuing, ensure that the DNS zone you created is authoritative and correctly delegated from your main domain First, get the validation records with the following command: ``` aws acm describe-certificate \ --certificate-arn="${CERTIFICATE_ARN}" \ --region="${AWS_REGION}" \ --query='Certificate.DomainValidationOptions[0].ResourceRecord' ``` Create a change batch file and replace the values highlighted: resource-record.json ``` { "Comment": "Add a CNAME record for foo to point to bar.com", "Changes": [ { "Action": "CREATE", "ResourceRecordSet": { "Name": "REPLACE ME WITH RESOURCE RECORD NAME", "Type": "CNAME", "TTL": 300, "ResourceRecords": [ { "Value": "REPLACE ME WITH RESOURCE RECORD VALUE" } ] } } ] } ``` Publish the validation records: ``` aws route53 change-resource-record-sets \ --hosted-zone-id="${HOSTED_ZONE_ID}" \ --change-batch=file://resource-record.json ``` Watch the status of the validation: ``` aws acm describe-certificate \ --certificate-arn="${CERTIFICATE_ARN}" \ --region="${AWS_REGION}" \ --query='Certificate.DomainValidationOptions[0].ValidationStatus' ``` It will eventually change from `PENDING_VALIDATION` to `SUCCESS`. tip You can wait until your certificate is validated with the following command: ``` aws acm wait certificate-validated \ --certificate-arn="${CERTIFICATE_ARN}" \ --region="${AWS_REGION}" ``` It internally polls the AWS API every 60 seconds. It will exit with a 255 exit code after 40 failed attempts. ## Configure Okteto to use your ACM Certificate Apply the following snippet to your Okteto Helm configuration file and replace the highlighted value: config.yaml ``` ingress-nginx: controller: service: annotations: service.beta.kubernetes.io/aws-load-balancer-type: "nlb" service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "ssl" service.beta.kubernetes.io/aws-load-balancer-ssl-cert: "<>" service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "https" service.beta.kubernetes.io/aws-load-balancer-scheme: "internet-facing" service.beta.kubernetes.io/aws-load-balancer-alpn-policy: "HTTP2Preferred" ``` Finally, [upgrade your Okteto instance](/docs/self-hosted/manage/upgrade.md) 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. note If you didn't install the Load Balancer Controller, you will need to setup the ALPN policy to HTTP2Preferred in the AWS NLB TLS listener at port 443. [Use the official AWS Docs](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/listener-update-certificates.html#update-alpn-policy) for instructions on how to do this using the console or through the AWS CLI. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # 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`. Import the secret into your kubernetes cluster by running the command below: ``` kubectl create secret tls ${CERT_NAME} --key ${KEY_FILE} --cert ${CERT_FILE} --namespace okteto ``` Where `CERT_NAME` is `your-ssl-certificate-secret`. After you create the secret, add the following to your Helm configuration file to tell Okteto and NGINX to use your certificate. config.yaml ``` wildcardCertificate: create: false name: your-ssl-certificate-secret ingress-nginx: controller: extraArgs: 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. 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](/docs/self-hosted/manage/upgrade.md) your Okteto installation for the new configuration to be applied. info If [`publicOverride`](/docs/self-hosted/helm-configuration.md#publicoverride) is set, its value must also be included in the certificate's `Subject Alternative Name` list. For example, if you use `dev.example.com` as the `publicOverride`, and `okteto.net` as the `subdomain`, you need to generate a certificate that includes `*.okteto.net` and `dev.example.com` in the `Subject Alternative Name` list. # Bring your own Certificate Authority By default, Okteto will trust a certificate issued by any well-know certificate authority. If your certificate is self-signed, issued by a new certificate authority, or issued by a private certificate authority, you'll need to import your certificate authority's public key. First import your certificate authority by running the command below: ``` kubectl create secret generic ${CA_NAME} --from-file=ca.crt=${CA_FILE} --namespace okteto ``` Where `CA_NAME` is your `your-ca-secret`. After you create the secret, add the following to your Helm configuration file to tell Okteto to use your certificate authority: config.yaml ``` wildcardCertificate: create: false name: your-ssl-certificate-secret privateCA: enabled: true secret: name: your-ca-secret key: ca.crt ingress-nginx: controller: extraArgs: default-ssl-certificate: $(POD_NAMESPACE)/your-ssl-certificate-secret ``` Finally, [upgrade your Okteto instance](/docs/self-hosted/manage/upgrade.md) 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. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # 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) This video tutorial walks through configuring certificates for Okteto using cert-manager and Let's Encrypt: [YouTube video player](https://www.youtube.com/embed/sqfgttiZ24o) --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # 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 | 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](/docs/self-hosted/install/divert/istio-installation.md) 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](/docs/self-hosted/install/divert/linkerd-installation.md) 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](/docs/self-hosted/install/divert/linkerd-installation.md) 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](/docs/self-hosted/install/divert/istio-installation.md) 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 ``` deploy: commands: - helm upgrade --install myservice chart divert: driver: nginx # Optional, this is the default namespace: staging ``` ### istio Driver Example ``` 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: ``` 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](/docs/self-hosted/helm-configuration.md#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](/docs/self-hosted/install/divert/linkerd-installation.md)** - Enhanced routing with Linkerd (nginx driver only) * **[Istio Installation](/docs/self-hosted/install/divert/istio-installation.md)** - Full Istio setup guide (istio driver) * **[Using Divert](/docs/development/using-divert.md)** - Developer implementation guide * **[Divert Tutorial](/docs/tutorials/divert.md)** - Getting started guide for developers * **[Core Concepts](/docs/core/divert.md)** - Understanding Divert architecture --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Istio Installation for Divert 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. 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](/docs/self-hosted/install/divert.md) 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). 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: ``` # 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: ``` helm upgrade okteto okteto/okteto -f values.yaml ``` ## Install Istio 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 ``` 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: ``` export OKTETO_DOMAIN=okteto.example.com ``` ### Step 3: Install Istio Base (CRDs) ``` helm install --namespace istio-system --create-namespace istio-base istio/base --wait ``` ### Step 4: Prepare the Istio Ingress Namespace ``` 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: ``` 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: ``` 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: ``` 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: ``` 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: ``` 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): ``` envsubst < istio-ingress-config.yaml | kubectl apply -n istio-ingress -f - ``` ### Step 8: Verify Installation Check that all Istio components are running: ``` 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: ``` networkPolicies: enabled: true ingress: - from: - namespaceSelector: matchLabels: dev.okteto.com/okteto-managed: "true" ``` tip For complete network policy options, see the [Helm Configuration reference](/docs/self-hosted/helm-configuration.md#networkpolicies). ## Troubleshooting ### Sidecar Not Injected 1. Verify the namespace has the Istio injection label: ``` kubectl get namespace --show-labels ``` 2. Restart deployments to inject sidecars: ``` kubectl rollout restart deployment -n ``` 3. Verify sidecar containers are present: ``` 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: ``` 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: ``` kubectl exec -it -- curl -H "baggage: okteto-divert=" http://service/path ``` 4. Check Istio proxy logs: ``` kubectl logs -c istio-proxy -n ``` ### Ingress Not Working 1. Verify the `istio-ingress-config.yaml` was applied correctly: ``` 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: ``` 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 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: ``` # 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: ``` okteto-nginx: enabled: true virtualServices: enabled: false namespace: labels: {} ``` Then upgrade Okteto: ``` helm upgrade okteto okteto/okteto -f values.yaml ``` ## Next Steps * **[Configure Divert](/docs/self-hosted/install/divert.md)** - Overview of Divert configuration * **[Using Divert](/docs/development/using-divert.md)** - 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 --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Linkerd Installation for Divert 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. 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](/docs/self-hosted/install/divert.md) 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 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: ``` # 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 ``` linkerd check --pre ``` Address any issues before proceeding. ### Step 3: Install Linkerd CRDs ``` linkerd install --crds | kubectl apply -f - ``` ### Step 4: Install Linkerd Control Plane ``` linkerd install | kubectl apply -f - ``` ### Step 5: Verify Installation ``` linkerd check ``` All checks should pass before continuing. ### Step 6: Install Linkerd Viz (Optional) For observability dashboards: ``` 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: ``` namespace: annotations: linkerd.io/inject: enabled ``` Upgrade your Okteto installation: ``` helm upgrade okteto okteto/okteto -f values.yaml ``` ### Existing Namespaces For existing namespaces, add the annotation: ``` kubectl annotate namespace linkerd.io/inject=enabled ``` Then restart deployments to inject sidecars: ``` 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: ``` 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: ``` networkPolicies: enabled: true ingress: - from: - namespaceSelector: matchLabels: dev.okteto.com/okteto-managed: "true" ``` tip For complete network policy options, see the [Helm Configuration reference](/docs/self-hosted/helm-configuration.md#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 ``` linkerd viz dashboard ``` Navigate to the namespace view to see: * Request rates per service * Success rates * Latency percentiles * Traffic flow between services ### CLI Monitoring ``` # 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: ``` kubectl get namespace -o jsonpath='{.metadata.annotations}' ``` 2. Check Linkerd injection status: ``` kubectl get pods -n -o jsonpath='{.items[*].spec.containers[*].name}' ``` 3. Restart deployments: ``` 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: ``` 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: ``` kubectl exec -it -- curl -H "baggage: okteto-divert=" http://service/path ``` ## Uninstalling Linkerd If you need to remove Linkerd: ``` # 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](/docs/self-hosted/install/divert.md)** - Overview of Divert configuration * **[Using Divert](/docs/development/using-divert.md)** - Developer implementation guide * **[Linkerd Documentation](https://linkerd.io/2/overview/)** - Official Linkerd docs --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # GitHub integration You can configure Okteto to use a GitHub App to give your developers access to private GitHub repositories. There are several reasons for considering this approach including: * Your users can select a repo from a list, instead of having to type the full repository URL. * Give everyone on your cluster read-only access to private repositories. * Control access to Okteto and the repositories at the Organization level, or per repository. * The pipelines use an app-scoped token, instead of a shared ssh key. ## Configuration Steps Setting up the GitHub integration requires several steps in both GitHub and your Okteto instance. Complete the following steps in GitHub: 1. [Create the GitHub Application](#creating-the-github-app) 2. [Generate a private key for the GitHub App](#generating-a-private-key-for-the-github-app) Complete the following steps in your Okteto Self-Hosted instance: 1. [Adding the GitHub App Configuration to Okteto](#adding-the-github-app-configuration-to-okteto) 2. [Verify your installation](#verifying-your-installation) Once this configuration has been completed, your instance of Okteto will use the GitHub Application you authenticate during the clone repository step of any Okteto pipelines. ### Creating the GitHub App 1. In the upper-right corner of any page in GitHub, select your `profile icon > Organizations`. 2. Click on the `settings` of the organization you want to use to create the application. 3. In the left navigation, select `Developer settings > GitHub Apps`. 4. Select `New GitHub App`. 5. Complete the following fields as follows: * `GitHub App Name:` enter an appropriate name for your application (e.g. `okteto-$YOUR_GITHUB_ORGANIZATION`) * `Homepage URL:` * `Callback URL:` (Necessary if you are going to use GitHub as your auth provider) 6. Uncheck the `Expire user authorization tokens` option. 7. Check the `Request user authorization (OAuth) during installation` option. 8. On the `Post Installation` section, check the `Redirect on update` option. 9. On the `Webhook` section, uncheck the `Active` option. 10. On the `Repository permissions` section, set the `Contents` permission to `Read-only`. 11. On the `Organization permissions` section, set the `Members` permission to `Read-only`. 12. On the `Account permissions` section, set the `Email addresses` permission to `Read-only`. 13. On the `Where can this GitHub App be installed?` section, select the `Any account` option. This will allow your users to install the application in their own GitHub account and deploy personal repositories in your Okteto instance. 14. Press the `Create GitHub App` button. 15. On the next screen, copy the values of `App Id` and `Client Id`, you'll need to pass those to your Okteto instance in a future step. > See [Creating a GitHub App](https://docs.github.com/en/developers/apps/building-github-apps/creating-a-github-app) for more information on creating a GitHub App from GitHub’s Developer guide. ### Generating a private key for the GitHub App After you have created the GitHub App, you will need to generate a private key for authenticating to the GitHub App. To generate a private key authenticating to the GitHub App: 1. In the upper-right corner of any page in GitHub, select your `profile icon > Organizations`. 2. Click on the `settings` of the organization you want to use to create the application. 3. In the left navigation, select `Developer settings > GitHub Apps`. 4. Select the GitHub App. 5. On the `Client secrets` section, press the `Generate a new client secret` button. Copy the value and save it in a safe place, since it won't be displayed again. You'll need to pass those to your Okteto instance in a future step. 6. On the `Private keys` section (it's at the bottom of the page), press the `Generate a private key` button. A file with the private key will be saved in your computer. ### Adding the GitHub App Configuration to Okteto Add the values we generated in the previous steps to your existing Helm configuration file: ``` github: enabled: true appId: "${YOUR_APP_ID}" clientId: ${YOUR_CLIENT_ID} clientSecret: ${YOUR_CLIENT_SECRET} installationUrl: https://github.com/apps/${YOUR_GITHUB_APP_NAME}/installations/new appPrivateKey: | -----BEGIN RSA PRIVATE KEY----- ...... ..... -----END RSA PRIVATE KEY----- ``` > You can also [use a secret](/docs/self-hosted/helm-configuration.md#store-sensitive-configuration-values-using-a-secret) to store the clientSecret and the appPrivateKey. * `clientID` and `clientSecret` refers to the values of the GitHub App you just created. * `appPrivateKey` is the private key you generated. > You can also use the appId and clientId values of your GitHub application in the `auth.github` section of your Helm configuration file if you're using GitHub as your [authentication provider](/docs/self-hosted/install/auth/github.md). Once you have updated your Helm configuration file, run the following command to reconfigure your Okteto instance: ``` helm upgrade okteto okteto/okteto -f config.yaml --namespace=okteto ``` If you're doing this as part of a fresh install, then run the following command: ``` helm install okteto okteto/okteto -f config.yaml --namespace=okteto ``` ### Verifying your installation If the installation was successful, you should now see a `GitHub` option in the `Deploy from Git` dialog. ![verify your installation](/docs/assets/images/verify-installation+1.46-eec6b33544971241fc4fceb2c147a3bb.jpg) When you click on it, you should see the list of repositories that you added in the previous step. [This document](/docs/development/deploy/from-private-repositories.md) has further information on how to deploy a private repository. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Configure the Okteto Registry with external storage Okteto supports different storage drivers to store the images inside the [Okteto Registry](/docs/core/container-registry.md): * [Filesystem](/docs/self-hosted/install/okteto-registry-storage/filesystem.md) * [Amazon S3 Bucket](/docs/self-hosted/install/okteto-registry-storage/aws-s3-bucket.md) * [Azure Storage Container](/docs/self-hosted/install/okteto-registry-storage/azure-storage-container.md) * [DigitalOcean Spaces](/docs/self-hosted/install/okteto-registry-storage/digitalocean-spaces.md) * [Google Cloud Storage](/docs/self-hosted/install/okteto-registry-storage/google-cloud-storage.md) Check out our video tutorial on how to configure a persistent storage for your Okteto installation: [YouTube video player](https://www.youtube.com/embed/eaKc05Qzlvw) --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto Registry with Amazon S3 Bucket This guide will walk you through the process of setting up the Okteto Registry with S3 storage to store your container images. ## Requirements Before you start, make sure you have the following CLI installed in your machine: * `eksctl` >= 0.171 ([eksctl installation guides](https://eksctl.io/installation/)) * `aws` >= 2.15 ([aws installation guides](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions)) * `kubectl` >= 1.28 ([kubectl installation guides](https://kubernetes.io/docs/tasks/tools/#kubectl)) ## Setting up environment variables We recommend configuring the following environment variables to help you scripting the Okteto Registry configuration: Your Kubernetes cluster name: ``` export CLUSTER_NAME="okteto" ``` Your bucket name: ``` export BUCKET_NAME="${CLUSTER_NAME}-registry-bucket" ``` tip S3 bucket names must be globally unique. Ensure you select a unique name for your bucket. You may include a random string in the bucket name to guarantee its uniqueness. Your AWS Account ID: ``` export AWS_ACCOUNT_ID="$(aws sts get-caller-identity --query "Account" --output text)" ``` Your AWS Region: ``` export AWS_REGION="$(aws configure get region)" ``` Disable AWS CLI pagination (optional): ``` export AWS_PAGER="" ``` ## Create S3 Bucket Create your S3 bucket with the following command: ``` aws s3api create-bucket \ --bucket="${BUCKET_NAME}" \ --region="${AWS_REGION}" \ --create-bucket-configuration=LocationConstraint="${AWS_REGION}" ``` ## Create IAM Role Save the following IAM Policy definition to a file and update the `Resource` field to match your S3 bucket name: okteto-registry-iam-policy.json ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:ListBucket", "s3:GetBucketLocation", "s3:ListBucketMultipartUploads" ], "Resource": "arn:aws:s3:::REPLACE-ME-WITH-YOUR-BUCKET-NAME" }, { "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject", "s3:DeleteObject", "s3:ListMultipartUploadParts", "s3:AbortMultipartUpload" ], "Resource": "arn:aws:s3:::REPLACE-ME-WITH-YOUR-BUCKET-NAME/*" } ] } ``` note The IAM policy is maintained by the `distribution/distribution` project. You can find the latest version of the policy [here](https://distribution.github.io/distribution/storage-drivers/s3/#s3-permission-scopes). Create the IAM Policy with the following command: ``` aws iam create-policy \ --policy-name="${CLUSTER_NAME}-okteto-registry-policy" \ --policy-document="file://okteto-registry-iam-policy.json" ``` Configure your Kubernetes context to the cluster where Okteto is installed and get the Okteto Registry service account name with the following command: ``` export OKTETO_REGISTRY_SERVICE_ACCOUNT_NAME="$(kubectl get sa -n=okteto -l=app.kubernetes.io/component=registry -o=jsonpath='{.items[0].metadata.name}')" ``` Create the IAM Role with the following command: ``` eksctl create iamserviceaccount \ --region="${AWS_REGION}" \ --name="${OKTETO_REGISTRY_SERVICE_ACCOUNT_NAME}" \ --namespace="okteto" \ --cluster="${CLUSTER_NAME}" \ --role-name="${CLUSTER_NAME}-okteto-registry-role" \ --role-only \ --attach-policy-arn="arn:aws:iam::${AWS_ACCOUNT_ID}:policy/${CLUSTER_NAME}-okteto-registry-policy" \ --approve ``` ## Configure Okteto to use your IAM Role Set the IAM Role ARN with the following command: ``` export ROLE_ARN="arn:aws:iam::${AWS_ACCOUNT_ID}:role/${CLUSTER_NAME}-okteto-registry-role" ``` Apply the following snippet to your Okteto Helm configuration file and replace the highlighted values: config.yaml ``` registry: storage: provider: aws: enabled: true bucket: "REPLACE ME WITH YOUR BUCKET NAME" region: "REPLACE ME WITH YOUR AWS REGION" iam: enabled: false serviceAccount: annotations: eks.amazonaws.com/role-arn: "REPLACE_ME_WITH_YOUR_ROLE_ARN" ``` Finally, [upgrade your Okteto instance](/docs/self-hosted/manage/upgrade.md) 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. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto Registry with Azure Storage Container This guide will walk you through the process of setting up the Okteto Registry with Azure Storage Container to store your container images. In this guide, `<>` refers to a storage account access key with read/write permissions to the storage container you want to use for the Okteto Registry. Create a secret with the value of `<>` using the command below: ``` kubectl create secret generic okteto-registry-secret --namespace=okteto --from-literal=secretKey=<> ``` Then, add the following configuration to your Okteto Helm configuration file: config.yaml ``` registry: storage: provider: azure: enabled: true storage: container: <> accountName: <> ``` Finally, [upgrade your Okteto instance](/docs/self-hosted/manage/upgrade.md) 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. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto Registry with DigitalOcean Spaces This guide will walk you through the process of setting up the Okteto Registry with DigitalOcean Spaces to store your container images. In this guide, `<>` refers to the access key of the storage space you want to use for the Okteto Registry. Create a secret with the value of `<>` using the command below: ``` kubectl create secret generic okteto-registry-secret --namespace=okteto --from-literal=secretKey=<> ``` Then, add the following configuration to your Okteto Helm configuration file: config.yaml ``` registry: storage: provider: digitalocean: enabled: true space: name: <> accessKeyID: <> ``` Finally, [upgrade your Okteto instance](/docs/self-hosted/manage/upgrade.md) 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. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto Registry with Filesystem storage This guide will walk you through the process of setting up the Okteto Registry with filesystem persistency to store your container images. Filesystem storage might limit your ability to scale up the registry, depending on the type of storage you are using. In your Helm configuration file, set `filesystem.enabled` to true if you want to store the images in the container filesystem. Additionally, set `filesystem.persistence.enabled` to true if you want to store the images in a PVC attached to the Okteto Registry. You can also customize the `storageClass` (optional), the `size` of the volume (defaults to 40Gi), or attach a pre-existing persistent volume claim via `claimName`. config.yaml ``` registry: storage: filesystem: enabled: true persistence: enabled: true claimName: "" accessMode: ReadWriteOnce storageClass: "" size: 40Gi ``` Finally, [upgrade your Okteto instance](/docs/self-hosted/manage/upgrade.md) 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. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto Registry with Google Cloud Storage This guide will walk you through the process of setting up the Okteto Registry with Google Cloud Storage to store your container images. The first step is creating a Cloud Storage bucket in GCP. You can follow the steps mentioned [here](https://cloud.google.com/storage/docs/creating-buckets) to do that. It is okay to proceed with the default settings. Just make sure that your bucket does not have public access enabled. Next, create a service account, for example "", with access to you to your bucket. Then run the following command to grant the `okteto-registry` Kubernetes service account the ability to impersonate the Google Cloud service account that we just created using Workload Identity. By binding the `roles/iam.workloadIdentityUser` role, the Kubernetes service account can authenticate as the Google Cloud service account, allowing it to securely access the Cloud Storage bucket without needing to manage long-lived service account keys: ``` gcloud iam service-accounts add-iam-policy-binding \ GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com \ --role roles/iam.workloadIdentityUser \ --member "serviceAccount:$GCP_PROJECT.svc.id.goog[okteto/okteto-registry]" \ --project $GCP_PROJECT ``` Important: Make sure you have [Workload Identity enabled](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#option_2_node_pool_modification) in your cluster for this to work. Workload Identity in Google Kubernetes Engine (GKE), allows for seamless and secure communication between Kubernetes workloads and Google Cloud services. After this, configure the Okteto Registry with a workload ID in your Okteto Helm configuration file: config.yaml ``` registry: storage: provider: gcp: enabled: true bucket: <> project: <> workloadIdentity: enabled: true serviceAccount: annotations: iam.gke.io/gcp-service-account: "GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com" ``` Finally, [upgrade your Okteto instance](/docs/self-hosted/manage/upgrade.md) 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. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Volume Snapshots for Self-Hosted Okteto 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`. ### CSI driver installation 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 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. Follow your vendor's installation instructions for driver-specific setup details. ### VolumeSnapshotClass Create a `VolumeSnapshotClass` in your cluster to determine the CSI driver and `deletionPolicy` for your `VolumeSnapshots`. The following manifest is an example of a VolumeSnapshotClass: * Amazon EBS * GCE Persistent Disk * DigitalOcean Block Storage ``` # okteto-snapshot-class.yaml apiVersion: snapshot.storage.k8s.io/v1 kind: VolumeSnapshotClass metadata: name: okteto-snapshot-class driver: ebs.csi.aws.com deletionPolicy: Delete ``` ``` # okteto-snapshot-class.yaml apiVersion: snapshot.storage.k8s.io/v1 kind: VolumeSnapshotClass metadata: name: okteto-snapshot-class driver: pd.csi.storage.gke.io deletionPolicy: Delete ``` ``` # okteto-snapshot-class.yaml apiVersion: snapshot.storage.k8s.io/v1 kind: VolumeSnapshotClass metadata: name: okteto-snapshot-class driver: dobs.csi.digitalocean.com deletionPolicy: Delete ``` To create the `VolumeSnapshotClass`, run the following command after creating the file: ``` kubectl apply -f okteto-snapshot-class.yaml ``` ### StorageClass (optional) Optionally, you can also create a storage class. Okteto uses this storage class when creating the volumes. * Amazon EBS * GCE Persistent Disk * DigitalOcean Block Storage ``` # okteto-snapshot-sc.yaml kind: StorageClass apiVersion: storage.k8s.io/v1 metadata: name: okteto-snapshot-sc provisioner: ebs.csi.aws.com reclaimPolicy: Delete volumeBindingMode: WaitForFirstConsumer ``` ``` # okteto-snapshot-sc.yaml kind: StorageClass apiVersion: storage.k8s.io/v1 metadata: name: okteto-snapshot-sc provisioner: pd.csi.storage.gke.io parameters: type: pd-standard reclaimPolicy: Delete volumeBindingMode: WaitForFirstConsumer ``` ``` # okteto-snapshot-sc.yaml kind: StorageClass apiVersion: storage.k8s.io/v1 metadata: name: okteto-snapshot-sc provisioner: dobs.csi.digitalocean.com reclaimPolicy: Delete volumeBindingMode: WaitForFirstConsumer ``` To create the `StorageClass`, run the following command after creating the file: ``` 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. See the [Volume Snapshots Helm configuration](/docs/self-hosted/helm-configuration.md#volumesnapshots) for all available settings. * Amazon EBS * GCE Persistent Disk * DigitalOcean Block Storage ``` volumeSnapshots: enabled: true driver: ebs.csi.aws.com class: okteto-snapshot-class storageClass: okteto-snapshot-sc ``` ``` volumeSnapshots: enabled: true driver: pd.csi.storage.gke.io class: okteto-snapshot-class storageClass: okteto-snapshot-sc ``` ``` volumeSnapshots: enabled: true driver: dobs.csi.digitalocean.com class: okteto-snapshot-class storageClass: okteto-snapshot-sc ``` 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 Follow [this guide](/docs/core/use-volume-snapshots.md#using-volume-snapshots-in-your-development-environment) to use Volume Snapshots in your development environment. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Air-Gapped Network EnvironmentsEnterpriseSelf-Hosted Okteto Enterprise can be installed in air-gapped environments—isolated networks without internet access. This guide explains how to install, configure and use a self-hosted Okteto instance entirely offline. For personalized assistance, feel free to [talk to us](https://www.okteto.com/contact/) to guide you during the installation. ## Step 1: Disable Okteto Telemetry By default, Okteto sends [telemetry data](/docs/self-hosted/helm-configuration.md#telemetry) to help us understand usage patterns and prioritize improvements. In air-gapped environments, you can disable telemetry by adding the following to your Okteto Helm configuration: ``` telemetry: enabled: false ``` Disabling telemetry ensures that no usage analytics are sent from the Okteto CLI. ## Step 2: Set Up a Private Registry for Required Images By default, all the images needed to deploy the Okteto Platform, and the images used by the Okteto CLI, are hosted in DockerHub. In air-gapped environments, you’ll need to host these images in your private registry. ### Push Images to your Private Registry For simplicity, we recommend using the same repository names and tags in your private registry. info Since Okteto doesn’t support `imagePullSecrets`, ensure your Kubernetes cluster is pre-configured to access your private registry. **Required Images for Okteto Platform Installation** Push the following images to your private registry for the Okteto Chart installation: * **ghcr.io/okteto/backend:1.46.0** * **ghcr.io/okteto/frontend:1.46.0** * **ghcr.io/okteto/buildkit:1.46.0** or **ghcr.io/okteto/buildkit:1.46.0-rootless** * **ghcr.io/okteto/registry:1.46.0** * **ghcr.io/okteto/pipeline-runner:1.46.0** or **ghcr.io/okteto/pipeline-runner:1.46.0-rootless** * **ghcr.io/okteto/daemon:1.46.0** * **ghcr.io/okteto/agent:1.46.0** * **ghcr.io/okteto/ingress-nginx-chroot:1.46.0** * **ghcr.io/okteto/reloader:1.46.0** * **ghcr.io/okteto/redis:1.46.0** For each Okteto CLI version, push the following images to your private registry: * **ghcr.io/okteto/okteto:3.21.0** info For Okteto Chart 1.46.0, we recommend enforcing the usage of Okteto CLI 3.21.0 in your developer's machines to reduce maintenance overhead ## Step 3: Update Helm Configuration These configurations ensure Okteto can pull required images from your private registry during deployment. Once your images are pushed to your private registry, update your Okteto Helm configuration as follows: **Example Registry URL:**
Replace`<>` with the hostname or IP address of your private registry. It should look something like this: `my-registry.example.com:5000` Ensure it is accessible within your air-gapped environment and uses the correct protocol (https) and port. ``` globals: registry: <> cli: image: registry: <> ingress-nginx: controller: image: registry: <> okteto-nginx: controller: image: registry: <> reloader: global: imageRegistry: <> ``` ## Step 4: Install or Upgrade Okteto Run the following command to install Okteto for the first time or to upgrade an existing instance: ``` helm upgrade --install okteto okteto/okteto -f config.yaml --namespace=okteto --create-namespace --version=1.46.0 ``` ## Step 5: Install the Okteto CLI The Okteto CLI needs to be installed on your own machine as well as on the machines of all developers on your team who will be using Okteto. #### Download the latest version of the Okteto CLI for your operating system: ``` https://github.com/okteto/okteto/releases/download/3.21.0 ``` * For Linux/MacOS, the binary is named `okteto` * For Windows, the binary is named `okteto.exe` #### Set Up the Okteto Configuration Directory Create a `.okteto` folder in your `$HOME` directory to store runtime configurations and dependencies for the CLI. ``` mkdir -p $HOME/.okteto ``` #### Download and Configure Syncthing Okteto uses [Syncthing](https://syncthing.net/) to synchronize files between your local machine and your remote Development Environments. Download the syncthing binary from their official releases page: ``` https://github.com/syncthing/syncthing/releases/tag/v2.1.1 ``` * Uncompress the downloaded file * Move the syncthing binary (or syncthing.exe for Windows) to your $HOME/.okteto folder #### Set Executable Permissions (Linux/MacOS only) Finally, if you are on Linux or MacOS, make sure to give executable permissions to both `okteto` and `syncthing`: ``` chmod +x okteto chmod +x $HOME/.okteto/syncthing ``` ### You are now ready to start using Okteto *Need help with your installation? [Contact us](https://www.okteto.com/contact/) for expert guidance.* note ### Browser Compatibility The Okteto Dashboard is supported on: * **Google Chrome**: Last 8 versions * **Mozilla Firefox**: Last 8 versions * **Microsoft Edge**: Last 8 versions * **Safari**: Last 2 major versions (macOS only) Ensure all users in an air-gapped setup have access to these browsers to avoid compatibility issues. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Configure Argo CD ## Deploy Okteto with an Argo CD Application In this guide, we'll learn how to deploy Okteto within an [Argo CD Application manifest](https://argo-cd.readthedocs.io/en/stable/user-guide/application-specification/). ## Set Up the Source Okteto Self Hosted is distributed as a [Helm Chart](https://helm.sh/docs/topics/charts/) that can be sourced from Okteto's official repository: ``` helm repo add okteto https://charts.okteto.com helm repo update ``` To configure it in the Argo CD manifest, you'll need to add it as a [Helm type source](https://argo-cd.readthedocs.io/en/stable/user-guide/helm/): ``` source: repoURL: 'https://charts.okteto.com' chart: 'okteto' targetRevision: '[LATEST RELEASE ex: 1.17.0]' helm: releaseName: 'okteto' ``` ## Set Up the Destination Now it is time to tell Okteto where it is going to live, specifically the cluster and namespace: ``` destination: server: 'https://kubernetes.default.svc' namespace: 'okteto' ``` ## Configure the Sync Policy The following [`syncOptions`](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-options/) are recommended for installing Okteto in Argo CD and keeping it in a healthy state: ``` syncPolicy: automated: prune: true selfHeal: true syncOptions: - 'RespectIgnoreDifferences=true' - 'PruneLast=true' - 'CreateNamespace=true' - 'ApplyOutOfSyncOnly=true' ``` * `syncPolicy.automated` * `prune`: There are some objects created by Okteto whose names contain a hash derived from the configuration, so when it changes, Argo CD detects objects that no longer belong to the chart and that should be pruned. This option performs this task automatically. Otherwise, you'll need to manually set the "Prune" checkbox (or set the [operation](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-kubectl/#prune) to "prune") when performing a manual sync. * `selfHeal`: This option will keep manifests consistent with the desired state and will recreate Okteto configuration in case it is deleted or modified externally by accident. * `syncPolicy.syncOptions` * `'RespectIgnoreDifferences=true'`: This option ensures sync operations respect the indications set in the ["Configure the ignore differences"](#configure-ignore-differences). * `'PruneLast=true'`: Ensure that pruning takes place after syncing Okteto to the desired state. * `'CreateNamespace=true'`: Optionally let Argo CD auto-create the namespace set in the ["Set Up the Destination"](#set-up-the-destination) section. * `'ApplyOutOfSyncOnly=true'`: Okteto chart makes use of Helm templating to render some configurations dynamically such as internal certificates and private keys. Leaving this option enabled ensures those don't get recreated unnecessarily. ## Configure Ignore Differences Some Okteto resources are rendered via Helm templating functions that need access to the cluster's previous state. This is not possible in Argo CD; therefore, the following [`ignoreDifferences`](https://argo-cd.readthedocs.io/en/stable/user-guide/diffing/) must be configured: ``` ignoreDifferences: # TLS secrets generated by Okteto - kind: 'Secret' jsonPointers: - '/data/ca.crt' - '/data/tls.crt' - '/data/tls.key' - '/stringData/ca.crt' - '/stringData/tls.crt' - '/stringData/tls.key' # Mutation webhook cabundles patched by Okteto - group: 'admissionregistration.k8s.io' kind: 'MutatingWebhookConfiguration' jqPathExpressions: - '.webhooks[].clientConfig.caBundle' # Validation webhook cabundles patched by Okteto - group: 'admissionregistration.k8s.io' kind: 'ValidatingWebhookConfiguration' 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' jsonPointers: - '/metadata/labels/app' - '/metadata/labels/app.kubernetes.io~1instance' - '/metadata/labels/chart' - '/metadata/labels/heritage' - '/metadata/labels/release' # Internal service account managed by Okteto - kind: 'ServiceAccount' name: 'okteto-admin' jsonPointers: - '/metadata/labels/app' - '/metadata/labels/app.kubernetes.io~1instance' - '/metadata/labels/chart' - '/metadata/labels/heritage' - '/metadata/labels/release' # Annotations for restarting internal components - group: 'apps' kind: 'DaemonSet' jsonPointers: - '/spec/template/metadata/annotations/checksum~1certs' - group: 'apps' kind: 'Deployment' jsonPointers: - '/spec/template/metadata/annotations/checksum~1secrets' ``` ## Caveats * Changes to any part of the configuration will cause orphan resources to appear, which can be safely pruned automatically or manually by Argo CD. These resources are: * `clustermetrics-` job * `migration-` job * Changes to the following specific paths of the configuration may cause a small outage while syncing/applying: * `.Values.webhook.internalCertificate.annotations` will cause the webhooks registered by Okteto to recreate their certificates. * `.Values.wildcardCertificate.annotations` if `.Values.wildcardCertificate.create == true` will cause the self-signed certificates used for external access to recreate them. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # 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`: ``` 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: ``` 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](/docs/get-started/install/google-gke.md). ## Amazon EKS (Beta) 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 ``` eksctl create cluster -f - < **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Backup and Restore This guide outlines the steps to recover an Okteto instance in the event of an unexpected failure and for disaster recovery preparedness. ## Okteto Metadata The most important resources to backup so you can effectively recover an Okteto instance are: * **Service Accounts**: A Kubernetes service account is created for every user that logs in to Okteto. Backing up all the service accounts in the `okteto` namespace with the label `dev.okteto.com: "true"` will ensure your users do not need to recreate their Okteto accounts. * **Secrets**: Kubernetes secrets store Okteto variables, tokens, certificates, ssh keypairs, and any other secrets in the `okteto` namespace. Backing up secrets will save a lot of time reconfiguring all of these during a recovery process. * **Custom Resources**: Any Custom Resources in the `okteto` namespace corresponding to the Okteto CRDs. These CRDs can be identified with the label `app.kubernetes.io/part-of: okteto`. Okteto uses CRDs to store your Catalog, Container Registry Credentials, and more We recommend to backup these resources every 24h. ## Recovery Process You can follow two different recovery processes: * **Okteto Metadata recovery process**: recovers all the users’ metadata, tokens, variables, secrets, and custom resources mentioned [in the section above](/docs/self-hosted/manage/backup.md#okteto-metadata). It doesn’t recover users’ namespaces, preview environments and volumes. * **Okteto Metadata and Users' Namespaces recovery process**: recovers the Okteto metadata, namespaces, preview environments, and volumes for all users. This is a full and complete recovery of the Okteto instance Namespaces are ephemeral in Okteto so we recommend using the `Okteto Metadata recovery process` and let your developers recreate their namespaces as needed. ### Okteto Metadata Recovery Process This is the fastest and easiest recovery process. This recovery process will **not** restore users' namespaces and application data. * Backup the [Okteto Metadata](/docs/self-hosted/manage/backup.md#okteto-metadata) in your `okteto` namespace. * Create a new cluster * Reinstall the Okteto Helm chart with the same configuration as your previous Okteto instance in the new cluster. * Restore the [Okteto Metadata](/docs/self-hosted/manage/backup.md#okteto-metadata) in the `okteto` namespace of the new cluster. * The Ingress-Nginx service in the new cluster will have a new load balancer. Configure your DNS settings to point to the IP of this new load balancer. * Once the restore work is complete and it has been verified that the new cluster is functioning correctly you can delete the old cluster ### Users and Namespaces Recovery This option requires more time and the use of external tools to backup all your namespaces: * Backup users' namespaces using a tool like [Velero](https://velero.io/). All these namespaces have the label `dev.okteto.com: "true"`. * Backup the [Okteto Metadata](/docs/self-hosted/manage/backup.md#okteto-metadata) in your `okteto` namespace. * Create a new cluster * Restore users' namespaces using a tool like [Velero](https://velero.io/) in the new cluster before reinstalling Okteto. * Reinstall the Okteto Helm chart with the same configuration as your previous Okteto instance in the new cluster. * Restore the [Okteto Metadata](/docs/self-hosted/manage/backup.md#okteto-metadata) in the `okteto` namespace of the new cluster. * The Ingress-Nginx service in the new cluster will have a new load balancer. Configure your DNS settings to point to the IP of this new load balancer. * Once the restore work is complete and it has been verified that the new cluster is functioning correctly you can delete the old cluster > Keep in mind that private registry configurations are not reestablished until the Helm chart is reinstalled. This may temporarily affect the ability of certain pods to pull images from the Okteto Registry. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Configuring BuildKit for High Performance Optimizing BuildKit performance is essential for a smooth development experience with Okteto. A high-performance BuildKit setup accelerates image builds, [test executions](/docs/testing.md), and deploy commands when using [Remote Execution](/docs/core/remote-execution.md). ## 1. Dedicated Node Pool for BuildKit BuildKit is resource-intensive. We recommend deploying BuildKit in a dedicated node pool for optimal performance and to minimize interference from other workloads. To deploy BuildKit on a dedicated build pool, you can add [taints and tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) to the BuildKit node pool in Kubernetes, and then add the following settings to your Okteto Helm configuration: ``` buildkit: nodeSelectors: okteto-node-pool: build tolerations: - effect: NoSchedule key: okteto-node-pool operator: Equal value: build ``` ## 2. Scale Vertically: Increase CPUs for Faster Builds BuildKit performance depends heavily on allocated CPU and memory resources. Start with 2 nodes for higher availability, with the following recommended instance types (4 CPUs and 16GB RAM): * Amazon Web Services: `m6a.xlarge` * Google Cloud Platform: `t2d-standard-4` * Microsoft Azure Cloud Platform: `Standard_D4as_v5` Set the replicaCount to match the number of nodes in the BuildKit node pool: ``` buildkit: replicaCount: 2 ``` Monitor performance and adjust node resources as needed. For instance, upgrading your BuildKit nodes to 8 CPUs and 32 GB of memory each can provide approximately a 2x performance improvement 😎. ## 3. Configure SSD Storage BuildKit is I/O intensive, especially for pulling, extracting, and pushing container images. Using a SSD storage class can significantly improve your BuildKit performance. ``` buildkit: persistence: enabled: true class: <> ``` You may also increase the size of the BuildKit cache to increase the number of BuildKit cache hits (default: 100 GB): ``` buildkit: persistence: enabled: true size: 200Gi ``` ## 4. Enable HPA to Optimize Performance and Costs Horizontal Pod Autoscaler (HPA) dynamically adjusts the number of BuildKit pods based on active build workloads. This ensures you have enough capacity during peak times while reducing costs during idle periods. Build Queue System and HPA The [Build Queue System](/docs/core/build-service.md#build-queue-system) distributes builds across BuildKit instances and queues builds when instances exceed resource thresholds. This keeps build performance consistent, but the Build Queue System does not scale BuildKit pods. Without HPA, you must choose between running fewer BuildKit instances (which queues more builds during peak usage, increasing wait times) or running many replicas at all times (which wastes resources during idle periods). HPA complements the Build Queue System by automatically adding and removing BuildKit pods based on demand — providing enough build capacity at peak times while reducing costs when demand is low. Okteto supports the following metrics for HPA scaling: * `okteto_build_active_builds` - Number of active builds (recommended) * `okteto_build_cpu_pressure` - CPU pressure in 10-second intervals * `okteto_build_memory_usage` - Memory usage as a percentage out of 100% * `okteto_build_io_pressure` - I/O pressure in 10-second intervals By default, HPA is configured to scale based on the `okteto_build_active_builds` metric, with the following settings: ``` buildkit: 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 ``` This configuration: * Scales up quickly (within 30 seconds) when build pressure increases * Scales down conservatively (pod by pod every 10 minutes) to avoid thrashing * Maintains between 1 and 5 BuildKit pods based on active builds Metrics Adapter Okteto includes a built-in metrics adapter that exposes BuildKit metrics via the `v1beta2.custom.metrics.k8s.io` API. This adapter is automatically deployed when HPA is enabled. 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 Even the best BuildKit setup cannot compensate for un-optimized Dockerfiles or inefficient [Remote Execution](/docs/core/remote-execution.md) configurations. To make the most of your BuildKit configuration, we have the following recommendations: * 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](/docs/core/remote-execution.md#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. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Custom Resource Definitions 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: ``` kubectl get crd | grep okteto.com ``` You can let Okteto install these CRDs or you can choose to install them manually, but be aware they are needed for Okteto to work properly. You can use the [following configuration setting](/docs/self-hosted/helm-configuration.md#crds) to let Okteto know if it should install them or not. By default, Okteto will install them. ## Private Registries Private registry configurations can be managed either through the [Admin dashboard](/docs/admin/dashboard.md#registry-credentials) or by using one of Okteto’s installed CRDs: `admin.okteto.com`. This last case is useful, for example, if you have your own mechanism to provision credentials/secrets in your cluster. There are 3 types of registries you can configure: Static credentials, AWS IAM User, and AWS IAM Role. ### Static Credentials To define your private registries with static credentials using CRDs, you must first create an [Opaque Kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/#creating-a-secret) containing the necessary data to access your private registry. This secret should include both the username and password for accessing the registry. Once the secret is created, you will need to create a resource with the `apiVersion`: `admin.okteto.com/v1` and `Registry` kind, which is one of the CRDs installed by Okteto, referring to the secret which contains the credentials. The name of this new resource should be the hostname of the registry (e.g. `index.docker.io`). For example, if you want to add a configuration for Docker's registry, you will need to create a resource like this: note Defining the port through `spec.static.port` is optional and only available for static registries. It should only be used if the registry listens on a port other than the default http(s) 80/443 ``` apiVersion: admin.okteto.com/v1 kind: Registry metadata: name: index.docker.io # hostname of the registry to be configured namespace: okteto spec: static: port: 5000 # optional passwordSecretRef: key: # key of the secret which contains the password name: # name of the secret where the password is stored userSecretRef: key: # key of the secret which contains the username name: # name of the secret where the username is stored ``` ### AWS IAM User In the case of AWS IAM User, where you have to specify the Access Key and Access Secret, the process is similar to the static credentials CRD. For AWS IAM User credentials (Access Key and Secret Access Key), the process is similar to configuring static credentials. First, create a secret containing the Access Key and Secret Access Key values. Then, create a CRD like this (the name of the resource has to be the hostname of the registry to be configured and it has to end with `.amazonaws.com`, e.g. `111122223333.dkr.ecr.eu-central-1.amazonaws.com`): ``` apiVersion: admin.okteto.com/v1 kind: Registry metadata: name: 111122223333.dkr.ecr.eu-central-1.amazonaws.com # hostname of the registry to be configured namespace: okteto spec: awsIamUser: accessKeyIDSecretRef: key: # key of the secret which contains the access key name: # name of the secret where the access key is stored secretAccessKeySecretRef: key: # key of the secret which contains the access secret key name: # name of the secret where the access secret is stored ``` You can find more information [here](/docs/admin/registry-credentials/amazon-ecr.md#using-iam-user-credentials) about how to obtain the values to use. ### AWS IAM Role In this case, the process is a bit simpler. It doesn't require a secret, as it doesn't store sensitive information. So, you will only need to create a CRD like the following one specifying the registry hostname as the resource name (it has to end with `.amazonaws.com`, e.g. `111122223333.dkr.ecr.eu-central-1.amazonaws.com`): ``` apiVersion: admin.okteto.com/v1 kind: Registry metadata: name: 111122223333.dkr.ecr.eu-central-1.amazonaws.com # hostname of the registry to be configured namespace: okteto spec: awsIamRole: audience: okteto.example.com/us-east-2 # Audience used to exchange token to access the registry roleARN: arn:aws:iam::112233445566:role/my-private-registry # ARN role with the permissions needed to access to the registry ``` You can find more information [here](/docs/admin/registry-credentials/amazon-ecr.md#using-iam-roles-via-openid-connect-oidc-federation) about how to obtain the values to use. ## Catalog Items Catalog items are typically managed via the [Admin dashboard](/docs/admin/catalog.md), but can also be managed via one of the CRDs installed by Okteto: `catalogitems.git.okteto.com`. This approach is useful if you want to add catalog items manually with kubectl commands or manage your catalog using GitOps. note If you add Catalog items 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. To configure a catalog item, create a resource like this: * `metadata.name`: name of the `CatalogItem` resource to be created * `spec.branch`: default branch for the CatalogItem. (optional) * `spec.manifestPath`: path to the manifest file in the repository (optional) * `spec.name`: Display name in the Catalog UI list * `spec.repositoryUrl`: URL of the repository * `spec.variables`: list of variables suggested to the user at deployment time. Each variable can be defined by name only, or by name and value (optional) my-catalog-item.yaml ``` apiVersion: git.okteto.com/v1 kind: CatalogItem metadata: name: my-catalog-item namespace: okteto spec: branch: "" manifestPath: "" name: my-catalog-item repositoryUrl: https://github.com/okteto/movies-with-helm variables: - name: VARIABLE_WITH_VALUE value: my-value - name: VARIABLE_WITHOUT_VALUE ``` To apply the changes manually, run the command `kubectl apply -f my-catalog-item.yaml` from your terminal to add the catalog item to the your Catalog in the cluster. ## Cloud Credentials Cloud Credentials are mainly managed via the [Admin dashboard](/docs/admin/dashboard.md#cloud-credentials), but can also be managed via one of the CRDs installed by Okteto: `dynamicconfigs.admin.okteto.com`. Using CRDs can be useful if you would like to add Cloud Credentials manually with a simple `kubectl` command or manage your Cloud Credentials using GitOps. note 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. For example, if you want to add a configuration for **GCP Cloud Credential**, you will need to create a resource like this: * `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`: 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. gcp-cloud-credential.yaml ``` apiVersion: admin.okteto.com/v1 kind: DynamicConfig metadata: name: gcp-credentials-config namespace: okteto spec: audience: projectNumber: providerId: workloadIdentityPoolId: ``` Alternatively, if you would like to add a configuration for **AWS Cloud Credentials**, you will need to create a resource like this: * `metadata.name`: `aws-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.region`: This specifies the AWS region where the credentials will be used. It is a string that identifies the geographic area where AWS resources are located. * `spec.roleARN`: This is the Amazon Resource Name (ARN) of the IAM role that will be assumed. It uniquely identifies the role within AWS and is used to specify which role will be used to authenticate the credentials. aws-cloud-credential.yaml ``` apiVersion: admin.okteto.com/v1 kind: DynamicConfig metadata: name: aws-credentials-config namespace: okteto spec: audience: region: roleARN: ``` To apply the changes manually, run the command `kubectl apply -f aws-cloud-credential.yaml` from your terminal to add the catalog item to the your Cloud Credential to the cluster. note Each cloud provider credential configuration in Okteto must use a specific name: gcp-credentials-config for Google Cloud Platform and aws-credentials-config for Amazon Web Services. Only one credential configuration is allowed per provider, meaning you can define one for GCP and one for AWS, but no more than one for each. ## Okta User De-provisioning Okta user de-provisioning can be managed through the [Admin dashboard](/docs/admin/integrations/okta-user-deprovisioning.md), or via one of the CRDs installed by Okteto. This allows administrators to define deprovisioning policies declaratively, ensuring that users who are removed from Okta are also deactivated in Okteto automatically. ### 1. Create the Event Hook Token in Okta To start, **follow Step 1** in the [Okta User De-provisioning documentation](/docs/admin/integrations/okta-user-deprovisioning.md) to configure the event hook in Okta. When finished with Step 1, return here. ### 2. Create the Required Secret Next, you must create an [Opaque **Kubernetes secret**](https://kubernetes.io/docs/concepts/configuration/secret/#creating-a-secret) that contains the necessary configuration for Okta user de-provisioning. That secret should contain 2 keys with the information: * `eventsEnabled`: A boolean (`true` or `false`, base64-encoded) indicating whether Okta user de-provisioning is enabled * "true" → `dHJ1ZQ==` * "false" → `ZmFsc2U=` * `eventsAuthSecret`: The webhook authorization secret specified when configuring the event hook in Okta ``` apiVersion: v1 kind: Secret metadata: name: okta-deprovisioning-secret namespace: okteto type: Opaque data: eventsAuthSecret: eventsEnabled: ``` ### 3. Create the CRD Configuration Once the secret is created, define the Okta user de-provisioning CRD referencing the secret: ``` apiVersion: admin.okteto.com/v1 kind: DynamicConfig metadata: name: okta-config namespace: okteto secretRef: okta-deprovisioning-secret ``` * `secretRef` is the secret name created in the previous step ### 4. Apply the Configuration To apply the configuration run ``` kubectl apply -f okta-deprovisioning-secret.yaml kubectl apply -f okta-deprovisioning-crd.yaml ``` ### 5. Verify Okta Event Hook Integration 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. ## 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=` ``` 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: ``` apiVersion: admin.okteto.com/v1 kind: DynamicConfig metadata: name: ssh-known-hosts namespace: okteto secretRef: ssh-known-hosts-secret ``` ### 4. Apply the Configuration ``` 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. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Diagnostics Okteto provides a diagnostics tool through the [Replicated Troubleshoot](https://troubleshoot.sh) framework. This tool is completely optional but can help troubleshoot complex issues, specially if you are getting assistance through Okteto Support. Starting in Okteto 1.16, as part of the helm installation we deploy a `okteto-support-bundle` configmaps in the okteto namespace that contain the specs to create a support bundle. ## Installation The support-bundle provided by Replicated Troubleshoot is a client-side utility, packaged as a kubectl plugin and distributed through the [krew](https://github.com/kubernetes-sigs/krew/) package manager. Make sure to have it installed as per the [installation guide](https://krew.sigs.k8s.io/docs/user-guide/setup/install/) note Run `kubectl krew` to check the installation and make sure `krew` is in your $PATH as described in the installation guide Once krew is installed, you can install the `kubectl` plugin: ``` kubectl krew install support-bundle ``` More info about the installation [here](https://troubleshoot.sh/docs/#installation). # Support bundle Creates a gzipped tarball which includes cluster information, logs for okteto components, and other relevant information. This bundle can help troubleshoot issues with the cluster specially during an incident in which you are getting assistance from Okteto Support. ``` kubectl support-bundle \ --interactive=false \ --debug \ -n okteto \ --load-cluster-specs ``` The default file name for the bundle is `support-bundle-TIMESTAMP.tar.gz` but it can be overridden with `-o `. More info about the support bundle command, extra arguments, etc can be found here: --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # 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](/docs/admin/billing.md). ## When a license is required Okteto requires a license key to use any of our paid products: [BYOC and Self-Hosted](/docs/byoc-vs-self-hosted.md). 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](/docs/admin/billing.md). ## 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. 2. [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: ``` license: ABC123...XYZ456 ``` note You can also optionally include your Okteto license using [Cloud Secrets](/docs/self-hosted/helm-configuration.md#secret). After updating the license, [upgrade](/docs/self-hosted/manage/upgrade.md) your Okteto instance for the new license to take effect. ## Checking your seat usage Your current account count is visible in the [Admin Dashboard](/docs/admin/dashboard.md) and via the [Okteto API](/docs/admin/okteto-api.md). For the rules on what counts as a seat and how overages are handled, see [Billing](/docs/admin/billing.md). ## 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. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Troubleshoot your Okteto instance Welcome to the Okteto troubleshooting guide. This page provides answers to some common issues encountered while using Okteto. Please also review our [FAQ Guide](/docs/reference/faqs.md) 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](/docs/reference/okteto-cli.md#doctor) with the okteto logs for a given development container. ### For Administrators of Okteto: Please use our [Okteto Diagnostics tool](/docs/self-hosted/manage/diagnostics.md) 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](/docs/byoc/aws.md). 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](/docs/byoc/gcp.md). 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: ``` helm list -n okteto helm get values "okteto" -n okteto -o yaml ``` The following are sample outputs of the commands: * helm list * helm get values ``` ~ % 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 ``` ``` ~ % 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: ``` # 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: ``` # 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: ``` 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: * kubectl get all * kubectl get ingress,service * kubectl get cm,secret,pvc ``` ~ % 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 ``` ``` ~ % 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 ``` ``` ~ % 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: ``` 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: * kubectl get svc * kubectl get endpoints ``` ~ % 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 ``` ``` ~ % 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: ``` 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: ``` 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: ``` # 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: ``` {“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](/docs/self-hosted/helm-configuration.md#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](/docs/get-started/install/amazon-eks.md) for details. 2. **Recreate your node group** with the supported AMI family. For example, using `eksctl`: ``` 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: ``` kubectl get jobs -l=dev.okteto.com/pipeline-name=movies -l=dev.okteto.com/pipeline-namespace=cindy --namespace=okteto ``` ``` 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](/docs/self-hosted/helm-configuration.md#webhook). ## Docker Hub credentials misconfiguration As you can [configure your own Docker Hub account](/docs/admin/dashboard.md#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](/docs/self-hosted/helm-configuration.md#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](/docs/self-hosted/manage/upgrade.md) 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! --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Uninstalling Okteto To delete an existing release use: ``` helm uninstall okteto ``` This will delete Okteto, but not the resources created when using it (e.g. namespaces, accounts, deployments, etc...). # Troubleshooting We've done our best to make Okteto easy to install and operate. [The troubleshooting page](/docs/self-hosted/manage/troubleshooting.md) has tips and tricks to help troubleshoot common issues. You can also [reach out to support](https://okteto.com/support) if you need assistance. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Upgrade your Okteto instance ## Upgrade your Okteto Instance tip To ensure a successful Okteto upgrade, we recommend testing it on a dedicated test cluster. Please contact your sales representative to request a test license for your test cluster. ### How to Upgrade To upgrade a new release, modify the `config.yaml` with your desired changes and then use: ``` helm repo update helm upgrade okteto okteto/okteto -f config.yaml --namespace=okteto --version ``` For example: ``` helm repo update helm upgrade okteto okteto/okteto -f config.yaml --namespace=okteto --version 1.46.0 ``` *You can use `helm ls` to find the name of your release.* Please review [the release notes](/docs/release-notes.md) 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`): ``` 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 1.46.0 ``` tip If you need to use a different registry (neither ghcr.io nor docker.io), see our [Air-Gapped Networks guide](/docs/self-hosted/manage/air-gapped.md) 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](/docs/self-hosted/helm-configuration.md#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](/docs/self-hosted/manage/argocd.md). 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](/docs/self-hosted/helm-configuration.md#redis). If you previously customized Redis using Bitnami-specific Helm values, review and update your values file before upgrading. Unsupported Bitnami values will be silently ignored, which could result in unexpected Redis behavior. ## Upgrading to Okteto 1.35.x – Kubernetes 1.33 Support and Amazon Linux 2023 (AL2023)Compatibility Okteto 1.35 is the first release with official support for **Kubernetes 1.33** and **Amazon Linux 2023 (AL2023)**. If you are running Okteto in AWS, we recommend the following upgrade sequence to ensure compatibility and a smooth rollout: 1. Upgrade Okteto to **version 1.35** 2. (Recommended) Upgrade your node pool to Amazon Linux 2023 and verify that your workloads are healthy. 3. Then upgrade your EKS cluster to **Kubernetes 1.33** This order helps preserve rollback options in case of unexpected issues. If you upgrade to Kubernetes 1.33 before updating Okteto to 1.35, you may encounter compatibility problems, as Okteto 1.34 and earlier do not support Kubernetes 1.33. ## Upgrading to Okteto 1.31.x – Schema 1 Image Deprecation With the upcoming release of Okteto, support for **Docker Image Manifest Schema 1** will be fully deprecated due to underlying upgrades in our dependencies. **What This Means for You** * If you are using older container images that rely on **Schema 1**, they will no longer be pulled or deployed successfully * This change aligns with the broader container ecosystem, as Schema 1 images have been deprecated since 2021 and are no longer supported by modern container runtimes ### **How to Check If Your Images Are Affected** You can verify your images by running: ``` docker manifest inspect ``` * If the output contains `"schemaVersion": 1`, you will need to update the image * If it contains `"schemaVersion": 2`, no action is required ### **What You Need to Do** * If you are using Schema 1 images, we strongly recommend migrating to Schema 2 images before the next Okteto release * If your image is outdated, check for an updated version or rebuild and push it using a modern Docker version: ``` docker pull docker tag myrepo/myimage:v2 docker push myrepo/myimage:v2 ``` ## Upgrading to Okteto 1.26.x – Hostname Limits, Helm Release Name Changes * **ACTION REQUIRED: Hostname Length Limit**
Deployments now fail 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 ## Upgrading to Okteto 1.25.x – CLI 3.0.0 Upgrade Starting with the [1.25 release](/docs/archived-release-notes.md#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 As part of the [1.22 release](/docs/archived-release-notes.md#1220), we have reorganized some helm settings that allow you to configure annotations, labels, and role bindings to apply to user's service accounts. Settings changed are the following: * `clusterRole` setting is now moved to [`serviceAccounts.roleBindings.namespaces`](/docs/self-hosted/helm-configuration.md#serviceaccounts) * `globalClusterRole` setting is now moved to [`serviceAccounts.clusterRoleBinding`](/docs/self-hosted/helm-configuration.md#serviceaccounts) * `user.serviceAccounts.annotations` is now moved to [`serviceAccounts.annotations`](/docs/self-hosted/helm-configuration.md#serviceaccounts) * `user.serviceAccounts.labels` is now moved to [`serviceAccounts.labels`](/docs/self-hosted/helm-configuration.md#serviceaccounts) * `user.extraRoleBindings.roleBindings` is now moved to [`serviceAccounts.extraRoleBindings`](/docs/self-hosted/helm-configuration.md#serviceaccounts) Summarizing, in case you have all or some of these settings configured as they were before: ``` clusterRole: cluster-admin globalClusterRole: example-cluster-role user: serviceAccount: annotations: custom.annotation/one: one custom.annotation/two: two labels: custom.label/one: one custom.label/two: two extraRoleBindings: enabled: true roleBindings: namespace-name1: - cluster-role1 - cluster-role2 namespace-name2: - cluster-role3 ``` The configuration for 1.22 versions would be the following: ``` serviceAccounts: annotations: custom.annotation/one: one custom.annotation/two: two labels: custom.label/one: one custom.label/two: two roleBindings: namespaces: cluster-admin clusterRoleBinding: example-cluster-role extraRoleBindings: namespace-name1: - cluster-role1 - cluster-role2 namespace-name2: - cluster-role3 ``` note Old settings are still considered and have preference, but their support will be removed in a future version. Please consider migrating them as soon as possible. We have also made another relevant change to consider when migrating to `1.22`. We have stopped creating an automatic role binding to any custom service account created on namespaces managed by Okteto to the cluster role specified on `serviceAccounts.roleBindings.namespaces` (`clusterRole` in previous versions). If you create any custom service account as part of your application, make sure you also create any role or role binding needed. If you experience issues with permissions in this regard, we recommend creating an explicit role and role-binding, but as an alternative solution you can also manually create the role-binding to the `cluster-admin` role, using the following approach: 1. Create the `rb.yml.tpl` file with the following content: ``` apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: cluster-admin subjects: - kind: ServiceAccount name: namespace: ${OKTETO_NAMESPACE} ``` 2. Replace `` with the name of the service account you want to bind to the `cluster-admin` role. 3. In the Okteto Manifest deploy commands, use `envsubst` to replace the `${OKTETO_NAMESPACE}` variable: ``` deploy: - envsubst < k8s/rb.yml.tpl > k8s/rb.yml - kubectl apply -f k8s ``` ## Upgrading to Okteto 1.20.x – Pull Secrets Enabled by Default In the Okteto [1.20 release](/docs/archived-release-notes.md#1200), we have enabled [Pull Secrets by default](/docs/admin/registry-credentials.md). If you do no wish to manage Pull Secrets the following helm values should be disabled: * `regcredsManager.pullSecrets.enabled` should be set to `false` * `daemonset.configurePrivateRegistriesInNodes.enabled` should be set to `false` (if you are already preventing Okteto to manage credentials in the node, this may already be configured correctly) --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Welcome to Okteto Test Okteto Test is a new feature designed to seamlessly integrate testing into your development workflow on the Okteto platform. Whether you're running unit tests or end-to-end (E2E) tests, Okteto Test ensures an efficient testing experience before and after making a pull request. ## Why Okteto Test? This is how the software development process looks like for application based on microservices before adopting Okteto: ![Diagram comparing development, CI, and production stages running on different platforms: local environment, virtual machine, and Kubernetes](/docs/assets/images/classic-software-development-60c75f9e02de7f0685635dab04da3cd3.png) Developers set up local development environments with tools like Docker Compose, CI (Continuous integration) runs tests on a dedicated virtual machine, and production runs on Kubernetes. This setup leads to inconsistencies because the app runs on different platforms at different stages between (dev, CI, production), often resulting in unexpected bugs and integration issues. After adopting Okteto for Development Environments, this is how the software development process looks like: ![Diagram showing development and production both running on Kubernetes with Okteto, while CI still runs on a virtual machine](/docs/assets/images/okteto-for-development-e7f4871ca3a911533cfe25c9d4e805cf.png) Now your dev and production environments run on Kubernetes, reducing integration issues between dev and prod. But there's still a gap: CI is running on a different platform. Why not leverage Okteto to run CI on Kubernetes as well? ![Diagram showing development, CI, and production all running on Kubernetes with Okteto for consistent environments](/docs/assets/images/okteto-for-testing-21aea4301ca1834e91ae4a48129e8855.png) By using Okteto Test and Preview Environments, you can run CI on Okteto, and ensure your entire software development cycle runs on Kubernetes. This minimizes integration and configuration issues, making your development process smoother and more efficient. ## Benefits of Okteto Test ### 1. Seamless Integration and Remote Execution Developers can execute tests in the same remote production-like Kubernetes environment where their code runs - without having to install anything locally. Running your tests in the cluster network simplifies access to private services, reduces latency, ensures consistency and reduces configuration overhead. ### 2. Simplified Configuration The new `test` section in the [Okteto manifest](/docs/reference/okteto-manifest.md#test-object-optional) supports multiple Test Containers, allowing you to define your test environment with minimal YAML configuration. This eliminates the need for complex setups and advanced Kubernetes knowledge. ## Getting Started with Okteto Test View our [Getting Started with Okteto Test Guide](/docs/testing/getting-started-test.md) to learn how to configure Test Containers. ## Get Involved Okteto Test is a new feature. We value your feedback and encourage you to share your experiences and suggestions. Join our [community](https://community.okteto.com/), participate in discussions, and help us improve Okteto Test. --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Getting started with Okteto Test This guide explains how to configure Test Containers for your first app in Okteto. ## Requirements Before you start this tutorial, make sure you fulfill the following requirements: * You have access to an Okteto instance. Otherwise, follow our [installation guide](/docs/get-started/install.md) * You have [configured the Okteto CLI](/docs/get-started/install-okteto-cli.md) with your Okteto instance * You have completed [our guide to deploy your first app to Okteto](/docs/get-started/deploy-your-app.md) ## What you will be building This tutorial will guide you on how to test our sample [Movies app](https://github.com/okteto/getting-started) using Okteto. ## Step 1: Deploy the Movies App Get a local version of the Movies Sample App by executing the following commands: ``` git clone https://github.com/okteto/getting-started cd getting-started ``` Switch to the `onboarded` branch: ``` git checkout onboarded ``` At the root of the directory, you'll find the `okteto.yaml` file. This file describes how to build, deploy and test the Movies app. Deploy your development environment by executing: ``` okteto deploy ``` ``` i Using cindy @ okteto.example.com as context i Running 'Helm Install' Release "movies" has been upgraded. Happy Helming! NAME: movies LAST DEPLOYED: Tue Jun 4 15:37:11 2024 NAMESPACE: pchico83 STATUS: deployed REVISION: 2 TEST SUITE: None NOTES: Success! Your application will be available shortly. i Endpoints available: - https://movies-cindy.okteto.example.com ✓ Development environment 'getting-started' successfully deployed ``` ## Step 2: Execute the `frontend` unit tests in a Test Container The [test](/docs/reference/okteto-manifest.md#test-object-optional) section in the Okteto Manifest defines how to test the Movies app. For example, add the Test Container to run unit tests for the `frontend` service like this: okteto.yaml ``` test: frontend: image: node:20 context: frontend caches: - yarn/.cache - node_modules commands: - yarn install - yarn test ``` `frontend` is the name of the Test Container. The meaning of the rest of the fields are: * `image`: the image used as the runtime of your Test Container. * `context`: the folder that will be synchronized between your local machine and the Test Container. * `caches`: a list of folders to persist between executions of the Test Container. This is very important for the performance of your Test Containers. * `commands`: a list of commands to execute your tests. Also, note that there is an `.oktetoignore` file in the `frontend` folder to indicate which files shouldn't be synchronized to your Test Container. This is useful to avoid synchronizing binaries, build artifacts, cache metadata, or dependencies like the `node_modules` folder. Next, execute the following command to run the `frontend` unit tests in a Test Container: ``` okteto test frontend ``` The first execution takes longer because `caches` aren't initialized yet, but you will get this output: ``` i Using cindy @ okteto.example.com as context i Executing test container 'frontend' i Running 'yarn install' yarn install v1.22.22 [1/4] Resolving packages... [2/4] Fetching packages... [3/4] Linking dependencies... [4/4] Building fresh packages... Done in 43.31s. ✓ Command 'yarn install' successfully executed i Running 'yarn test' yarn run v1.22.22 $ jest PASS src/components/Hero.test.jsx PASS src/components/TitleList.test.jsx PASS src/components/Item.test.jsx PASS src/components/App.test.jsx PASS src/components/UserProfile.test.jsx PASS src/components/ListToggle.test.jsx Test Suites: 6 passed, 6 total Tests: 20 passed, 20 total Snapshots: 0 total Time: 5.658 s Ran all test suites. Done in 6.59s. ✓ Command 'yarn test' successfully executed ✓ Test container 'frontend' passed ``` If you rerun your Test Container, execution will be faster because caches are already initialized. ## Step 3: Execute the `api` unit tests in a Test Container The Test Container to run unit tests for the `api` service looks like this: okteto.yaml ``` test: api: image: node:20 context: api caches: - yarn/.cache - node_modules commands: - yarn install - yarn test ``` Execute the following command to run the `api` unit tests in a Test Container: ``` okteto test api ``` ``` i Using cindy @ okteto.example.com as context i Executing test container 'api' i Running 'yarn install' yarn install v1.22.22 [1/4] Resolving packages... [2/4] Fetching packages... [3/4] Linking dependencies... [4/4] Building fresh packages... Done in 9.01s. ✓ Command 'yarn install' successfully executed i Running 'yarn test' yarn run v1.22.22 $ jest PASS ./load.test.js ● Console console.log all loaded at log (load.js:44:13) PASS ./server.test.js ● Console console.log Server running on port 8080. at log (server.js:52:13) console.log GET /api/movies at log (server.js:29:15) console.log GET /api/watching at log (server.js:41:15) Test Suites: 2 passed, 2 total Tests: 7 passed, 7 total Snapshots: 0 total Time: 1.098 s Ran all test suites. Done in 1.79s. ✓ Command 'yarn test' successfully executed ✓ Test container 'api' passed ``` ## Step 3: Execute the `e2e` integration tests in a Test Container The Test Container to run integration tests looks like this: okteto.yaml ``` test: e2e: image: ghcr.io/okteto/playwright:chromium context: e2e caches: - yarn/.cache - node_modules commands: - bash run_tests.sh artifacts: - test-results - playwright-report ``` `e2e` is the name of the Test Container. The meaning of the rest of fields is: * `image`: the image used as the runtime of your Test Container. * `context`: the folder that will be synchronized between your local machine and the Test Container. * `caches`: a list of folders to persist between executions of the Test Container. This is very important for the performance of your Test Containers. * `commands`: a list of commands to execute your tests. * `artifacts`: a list of files/folders to export to your local filesystem after the remote execution of the tests. Execute the following command to run your integration tests in a Test Container: ``` okteto test e2e ``` ``` i Using cindy @ okteto.example.com as context i Executing test container 'e2e' i Running 'bash run_tests.sh' yarn install v1.22.19 [1/4] Resolving packages... [2/4] Fetching packages... [3/4] Linking dependencies... [4/4] Building fresh packages... Done in 4.53s. yarn run v1.22.19 $ playwright test Running 6 tests using 2 workers ✓ 1 [chromium] › content.spec.js:26:5 › displays the movies section (3.2s) ✓ 2 [chromium] › content.spec.js:48:5 › displays the watching section (3.2s) ✓ 3 [chromium] › header.spec.js:3:5 › displays the header (762ms) ✓ 4 [chromium] › hero.spec.js:3:5 › displays the hero (936ms) ✓ 5 [chromium] › main.spec.js:3:5 › has title (1.6s) ✓ 6 [chromium] › main.spec.js:10:5 › matches screenshot (3.6s) 6 passed (9.9s) To open last HTML report run: yarn playwright show-report Done in 10.88s. ✓ Command 'bash run_tests.sh' successfully executed ✓ Test container 'e2e' passed ``` The `e2e` test container uses `playwright` to fetch the list of movies and compare the results with the list of Movies in the MongoDB database. The `BASE_URL` of the integration tests is built using the environment variables `OKTETO_NAMESPACE` and `OKTETO_DOMAIN`. This code shows you how to [form the BASE\_URL of your integration tests](https://github.com/okteto/getting-started/blob/main/e2e/playwright.config.js#L3). Note that your test scripts run in the `okteto` namespace, if you need to access private service like `mongodb`, you need to do it via the hostname `mongodb.${OKTETO_NAMESPACE}`. This code shows you how to [access private services from your integration tests](https://github.com/okteto/getting-started/blob/main/e2e/data/getStoredData.js#L5). ## Next Steps Congratulations, you just tested **your first application in Okteto** 🚀. Okteto lets you test your applications directly on Kubernetes. This way you can: * Make sure your tests run the same way in your inner development loop and [Okteto Preview Environments](/docs/previews.md) * Run your tests directly in Kubernetes, to simplify access to your application and reduce latency --- > **Documentation Index**: fetch the complete list of pages as Markdown at to find the right page before exploring further. # Okteto: the environment platform for agentic development ## 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/) ## Why Platform Teams choose Okteto? ### 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](/docs/assets/images/platform-team-diagram-96417fe24dd48e1f59750d96ed3be0a3.jpg) ### 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](/docs/assets/images/dev-environment-example-f81443e3f0dfeb485166d142ce41e10b.jpg) ### Okteto Manifest simplifies environment automation Utilize the [Okteto Manifest](/docs/core/okteto-manifest.md) 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](/docs/development/deploy/deploy-from-catalog.md) to create a collection of ready-to-use development environments for your development team. ![Platform team using Okteto diagram](/docs/assets/images/manifest-90628341a13529abc7446eed1de30420.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](/docs/agentic.md) covers the setup and example prompts. ### Development Environments Okteto's [Development Environments](/docs/development.md) enable you to deploy and develop applications directly in the cloud with a single [CLI command](/docs/development/using-okteto-cli.md) 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. ### Okteto Test: Shift Left, Test Fast Speed up your feedback loops by running **unit, integration, and end-to-end tests** inside your dev environments. With [Okteto Test](/docs/testing.md), you can catch bugs before they hit CI without waiting for long pipeline runs. ### Automated Preview Environments Collaborate and share your progress with ease. Okteto's [Preview Environments](/docs/previews.md) automatically generate a unique, shareable version of your application for each pull request, making code reviews, automated end-to-end testing, and stakeholder feedback a breeze. ### Unified management interface Manage your team's development environments, applications, workflows, and roles all from Okteto's [Admin Dashboard](/docs/admin/dashboard.md). This central hub provides visibility and control over your team's cloud-native development processes, making management straightforward and efficient. ### Automated Cleanup and Cost Optimization Okteto helps you reduce cloud costs without manual effort. The [**Garbage Collector**](/docs/admin/cleanup.md) scales down idle environments and removes unused resources automatically. The [**Resource Manager**](/docs/admin/resource-manager.md) adjusts CPU and memory limits based on real usage to avoid overprovisioning. Together, they keep your environments efficient and cost-effective. *** ## Choose How You Deploy Okteto Okteto is flexible enough to meet your deployment and compliance needs. * **Bring Your Own Cloud (BYOC)**: We maintain Okteto, you bring the cloud. You get full control of data and workloads, with none of the management overhead
[Learn about BYOC](/docs/byoc.md) * **Self-Hosted**: Install Okteto in your own Kubernetes cluster. Ideal for air-gapped, highly regulated, on-premise environments, or for small teams with Kubernetes expertise
[Install Okteto Self-Hosted](/docs/get-started/install.md) *** ## Get Started Today * 🚀 [Follow the installation guide](/docs/get-started/install.md) * 🗓️ [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. ---