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 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:443as the endpoint for the exposed cluster.
exportKubeConfig:
context: my-domain-context
server: https://my-domain.org:443
Customizing the default secret doesn't affect the additional kubeconfig secrets that are configured separately with the
exportKubeConfig.additionalSecrets field. In the example above, custom context and server values are used only
for the default secret vc-NAME and don't affect the additional secrets that you may have configured.
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.
Use the default namespace for the additional secret​
The following example configures a 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:443as the server endpoint for the exposed 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 doesn't affect the default kubeconfig secret. In the example above, custom context and server values are
used only for the additional secret vc-my-domain and don't affect the default kubeconfig secret, nor any other
additional secret that you may have configured.
Use a new namespace for the additional secret​
The following example configures a 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:443as the cluster endpoint. - Create a namespace called
kubeconfig-secret-namespaceto store the secret. - Name the secret
vc-my-domaininstead of using the default "vc-NAME" (whereNAMEis 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 with vCluster v0.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​
For every field under exportKubeConfig, see the exportKubeConfig reference.