Skip to main content

Export kubeconfig

Customize how vCluster exports the kubeconfig file to a secret for use in tools like ArgoCD or Terraform pipelines.

By default, vCluster stores the kubeconfig in a secret named vc-NAME within the namespace where vCluster is deployed. To create an additional secret with a specified configuration, configure exportKubeConfig.

Using the same namespace for the secret​

The following example configures a virtual cluster to use a specific kubeconfig context, server endpoint, and secret name within the same namespace:

  • Set the kubeconfig context name to my-domain-context.
  • Configure the kubeconfig to use https://my-domain.org:443 as the endpoint for the exposed virtual cluster.
  • Ensure the secret name reflects the virtual cluster domain name instead of the default cluster name, "my-cluster".
exportKubeConfig:
  context: my-domain-context
  server: https://my-domain.org:443
  secret:
    name: vc-my-domain

Using a new namespace for the secret​

The following example configures a virtual cluster to store the kubeconfig secret in a separate namespace while maintaining proper access control:

  • Set the kubeconfig context name to my-domain-context.
  • Configure the kubeconfig to use https://my-domain.org:443 as the virtual cluster endpoint.
  • Create a namespace called kubeconfig-secret-namespace to store the secret.
  • Name the secret vc-my-domain instead of using the default cluster name "my-cluster".
  • Additionally, grant access to the new namespace by creating a Role and RoleBinding for the vCluster service account:
    • Configure the new role with the same permissions assigned to the vCluster app role in the original namespace.
    • If needed, copy permissions from the default vCluster deployment.
    • When vCluster permissions change, update the unmanaged role in the target namespace accordingly.
exportKubeConfig:
  context: my-domain-context
  server: https://my-domain.org:443
  secret:
    namespace: kubeconfig-secret-namespace
    name: vc-my-domain

Config reference​

exportKubeConfig required object pro​

ExportKubeConfig describes how vCluster should export the vCluster kubeConfig file.

context required string pro​

Context is the name of the context within the generated kubeconfig to use.

server required string pro​

Override the default https://localhost:8443 and specify a custom hostname for the generated kubeconfig.

insecure required boolean false pro​

If tls should get skipped for the server

serviceAccount required object pro​

ServiceAccount can be used to generate a service account token instead of the default certificates.

name required string pro​

Name of the service account to be used to generate a service account token instead of the default certificates.

namespace required string pro​

Namespace of the service account to be used to generate a service account token instead of the default certificates. If omitted, will use the kube-system namespace.

clusterRole required string pro​

ClusterRole to assign to the service account.

secret required object pro​

Declare in which host cluster secret vCluster should store the generated virtual cluster kubeconfig. If this is not defined, vCluster will create it with vc-NAME. If you specify another name, vCluster creates the config in this other secret.

name required string pro​

Name is the name of the secret where the kubeconfig should get stored.

namespace required string pro​

Namespace where vCluster should store the kubeconfig secret. If this is not equal to the namespace where you deployed vCluster, you need to make sure vCluster has access to this other namespace.