Export kubeconfig

Limited vCluster Tenancy Configuration Support

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

• Host Nodes
• Private Nodes

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

By default, vCluster stores the kubeconfig in a secret named vc-NAME within the namespace where vCluster is deployed. You can customize this default secret.

In addition to the default secret, you can also export additional kubeconfig secrets.

Customize the default secret

The following example configures a virtual cluster to use a specific kubeconfig context and server endpoint for the default kubeconfig secret vc-NAME:

• 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.

exportKubeConfig:
  context: my-domain-context
  server: https://my-domain.org:443

Customizing the default secret does not affect the additional kubeconfig secrets that are configured separately with the exportKubeConfig.additionalSecrets field. E.g. in the above example, custom context and server values are used only for the default secret vc-NAME and do not affect the additional secrets that you may have configured.

note

The default secret and the secret specified with the deprecated exportKubeConfig.secret field are customized with the same set of fields (exportKubeConfig.context, exportKubeConfig.server, etc), so setting these fields customizes both the default and the deprecated secret in the same way. More details in the migration section below.

Export additional secrets

You can export additional kubeconfig secrets by specifying exportKubeConfig.additionalSecrets.

Using the default namespace for the additional secret

The following example configures a virtual cluster to export an additional secret vc-my-domain, which is created in the namespace where vCluster is deployed.

In this example, the additional secret vc-my-domain is customized in the following way:

• Set the kubeconfig context name to my-domain-context.
• Configure the kubeconfig to use https://my-domain.org:443 as the server endpoint for the exposed virtual cluster.

exportKubeConfig:
  additionalSecrets:
  - name: vc-my-domain
    context: my-domain-context
    server: https://my-domain.org:443

You can create multiple additional secrets. Each additional secret is configured separately, and configuring additional secrets does not affect the default kubeconfig secret. E.g. in the above example, custom context and server values are used only for the additional secret vc-my-domain and do not affect the default kubeconfig secret, nor any other additional secret that you may have configured.

Using a new namespace for the additional 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 "vc-NAME" (where NAME is the vCluster name).
• 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:
  additionalSecrets:
  - namespace: kubeconfig-secret-namespace
    name: vc-my-domain
    context: my-domain-context
    server: https://my-domain.org:443

Deprecated exportKubeConfig.secret config

Starting from version 0.24.0, the exportKubeConfig.secret configuration is deprecated and replaced by exportKubeConfig.additionalSecrets.

Migrate a deprecated secret to new additional secrets

It is recommended to migrate the deprecated exportKubeConfig.secret config to the new exportKubeConfig.additionalSecrets.

If my-secret is configured such as:

exportKubeConfig:
  secret:
    name: my-secret

You can migrate the secret to the new additional secret with the following:

exportKubeConfig:
  additionalSecrets:
  - name: my-secret

Migrate a customized deprecated secret to new additional secrets

The secret defined using the deprecated exportKubeConfig.secret field is customized using the same configuration fields (such as exportKubeConfig.context, exportKubeConfig.server) as the default kubeconfig secret.

For example, in the following configuration, vCluster exports a kubeconfig secret named vc-my-domain with:

• Context: my-domain-context
• Server endpoint: https://my-domain.org:443

vCluster also exports the default kubeconfig secret using these same context and server values.

exportKubeConfig:
  context: my-domain-context
  server: https://my-domain.org:443
  secret:
    name: vc-my-domain

When migrating this customized deprecated secret to the new additional secrets, you have the following two options.

1. Customize both the default and the additional kubeconfig secret.

exportKubeConfig:
  context: my-domain-context
  server: https://my-domain.org:443
  additionalSecrets:
  - name: vc-my-domain
    context: my-domain-context
    server: https://my-domain.org:443

In this example, both the default secret vc-NAME and the additional secret vc-my-domain use the same custom values for the context and the server, which gives you the same exported kubeconfig secrets as with the old config that used the deprecated exportKubeConfig.secret.

You might want to export the additional secret with different config values for the context and the server. You can achieve this by customizing the additional secret differently than the default secret:

exportKubeConfig:
  context: my-domain-context
  server: https://my-domain.org:443
  additionalSecrets:
  - name: vc-my-domain
    context: my-other-domain-context
    server: https://my-other-domain.org:443

2. Customize only the additional kubeconfig secret.

exportKubeConfig:
  additionalSecrets:
  - name: vc-my-domain
    context: my-domain-context
    server: https://my-domain.org:443

In this example, only the additional secret vc-my-domain uses custom values for the context and the server.

Config reference

exportKubeConfig required object

ExportKubeConfig describes how vCluster should export the vCluster kubeConfig file.

context required string

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

server required string

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

insecure required boolean false

If tls should get skipped for the server

serviceAccount required object

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

name required string

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

namespace required string

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

ClusterRole to assign to the service account.

secret required object

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.

Deprecated: Use AdditionalSecrets instead.

name required string

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

namespace required string

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.

additionalSecrets required object[]

AdditionalSecrets specifies the additional host cluster secrets in which vCluster will store the generated virtual cluster kubeconfigs.

context required string

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

server required string

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

insecure required boolean

If tls should get skipped for the server

serviceAccount required object

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

name required string

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

namespace required string

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

ClusterRole to assign to the service account.

name required string

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

namespace required string

Namespace where vCluster stores 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.