Skip to content

The Workspace Configuration

After completing this guide, you will have the necessary Workspace configuration for Kelda to boot your services in the development environment. Once you have this foundation, you will be able to write the Sync configuration to deploy local versions of services.


The Workspace configuration has two parts:

  1. A workspace.yaml file that describes what services and tunnels should be created in the development environment.
  2. A directory per service that contains the Kubernetes YAML for each service.

When Kelda boots, it initializes the development environment by:

  1. Getting the list of services to deploy from the workspace.yaml file.
  2. Deploying the Kubernetes YAML in each directory referenced in the service list.
  3. Creating tunnels between the local machine and remote cluster according to the tunnels in the workspace.yaml file.

Example workspace.yaml

The following workspace.yaml file is from the Node Todo example application.

For more explanation on the workspace.yaml format see the docs here.

# The version of the configuration format. This doesn't need to be changed.
version: "v1alpha1"

# Note how each service has a corresponding directory in the "Example
# Directory Structure" section below.
  - name: "mongodb"
  - name: "web-server"

# Requests to localhost:8080 will get forwarded to port 8080 in the
# web-server service.
# Note how the "web-server" service name is also in the "services" list above.
- serviceName: "web-server"
  remotePort: 8080
  localPort: 8080

Example Directory Structure

The Node Todo example application has the following directory structure. Note how there's a workspace.yaml file, along with a directory for each service referenced in the file.

├── mongodb
│   ├── mongodb-secret.yaml
│   ├── mongodb-statefulset.yaml
│   └── mongodb-svc.yaml
├── web-server
│   ├── web-server-dep.yaml
│   └── web-server-svc.yaml
└── workspace.yaml


  1. Create a directory for your workspace configuration.

    mkdir kelda-config
  2. Create the workspace.yaml file, adding service names and tunnels as appropriate for your application.

    version: "v1alpha1"
      - name: <name of first service>
      - name: <name of second service>
  3. Gather your Kubernetes YAML used for deploying the services.

    • If you have production Kubernetes YAML, then you're good to go.
    • If you're using Helm, place the Helm chart in the workspace directory according to these instructions.
    • If you're using Docker Compose, use kompose to convert your docker-compose.yml into Kubernetes YAML.
    Special handling for Docker Compose volumes

    Edit the Docker Compose file so that it doesn't have Docker-specific volume configuration since this is handled differently in Kubernetes.

    • volumes_from for data containers should use the InitContainer and shared volume approach described here.
    • All syncing should use Kelda's Sync configuration to define which files need to be synced.
  4. Modify your Kubernetes YAML to be suitable for the development environment.

    Although any Kubernetes YAML can be used with Kelda, production deployments often need to be tweaked to be suitable for development environments. See this guide for some common changes.

  5. Group your Kubernetes YAML into services.

    Create a directory per service containing the Kubernetes YAML for that service. Remember that the directory name must correspond with the name used in your workspace.yaml.

  6. If your Kubernetes YAML references private Docker images, grant Kelda access to pull them by following the instructions here.

  7. Point your user configuration at your new workspace.

    In the kelda-config directory that you created in step 1, run

    kelda config

    and answer the questions. This will update your ~/.kelda.yaml file so that the workspace field points at your newly created Workspace configuration.

  8. Test your Kubernetes YAML by deploying it with Kelda.

    The following command will deploy all the services in the workspace.yaml file. We're using the --no-sync flag because we haven't written any Sync configuration yet to tell Kelda what files to sync.

    kelda dev --no-sync

    If all goes well, your services should enter the Ready state. If not, follow the next step to fix your Kubernetes YAML.

  9. Modify your Kubernetes YAML until your application behaves as expected.

    To debug Kubernetes issues, access the cluster directly with

    kubectl --namespace <namespace in ~/.kelda.yaml>

    You will need to re-run kelda dev in order to deploy modifications to your YAML.

  10. Add tunnels to your workspace.yaml file. These can be used to test your application.

    - serviceName: <name from above list>
      remotePort: <port in container>
      localPort: <port on localhost>

    You will need to re-run kelda dev in order to deploy modifications to your workspace.yaml.