Okteto CLI

Dev Environments allow you to develop your deployed application locally. You continue coding in your favorite IDE and see the changes live on the deployed version of your application as soon as you hit save. Okteto CLI is an open source client-side only tool that allows you to launch Dev Environments in any Kubernetes cluster: your own, Okteto Cloud, or Okteto Self-Hosted.

Learn more about the Okteto CLI

• Installation guide
• Okteto CLI Reference
• File Synchronization
• SSH Server
• FAQs
• Known Issues

okteto up

The okteto up command is one of Okteto CLI's main features and key to the Okteto development experience. This command uses the Okteto Manifest you define to build, deploy, and synchronize your local files with the remote development container.

This command has two modes: sync (default mode) and hybrid which are detailed below.

	sync (default)	hybrid
Source code	Source code is edited locally and synchronizes bidirectionally (via Syncthing) with a copy of the source code in the remote development container.	Source code is edited locally for a chosen set of microservices.
App location	The application exists entirely within the remote development container.	Your application is split between your local environment and the remote development container based on your configuration.
command context	CLI commands run in the remote development container.	CLI commands run on your local machine, so traffic need to be rerouted to/from the cluster, e.g. using the reverse option

Below is a reference to help you configure your dev section based on the mode you select. Standard configuration options work in both modes and Sync options work only when sync is selected.

For example, if you select hybrid mode, you can only use the configuration options in your manifest dev section listed under Standard. Any configuration options in the Sync list will not work.

Configuration reference: dev section

Standard

• annotations
• autocreate
• command
• container
• envFiles
• environment
• environment
• forward
• metadata
• mode
• reverse
• selector
• workdir

Sync

• affinity
• context
• externalVolumes
• image
• imagePullPolicy
• initContainer
• initFromImage
• lifecycle
• namespace
• nodeSelector
• persistentVolume
• push
• replicas
• secrets
• securityContext
• serviceAccount
• sshServerPort
• sync
• tolerations
• volumes

When to use hybrid development mode

A typical use case for using hybrid development mode is when the filesync or rebuild is significantly slower on the remote dev container, such as when using Webpack where this becomes very noticeable compared to your local environment.

Another use case is when you’re using a framework that is IDE-heavy. For example, on Java/Spring, IDEs tend to be pre-configured to run tests, start services, and connect debuggers. You lose some of that ‘click and you are done’ when you are using the traditional okteto up and the default sync mode.

info

Keep in mind that using hybrid mode means breaking replicability between Operating Systems (local and remote) and may add latency when accessing other services in the cluster.

How to use hybrid development mode

In order to use hybrid mode you only need to configure the necessary ports to expose the service running on your local machine to the remote development container. This enables other components running on the cluster to communicate with your local service(s) as if your local service(s) was running in the cluster as well.

To do this, you can use the reverse field to expose the desired port of your local machine to the desired port on the remote development container.

dev:
  frontend:
    mode: hybrid
    reverse:
    - 3000:8080
    workdir: ./frontend
    command: ["npx webpack watch --mode development"]

In the example above we have indicated that we are developing the frontend service locally using the mode: hybrid field. The service running locally will execute the command instructions in the directory indicated in workdir. Additionally, the application will expose port 8080 on the local machine and communicate bidirectionally with port 3000 on the development container. This makes it possible for other components running on the cluster to access the local service as if it were running remotely.

Deployment Manifests

You need one of the following deployment manifests for your application so that Okteto CLI knows how to launch a Dev Environment for it. Okteto CLI will analyze your existing manifests (Helm, Kubernetes, etc.) and help you write an Okteto Manifest for your application. It will then use this Okteto Manifest instead of your existing deployment manifests to spin up Dev Environments.

If you're using a Docker Compose file, then Okteto CLI can directly launch a Dev Environment for your application without generating an Okteto Manifest. However, you can still choose to create the Okteto Manifest if you want more configuration over your environment.

Okteto CLI will look for deployment manifests for your application in the following order:

1. Okteto Manifest file: if there is an okteto.yaml or .okteto/okteto.yaml file in your folder, Okteto will use this file to deploy your development environment.
2. Docker Compose file: if there is an okteto-compose.yaml or docker-compose.yaml file, Okteto will use this file to deploy your development environment.
3. Helm Chart: if there is a chart, charts, helm/chart, or helm/charts directory with a Chart.yaml file in it, Okteto will detect the chart and run helm upgrade --install on it to deploy your development environment.
4. Kubernetes manifests folder: if there is a manifests, kubernetes, or k8s folder, Okteto will detect it and run kubectl apply to deploy your development environment.
5. Kubernetes manifests file: if there is a manifests.yaml, kubernetes.yaml, or k8s.yaml file, Okteto will detect it and run kubectl apply to deploy your development environment

