Rootless mode

Many Kubernetes cluster operators employ policies to restrict the usage of certain features, for example running pods with the root user. On this page you will see which options allow you to adjust vCluster configuration to successfully deploy it in such restricted host clusters.

Running as non-root user

If your host cluster policies disallow running containers with root user, or you simply prefer to run them this way, it is possible to configure it for vCluster components. Steps below show how to set the desired UID for syncer and control plane. The syncer also passes this UID down to the vCluster DNS deployment.

vcluster

Create a values.yaml file with the following lines:

fsGroup: 12345
securityContext:
  runAsUser: 12345
  runAsGroup: 12345
  runAsNonRoot: true

Then create the vCluster with the following command:

vcluster create my-vcluster -f values.yaml

helm

Update the vcluster.yaml file described in the deployment guide.

You will need to add the securityContext block as shown below:

fsGroup: 12345
securityContext:
  runAsUser: 12345
  runAsGroup: 12345
  runAsNonRoot: true

Then, install helm chart using vcluster.yaml for chart values as described in the deployment guide.

kubectl

You will need to add the securityContext blocks to the containers as shown below:

kubectl create namespace host-namespace-1
helm template my-vcluster vcluster --repo https://charts.loft.sh --set securityContext.runAsGroup=12345 --set fsGroup=12345 --set securityContext.runAsUser=12345 --set securityContext.runAsNonRoot=true -n host-namespace-1 | kubectl apply -f -

Values of the securityContext fields

You can substitute the runAsUser value as needed, e.g. if the host cluster limits the allowable UID ranges.
And you are free to set other securityContext fields as necessary to fulfill your host cluster policies.

caution

Running as non-root is currently supported only for the k3s distribution. While other distributions provided by vCluster may make use of the securityContext field from the values.yaml file, we do not guarantee that they will work as expected.

caution

vCluster doesn't currently provide a migration path from an instance that was running as root to running with a non-root user.