Connecting your IDE over SSH

okteto up runs an SSH server inside your Development Container and adds a host entry for it to your local SSH configuration. Any IDE that supports remote development over SSH can open a project through that host. In this setup the source code lives only in the container: you clone the repository there instead of synchronizing it from your machine, so the IDE's Git integration, language server, terminal, and debugger all work against the same copy.

This tutorial creates a Development Container, clones okteto/go-getting-started into it, deploys the application with okteto deploy from inside the container, and connects your IDE.

Prerequisites

• The Okteto CLI installed and configured against your Okteto instance.
• An IDE with SSH remote development, such as Visual Studio Code with the Remote - SSH extension or a JetBrains IDE with JetBrains Gateway.

Okteto Manifest for the remote workspace

Create an empty folder for the workspace configuration:

mkdir remote-workspace
cd remote-workspace

Add an okteto.yaml file:

okteto.yaml

dev:
  workspace:
    autocreate: true
    metadata:
      annotations:
        dev.okteto.com/inject-token: "true"
    image: ghcr.io/okteto/golang:1
    command: bash
    remote: 2222
    workdir: /workspace
    sync:
      - .:/workspace

Add a .stignore file that excludes every file from File Sync:

.stignore

*

Each field configures one part of the workspace:

• autocreate makes okteto up create a Deployment named workspace, so the manifest needs no deploy section.
• The dev.okteto.com/inject-token annotation, set under metadata, makes Okteto inject the OKTETO_CONTEXT and OKTETO_TOKEN environment variables into the container. The Okteto CLI inside the container uses them to authenticate against your Okteto instance as the owner of the Namespace, with no okteto context setup.
• remote fixes the local SSH port to 2222. Without it, okteto up picks a random port on every run.
• workdir sets the working directory of the container to /workspace, where okteto up opens its shell.
• sync is mandatory. Combined with the .stignore above, it transfers no files, but /workspace is still backed by the Development Container's persistent volume, so the repository you clone there survives okteto down and later okteto up sessions. okteto down -v deletes it.

Starting the Development Container

Start the Development Container from the remote-workspace folder:

okteto up

okteto up opens a shell in the container. Leave it running: it keeps the SSH tunnel to the container open. Run the commands in the next sections in that shell.

Installing the Okteto CLI

Install the Okteto CLI in the container:

curl https://get.okteto.com -sSfL | sh

Build your dependencies into the dev image

Everything installed outside /workspace is lost when the Development Container restarts, so you would install the Okteto CLI again on every okteto up. Build it into a custom image and set it in the image field of your Okteto Manifest instead:

FROM ghcr.io/okteto/golang:1
RUN curl https://get.okteto.com -sSfL | sh

Add any other tooling your remote session needs in the same image: language runtimes, debuggers such as Delve, linters, kubectl or helm, your Git configuration, and the backend of your remote IDE, so it isn't downloaded on the first connection. Keep your repositories in /workspace instead: it lives on the persistent volume and keeps your uncommitted changes across sessions.

Cloning and deploying the repository

Clone the repository:

git clone https://github.com/okteto/go-getting-started.git

note

To clone private repositories over SSH, mount your SSH key with the secrets field and trust GitHub's host key before cloning:

secrets:
  - $HOME/.ssh/id_ed25519:/root/.ssh/id_ed25519:400

ssh-keyscan github.com >> ~/.ssh/known_hosts
git clone git@github.com:<org>/<repo>.git

Okteto stores the files listed under secrets as a Kubernetes Secret in your Namespace, so use a key you are comfortable storing in the cluster.

Deploy the application from the cloned repository:

cd go-getting-started
okteto deploy

okteto deploy uses the injected credentials and deploys the application to your Namespace.

Connecting your IDE

okteto up adds this entry to your ~/.ssh/config file:

Host workspace.okteto
  HostName localhost
  Port 2222
  StrictHostKeyChecking no
  UserKnownHostsFile /dev/null

The host is named <dev-name>.okteto, where <dev-name> is the name under the dev section of your Okteto Manifest. Okteto generates the key pair for this connection at ~/.okteto/id_rsa_okteto the first time you run okteto up. Confirm the connection from a separate terminal:

ssh workspace.okteto

Point your IDE at the same host and open /workspace/go-getting-started:

• Visual Studio Code: install the Remote - SSH extension, run Remote-SSH: Connect to Host from the Command Palette, and select workspace.okteto.
• JetBrains IDEs: open JetBrains Gateway, select Connect via SSH, and create a connection with user root, host localhost, port 2222, and the private key ~/.okteto/id_rsa_okteto. Gateway installs the IDE backend you select inside the container.

The connection stays up while okteto up is running. If you stop it, run okteto up again and reconnect. The SSH Server reference describes the SSH setup in full.