Development Mode

Why?

The biggest advantages of developing directly inside Kubernetes is that your dev environment will be very similar to your production environment and you can have a much greater confidence that everything will work in production when shipping new features.

Kubernetes-based development can be useful in the following cases:

• Your applications needs to access cluster-internal services (e.g. Cluster DNS)
• You want to test your application in a production-like environment
• You want to debug issues that are hard to reproduce on your local machine

The development experience is very similar to using docker-compose, so if you are already familiar on how to develop with docker-compose, DevSpace will behave very similar. One of the major benefits of DevSpace versus docker-compose is that DevSpace allows you to develop in any Kubernetes cluster, either locally using minikube, Docker Kubernetes etc. or in any remote Kubernetes cluster.

Start Development Mode

Start the development mode using this command:

devspace dev

danger

It is highly discouraged to run devspace dev multiple times in parallel because multiple instances of port forwarding and file synchronization will disturb each other. Instead:

• Run devspace enter to open additional terminal sessions without port forwarding and file sync
• Run devspace logs to start log streaming without port forwarding and file sync
• Run devspace sync to sync files on-demand without starting port forwarding etc.
• Run devspace ui to open the localhost development UI in the browser

Important Flags for devspace dev

The following flags are available for all commands that trigger image building:

• -t / --terminal starts a terminal to a container
• -d / --force-deploy redeploy all deployments (even if they could be skipped because they have not changed)
• -b / --force-build rebuild all images (even if they could be skipped because context and Dockerfile have not changed)

Development Process

The development process first runs the deployment process (1. - 4.) and then continues with starting the development-specific features.

1. Deploy Dependencies

DevSpace loads the dependencies section from the devspace.yaml and creates a dependency tree. The current project will represent the root of this tree. Based on this dependency tree, DevSpace will start from the leaves and run these steps for each dependency:

• Build images of the dependency as configured in the images section of the dependency's devspace.yaml (unless skipBuild: true)
• Deploy the dependency as configured in the deployments section of the dependency's devspace.yaml

What are Dendencies?

Dependencies allow you to deploy microservices, that the project you are currently deploying relies on. Dependencies can be located in a subpath of your project or they can be automatically loaded from a different git repository.

2. Build, Tag & Push Images

DevSpace triggers the image building process for the images specified in the images section of the devspace.yaml.

3. Tag Replacement

After finishing the image building process, DevSpace searches your deployments for references to the images that are specified in the images section of the devspace.yaml. If DevSpace finds that an image is used by one of your deployments and the deployment does not explicitly define a tag for the image, DevSpace will append the tag that has been auto-generated as part of the automated image tagging during the image building process.

Prevent Hard-Coded Tags

To use automated tag replacement, make sure you do not specify image tags in the deployment configuration.

Replacing or appending tags to images that are used in your deployments makes sure that your deployments are always started using the most recently pushed image tag. This automated process saves a lot of time compared to manually replacing image tags each time before you deploy something.

DevSpace will replace the following things:

• registry.url/repo/name that corresponds to a images.*.image, will be rewritten to registry.url/repo/name:generated_tag
• ${runtime.images.image-key.image} that corresponds to a images.* key, will be rewritten to registry.url/repo/name. You can also use dependency images here with ${runtime.dependencies.dep1.images.dep-image.image}
• ${runtime.images.image-key.tag} that corresponds to a images.* key, will be rewritten to generated_tag. You can also use dependency images here with ${runtime.dependencies.dep1.images.dep-image.tag}

4. Deploy Project

DevSpace iterates over every item in the deployments array defined in the devspace.yaml and deploys each of the deployments using the respective deployment tool:

• kubectl deployments will be deployed with kubectl (optionally using kustomize if kustomize: true)
• helm deployments will be deployed with the helm client that comes in-built with DevSpace

kubectl Required

Deployments with kubectl require kubectl to be installed.

5. Start Port-Forwarding

DevSpace iterates over every item in the dev.ports array defined in the devspace.yaml and starts port-forwarding for each of the entries and the port mappings they define in the forward section.

note

Before starting the actual port-forwarding threads, DevSpace waits until the containers and services are ready.

info

Port-Fowarding allows you to access your containers and Kubernetes services via localhost.

For detailed logs about the port-forwarding, take a look at .devspace/logs/portforwarding.log.

6. Start File Synchronization

DevSpace iterates over every item in the dev.sync array defined in the devspace.yaml and starts a bi-directional, real-time code synchronization for each of the entries and the path mappings they define.

Initial Sync

Right after starting the file synchronization, DevSpace runs the so-called initial sync which quickly computes the differences between your local folders and the remote container filesystems. If DevSpace detects changes, it synchronizes them first to get a clean state before starting the real-time synchronization which is invoked every time a file changes.

