Verdaccio

Verdaccio is a lightweight private Node.js proxy registry.

TL;DR;

$ helm repo add verdaccio https://charts.verdaccio.org
$ helm repo update
$ helm install verdaccio verdaccio/verdaccio

⚠️ If you are using stable/verdaccio chart, be aware is deprecated, forward all new PR and or issues to this repository.

If you need support for Helm v2, please use <=v0.19.0, be aware we do not support Helm v2 anymore.

Introduction

This chart bootstraps a Verdaccio deployment on a Kubernetes cluster using the Helm package manager.

Prerequisites

• Kubernetes 1.7+ with Beta APIs enabled
• PV provisioner support in the underlying infrastructure

Installing the Chart

Add repository

helm repo add verdaccio https://charts.verdaccio.org

Install Verdaccio chart

In this example we use npm as release name:

# Helm v3+
helm install npm verdaccio/verdaccio

Note: Avoid release name verdaccio, otherwise, Kubernetes-generated environment variables may get into conflict with Verdaccio's own environment variables in the Pod itself. In case you insist naming the release verdaccio, to mitigate the problem, you can use either nameOverride or fullnameOverride to have a different name for the service.

Deploy a specific version

# Helm v3+
helm install npm --set image.tag=7.0.0 verdaccio/verdaccio

Chart 7.0.0 and later deploy Verdaccio 7. To stay on the Verdaccio 6.x line, pin the image or the chart:

# Verdaccio 6.x image with the current chart
helm install npm --set image.tag=6.11.1 verdaccio/verdaccio
# or the last chart of the 4.x series
helm install npm --version 4.36.0 verdaccio/verdaccio

Upgrading Verdaccio

helm upgrade npm verdaccio/verdaccio

The command deploys Verdaccio on the Kubernetes cluster in the default configuration. The configuration section lists the parameters that can be configured during installation.

Tip: List all releases using helm list

Uninstalling the Chart

To uninstall/delete the npm deployment:

# Helm v3+
helm uninstall npm

The command removes all the Kubernetes components associated with the chart and deletes the release.

Configuration

The following table lists the configurable parameters of the Verdaccio chart and their default values.

