Skip to main content
Version: v0.28

Deploy vCluster behind a corporate proxy

Configure vClustervClusterAn open-source software product that creates and manages virtual Kubernetes clusters inside a host Kubernetes cluster. vCluster improves isolation and multi-tenancy capabilities while reducing infrastructure costs.Related: Virtual Cluster, Host Cluster to work behind a corporate proxy using standard proxy environment variables.

Prerequisites​

  • Administrator access to a Kubernetes cluster: See Accessing Clusters with kubectl for more information. Run the command kubectl auth can-i create clusterrole -A to verify that your current kube-context has administrative privileges.

    info

    To obtain a kube-context with admin access, ensure you have the necessary credentials and permissions for your Kubernetes cluster. This typically involves using kubectl config commands or authenticating through your cloud provider's CLI tools.

  • helm: Helm v3.10 is required for deploying the platform. Refer to the Helm Installation Guide if you need to install it.

  • kubectl: Kubernetes command-line tool for interacting with the cluster. See Install and Set Up kubectl for installation instructions.

  • Corporate proxy URL and credentials (if required)

Overview​

When deploying vcluster behind a corporate proxy, you need to configure the standard proxy environment variables (HTTP_PROXY, HTTPS_PROXY, and NO_PROXY) on the vcluster control plane pods. The statefulSet configuration ensures that vcluster can:

  • Access external resources through the proxy when needed
  • Communicate with internal cluster services without going through the proxy
NO_PROXY configuration

When configuring NO_PROXY, ensure you include all internal cluster services that should bypass the proxy. For vCluster deployments using external etcd as their backing store, you must explicitly include <vcluster-name>-etcd in the list (see External etcd deployments section below).

Configure proxy settings​

Configure the proxy environment variables through the vCluster StatefulSet configuration:

vcluster.yaml
controlPlane:
  statefulSet:
    env:
      # HTTP proxy for non-encrypted traffic
      - name: HTTP_PROXY
        value: http://corp-proxy.example.com:3128

      # HTTPS proxy for encrypted traffic
      - name: HTTPS_PROXY
        value: http://corp-proxy.example.com:3128

      # NO_PROXY - services that should bypass the proxy
      # Include '<vcluster-name>-etcd' if using external etcd backing store
      - name: NO_PROXY
        value: localhost,127.0.0.1,.svc,.svc.cluster.local,.local,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

Configure required no-proxy entries​

Required entries​

The NO_PROXY environment variable must include the following entries for vCluster to function correctly:

EntryPurposeRequired
localhostLocal loopbackYes
127.0.0.1Local loopback IPYes
.svcService DNS suffixYes
.svc.cluster.localFull cluster DNS suffixYes
Cluster CIDR rangesInternal pod/service networksYes
<vcluster-name>-etcdvCluster's external etcd serviceOnly for external etcd deployments

Example configurations​

Minimal proxy configuration with required entries:

vcluster.yaml
controlPlane:
  statefulSet:
    env:
      - name: HTTP_PROXY
        value: http://corp-proxy.example.com:3128
      - name: HTTPS_PROXY
        value: http://corp-proxy.example.com:3128
      - name: NO_PROXY
        value: localhost,127.0.0.1,.svc,.svc.cluster.local,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

Deploy vCluster with proxy settings​

  1. Create a namespace for your vCluster:

    kubectl create namespace vcluster-proxy

  2. Create your vcluster.yaml configuration file with the proxy settings:

    Modify the following with your specific values to generate a copyable command:
    controlPlane:
      statefulSet:
        env:
          - name: HTTP_PROXY
            value: http://corp-proxy.example.com:3128
          - name: HTTPS_PROXY
            value: http://corp-proxy.example.com:3128
          - name: NO_PROXY
            # Include vCluster etcd service explicitly for external etcd deployments
            value: demo-vcluster-etcd,localhost,127.0.0.1,.svc,.svc.cluster.local,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

  3. (Optional) If your proxy requires authentication, create a secret with the credentials:

    kubectl create secret generic proxy-credentials \
      --namespace vcluster-proxy \
      --from-literal=username='your-proxy-username' \
      --from-literal=password='your-proxy-password'

    Then update your vcluster.yaml to reference the secret:

    Modify the following with your specific values to generate a copyable command:
    controlPlane:
      statefulSet:
        env:
          # Proxy URLs with authentication
          - name: HTTP_PROXY
            value: http://$(PROXY_USERNAME):$(PROXY_PASSWORD)@corp-proxy.example.com:3128
          - name: HTTPS_PROXY
            value: http://$(PROXY_USERNAME):$(PROXY_PASSWORD)@corp-proxy.example.com:3128
          - name: NO_PROXY
            value: demo-vcluster-etcd,localhost,127.0.0.1,.svc,.svc.cluster.local,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
          # Proxy credentials from secret
          - name: PROXY_USERNAME
            valueFrom:
              secretKeyRef:
                name: proxy-credentials
                key: username
          - name: PROXY_PASSWORD
            valueFrom:
              secretKeyRef:
                name: proxy-credentials
                key: password

  4. Deploy vCluster with the configuration:

    vcluster create my-vcluster \
      --namespace vcluster-proxy \
      --values vcluster.yaml

  5. Verify that the proxy settings are applied:

    kubectl get statefulset -n vcluster-proxy my-vcluster -o yaml | grep -A 5 "env:"

    You should see your proxy environment variables in the output.