You can also explicitly define the location of the Okteto Manifest using the -f flag on any Okteto CLI command.

Okteto manifest

The Okteto manifest allows you to provide configuration for building, deploying, and developing your application in a Development Environment. This file is optional if you already have a Docker Compose file for your application. Learn more about the Okteto manifest here.

Sample Okteto Manifest

icon: https://apps.okteto.com/movies/icon.png
build:
  api:
    context: .
deploy:
  - helm upgrade --install app chart --set image=${OKTETO_BUILD_API_IMAGE}
dev:
  api:
    command: ["bash"]
    forward:
      - 8080:8080
      - 9229:9229
    sync:
      - .:/usr/src/app

This example shows how to build the container image of the api microservice, how to deploy the application using its helm chart, and how to develop on the api microservice by synchronizing the local filesystem on the container path /usr/src/app. If you want to learn more about what all you can configure in this manifest, head over to the Okteto Manifest Reference.

Built-in Environment Variables

Default Environment Variables

The following environment variables are automatically populated to be referred in your Okteto Manifest or deploy/destroy commands:

• OKTETO_DOMAIN: the domain where Okteto exposes your application endpoints.
• OKTETO_NAMESPACE: the namespace where your application is going to be installed.
• OKTETO_USERNAME: your username in Okteto.
• OKTETO_REGISTRY_URL: the url of the Okteto Registry.
• OKTETO_GIT_BRANCH: the name of the Git branch currently being deployed.
• OKTETO_GIT_COMMIT: the SHA1 hash of the last commit of the branch.

Built-in Environment Variables for Images stored in the Okteto Registry

You can refer to the images defined in the build section of the Okteto Manifest using the following environment variables:

• OKTETO_BUILD_<image>_IMAGE: the full image reference
• OKTETO_BUILD_<image>_REGISTRY: the registry URL where the image was pushed
• OKTETO_BUILD_<image>_REPOSITORY: the name of the image that was pushed
• OKTETO_BUILD_<image>_SHA: The latest tag and the SHA of the image

For example, for the following build section:

build:
  hello-world:
    context: .

Okteto will build a random image tag like registry.cloud.okteto.net/cindy/hello-world:f56119a37b, and you would have the following environment variables available:

• OKTETO_BUILD_HELLO_WORLD_IMAGE: registry.cloud.okteto.net/cindy/hello-world@sha256:xxx
• OKTETO_BUILD_HELLO_WORLD_REGISTRY: registry.cloud.okteto.net
• OKTETO_BUILD_HELLO_WORLD_REPOSITORY: cindy/hello-world
• OKTETO_BUILD_HELLO_WORLD_SHA: f56119a37b@sha256:xxx

if an <image> name includes the symbol -, in the corresponding OKTETO_BUILD_<image> environment variables, the symbol - will be replaced by _. For example, if <image> is name-with-hyphen, the environment variable names will start with $OKTETO_BUILD_NAME_WITH_HYPHEN_.

Built-in Environment Variables for Dependencies

You can refer to the variables defined by your dependencies using the following environment variables:

• OKTETO_DEPENDENCY_<dependency>_VARIABLE_<variable>: the value of a variable of a dependency.

For example, if you have the following dependency in your Okteto Manifest:

dependencies:
  database:
    repository: https://github.com/okteto/my-database
    variables:
      USERNAME: okteto
    wait: true

and the repo https://github.com/okteto/my-database has the following Okteto Manifest:

deploy:
  - echo "PASSWORD=1234" >> $OKTETO_ENV

You can refer to the variables of https://github.com/okteto/my-database in the deploy section of your Okteto Manifest like this:

dependencies:
  database:
    repository: https://github.com/okteto/my-database
    variables:
      USERNAME: okteto
    wait: true
deploy:
  - echo ${OKTETO_DEPENDENCY_DATABASE_VARIABLE_USERNAME}
  - echo ${OKTETO_DEPENDENCY_DATABASE_VARIABLE_PASSWORD}

Note that USERNAME has an static value, and PASSWORD is dynamically generated.

Built-in Tools When Deploying To Okteto

When deploying your development environment, Okteto executes the sequence of deploy commands. The commands run in a Debian Linux container with the following tools preinstalled:

• bash
• cue
• curl
• envsubst
• git
• helm
• kubectl
• kustomize
• make
• okteto
• openssh
• wait-for-it

You can also configure your own container image to use your own tools in your deploy commands. For example, if you need to invoke terraform commands, you could do:

deploy:
  image: hashicorp/terraform:1.4
  commands:
    - terraform apply -auto-approve