Skip to main content
Version: 6.x (Latest)

Local Registry

DevSpace will detect when the local environment lacks push permissions for an image's registry. If the destination cluster is a local KinD cluster, images will be loaded using kind load docker-image. For other clusters, DevSpace will deploy a local image registry to the cluster and update the image URLs to use this local registry.

Unless persistence is enabled, the local registry will be deployed using a Deployment and an emptyDir volume, meaning your registry images will not be persisted during local registry restarts. Persistence using a StatefulSet and persistent volumes can be configured if you wish to avoid repeated image pushes.

Local registry configuration is defined in the localRegistry section of the devspace.yaml.


localRegistry currently only supports docker and buildkit

# If you do not configure anything, the local registry will be deployed with the following
# defaults when the image cannot be pushed and 'kind load docker-image' cannot be used.
# localRegistry:
# name: registry
# localbuild: false
# image: registry:2.8.1
# port: 5000

Image URLs

The local registry is deployed with a NodePort service and will be assigned a port by the Kubernetes control plane. DevSpace will transparently update all image URLs to refer to the local registry using localhost:[NODE_PORT]. This applies to every location the image is used, however no modifications will be saved to the devspace.yaml on disk.

image: # localhost:[NODE_PORT]/org/project/image
image: # localhost:[NODE_PORT]/org/project/image-dev

- image: # localhost:[NODE_PORT]/org/project/image

imageSelector: # localhost:[NODE_PORT]/org/project/image
devImage: # localhost:[NODE_PORT]/org/project/image-dev

Runtime Variables

In addition to image URLs, the following runtime variables are updated to the local registry URL:

  • runtime.images.IMAGE_NAME
  • runtime.images.IMAGE_NAME.image

Similarly, the following hook environment variable is updated to the local registry URL:



localRegistry required

LocalRegistry specifies the configuration for a local image registry

enabled required boolean false

Enabled enables the local registry for pushing images. When unset the local registry will be used as a fallback if there are no push permissions for the registry. When true the local registry will always be used. When false the local registry will never be used.

localbuild required boolean false

LocalBuild enables use of local docker builder instead of building in the cluster

namespace required string

Namespace where the local registry is deployed. Default is the current context's namespace

name required string

Name of the deployment and service of the local registry. Default is registry

image required string

Image of the local registry. Default is registry:2.8.1

buildKitImage required string

BuildKitImage of the buildkit sidecar. Default is moby/buildkit:master-rootless

port required integer

Port that the registry image listens on. Default is 5000

persistence required

Persistence settings for the local registry

enabled required boolean false

Enable enables persistence for the local registry

size required string

Size of the persistent volume for local docker registry storage. Default is 5Gi

storageClassName required string

StorageClassName of the persistent volume. Default is your cluster's configured default storage class