For detailed logs about the file synchronzation, take a look at .devspace/logs/sync.log for the current session and .devspace/logs/sync.log.old for previous logs.

7. Stream Logs or Open Terminal

DevSpace provides two options to develop applications in Kubernetes:

• using multi-container log streaming (default)
• using an interactive terminal session (run devspace dev -i)

Multi-Container Log Streaming (default)

The first option starts your application as defined in your Dockerfile or in your Kubernetes pod definition. After the pods are started, DevSpace streams the logs of all containers that are started with an image that was built during the image building process. Each log line is prefixed with the image name or alternatively with the pod name of the container. Before starting the actual log streaming, DevSpace prints the last 50 log lines of each container by default.

Learn how to customize which containers should be included in the log stream and how many log lines should be shown in the beginning.

Terminal Session

To start a terminal mode, run:

devspace dev -t

Instead of starting the multi-container log streaming, you can also start development mode using a terminal session.

Terminal is configurable by using the dev.terminal configuration section.

8. Open Links (optional)

DevSpace iterates over every item in the dev.open array defined in the devspace.yaml and tries to open the URL you provide for each item using the following method:

1. DevSpace starts to periodically send HTTP GET requests to the URLs provided via dev.open[*].url.
2. As soon as the first HTTP response has a status code which is neither 502 (Bad Gateway) nor 503 (Service Unavailable), DevSpace assumes that the application is now started, stops sending any further requests and opens the provided URL in the browser.
3. If the URL is still returning status code 502 or 503 after 4min, DevSpace will stop trying to open it. To not disturb the log streaming or the interactive terminal session, DevSpace will not show an error when hitting the 4min timeout.

Learn more about configuring auto-opening links.

Useful Commands

devspace enter

The command devspace dev -t starts a terminal but it also starts port-forwarding and file synchronization which can only be opened once. However, you often need additional terminal sessions. To open a simple terminal session without starting port-forwarding and file sync, run the following command:

devspace enter

If you do not provide a selector (e.g. pod name, label selector or image selector), DevSpace will show a picker with all available pods and containers.

note

This command is a general purpose command which also works for any pod/container in Kubernetes even if you are not within a DevSpace project.

devspace logs [-f]

If you want to print or stream the logs of a single container, run:

# Print logs
devspace logs

# Stream logs
devspace logs -f

If you do not provide a selector (e.g. pod name, label selector or image selector), DevSpace will show a picker with all available pods and containers.

note

This command is a general purpose command which also works for any pod/container in Kubernetes even if you are not within a DevSpace project.

devspace sync

If you want to start code synchronization on-demand (and even outside a DevSpace project), you can run commands like the ones shown here:

devspace sync --local-path=subfolder --container-path=/app
devspace sync --exclude=node_modules --exclude=test
devspace sync --pod=my-pod --container=my-container

If you do not provide a selector (e.g. pod name, label selector or image selector), DevSpace will show a picker with all available pods and containers.

note

This command is a general purpose command which also works for any pod/container in Kubernetes even if you are not within a DevSpace project.

devspace open

To view your project in the browser either via port-forwarding or via ingress (domain), run the following command:

devspace open

When DevSpace asks you how to open your application, you have two options as shown here:

? How do you want to open your application?
  [Use arrows to move, space to select, type to filter]
> via localhost (provides private access only on your computer via port-forwarding)
  via domain (makes your application publicly available via ingress)

To use the second option, you need to make sure that the DNS of your domain points to your Kubernetes cluster and that you have an ingress-controller running in your cluster.

Automatic Error Analytics

If your application does not open as exepected, run devspace analyze and DevSpace will try to identify the issue.

devspace analyze

If your application is not starting as expected or there seems to be some kind of networking issue, you can let DevSpace run an automated analysis of your namespace using the following command:

devspace analyze

After analyzing your namespace, DevSpace compiles a report with potential issues, which is a good starting point for debugging and fixing issues with your deployments.

devspace list commands

DevSpace allows you to share commands for common development tasks which can be executed with devspace run [command-name]. To get a list of available commands, run:

devspace list commands

Learn how to configure shared commands for devspace run.

devspace list deployments

To get a list of all deployments as well as their status and other information, run the following command:

devspace list deployments

devspace purge

If you want to delete a deployment from Kubernetes you can run:

# Removes all deployments remotely
devspace purge
# Removes deployment with given name
devspace purge --deployments=my-deployment-1,my-deployment-2

danger

Purging a deployment does not remove it from the deployments section in the devspace.yaml. It just removes the deployment from the Kubernetes cluster. To remove a deployment from devspace.yaml, run devspace remove deployment [NAME].

devspace update dependencies

If you are using dependencies from other git repositories, use the following command to update the cached git repositories of dependencies:

devspace update dependencies