Skip to main content
Version: v0.24 Stable

Export kubeconfig

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

Deprecated: Use AdditionalSecrets instead.

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.

additionalSecrets required object[] pro​

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

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

name required string pro​

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

namespace required string pro​

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.