Skip to main content
Version: main 🚧
Limited vCluster Tenancy Configuration Support

This feature is only available when using the following worker node types:

  • Host Nodes

    • Override the Alpine sidecar image in vCluster

    vCluster automatically creates a small Alpine Linux container (called a "sidecar") alongside your workloads to manage network routing. This sidecar modifies the /etc/hosts file inside your virtual cluster's pods so they can communicate properly with the host cluster. By default, vCluster downloads this Alpine image from Docker Hub, but you can configure it to use a different Alpine image from your own container registry instead.

    You might need this for:

    • Docker Hub rate limiting: Avoid hitting Docker Hub's download limits in busy environments.
    • Security requirements: Use only approved, internal registries.
    • Air-gapped environments: No internet access requires local image hosting.
    • Custom Alpine images: Use modified images with additional tools or security patches.

    Prerequisites​

    Before you begin, ensure you have:

    Required tools and access:

    • A running Kubernetes cluster with vCluster installed (or ready to install)
    • kubectl installed and configured to access your cluster
    • docker command-line tool installed for image management
    • Permission to create secrets in your vCluster's namespace

    Registry requirements:

    • Access to a container registry (local, cloud, or public)
    • Credentials for private registries (username/password or access tokens)
    • Network connectivity from your Kubernetes cluster to the registry

    Set up your container registry​

    Before configuring vCluster, you need a container registry with an Alpine image. You can choose the option that fits your environment from the following:

    Local testing or air-gapped environments​

    Create a simple local registry for development or environments without internet access:

    # Start a basic registry server
    docker run -d -p 5000:5000 --name local-registry registry:2

    # Verify it's running
    curl http://localhost:5000/v2/_catalog

    Cloud environments​

    Use existing managed registries for production deployments:

    • AWS ECR (Elastic Container Registry)
    • Google Container Registry (GCR)
    • Azure Container Registry (ACR)
    • Other cloud providers with managed registry services

    Complex air-gapped setups​

    For enterprise air-gapped environments, vCluster provides official automation scripts that automatically pull and push all required images with proper version compatibility. These scripts handle dependencies and version management for you. For more information and detailed setup instructions, refer to the vCluster air-gapped installation guide.

    Upload the Alpine image​

    After you have a registry, upload an Alpine image to it. Start by pulling the official Alpine image and pushing it to your registry:

    # Pull the Alpine image
    docker pull alpine:latest

    # Tag for your registry
    docker tag alpine:latest your-registry.com/alpine:latest

    # Push to your registry
    docker push your-registry.com/alpine:latest

    The commands vary by registry type:


    docker tag alpine:latest localhost:5000/alpine:latest
    docker push localhost:5000/alpine:latest

    Configure vCluster to use your image​

    Add the image configuration to your vcluster.yaml file. This enables vCluster's pod sync to use your custom Alpine image instead of the default one when it creates the sidecar container that manages host file entries. The sync.toHost.pods.rewriteHosts.initContainer.image setting specifically controls which image vCluster uses for the network routing sidecar.


    sync:
      toHost:
        pods:
          rewriteHosts:
            initContainer:
              image: "your-registry.com/alpine:latest"

    The following are examples for different registry types:


    sync:
      toHost:
        pods:
          rewriteHosts:
            initContainer:
              image: "localhost:5000/alpine:latest"

    Set up authentication for private registries​

    note

    Skip this section if you're using a public registry, such as a local registry without authentication.

    Private registries require authentication. Most cloud registries (AWS ECR, Google Container Registry, GitHub Container Registry) and enterprise registries need credentials to pull images.

    Create a Kubernetes secret with your registry credentials. Replace the placeholder values with your actual registry URL, username, and password:


    kubectl create secret docker-registry my-registry-secret \
      --docker-server=your-registry.com \
      --docker-username=your-username \
      --docker-password=your-password \
      --docker-email=your-email@example.com \
      --namespace=vcluster-namespace

    Then you can configure vCluster to use the secret by adding it to your vcluster.yaml file. This configures the service account that vCluster uses to run workloads. This gives it permission to pull images from your private registry using the credentials you created:


    controlPlane:
      advanced:
        workloadServiceAccount:
          imagePullSecrets:
            - name: my-registry-secret

    Configuration examples​

    The following are complete vcluster.yaml configurations for different scenarios:


    sync:
      toHost:
        pods:
          rewriteHosts:
            initContainer:
              image: "localhost:5000/alpine:latest"

    Deploy your changes​

    After updating your vcluster.yaml file, apply the configuration:


    vcluster create my-vcluster --values vcluster.yaml

    This creates a new vCluster using your custom Alpine image configuration.

    Troubleshoot​

    If you encounter problems, check these common issues:

    • Image pull errors: Verify the image exists at the specified URL and the URL format is correct. Test manually with docker pull your-registry.com/alpine:latest to confirm the image is accessible.

    • Authentication failures: Ensure your secret is in the correct namespace and contains valid credentials. For cloud registries like ECR, check that tokens haven't expired and recreate the secret if needed.

    • Registry connectivity: Confirm your Kubernetes cluster can reach the registry URL. Test with kubectl run test-pod --image=curlimages/curl --rm -it --restart=Never -- curl -I https://your-registry.com/v2/ to verify network access.

    • Version compatibility: Use Alpine images that include basic networking tools like iptables and ip that vCluster requires. Standard alpine:latest works well, but minimal custom images may be missing required utilities.