Parameter	Description	Default
type	The type of resource to create. Either deployment or statefulset. Note: Statefulset is primarly useful when Verdaccio is being used as an edge cache	deployment
annotations	Annotations to set on the deployment	{}
affinity	Affinity for pod assignment	{}
existingConfigMap	Name of custom ConfigMap to use	false
image.pullPolicy	Image pull policy	IfNotPresent
image.pullSecrets	Image pull secrets	[]
image.repository	Verdaccio container image repository	verdaccio/verdaccio
image.tag	Verdaccio container image tag. Also used as app.kubernetes.io/version label when set	defaults to appVersion in Chart.yaml
nodeSelector	Node labels for pod assignment	{}
tolerations	List of node taints to tolerate	[]
persistence.accessMode	PVC Access Mode for Verdaccio volume	ReadWriteOnce
persistence.annotations	Annotations to add to the PVC	{}
persistence.enabled	Enable persistence using PVC	true
persistence.existingClaim	Use existing PVC. Ignored when type is statefuleset	nil
persistence.mounts	Additional mounts	nil
persistence.resourcePolicy	Set "keep" to avoid removing PVC during a helm delete operation	""
persistence.selector	Selector to match an existing Persistent Volume	{} (evaluated as a template)
persistence.size	PVC Storage Request for Verdaccio volume	8Gi
persistence.storageClass	PVC Storage Class for Verdaccio volume	nil
persistence.volumes	Additional volumes	nil
topologySpreadConstraints	Topology Spread Constraints for pod assignment	[]
podLabels	Additional pod labels	{} (evaluated as a template)
podAnnotations	Annotations to add to each pod	{}
priorityClass.enabled	Enable specifying pod priorityClassName	false
priorityClass.name	PriorityClassName to be specified in pod spec	""
replicaCount	Desired number of pods	1
replicaCountEnabled	Enable the replicaCount field	true
autoscaling.enabled	Enable the HorizontalPodAutoscaler (omits replicas so the HPA owns it)	false
autoscaling.minReplicas	Minimum number of replicas	2
autoscaling.maxReplicas	Maximum number of replicas	5
autoscaling.targetCPUUtilizationPercentage	Target CPU utilization percentage	80
autoscaling.targetMemoryUtilizationPercentage	Target memory utilization percentage	none
autoscaling.behavior	Scaling behavior policies for the HPA	{}
podDisruptionBudget.enabled	Enable a PodDisruptionBudget	false
podDisruptionBudget.maxUnavailable	Maximum number/percentage of pods that can be unavailable	1
podDisruptionBudget.minAvailable	Minimum number/percentage of pods that must remain available (mutually exclusive with maxUnavailable)	none
strategy	The deployment strategy field	If persistence is enabled, the strategy type is set to Recreate, otherwise RollingUpdate
livenessProbe	Configuration of liveness probe	{}
readinessProbe	Configuration of readiness probe	{}
resources	CPU/Memory resource requests/limits	{}
service.annotations	Annotations to add to service	none
service.clusterIP	IP address to assign to service	""
service.externalIPs	Service external IP addresses	[]
service.loadBalancerIP	IP address to assign to load balancer (if supported)	""
service.loadBalancerSourceRanges	List of IP CIDRs allowed access to load balancer (if supported)	[]
service.port	Service port to expose	4873
service.nodePort	Service port to expose	none
service.type	Type of service to create	ClusterIP
serviceAccount.create	Create service account	false
serviceAccount.name	Service account Name	none
extraEnvVars	Define environment variables to be passed to the container	[]
secretEnvVars	Define sensitive environment variables to be passed to the container	{}
existingSecret	Existing secret containing environment variables to be passed to the container	""
extraInitContainers	Define additional initContainers to be added to the deployment	[]
securityContext	Define Container Security Context	{runAsUser=10001}
podSecurityContext	Define Pod Security Context	{fsGroup=101}
nameOverride	Set resource name override	""
fullnameOverride	Set resource fullname override	""
useSecretHtpasswd	Use htpasswd from .Values.secrets.htpasswd. This require helm v3.2.0 or above.	false
secrets.htpasswd	user and password list to generate htpasswd.	[]
secrets.existingSecretHtpasswd	Existing secret containing htpasswd file (alternative to secrets.htpasswd)	""
secrets.existingSecretHtpasswdKey	Key in the existing secret that contains the htpasswd file content	"htpasswd"
gatewayApi.enabled	Enable/Disable Gateway API HTTPRoute (alternative to Ingress)	false
gatewayApi.parentRefs	List of parent Gateway references	[]
gatewayApi.hostnames	List of hostnames for the HTTPRoute	[]
gatewayApi.annotations	HTTPRoute Annotations	{}
gatewayApi.labels	HTTPRoute Labels	{}
gatewayApi.rules	Custom HTTPRoute routing rules. Defaults to PathPrefix / if not set	nil
ingress.enabled	Enable/Disable Ingress	false
ingress.className	Ingress Class Name (k8s >=1.18 required)	""
ingress.labels	Ingress Labels	{}
ingress.annotations	Ingress Annotations	{}
ingress.hosts	List of Ingress Hosts	[]
ingress.paths	List of Ingress Paths	["/"]
ingress.extraPaths	List of extra Ingress Paths	[]
extraPorts	List of extra ports to expose from the pods	[]
extraManifests	List of extra manifests to deploy within the chart	[]

Specify each parameter using the --set key=value[,key=value] argument to helm install. For example,

# Helm v3+
$ helm install my-release \
  --set service.type=LoadBalancer \
    verdaccio/verdaccio

The above command sets the service type LoadBalancer.

Alternatively, a YAML file that specifies the values for the above parameters can be provided while installing the chart. For example,

# Helm v3+
$ helm install npm -f values.yaml verdaccio/verdaccio

Tip: You can use the default values.yaml

Generate htpasswd using helm

This requires helm v3.2.0 or above. You can list all username and password in .Values.secrets.htpasswd. Helm will generate secret with htpaswd format. This file is mounted on pod in this path /verdaccio/auth/htpasswd. The Default config uses this. The conditional statement {{- if .Values.secrets.htpasswd }} is evaluated as false if the list is an empty collection. (Source helm flow control)

Tip: These values are in plaintext. So don't forget to put additional encryption.

Example

secrets:
  # list of users and password for htpasswd plugin
  # This this is mounted as /verdaccio/auth/htpasswd on pods
  htpasswd:
    - username: "verdaccio"
      password: "verdaccio"

