Okteto Cheat Sheet

Overview

Okteto is a Kubernetes-native development platform that allows developers to work on applications running in a Kubernetes cluster with the experience of local development. It replaces running containers with a development environment that syncs code in real-time, forwards ports, and provides hot-reload capabilities.

Okteto offers both a cloud-hosted platform (Okteto Cloud) and a self-hosted solution (Okteto Self-Hosted). Developers define their development environments using an okteto.yaml manifest that specifies how to build, deploy, and develop services. Okteto supports Docker Compose, Helm, and raw Kubernetes manifests.

Installation

# macOS
brew install okteto

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

# Windows
choco install okteto

# Verify
okteto version

# Set context to Okteto Cloud
okteto context use https://cloud.okteto.com

# Or self-hosted
okteto context use https://okteto.mycompany.com

Core Commands

Command	Description
okteto context	Manage cluster contexts
okteto deploy	Deploy development environment
okteto up	Start development mode
okteto down	Deactivate development mode
okteto destroy	Destroy development environment
okteto build	Build and push images
okteto logs	Stream application logs
okteto exec	Execute command in dev container
okteto endpoints	List environment endpoints
okteto namespace	Manage namespaces

Configuration

Basic okteto.yaml

build:
  api:
    context: .
    dockerfile: Dockerfile

deploy:
  - helm upgrade --install api charts/api

dev:
  api:
    image: node:20
    command: bash
    sync:
      - .:/app
    forward:
      - 3000:3000
      - 9229:9229
    environment:
      - NODE_ENV=development

Docker Compose Based

build:
  frontend:
    context: frontend
  backend:
    context: backend

deploy:
  compose:
    - docker-compose.yml

dev:
  frontend:
    command: npm run dev
    sync:
      - frontend:/app
    forward:
      - 3000:3000

  backend:
    command: python manage.py runserver 0.0.0.0:8000
    sync:
      - backend:/app
    forward:
      - 8000:8000

Kubernetes Manifest Deployment

deploy:
  - kubectl apply -f k8s/

dev:
  api:
    selector:
      app: api
    command: bash
    sync:
      - .:/app
    forward:
      - 8080:8080

Development Workflow

Start Development

# Deploy the environment
okteto deploy

# Start dev mode for a service
okteto up

# Start dev mode for specific service
okteto up api

# With build
okteto up --build

# Check endpoints
okteto endpoints

File Sync

dev:
  api:
    sync:
      - .:/app
    persistentVolume:
      enabled: true
      size: 10Gi
    volumes:
      - /app/node_modules  # Exclude from sync

Remote Execution

# Execute command in dev container
okteto exec api -- npm test

# Open shell
okteto exec api -- bash

# Run database migration
okteto exec api -- python manage.py migrate

Advanced Usage

External Resources

external:
  database:
    icon: database
    notes: config/database-notes.md
    endpoints:
      - name: postgres
        url: jdbc:postgresql://db.example.com:5432/mydb

deploy:
  - helm upgrade --install api charts/api

Build Configuration

build:
  api:
    context: .
    dockerfile: Dockerfile
    target: development
    args:
      NODE_VERSION: "20"
    cache_from:
      - registry.example.com/api:cache
    export_cache:
      - registry.example.com/api:cache
    secrets:
      npmrc: .npmrc

Multi-Service Development

dev:
  frontend:
    image: node:20
    command: npm run dev
    sync:
      - frontend:/app
    forward:
      - 3000:3000
    environment:
      - API_URL=http://backend:8000

  backend:
    image: python:3.12
    command: python manage.py runserver 0.0.0.0:8000
    sync:
      - backend:/app
    forward:
      - 8000:8000
    environment:
      - DATABASE_URL=postgres://postgres:password@postgres:5432/mydb
    services:
      - name: postgres
        image: postgres:16
        ports:
          - 5432
        environment:
          - POSTGRES_PASSWORD=password

Divert (Traffic Routing)

dev:
  api:
    mode: sync
    sync:
      - .:/app
    divert:
      driver: istio
      virtualServices:
        - name: api-vs
          namespace: staging
          routes:
            - headers:
                x-developer: my-name

GitHub Actions Integration

# .github/workflows/preview.yml
name: Preview
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: okteto/context@latest
        with:
          url: ${{ secrets.OKTETO_URL }}
          token: ${{ secrets.OKTETO_TOKEN }}
      - uses: okteto/deploy-preview@latest
        with:
          name: pr-${{ github.event.number }}
          timeout: 15m

Lifecycle Hooks

dev:
  api:
    command: bash
    sync:
      - .:/app
    initContainer:
      image: node:20
      command:
        - sh
        - -c
        - "npm install"
    probes:
      liveness: false
    lifecycle:
      postStart:
        command:
          - sh
          - -c
          - "python manage.py migrate"

Troubleshooting

Issue	Solution
Sync slow or not working	Check for large directories; add to volumes exclusion
Container crash on up	Verify command and image in okteto.yaml
Build context too large	Add .dockerignore to exclude unnecessary files
Port already in use	Change local forward port in forward config
Authentication failed	Run okteto context and re-authenticate
Persistent volume full	Increase persistentVolume.size or clean up

# Debug mode
okteto up --debug

# Check context
okteto context show

# View logs
okteto logs api

# List endpoints
okteto endpoints

# Deactivate dev mode
okteto down

# Destroy everything
okteto destroy

# Reset sync state
okteto down -v