DevSpace Cheat Sheet

Overview

DevSpace is an open-source developer tool for Kubernetes that automates the inner-loop development workflow. It builds Docker images, deploys Helm charts or Kubernetes manifests, syncs files between local and remote containers, forwards ports, and streams logs — all configured in a single devspace.yaml file.

DevSpace supports hot-reloading through bi-directional file sync, replacing the slow build-push-deploy cycle with instant code updates. It works with any Kubernetes cluster (local or remote) and integrates with existing Helm charts, Kustomize, and kubectl manifests.

Installation

# macOS
brew install devspace

# Linux
curl -L -o devspace "https://github.com/devspace-sh/devspace/releases/latest/download/devspace-linux-amd64"
chmod +x devspace
sudo mv devspace /usr/local/bin/

# Windows
choco install devspace

# npm
npm install -g devspace

# Verify
devspace --version

Core Commands

Command	Description
devspace init	Initialize devspace.yaml for a project
devspace dev	Start development mode (build, deploy, sync, port-forward)
devspace deploy	Build and deploy without dev mode
devspace build	Build images only
devspace purge	Delete deployed resources
devspace enter	Open shell in a container
devspace logs	Stream container logs
devspace ui	Open web-based UI
devspace list commands	List custom commands
devspace use context	Select kubectl context
devspace use namespace	Select namespace

Configuration

Basic devspace.yaml

version: v2beta1
name: my-app

pipelines:
  dev:
    run: |-
      run_dependencies --all
      ensure_pull_secrets --all
      build_images --all
      create_deployments --all
      start_dev --all

images:
  app:
    image: myregistry/my-app
    dockerfile: Dockerfile
    context: .

deployments:
  app:
    helm:
      chart:
        name: ./charts/my-app
      values:
        image: ${images.app.image}:${images.app.tag}

dev:
  app:
    imageSelector: ${images.app.image}
    sync:
      - path: ./src:/app/src
    ports:
      - port: "8080:8080"
    terminal:
      command: ./start-dev.sh

kubectl Manifests Deployment

version: v2beta1
name: my-app

images:
  app:
    image: my-app
    dockerfile: Dockerfile

deployments:
  app:
    kubectl:
      manifests:
        - k8s/deployment.yaml
        - k8s/service.yaml

dev:
  app:
    imageSelector: my-app
    sync:
      - path: ./src:/app/src
    ports:
      - port: "3000:3000"

Kustomize Deployment

deployments:
  app:
    kubectl:
      kustomize: true
      manifests:
        - kustomize/overlays/dev

Development Mode

File Sync

dev:
  app:
    imageSelector: ${images.app.image}
    sync:
      - path: ./src:/app/src
        excludePaths:
          - node_modules/
          - .git/
        uploadExcludePaths:
          - "*.pyc"
        onUpload:
          restartContainer: true

      - path: ./config:/app/config
        disableDownload: true

Port Forwarding

dev:
  app:
    imageSelector: ${images.app.image}
    ports:
      - port: "8080:8080"
      - port: "5432:5432"
        localAddress: "127.0.0.1"
    reversePorts:
      - port: "9229:9229"  # For debugging

Dev Container Replacement

dev:
  app:
    imageSelector: ${images.app.image}
    devImage: node:20-alpine
    command: ["sleep", "infinity"]
    workingDir: /app
    resources:
      requests:
        cpu: 500m
        memory: 512Mi
    env:
      - name: NODE_ENV
        value: development
    sync:
      - path: .:/app
    terminal:
      command: sh
    ports:
      - port: "3000:3000"

Pipelines

Custom Pipelines

pipelines:
  dev:
    run: |-
      run_dependencies --all
      build_images --all
      create_deployments --all
      start_dev --all

  deploy:
    run: |-
      run_dependencies --all
      build_images --all --tag ${DEVSPACE_GIT_COMMIT}
      create_deployments --all

  test:
    run: |-
      build_images --all
      create_deployments --all
      exec_container --label-selector app=my-app -- npm test
      purge_deployments --all

# Run specific pipeline
devspace run-pipeline deploy
devspace run-pipeline test

Custom Commands

commands:
  migrate:
    command: |-
      devspace enter -c app -- python manage.py migrate

  seed:
    command: |-
      devspace enter -c app -- python manage.py loaddata fixtures/seed.json

  shell:
    command: |-
      devspace enter -c app

devspace run migrate
devspace run seed
devspace run shell

Advanced Usage

Profiles

profiles:
  - name: production
    patches:
      - op: replace
        path: images.app.dockerfile
        value: Dockerfile.prod
    merge:
      deployments:
        app:
          helm:
            values:
              replicaCount: 3

  - name: debug
    merge:
      dev:
        app:
          ports:
            - port: "9229:9229"
          env:
            - name: NODE_OPTIONS
              value: "--inspect=0.0.0.0:9229"

# Use profile
devspace dev -p debug
devspace deploy -p production

Dependencies

dependencies:
  shared-lib:
    source:
      path: ../shared-lib
    pipeline: deploy

  database:
    source:
      path: ../database
    pipeline: dev

Variables

vars:
  IMAGE_TAG:
    source: env
    default: latest
  DEPLOY_ENV:
    question: "Which environment?"
    options:
      - dev
      - staging
      - production

images:
  app:
    image: myregistry/my-app
    tags:
      - ${IMAGE_TAG}

Hooks

hooks:
  - name: "pre-deploy"
    events: ["before:deploy"]
    command: "echo"
    args: ["Deploying..."]

  - name: "post-deploy"
    events: ["after:deploy"]
    container:
      imageSelector: ${images.app.image}
    command: "python"
    args: ["manage.py", "migrate"]

Troubleshooting

Issue	Solution
Sync not working	Check excludePaths; verify container path exists
Port forward fails	Check for local port conflicts
Image build fails	Run devspace build -v debug for details
Pod crash loop	Check devspace logs; verify devImage is correct
Slow sync	Add large dirs to excludePaths (node_modules, .git)
Context/namespace wrong	Run devspace use context and devspace use namespace

# Debug mode
devspace dev --debug

# Verbose logging
devspace dev -v debug

# Enter container shell
devspace enter

# View logs
devspace logs -f

# Reset devspace state
devspace reset pods

# Clean up everything
devspace purge

# Print resolved config
devspace print