Troubleshoot proxy issues​

vCluster fails to start with etcd connection errors​

For vCluster deployments using external etcd, if you see errors like "failed to connect to etcd" or proxy logs showing TCP_DENIED/403 for etcd connections on port 2379, verify that:

  1. The etcd service name (<vcluster-name>-etcd) is explicitly listed in your NO_PROXY configuration
  2. The NO_PROXY value doesn't have spaces between entries (use commas only)
  3. The environment variables are correctly applied to the StatefulSet
  4. You're using the correct service name format (check with kubectl get svc -n <namespace>)

Verify proxy configuration​

Check that the proxy settings are correctly applied to the vCluster pods:

# Check the environment variables in the running pod
kubectl exec -n vcluster-proxy my-vcluster-0 -- env | grep -E "PROXY|proxy"

Test connectivity​

Verify that internal services bypass the proxy:

# Test etcd connectivity from within the vCluster pod
kubectl exec -n vcluster-proxy my-vcluster-0 -- curl -I http://my-vcluster-etcd:2379/health

External etcd deployments​

When using external etcd as the backing store for vCluster instead of the default embedded SQLite/k3s, you must include the etcd service name explicitly in the NO_PROXY environment variable. The service name follows the pattern <vcluster-name>-etcd. This requirement is critical because:

  • The Go HTTP client used by vCluster requires exact hostname matches for services without a leading dot
  • Domain patterns like .local or .svc.cluster.local do not cover the etcd service name
  • Without this explicit entry, vCluster will route etcd connections through the proxy, causing connection failures

Configure proxy for external etcd​

vcluster-external-etcd.yaml
# External etcd configuration with proxy settings
controlPlane:
  # Use external etcd as backing store
  backingStore:
    etcd:
      deploy:
        enabled: true
        statefulSet:
          highAvailability:
            replicas: 3

  # Proxy configuration for control plane
  statefulSet:
    env:
      - name: HTTP_PROXY
        value: http://corp-proxy.example.com:3128
      - name: HTTPS_PROXY
        value: http://corp-proxy.example.com:3128
      # CRITICAL: Must include the etcd service name
      # Pattern: <vcluster-name>-etcd (e.g., my-vcluster-etcd)
      - name: NO_PROXY
        value: my-vcluster-etcd,localhost,127.0.0.1,.svc,.svc.cluster.local,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
Critical for external etcd

When using external etcd, omitting the etcd service name (format: <vcluster-name>-etcd) from NO_PROXY will cause vCluster to fail with connection errors to the etcd service. The proxy will deny these connections with 403 errors. This is the most common cause of proxy-related failures in external etcd deployments.

Additional considerations​

Use authenticated proxies​

If your corporate proxy requires authentication, use Kubernetes secrets to securely manage credentials:

First, create a Kubernetes secret with your proxy credentials:

kubectl create secret generic proxy-credentials \
  --namespace <vcluster-namespace> \
  --from-literal=username='your-proxy-username' \
  --from-literal=password='your-proxy-password'

Then reference the secret in your vCluster configuration:

vcluster.yaml
controlPlane:
  statefulSet:
    env:
      # Proxy URLs with authentication variables
      - name: HTTP_PROXY
        value: http://$(PROXY_USERNAME):$(PROXY_PASSWORD)@corp-proxy.example.com:3128
      - name: HTTPS_PROXY
        value: http://$(PROXY_USERNAME):$(PROXY_PASSWORD)@corp-proxy.example.com:3128
      - name: NO_PROXY
        value: localhost,127.0.0.1,.svc,.svc.cluster.local,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
      # Proxy credentials from secret
      - name: PROXY_USERNAME
        valueFrom:
          secretKeyRef:
            name: proxy-credentials
            key: username
      - name: PROXY_PASSWORD
        valueFrom:
          secretKeyRef:
            name: proxy-credentials
            key: password

Proxy settings for vCluster workloads​

The proxy configuration shown previously applies only to the vCluster control plane. If you need proxy settings for workloads running inside the virtual cluster, configure them separately through:

  • Pod environment variables in your workload manifests
  • ConfigMaps or Secrets mounted to your workloads
  • Admission webhooks that inject proxy settings automatically