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.

note

localRegistry currently only supports docker and buildkit

Defaults

# 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
#   namespace: [KUBE CONTEXT NAMESPACE]
#   localbuild: false
#   image: registry:2.8.1
#   port: 5000

Build locally with Docker/Podman

# The local registry will not use buildkit on the cluster, but your docker/podman daemon
# and then push it to the local registry in the cluster
localRegistry:
  localbuild: true

Force Local Registry

# The local registry will use an emptyDir volume by default. If the registry is restarted all
# previously pushed images will be lost. If you wish to add persistence, here is an example
# using the cluster's default storage class and a 10Gi volume size.
localRegistry:
  persistence:
    enabled: true
    size: 10Gi

Persistence

# If you want to always use the local registry.
localRegistry:
  enabled: true

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.

devspace.yaml

images:
  backend:
    image: ghcr.io/org/project/image           # localhost:[NODE_PORT]/org/project/image
  backend-dev:
    image: ghcr.io/org/project/image-dev       # localhost:[NODE_PORT]/org/project/image-dev

deployments:
  backend:
    helm:
      values:
        containers:
          - image: ghcr.io/org/project/image   # localhost:[NODE_PORT]/org/project/image

dev:
  backend:
    imageSelector: ghcr.io/org/project/image   # localhost:[NODE_PORT]/org/project/image
    devImage: ghcr.io/org/project/image-dev    # 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:

• $DEVSPACE_HOOK_IMAGE_NAME

Configuration

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