There are a number of patterns for developing applications that are ultimately deployed onto Kubernetes from within Gitpod, we’ve summarized some of the main approaches below with some of their advantages and limitations.

  1. Using Docker in Gitpod
  2. Using Docker Compose in Gitpod
  3. Using a Kubernetes Network Proxy in Gitpod (e.g. Telepresence)
  4. Running Kubernetes clusters in Gitpod (e.g. MiniKube)
  5. Connecting to a remote Kubernetes cluster inside Gitpod

1. Using Docker in Gitpod

Gitpod integrates Docker, enabling you to build, run and manage Docker containers directly within their development environments. Inside a Gitpod workspace, you can run Docker commands as you would locally. Or, configure your .gitpod.yml so your containers automatically spin up as soon as your Gitpod workspace starts. Below is an example configuration based on Docker’s getting started guide.

Note: Running Docker in Gitpod is not to be confused with Docker support for workspace images. The workspace environment itself can also be based upon a Docker image, but that doesn’t prevent you from running one or many docker containers inside a Gitpod workspace.

    - init: docker build -t getting-started .
      command: docker run -dp getting-started

    - port: 3000
      onOpen: open-preview
      visibility: private


  • All you need is to add a docker run command to your .gitpod.yml
  • You can use Docker in Gitpod without impacting your local machine performance.
  • You can run as many Docker containers as you need within a Gitpod workspace.
  • You can run multiple workspaces in parallel with running docker containers.

2. Using Docker Compose in Gitpod 

Gitpod supports the execution of multi-container Docker applications, if you want to try it in action,  here’s an example rails application using docker-compose.. The benefits and drawbacks are the same listed for Docker, docker-compose is an additional convenience wrapper to run multiple containers, and is also supported by Gitpod. Plus with an additional advantage of when configured in the .gitpod.yml file, containers become instantly accessible upon the initiation of the workspace.

To run docker-compose in a .gitpod.yml:

language icon bash
    - command: docker-compose up

3. Using a Kubernetes Network Proxy in Gitpod (e.g. Telepresence)

Network proxy solution tools like Telepresence work by creating a secure tunnel between your Gitpod workspace and a remote Kubernetes cluster, allowing your service that is running in a Gitpod workspace to communicate as if the service were running within the cluster itself. This method of network proxying enables real-time code changes and testing in the context of the full application stack, without the need to deploy to the cluster and waiting for changes to be applied.

One challenge in using these types of proxy tools is how developers have to learn, understand and configure the tool themselves. With Gitpod you can automate the installation and configuration of tools like Telepresence so your development environments are always working. To learn more and see how a network proxy can be set up see our Telepresence guide.


  • Accelerates code/build/test cycles compared to build/push/wait CI cycles.
  • Helps test development environments in realistic “production-like” environments.
  • Run a single service in Gitpod and leverage a remote cluster for reproducibility
  • Twinned with Gitpod you can automate your Proxy settings and configurations.
  • Can reduce cloud costs by optimizing usage (e.g. sharing remote clusters).

Telepresence is a popular choice for network proxying with Kubernetes, but other tools exist on the market: MirrorD, Gefyra and others, depending on your preferences.

4. Running Kubernetes clusters in Gitpod (e.g. MiniKube)

Note: Due to the virtualisation constraints of Gitpod workspaces, it is not currently possible to run entire Kubernetes clusters inside of a Gitpod workspaces using tools like MiniKube or Kind.

If your goal is to align your development and production configurations, running the entire cluster locally is not a silver bullet. Given the options listed on this page, we are very confident you can craft a compelling, cost-effective, developer-first experience for developers building Kubernetes applications without neeidng to emulate an entire distributed Kubernetes cluster inside a single machine (workspace).

With Gitpod, you can give your developers the tools and configurations they already know, such as Docker and Docker Compose. You can scale their setup far beyond your typical laptops and local machines using cloud compute, and then automate incredibly fast feedback loops to any remote clusters for further testing using Gitpod.

Additionally, you can use tools like Tilt, DevSpaces and Skaffold with Gitpod.

5. Connecting to a remote Kubernetes cluster inside Gitpod

Sometimes your development environment consists of more resources than ever will practically fit inside a Gitpod workspace. Let’s say that you are working with remote resources outside the Gitpod workspace, such as connecting to a Kubernetes cluster, a cloud database, or other external resources. With Gitpod you can automate the installation of tools into your workspace, but you can also automate the secrets and access necessary to make connections to external resources such as a Kubernetes cluster.


  • Work directly on the actual infrastructure that the application will eventually run on
  • You are not constrained by local resources (e.g. laptop)
  • Flexibility to manage clusters from development to production

Authenticating with kubectl from a Gitpod workspace

The following is a basic example of how you can connect to a remote Kubernetes cluster. It shows you how to configure kubectl to connect to an external environment using environment variables in Gitpod.

Note For a more secure and scalable solution, consider setting up Workspace OIDC authentication with a secrets manager such as Vault, or AWS Secrets Manager to benefit from centralized secrets management.

  1. Navigate to Gitpod’s environment variables section in the Gitpod dashboard
  2. Add variable KUBECONFIG and paste your kubeconfig (base64 format)
  3. Add a .gitpod.Dockerfile to ensure that kubectl is installed

An example Dockerfile that includes kubectl:

FROM gitpod/workspace-base:latest

## Install Kubectl

RUN curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" && \
   chmod +x ./kubectl && \
   sudo mv ./kubectl /usr/local/bin/kubectl && \
   mkdir ~/.kube

Now, run kubectl config get-clusters to get a view of all your clusters.

For more on authenticating with kubectl see this sample repo.

Was this helpful?