Skip to main content
Version: main 🚧

API key

Enterprise-Only Feature

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.


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​

  1. Log in to vCluster Platform and create an access key.

  2. When creating the access key, you must define the vcluster role in the API key YAML specification in the platform console:

    Role specification
    spec:
      scope:
        roles:
          - role: vcluster
        projects:
          - project: '*'
      allowLoftCli: true
    type: User
    status: {}
    note

    Assigning the vcluster role is required. Without it, the vCluster cannot authenticate with the platform and connection errors occur.

  3. Create the Secret in a namespace on the host cluster. This defaults to vcluster-platform-api-key if undefined.

    note

    This 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 example loft.my-domain.com
    • Replace SECRET_NAMESPACE with the namespace where you want to store the Secret.
    note

    You 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

  4. 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 to vcluster-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 to true, vCluster automatically creates the necessary Role and RoleBinding 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

Example​

Shared access key example
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.

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

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.

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.

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.