Skip to content


User Configuration

Each developer's workstation requires a configuration file located at ~/.kelda.yaml.

# The version of the configuration format.
version: v1alpha1

# A unique namespace that will be used for the development namespace.
namespace: user

# The Kubernetes cluster to use for development. The name of the current
# cluster can be retrieved through `kubectl config current-context`.
context: dev-cluster

# The path to the configuration for deploying the application.
# More explanation on the workspace.yaml is below.
workspace: ~/kelda-workspace/workspace.yaml


This configuration can be generated using the Kelda CLI.

  1. Ensure that the current Kubernetes context is set to the development cluster. You can verify this with kubectl config current-context.
  2. cd into the Kelda workspace directory.
  3. Run kelda config.

    The config command is used to set up a user-specific configuration for Kelda. Running this command will ask you a couple of questions.

    After completing these configuration prompts, a Kelda configuration file will be written to your home directory.

    Wrote config to /home/user/.kelda.yaml



The Kubernetes context for the Kelda Kubernetes cluster. Kelda connects to the remote cluster by looking up the cluster and authentication information for this context in your local kubeconfig file.


The namespace in the Kubernetes cluster that the Kubernetes objects will be deployed to.

This namespace is created and managed by Kelda, but you can also interact directly with it with kubectl. For example, to get detailed information on pods, run

kubectl describe pods -n <namespace>


The path to the workspace.yaml file that describes what services should be deployed to the development cluster.


The version of the configuration file format. Only v1alpha1 is currently supported.

Workspace Configuration

The workspace.yaml file specifies what services and tunnels should be created in the development namespace.

# Sample workspace.yaml file that defines three services, and proxies
# ports from one service to the local workstation.

version: "v1alpha1"

- name: "authorization-api"
- name: "web-server"
- name: "content-api"

- serviceName: "gateway"
  remotePort: 80
  localPort: 8080

# Sample workspace directory structure. Each service defined in the
# workspace.yaml file must have a corresponding directory.

├── workspace.yaml
├── authorization-api
│   ├── deployment-authorization-api.yaml
│   └── service-authorization-api.yaml
├── content-api
│   ├── configmap-scss-compiler-config.yaml
│   ├── deployment-content-api.yaml
│   └── service-content-api.yaml
└── web-server
    ├── configmap-web-app-config.yaml
    ├── deployment-web.yaml
    └── service-web.yaml



- name: "authorization-api"
- name: "web-server"
- name: "content-api"

A list of service objects that describe what services should be deployed. The only field is name.

Each service name must have a corresponding directory containing the Kubernetes YAML for that service. The service name is the identifier used by the kelda logs and kelda ssh commands, as well as the name field of the Sync configuration.

In the example above we have defined three services, and each service that is defined in the workspace.yaml file has its own directory which defines the Kubernetes configuration for that service.


- serviceName: "gateway"
  remotePort: 80
  localPort: 8080

A list of tunnel objects for accessing remote services directly from your local machine.

In the example above, we are proxying port 80 on the remote gateway service to port 8080 on our local workstation.

The serviceName, localPort, and remotePort fields are required.


The version of the configuration file format. Only v1alpha1 is currently supported.

Registry Credentials

The regcred secret in the kelda namespace is automatically copied to each development namespace and added to the default Service Account.

You can create this secret by running the following command:

kubectl create secret docker-registry regcred -n kelda \
    --docker-server \
    --docker-username=USERNAME \
    --docker-password=PASSWORD \

Note: Since every developer will have access to this secret, we recommend using a service account instead of a user-specific Dockerhub account.

Sync Configuration

The directory from which kelda dev is run must have a configuration file named kelda.yaml that specifies how to run the service in development mode.

# REQUIRED. The version of the configuration format.
version: "v1alpha1"

# REQUIRED. Name of the service. Must match the name in workspace.yaml.

# REQUIRED. The files to sync from the local machine to the container.
  except: ['.git']
- from: SRC
  to: DST
  triggerInit: true

# OPTIONAL. The image to run.
# If not set, Kelda uses the same image as when not developing.
image: DEV_IMAGE

# OPTIONAL. The command to run in the development container after each file sync.
# If not set, Kelda uses the same command as when not developing.
command: ['DEV_COMMAND']

# OPTIONAL. The command to run for sync rules that have `triggerInit` set
# to true (e.g. the second rule above).
initCommand: ['INIT_COMMAND']



The name of the service. This must match the name used in the Workspace configuration.


The main process run by the container. It is restarted after each file change.

Must be a list of strings.


An optional command that can be triggered when certain files are synced. After the initCommand completes successfully, the normal command is run.

Must be a list of strings.


A list of sync rules that describe how files are synced from the local filesystem to the remote container.

from and to are the paths in the local and remote container, and are required.

except is an optional list of paths to ignore within the from and to paths. For example, the following sync rule ignores local/node_modules, remote/node_modules, and local/node_modules/express.

from: local
to: remote
except: ['node_modules']

triggerInit is an optional flag that causes the initCommand to be run before the command is restarted. It defaults to false.


image is an optional override for the image to be used when running in development mode. By default, Kelda uses the image in the Kubernetes object in the Workspace configuration.


The version of the configuration file format. Only v1alpha1 is currently supported.