apiKey
This feature is an Enterprise feature. See our pricing plans or contact our sales team for more information.
Enable secure communication between your virtual cluster and the vCluster Platform. You can configure the platform to manage and authenticate virtual cluster connections consistently across different environments.
Connect virtual clusters to the vCluster Platformβ
To connect a virtual cluster to the vCluster Platform, you can use an API keyβreferred to as an access key in the platform's console. There are two authentication methods:
-
** Shared access key** (Recommended): Create a single Kubernetes Secret containing the access key, and reference it in multiple virtual clusters, even if they are deployed in different namespaces. This approach simplifies management, reduces overhead, and eases credential rotation, making it suitable for most users and production environments. For most scenarios, using a shared access key is the preferred approach due to its simplicity and ease of maintenance.
-
Dedicated access key: Create separate Kubernetes Secrets, each with a unique access key, for every virtual cluster. This method provides granular access control and allows revocation of access to individual clusters.
- Shared access key
- Dedicated access key
Connect a virtual cluster to the platform using a shared access keyβ
Use a shared access key to authenticate and connect your virtual cluster to the platform.
Prerequisitesβ
Before you begin, ensure you have:
- A vCluster Platform instance set up and accessible.
- Permissions to create and configure an access key in the platform.
- Access to create Kubernetes Secrets on the host Kubernetes cluster (where the virtual cluster runs).
Configure shared access for a virtual clusterβ
Log in to vCluster Platform and create an access key.
When creating the access key, you must define the
vcluster
role in the API key YAML specification in the platform console:Role specificationspec:
scope:
roles:
- role: vcluster
projects:
- project: '*'
allowLoftCli: true
type: User
status: {}noteAssigning the
vcluster
role is required. Without it, the vCluster cannot authenticate with the platform and connection errors occur.Create the Secret in a namespace on the host cluster. This defaults to
vcluster-platform-api-key
if undefined.noteThis namespace does not need to match the target namespace used by the virtual cluster, but it must exist on the host where the vCluster is deployed.
Run the create command, ensuring you replace the placeholders with your specific values:
- Replace
ACCESS_KEY
with your API key (also referred to as an access key). - Replace
PLATFORM_HOST
with the platform domain. For exampleloft.my-domain.com
- Replace
SECRET_NAMESPACE
with the namespace where you want to store the Secret.
noteYou can create the Secret in the
vcluster-platform
namespace by default to ensure access for all virtual clusters managed by the platform. Use a different namespace only if there's a specific need to scope it separately.Modify the following with your specific values to generate a copyable command:kubectl create secret generic vcluster-platform-api-key \
--from-literal=accessKey=YOUR_ACCESS_KEY \
--from-literal=host=YOUR_PLATFORM_HOST \
-n SECRET_NAMESPACE- Replace
In your
vcluster.yaml
file, define the following parameters to reference the Secret and configure access control:secretName
: Specifies the name of the Secret containing the API key. Defaults tovcluster-platform-api-key
if undefined.namespace
: Specifies the namespace where the Secret is located. If different from the virtual cluster's namespace, ensure that the virtual cluster has access to this namespace.createRBAC
: When set totrue
, vCluster automatically creates the necessaryRole
andRoleBinding
resources to allow access to the Secret. Defaults to true.
Modify the following with your specific values to generate a copyable command:external:
platform:
apiKey:
secretName: vcluster-platform-api-key
namespace: SECRET_NAMESPACE
createRBAC: true
Connect a virtual cluster to the platform with a dedicated access keyβ
Authenticate a virtual cluster with the platform using a dedicated access key.
Prerequisitesβ
Before you begin, ensure you have:
- Access to the vCluster Platform.
- The vCluster CLI installed installed on your local machine.
- The ability for each user to generate their own access key from the platform console.
Connect a virtual cluster to the platform using dedicated accessβ
You must configure
vcluster.yaml
to define how your virtual cluster connects to the platform.- If you are creating a new virtual cluster, create a new
vcluster.yaml
file in your working directory. - If you are modifying an existing virtual cluster, locate the
vcluster.yaml
file used during its deployment.
noteThe
vcluster.yaml
file is typically stored locally in your project folder or provided as part of the Helm configuration used to deploy the virtual cluster.- If you are creating a new virtual cluster, create a new
Update your
vcluster.yaml
file to enable individual virtual cluster authentication:vcluster.yamlexternal:
platform:noteThis configuration requires authentication with a dedicated access key instead of creating a shared Kubernetes Secret.
Then in the vCluster CLI, deploy the updated configuration:
Modify the following with your specific values to generate a copyable command:vcluster create --upgrade VCLUSTER_NAME -n VCLUSTER_NAMESPACE -f vcluster.yaml
To connect to the virtual cluster using individual access, each user must:
- Log in to the vCluster Platform console.
- Navigate to Users and click Access Keys.
- Click Create Access Key, configure the settings by providing a display name and optionally limiting its scope to specific clusters, namespaces, or virtual clusters, and save to generate a new access key.
- Copy and securely store the access key.
noteTo view your generated access keys, navigate to Users > Access Keys.
Each user can connect to the virtual cluster by using their dedicated access key through the vCluster CLI.
Log in to the platform:
Modify the following with your specific values to generate a copyable command:vcluster platform login YOUR_PLATFORM_URL --access-key YOUR_DEDICATED_ACCESS_KEY
Then, connect to the virtual cluster:
Modify the following with your specific values to generate a copyable command:vcluster connect VCLUSTER_NAME --project DEFAULT
Exampleβ
- Shared access key
- Dedicated access key
external:
platform:
apiKey:
secretName: vcluster-platform-api-key # Defaults to vcluster-platform-api-key if undefined
namespace: vcluster-namespace # Namespace to search for the secret. If undefined, it searches the vCluster namespace. If different, vCluster needs access to the target namespace.
createRBAC: true # Defaults to true. Automatically creates the necessary RBAC roles and role bindings to locate the secret.
external:
platform:
Config referenceβ
apiKey
required object proβ
APIKey defines where to find the platform access key and host. By default, vCluster will search in the following locations in this precedence:
- environment variable called LICENSE
- secret specified under external.platform.apiKey.secretName
- secret called "vcluster-platform-api-key" in the vCluster namespace
apiKey
required object proβsecretName
required string proβ
SecretName is the name of the secret where the platform access key is stored. This defaults to vcluster-platform-api-key if undefined.
secretName
required string proβnamespace
required string proβ
Namespace defines the namespace where the access key secret should be retrieved from. If this is not equal to the namespace
where the vCluster instance is deployed, you need to make sure vCluster has access to this other namespace.
namespace
required string proβcreateRBAC
required boolean proβ
CreateRBAC will automatically create the necessary RBAC roles and role bindings to allow vCluster to read the secret specified
in the above namespace, if specified.
This defaults to true.
createRBAC
required boolean proβ