This config will create a htpasswd file with user "verdaccio", If in config 'htpasswd' auth is used. You can login using this credentials.

Use existing secret for htpasswd

Instead of providing plain text credentials in values.yaml, you can reference an existing Kubernetes secret containing the htpasswd file. This is more secure as it avoids storing passwords in plain text in your values files.

When secrets.existingSecretHtpasswd is set, the chart will use the specified secret instead of generating one from secrets.htpasswd. The secret must contain a key with the htpasswd file content (default key: htpasswd, configurable via secrets.existingSecretHtpasswdKey).

Example

secrets:
  # Reference an existing secret instead of providing plain text credentials
  existingSecretHtpasswd: "my-htpasswd-secret"
  existingSecretHtpasswdKey: "htpasswd"  # Optional, defaults to "htpasswd"

The existing secret should contain the htpasswd file content in the specified key. You can create such a secret using:

kubectl create secret generic my-htpasswd-secret \
  --from-file=htpasswd=/path/to/htpasswd

Note: If both secrets.htpasswd and secrets.existingSecretHtpasswd are set, secrets.existingSecretHtpasswd takes precedence and no secret will be generated from secrets.htpasswd.

Important: When using an existing secret, pods will not automatically restart when the secret content is updated. This is a limitation of Kubernetes - it doesn't track changes to external secrets. You need to manually trigger a pod restart after updating the secret:

kubectl rollout restart deployment/<release-name>-verdaccio

Gateway API (HTTPRoute)

As an alternative to traditional Ingress, this chart supports creating an HTTPRoute resource for use with the Gateway API. This requires a Gateway API implementation (e.g., Envoy Gateway, Istio, Cilium, nginx-gateway-fabric) and a Gateway resource already deployed in your cluster.

Example

gatewayApi:
  enabled: true
  parentRefs:
    - name: my-gateway
      namespace: default
  hostnames:
    - npm.example.com

Note: The chart only creates an HTTPRoute — the Gateway resource itself should be managed separately as cluster infrastructure. Both ingress and gatewayApi can coexist if needed during migration.

Custom ConfigMap

When creating a new chart with this chart as a dependency, CustomConfigMap can be used to override the default config.yaml provided. It also allows for providing additional configuration files that will be copied into /verdaccio/conf. In the parent chart's values.yaml, set the value to true and provide the file templates/config.yaml for your use case.

Persistence

The Verdaccio image stores persistence under /verdaccio/storage path of the container. A dynamically managed Persistent Volume Claim is used to keep the data across deployments, by default. This is known to work in GCE, AWS, and minikube. Alternatively, a previously configured Persistent Volume Claim can be used.

It is possible to mount several volumes using Persistence.volumes and Persistence.mounts parameters.

Existing PersistentVolumeClaim

1. Create the PersistentVolume
2. Create the PersistentVolumeClaim
3. Install the chart

# Helm v3+
$ helm install npm \
    --set persistence.existingClaim=PVC_NAME \
    verdaccio/verdaccio

Migrating chart 2.x -> 3.x

Due to some breaking changes in Selector Labels and Security Contexts in Chart 3.0.0 you will need to migrate when upgrading.

First off, the securityContext.enabled field has been removed. In addition to this, fsGroup is not a valid Container Security Context field and has been migrated to the podSecurityContext instead.

# values.yaml
podSecurityContext:
+  fsGroup: 101
 securityContext:
-  enabled: true
-  fsGroup: 101
   runAsUser: 10001

Secondly, the apps.v1.Deployment.spec.selector field is immutable and changes were made to Selector Labels which tries to update this. To get around this, you will need to kubectl delete deployment $deploymentName before doing a helm upgrade So long as your PVC is not destroyed, the new deployment will be rolled out with the same PVC as before and your data will remain intact.

Migrating chart 3.x -> 4.x

Due the major release Verdaccio 5 has some breaking changes to be aware of, please read the migration guide here.

Migrating chart 4.x -> 7.x

Chart 7.0.0 moves the default image to Verdaccio 7 (appVersion: 7.0.0); the chart major now follows the Verdaccio major. The chart templates and values are unchanged, but Verdaccio 7 has breaking changes for the registry itself: read the Verdaccio 6 to 7 migration guide and the release post before upgrading. To stay on 6.x, pin image.tag to a 6.x version or install chart 4.36.0.