Platform configuration

This document explains how to configure the platformThe PlatformThe vCluster Platform that provides management, access control, and operational features for virtual clusters across multiple physical host clusters.Related: Project, including its operational settings and features such as SSO login, custom branding, and auditing.

Understand platform configuration

Configure the platform through the vcluster-platform Helm chart, which comes from the loft-sh/loft repository. Find the default configuration values in the chart's values.yaml file.

Identify configuration types

The platform's values.yaml file contains multiple configuration sections:

1. Installation settings - Control how the platform deploys
   • Top-level fields in the vcluster-platform chart's values.yaml
   • Located in the platform Helm chart (loft-sh/loft)
   • Examples: replicaCount, resources, ingress, persistence, etc.
   • These configure Kubernetes deployment aspects like resources and replicas

2. Operational settings - Control how the platform functions after deployment
   • These are grouped under the config: section of the vcluster-platform chart
   • Located in the platform Helm chart (loft-sh/loft)
   • Examples: config.auth, config.audit, config.loftHost
   • You can also manage these through the UI in Admin > Config

3. Agent settings - Control how the platform agent operates in connected clusters
   • Set through the top-level agentValues: section of the vcluster-platform chart
   • Located in the platform Helm chart (loft-sh/loft)
   • You can override these per-cluster with annotations

Distinguish between values.yaml and config sections

When configuring the platform, understand the difference between the main values.yaml settings and the config section inside it:

• values.yaml (installation settings) - Controls how the platform itself installs
  • Affects the Kubernetes resources created during installation
  • Examples: replica count, resource limits, persistence settings, ingress configuration
  • You typically set these options once during deployment
  • Not accessible through the UI after installation
  • Requires a Helm upgrade to change after initial deployment

• config section - Controls what the platform does after installation
  • Located in the vcluster-platform chart's values.yaml as the config: key
  • Defined in loft-sh/loft/chart/values.yaml
  • Stores settings in a dedicated Kubernetes resource that persists across platform upgrades
  • Contains settings that the platform reads and applies at runtime
  • Affects the platform's behavior, features, and integrations
  • Examples: authentication options, audit settings, UI customization
  • You can change these any time through the UI in Admin > Config
  • Changes are detected and applied without requiring a restart or redeployment

Complete common configuration tasks

For common tasks, configure the following:

Task	Configuration location	Example
Setting admin credentials	admin: section (root level)	admin.username, admin.password
Configuring replicas for HA	replicaCount: setting (root level)	replicaCount: 2
Setting up ingress	ingress: section (root level)	ingress.enabled: true
Setting resource limits	resources: section (root level)	resources.limits.memory
Configuring auth providers	config.auth: section	config.auth.github
Setting custom domain	config: section	config.loftHost

Review platform configuration example

The following example is of a platform values.yaml file showing the configuration sections:

Example platform values.yaml with all configuration sections

# Installation settings (top-level)
replicaCount: 2
resources:
  requests:
    memory: 512Mi
    cpu: 400m

# Admin user settings (top-level)
admin:
  create: true
  username: my-admin-user
  password: my-secure-password

# Ingress configuration (top-level)
ingress:
  enabled: true
  host: platform.example.com

# Agent settings (top-level)
agentValues:
  resources:
    requests:
      memory: 256Mi
  # Security contexts for agent pods
  securityContext:
    runAsNonRoot: true
    runAsUser: 1001
  podSecurityContext:
    fsGroup: 2001

# Operational settings (inside config section)
config:
  loftHost: platform.example.com
  audit:
    enabled: true
  auth:
    github:
      clientId: $CLIENT_ID

Apply configuration

Apply the platform configuration in two ways:

• Through helm values when installing or upgrading the platform
• Through the UI in Admin > Config after installation (operational settings only)

Using helm values allows you to manage configuration declaratively and enables deployment through GitOps solutions such as ArgoCD.

Here's an example of applying platform configuration with helm:

Apply platform configuration using Helm

RELEASE_NAME=vcluster-platform
RELEASE_NAMESPACE=vcluster-platform
PLATFORM_VERSION='' # Set this to a specific version or leave empty for latest

helm upgrade $RELEASE_NAME vcluster-platform \
  --install \
  --repo https://charts.loft.sh/ \
  --namespace $RELEASE_NAMESPACE \
  --create-namespace \
  --values values.yaml \
  ${PLATFORM_VERSION:+--version $PLATFORM_VERSION}

Set a custom domain

The loftHost variable is a critical configuration setting that defines the domain where users access the platform.

Determine when to set this value

Set the loftHost value after:

1. Installing the platform
2. Configuring TLS certificates
3. Setting up ingress with a custom domain

Define what to set

The loftHost value should be:

• The same hostname specified in your ingress resource
• Only the hostname (e.g., platform.example.com)
• Without protocols (e.g., no https://)
• Without subpaths (e.g., no /platform)

Configure custom domain in platform config

config:
  loftHost: platform.example.com

Reconnect clusters after changing the domain

After updating the loftHost value, you must reconnect all clusters to the platform by running the same connection commands in each Kubernetes context. See connecting clusters for detailed instructions.

Important

You must also reconnect clusters if you change the additionalCA or insecureSkipVerify values after the initial setup.

Manage sensitive information

Many configuration options require sensitive information such as API keys or tokens. Rather than storing these directly in your values.yaml file, you can use environment variable placeholders.

Use secret references

To securely provide sensitive information, store it in a Kubernetes secret and reference it in your configuration:

Store sensitive values using Kubernetes secrets

# Secret references
envValueFrom:
  CLIENT_ID:
    secretKeyRef:
      name: github-auth-secret
      key: client_id
  CLIENT_SECRET:
    secretKeyRef:
      name: github-auth-secret
      key: client_secret

# Platform configuration
config:
  auth:
    github:
      clientId: $CLIENT_ID
      clientSecret: $CLIENT_SECRET
      redirectURI: https://my-platform.example.com/auth/github/callback

Configure custom HTTP headers

You can configure the platform to add custom HTTP headers to all API responses. This is useful for security-related headers or when integrating with specific environments.

Adding custom HTTP headers

config:
  auth:
    customHttpHeaders:
      X-Frame-Options: SAMEORIGIN
      X-XSS-Protection: 1; mode=block
      Content-Security-Policy: default-src 'self'

Manage certificates

Use a custom certificate authority

If you want all virtual clusters to trust a specific certificate authority when communicating with the platform, you can configure it centrally rather than in each individual virtual cluster.

Prerequisite

Before setting a custom certificate authority, you must configure TLS for the platform.

Setting a custom certificate authority

# Base64-encoded CA certificate - top-level setting, not inside config:
additionalCA: "(base64 encoded CA)"

Import existing virtual clusters with certificate validation

When importing externally managed virtual clusters, you can enable secure communication by using the same certificate authority:

1. Get the current certificate authority from your platform:

Get the certificate authority value

helm get values --namespace $RELEASE_NAMESPACE $RELEASE_NAME --all | grep additionalCA

2. Import the virtual cluster with certificate validation:

Import a virtual cluster with certificate validation

vcluster platform add vcluster <VCLUSTER_NAME> \
--namespace=<VCLUSTER_NAMESPACE> \
--project=<PROJECT_NAME> \
--ca-data <BASE64_CA_VALUE>

The imported virtual cluster restarts and reports Ready once it establishes a secure connection to the platform.

Work with the platform agent

Understand what the platform agent does

The platform agent is a component that runs in each connected Kubernetes cluster. It handles:

• Cluster resource management
• Communication with the platform
• Reconciliation of cluster-scoped resources

important

Every cluster connected to the platform, including the cluster where the platform itself runs, must have the platform agent installed.

Use default agent deployment

By default, the platform automatically installs the agent in:

1. The cluster where the platform is deployed
2. Any new clusters connected to the platform

Disable automatic agent deployment

In some environments, particularly those using GitOps tools, you might want to manage agent deployment manually. There are two ways to disable automatic agent deployment:

1. Platform-wide - Disable for all clusters:

Disable automatic agent deployment platform-wide

# Not inside config: section - this is a top-level setting
env:
  DISABLE_AGENT: true

2. Per-cluster - Disable for specific clusters by setting the loft.sh/cluster-ignore-agent annotation to true on the Cluster resource.

Agent required

Even if you disable automatic deployment, the platform agent is still required in every connected cluster. You must deploy it manually or through GitOps tools.

Install the agent manually

To manually install the platform agent:

Manual agent installation

RELEASE_NAME=vcluster-platform
RELEASE_NAMESPACE=vcluster-platform
PLATFORM_VERSION='' # Set this to a specific version or leave empty for latest

helm upgrade $RELEASE_NAME vcluster-platform \
  --install \
  --repo https://charts.loft.sh/ \
  --namespace $RELEASE_NAMESPACE \
  --create-namespace \
  --set agentOnly=true \
  ${PLATFORM_VERSION:+--version $PLATFORM_VERSION}

Configure the agent

Understand agent values

The platform agent uses its own set of configuration values, which you can specify in several ways:

1. Default behavior: By default, the agent inherits values from the platform configuration.
2. Global agent values: The agentValues: section in the platform values.yaml specifies default values for all agents.
3. Cluster-specific values: The loft.sh/agent-values annotation on a Cluster resource overrides global values for that specific cluster.

When the platform upgrades an agent, it uses the values from the agentValues section (or from the cluster annotation if present).

Retrieve agent values

For a platform instance on host nimbus.vcluster.cloud with a connected cluster named staging, the following table shows how to retrieve agent values for each tier. Use these endpoints to determine current platform configuration or to layer values instead of overriding them.

You can specify multiple values files:

--values=https://<platform-config-endpoint> --values=https://<cluster-annotation-endpoint>

An access key is required for authentication.

Host	Cluster Name	Source	Request	Response
nimbus.vcluster.cloud	staging	none	https://nimbus.vcluster.cloud/clusters/staging?token=access-key	Current agent values
nimbus.vcluster.cloud	staging	platform-config	https://nimbus.vcluster.cloud/clusters/staging?token=access-key&source=platform-config	Content of agentValues section in platform config
nimbus.vcluster.cloud	staging	cluster-annotation	https://nimbus.vcluster.cloud/clusters/staging?token=access-key&source=cluster-annotation	Value of the loft.sh/agent-values annotation on the Cluster Object

Configure the agent through the platform

To customize the agent configuration when deployed by the platform, use the agentValues section in your platform configuration:

Customizing agent configuration

# Agent-specific configuration - top-level setting, not in config: section
agentValues:
  # Configure container-level security context for the agent
  securityContext:
    allowPrivilegeEscalation: false
    runAsNonRoot: true
    runAsUser: 1001
    capabilities:
      drop:
      - ALL
  
  # Configure pod-level security context for the agent
  podSecurityContext:
    fsGroup: 2001
    runAsGroup: 3001

  # Set resource limits for the agent
  resources:
    limits:
      cpu: 500m
      memory: 512Mi
    requests:
      cpu: 100m
      memory: 128Mi

Security Context Precedence

When multiple security contexts are configured, the agent uses this precedence order (highest to lowest):

1. Cluster-specific agentValues (via loft.sh/agent-values annotation)
2. Platform-wide agentValues (in platform values.yaml)
3. Platform default securityContext and podSecurityContext

For detailed information about security context configuration and examples, see Configure the Agent - Security Context Configuration.

Configure cluster-specific agents

To apply different configuration to the agent in specific clusters, set the loft.sh/agent-values annotation on the Cluster resource. These values override any settings from the platform's agentValues.

Review configuration reference

For a complete reference of all platform configuration options under the config: section, see below:

auth required object

Authentication holds the information for authentication

oidc required object

OIDC holds oidc authentication configuration

issuerUrl required string

IssuerURL is the URL the provider signs ID Tokens as. This will be the "iss" field of all tokens produced by the provider and is used for configuration discovery.

The URL is usually the provider's URL without a path, for example "https://accounts.google.com" or "https://login.salesforce.com".

The provider must implement configuration discovery. See: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig

clientId required string

ClientID the JWT must be issued for, the "sub" field. This plugin only trusts a single client to ensure the plugin can be used with public providers.

The plugin supports the "authorized party" OpenID Connect claim, which allows specialized providers to issue tokens to a client for a different client. See: https://openid.net/specs/openid-connect-core-1_0.html#IDToken

clientSecret required string

ClientSecret to issue tokens from the OIDC provider

redirectURI required string

loft redirect uri. E.g. https://loft.my.domain/auth/oidc/callback

postLogoutRedirectURI required string

Loft URI to be redirected to after successful logout by OIDC Provider

caFile required string

Path to a PEM encoded root certificate of the provider. Optional

insecureCa required boolean

Specify whether to communicate without validating SSL certificates

preferredUsername required string

Configurable key which contains the preferred username claims

loftUsernameClaim required string

LoftUsernameClaim is the JWT field to use as the user's username.

usernameClaim required string

UsernameClaim is the JWT field to use as the user's id.

emailClaim required string

EmailClaim is the JWT field to use as the user's email.

allowedExtraClaims required string[]

AllowedExtraClaims are claims of interest that are not part of User by default but may be provided by the OIDC provider.

usernamePrefix required string

UsernamePrefix, if specified, causes claims mapping to username to be prefix with the provided value. A value "oidc:" would result in usernames like "oidc:john".

groupsClaim required string

GroupsClaim, if specified, causes the OIDCAuthenticator to try to populate the user's groups with an ID Token field. If the GroupsClaim field is present in an ID Token the value must be a string or list of strings.

groups required string[]

If required groups is non empty, access is denied if the user is not part of at least one of the specified groups.

scopes required string[]

Scopes that should be sent to the server. If empty, defaults to "email" and "profile".

getUserInfo required boolean

GetUserInfo, if specified, tells the OIDCAuthenticator to try to populate the user's information from the UserInfo.

groupsPrefix required string

GroupsPrefix, if specified, causes claims mapping to group names to be prefixed with the value. A value "oidc:" would result in groups like "oidc:engineering" and "oidc:marketing".

type required string

Type of the OIDC to show in the UI. Only for displaying purposes

github required object

Github holds github authentication configuration

clientId required string

ClientID holds the github client id

clientSecret required string

ClientID holds the github client secret

redirectURI required string

RedirectURI holds the redirect URI. Should be https://loft.domain.tld/auth/github/callback

orgs required object[]

Loft queries the following organizations for group information. Group claims are formatted as "(org):(team)". For example if a user is part of the "engineering" team of the "coreos" org, the group claim would include "coreos:engineering".

If orgs are specified in the config then user MUST be a member of at least one of the specified orgs to authenticate with loft.

name required string

Organization name in github (not slug, full name). Only users in this github organization can authenticate.

teams required string[]

Names of teams in a github organization. A user will be able to authenticate if they are members of at least one of these teams. Users in the organization can authenticate if this field is omitted from the config file.

hostName required string

Required ONLY for GitHub Enterprise. This is the Hostname of the GitHub Enterprise account listed on the management console. Ensure this domain is routable on your network.

rootCA required string

ONLY for GitHub Enterprise. Optional field. Used to support self-signed or untrusted CA root certificates.

gitlab required object

Gitlab holds gitlab authentication configuration

clientId required string

Gitlab client id

clientSecret required string

Gitlab client secret

redirectURI required string

Redirect URI

baseURL required string

BaseURL is optional, default = https://gitlab.com

groups required string[]

Optional groups whitelist, communicated through the "groups" scope. If groups is omitted, all of the user's GitLab groups are returned. If groups is provided, this acts as a whitelist - only the user's GitLab groups that are in the configured groups below will go into the groups claim. Conversely, if the user is not in any of the configured groups, the user will not be authenticated.

google required object

Google holds google authentication configuration

clientId required string

Google client id

clientSecret required string

Google client secret

redirectURI required string

loft redirect uri. E.g. https://loft.my.domain/auth/google/callback

scopes required string[]

defaults to "profile" and "email"

hostedDomains required string[]

Optional list of whitelisted domains If this field is nonempty, only users from a listed domain will be allowed to log in

groups required string[]

Optional list of whitelisted groups If this field is nonempty, only users from a listed group will be allowed to log in

serviceAccountFilePath required string

Optional path to service account json If nonempty, and groups claim is made, will use authentication from file to check groups with the admin directory api

adminEmail required string

Required if ServiceAccountFilePath The email of a GSuite super user which the service account will impersonate when listing groups

microsoft required object

Microsoft holds microsoft authentication configuration

clientId required string

Microsoft client id

clientSecret required string

Microsoft client secret

redirectURI required string

loft redirect uri. Usually https://loft.my.domain/auth/microsoft/callback

tenant required string

tenant configuration parameter controls what kinds of accounts may be authenticated in loft. By default, all types of Microsoft accounts (consumers and organizations) can authenticate in loft via Microsoft. To change this, set the tenant parameter to one of the following:

common - both personal and business/school accounts can authenticate in loft via Microsoft (default) consumers - only personal accounts can authenticate in loft organizations - only business/school accounts can authenticate in loft tenant uuid or tenant name - only accounts belonging to specific tenant identified by either tenant uuid or tenant name can authenticate in loft

groups required string[]

It is possible to require a user to be a member of a particular group in order to be successfully authenticated in loft.

onlySecurityGroups required boolean

configuration option restricts the list to include only security groups. By default all groups (security, Office 365, mailing lists) are included.

useGroupsAsWhitelist required boolean

Restrict the groups claims to include only the user’s groups that are in the configured groups

saml required object

SAML holds saml authentication configuration

redirectURI required string

If the response assertion status value contains a Destination element, it must match this value exactly. Usually looks like https://your-loft-domain/auth/saml/callback

ssoURL required string

SSO URL used for POST value.

caData required string

CAData is a base64 encoded string that holds the ca certificate for validating the signature of the SAML response. Either CAData, CA or InsecureSkipSignatureValidation needs to be defined.

usernameAttr required string

Name of attribute in the returned assertions to map to username

emailAttr required string

Name of attribute in the returned assertions to map to email

groupsAttr required string

Name of attribute in the returned assertions to map to groups

ca required string

CA to use when validating the signature of the SAML response.

insecureSkipSignatureValidation required boolean

Ignore the ca cert

entityIssuer required string

When provided Loft will include this as the Issuer value during AuthnRequest. It will also override the redirectURI as the required audience when evaluating AudienceRestriction elements in the response.

ssoIssuer required string

Issuer value expected in the SAML response. Optional.

groupsDelim required string

If GroupsDelim is supplied the connector assumes groups are returned as a single string instead of multiple attribute values. This delimiter will be used split the groups string.

allowedGroups required string[]

List of groups to filter access based on membership

filterGroups required boolean

If used with allowed groups, only forwards the allowed groups and not all groups specified.

nameIDPolicyFormat required string

Requested format of the NameID. The NameID value is is mapped to the ID Token 'sub' claim.

This can be an abbreviated form of the full URI with just the last component. For example, if this value is set to "emailAddress" the format will resolve to:

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

If no value is specified, this value defaults to:

urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

rancher required object

Rancher holds the rancher authentication options

host required string

Host holds the rancher host, e.g. my-domain.com

bearerToken required string

BearerToken holds the rancher API key in token username and password form. E.g. my-token:my-secret

insecure required boolean

Insecure tells Loft if the Rancher endpoint is insecure.

password required object

Password holds password authentication relevant information

disabled required boolean

If true login via password is disabled

connectors required object[]

Connectors are optional additional connectors for Loft.

id required string

ID is the id that should show up in the url

displayName required string

DisplayName is the name that should show up in the ui

oidc required object

OIDC holds oidc authentication configuration

issuerUrl required string

IssuerURL is the URL the provider signs ID Tokens as. This will be the "iss" field of all tokens produced by the provider and is used for configuration discovery.

The URL is usually the provider's URL without a path, for example "https://accounts.google.com" or "https://login.salesforce.com".

The provider must implement configuration discovery. See: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig

clientId required string

ClientID the JWT must be issued for, the "sub" field. This plugin only trusts a single client to ensure the plugin can be used with public providers.

The plugin supports the "authorized party" OpenID Connect claim, which allows specialized providers to issue tokens to a client for a different client. See: https://openid.net/specs/openid-connect-core-1_0.html#IDToken

clientSecret required string

ClientSecret to issue tokens from the OIDC provider

redirectURI required string

loft redirect uri. E.g. https://loft.my.domain/auth/oidc/callback

postLogoutRedirectURI required string

Loft URI to be redirected to after successful logout by OIDC Provider

caFile required string

Path to a PEM encoded root certificate of the provider. Optional

insecureCa required boolean

Specify whether to communicate without validating SSL certificates

preferredUsername required string

Configurable key which contains the preferred username claims

loftUsernameClaim required string

LoftUsernameClaim is the JWT field to use as the user's username.

usernameClaim required string

UsernameClaim is the JWT field to use as the user's id.

emailClaim required string

EmailClaim is the JWT field to use as the user's email.

allowedExtraClaims required string[]

AllowedExtraClaims are claims of interest that are not part of User by default but may be provided by the OIDC provider.

usernamePrefix required string

UsernamePrefix, if specified, causes claims mapping to username to be prefix with the provided value. A value "oidc:" would result in usernames like "oidc:john".

groupsClaim required string

GroupsClaim, if specified, causes the OIDCAuthenticator to try to populate the user's groups with an ID Token field. If the GroupsClaim field is present in an ID Token the value must be a string or list of strings.

groups required string[]

If required groups is non empty, access is denied if the user is not part of at least one of the specified groups.

scopes required string[]

Scopes that should be sent to the server. If empty, defaults to "email" and "profile".

getUserInfo required boolean

GetUserInfo, if specified, tells the OIDCAuthenticator to try to populate the user's information from the UserInfo.

groupsPrefix required string

GroupsPrefix, if specified, causes claims mapping to group names to be prefixed with the value. A value "oidc:" would result in groups like "oidc:engineering" and "oidc:marketing".

type required string

Type of the OIDC to show in the UI. Only for displaying purposes

github required object

Github holds github authentication configuration

clientId required string

ClientID holds the github client id

clientSecret required string

ClientID holds the github client secret

redirectURI required string

RedirectURI holds the redirect URI. Should be https://loft.domain.tld/auth/github/callback

orgs required object[]

Loft queries the following organizations for group information. Group claims are formatted as "(org):(team)". For example if a user is part of the "engineering" team of the "coreos" org, the group claim would include "coreos:engineering".

If orgs are specified in the config then user MUST be a member of at least one of the specified orgs to authenticate with loft.

name required string

Organization name in github (not slug, full name). Only users in this github organization can authenticate.

teams required string[]

Names of teams in a github organization. A user will be able to authenticate if they are members of at least one of these teams. Users in the organization can authenticate if this field is omitted from the config file.

hostName required string

Required ONLY for GitHub Enterprise. This is the Hostname of the GitHub Enterprise account listed on the management console. Ensure this domain is routable on your network.

rootCA required string

ONLY for GitHub Enterprise. Optional field. Used to support self-signed or untrusted CA root certificates.

gitlab required object

Gitlab holds gitlab authentication configuration

clientId required string

Gitlab client id

clientSecret required string

Gitlab client secret

redirectURI required string

Redirect URI

baseURL required string

BaseURL is optional, default = https://gitlab.com

groups required string[]

Optional groups whitelist, communicated through the "groups" scope. If groups is omitted, all of the user's GitLab groups are returned. If groups is provided, this acts as a whitelist - only the user's GitLab groups that are in the configured groups below will go into the groups claim. Conversely, if the user is not in any of the configured groups, the user will not be authenticated.

google required object

Google holds google authentication configuration

clientId required string

Google client id

clientSecret required string

Google client secret

redirectURI required string

loft redirect uri. E.g. https://loft.my.domain/auth/google/callback

scopes required string[]

defaults to "profile" and "email"

hostedDomains required string[]

Optional list of whitelisted domains If this field is nonempty, only users from a listed domain will be allowed to log in

groups required string[]

Optional list of whitelisted groups If this field is nonempty, only users from a listed group will be allowed to log in

serviceAccountFilePath required string

Optional path to service account json If nonempty, and groups claim is made, will use authentication from file to check groups with the admin directory api

adminEmail required string

Required if ServiceAccountFilePath The email of a GSuite super user which the service account will impersonate when listing groups

microsoft required object

Microsoft holds microsoft authentication configuration

clientId required string

Microsoft client id

clientSecret required string

Microsoft client secret

redirectURI required string

loft redirect uri. Usually https://loft.my.domain/auth/microsoft/callback

tenant required string

tenant configuration parameter controls what kinds of accounts may be authenticated in loft. By default, all types of Microsoft accounts (consumers and organizations) can authenticate in loft via Microsoft. To change this, set the tenant parameter to one of the following:

common - both personal and business/school accounts can authenticate in loft via Microsoft (default) consumers - only personal accounts can authenticate in loft organizations - only business/school accounts can authenticate in loft tenant uuid or tenant name - only accounts belonging to specific tenant identified by either tenant uuid or tenant name can authenticate in loft

groups required string[]

It is possible to require a user to be a member of a particular group in order to be successfully authenticated in loft.

onlySecurityGroups required boolean

configuration option restricts the list to include only security groups. By default all groups (security, Office 365, mailing lists) are included.

useGroupsAsWhitelist required boolean

Restrict the groups claims to include only the user’s groups that are in the configured groups

saml required object

SAML holds saml authentication configuration

redirectURI required string

If the response assertion status value contains a Destination element, it must match this value exactly. Usually looks like https://your-loft-domain/auth/saml/callback

ssoURL required string

SSO URL used for POST value.

caData required string

CAData is a base64 encoded string that holds the ca certificate for validating the signature of the SAML response. Either CAData, CA or InsecureSkipSignatureValidation needs to be defined.

usernameAttr required string

Name of attribute in the returned assertions to map to username

emailAttr required string

Name of attribute in the returned assertions to map to email

groupsAttr required string

Name of attribute in the returned assertions to map to groups

ca required string

CA to use when validating the signature of the SAML response.

insecureSkipSignatureValidation required boolean

Ignore the ca cert

entityIssuer required string

When provided Loft will include this as the Issuer value during AuthnRequest. It will also override the redirectURI as the required audience when evaluating AudienceRestriction elements in the response.

ssoIssuer required string

Issuer value expected in the SAML response. Optional.

groupsDelim required string

If GroupsDelim is supplied the connector assumes groups are returned as a single string instead of multiple attribute values. This delimiter will be used split the groups string.

allowedGroups required string[]

List of groups to filter access based on membership

filterGroups required boolean

If used with allowed groups, only forwards the allowed groups and not all groups specified.

nameIDPolicyFormat required string

Requested format of the NameID. The NameID value is is mapped to the ID Token 'sub' claim.

This can be an abbreviated form of the full URI with just the last component. For example, if this value is set to "emailAddress" the format will resolve to:

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

If no value is specified, this value defaults to:

urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

disableTeamCreation required boolean

Prevents from team creation for the new groups associated with the user at the time of logging in through sso, Default behaviour is false, this means that teams will be created for new groups.

disableUserCreation required boolean

DisableUserCreation prevents the SSO connectors from creating a new user on a users initial signin through sso. Default behaviour is false, this means that a new user object will be created once a user without a Kubernetes user object logs in.

accessKeyMaxTTLSeconds required integer

AccessKeyMaxTTLSeconds is the global maximum lifespan of an accesskey in seconds. Leaving it 0 or unspecified will disable it. Specifying 2592000 will mean all keys have a Time-To-Live of 30 days.

loginAccessKeyTTLSeconds required integer

LoginAccessKeyTTLSeconds is the time in seconds an access key is kept until it is deleted. Leaving it unspecified will default to 20 days. Setting it to zero will disable the ttl. Specifying 2592000 will mean all keys have a default Time-To-Live of 30 days.

customHttpHeaders required object

CustomHttpHeaders are additional headers that should be set for the authentication endpoints

groupsFilters required string[]

GroupsFilters is a regex expression to only save matching sso groups into the user resource

oidc required object

DEPRECATED: Configure the OIDC clients using either the OIDC Client UI or a secret. By default, vCluster Platform as an OIDC Provider is enabled but does not function without OIDC clients.

enabled required boolean

If true indicates that loft will act as an OIDC server

wildcardRedirect required boolean

If true indicates that loft will allow wildcard '*' in client redirectURIs

clients required object[]

The clients that are allowed to request loft tokens

name required string

The client name

clientId required string

The client id of the client

clientSecret required string

The client secret of the client

redirectURIs required string[]

A registered set of redirect URIs. When redirecting from dex to the client, the URI requested to redirect to MUST match one of these values, unless the client is "public".

apps required object

Apps holds configuration around apps

noDefault required boolean

If this option is true, loft will not try to parse the default apps

repositories required object[]

These are additional repositories that are parsed by loft

name required string

Name is the name of the repository

url required string

URL is the repository url

username required string

Username of the repository

password required string

Password of the repository

insecure required boolean

Insecure specifies if the chart should be retrieved without TLS verification

predefinedApps required object[]

Predefined apps that can be selected in the Spaces ) Space menu

chart required string

Chart holds the repo/chart name of the predefined app

initialVersion required string

InitialVersion holds the initial version of this app. This version will be selected automatically.

initialValues required string

InitialValues holds the initial values for this app. The values will be prefilled automatically. There are certain placeholders that can be used within the values that are replaced by the loft UI automatically.

clusters required string[]

Holds the cluster names where to display this app

title required string

Title is the name that should be displayed for the predefined app. If empty the chart name is used.

iconUrl required string

IconURL specifies an url to the icon that should be displayed for this app. If none is specified the icon from the chart metadata is used.

readmeUrl required string

ReadmeURL specifies an url to the readme page of this predefined app. If empty an url will be constructed to artifact hub.

audit required object

Audit holds audit configuration

enabled required boolean

If audit is enabled and incoming api requests will be logged based on the supplied policy.

disableAgentSyncBack required boolean

If true, the agent will not send back any audit logs to Loft itself.

level required integer

Level is an optional log level for audit logs. Cannot be used together with policy

policy required object

The audit policy to use and log requests. By default loft will not log anything

rules required object[]

Rules specify the audit Level a request should be recorded at. A request may match multiple rules, in which case the FIRST matching rule is used. The default audit level is None, but can be overridden by a catch-all rule at the end of the list. PolicyRules are strictly ordered.

level required string

The Level that requests matching this rule are recorded at.

users required string[]

The users (by authenticated user name) this rule applies to. An empty list implies every user.

userGroups required string[]

The user groups this rule applies to. A user is considered matching if it is a member of any of the UserGroups. An empty list implies every user group.

verbs required string[]

The verbs that match this rule. An empty list implies every verb.

resources required object[]

Resources that this rule matches. An empty list implies all kinds in all API groups.

group required string

Group is the name of the API group that contains the resources. The empty string represents the core API group.

resources required string[]

Resources is a list of resources this rule applies to.

For example: 'pods' matches pods. 'pods/log' matches the log subresource of pods. '' matches all resources and their subresources. 'pods/' matches all subresources of pods. '*/scale' matches all scale subresources.

If wildcard is present, the validation rule will ensure resources do not overlap with each other.

An empty list implies all resources and subresources in this API groups apply.

resourceNames required string[]

ResourceNames is a list of resource instance names that the policy matches. Using this field requires Resources to be specified. An empty list implies that every instance of the resource is matched.

namespaces required string[]

Namespaces that this rule matches. The empty string "" matches non-namespaced resources. An empty list implies every namespace.

nonResourceURLs required string[]

NonResourceURLs is a set of URL paths that should be audited. s are allowed, but only as the full, final step in the path. Examples: "/metrics" - Log requests for apiserver metrics "/healthz" - Log all health checks

omitStages required string[]

OmitStages is a list of stages for which no events are created. Note that this can also be specified policy wide in which case the union of both are omitted. An empty list means no restrictions will apply.

requestTargets required string[]

RequestTargets is a list of request targets for which events are created. An empty list implies every request.

clusters required string[]

Clusters that this rule matches. Only applies to cluster requests. If this is set, no events for non cluster requests will be created. An empty list means no restrictions will apply.

omitStages required string[]

OmitStages is a list of stages for which no events are created. Note that this can also be specified per rule in which case the union of both are omitted.

dataStoreEndpoint required string

DataStoreEndpoint is an endpoint to store events in.

dataStoreTTL required integer

DataStoreMaxAge is the maximum number of hours to retain old log events in the datastore

path required string

The path where to save the audit log files. This is required if audit is enabled. Backup log files will be retained in the same directory.

maxAge required integer

MaxAge is the maximum number of days to retain old log files based on the timestamp encoded in their filename. Note that a day is defined as 24 hours and may not exactly correspond to calendar days due to daylight savings, leap seconds, etc. The default is not to remove old log files based on age.

maxBackups required integer

MaxBackups is the maximum number of old log files to retain. The default is to retain all old log files (though MaxAge may still cause them to get deleted.)

maxSize required integer

MaxSize is the maximum size in megabytes of the log file before it gets rotated. It defaults to 100 megabytes.

compress required boolean

Compress determines if the rotated log files should be compressed using gzip. The default is not to perform compression.

loftHost required string

LoftHost holds the domain where the loft instance is hosted. This should not include https or http. E.g. loft.my-domain.com

projectNamespacePrefix required string

ProjectNamespacePrefix holds the prefix for loft project namespaces. Omitted defaults to "p-"

devPodSubDomain required string

DevPodSubDomain holds a subdomain in the following form *.workspace.my-domain.com

uiSettings required object

UISettings holds the settings for modifying the Loft user interface

loftVersion required string

LoftVersion holds the current loft version

logoURL required string

LogoURL is url pointing to the logo to use in the Loft UI. This path must be accessible for clients accessing the Loft UI!

smallLogoURL required string

SmallLogoURL is url pointing to the small logo to use in the Loft UI. This path must be accessible for clients accessing the Loft UI!

logoBackgroundColor required string

LogoBackgroundColor is the color value (ex: "#12345") to use as the background color for the logo

legalTemplate required string

LegalTemplate is a text (html) string containing the legal template to prompt to users when authenticating to Loft

primaryColor required string

PrimaryColor is the color value (ex: "#12345") to use as the primary color

sidebarColor required string

SidebarColor is the color value (ex: "#12345") to use for the sidebar

accentColor required string

AccentColor is the color value (ex: "#12345") to use for the accent

customCss required string[]

CustomCSS holds URLs with custom css files that should be included when loading the UI

customJavaScript required string[]

CustomJavaScript holds URLs with custom js files that should be included when loading the UI

navBarButtons required object[]

NavBarButtons holds extra nav bar buttons

position required string

Position holds the position of the button, can be one of: TopStart, TopEnd, BottomStart, BottomEnd. Defaults to BottomEnd

text required string

Text holds text for the button

link required string

Link holds the link of the navbar button

icon required string

Icon holds the url of the icon to display

vault required object

VaultIntegration holds the vault integration configuration

enabled required boolean

Enabled indicates if the Vault Integration is enabled for the project -- this knob only enables the syncing of secrets to or from Vault, but does not setup Kubernetes authentication methods or Kubernetes secrets engines for vclusters.

address required string

Address defines the address of the Vault instance to use for this project. Will default to the VAULT_ADDR environment variable if not provided.

skipTLSVerify required boolean

SkipTLSVerify defines if TLS verification should be skipped when connecting to Vault.

namespace required string

Namespace defines the namespace to use when storing secrets in Vault.

auth required object

Auth defines the authentication method to use for this project.

token required string

Token defines the token to use for authentication.

tokenSecretRef required object

TokenSecretRef defines the Kubernetes secret to use for token authentication. Will be used if token is not provided.

Secret data should contain the token key.

name required string

Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Drop kubebuilder:default when controller-gen doesn't need it https://github.com/kubernetes-sigs/kubebuilder/issues/3896.

key required string

The key of the secret to select from. Must be a valid secret key.

optional required boolean

Specify whether the Secret or its key must be defined

syncInterval required string

SyncInterval defines the interval at which to sync secrets from Vault. Defaults to 1m. See https://pkg.go.dev/time#ParseDuration for supported formats.

disableConfigEndpoint required boolean

DisableLoftConfigEndpoint will disable setting config via the UI and config.management.loft.sh endpoint

cloud required object

Cloud holds the settings to be used exclusively in vCluster Cloud based environments and deployments.

releaseChannel required string

ReleaseChannel specifies the release channel for the cloud configuration. This can be used to determine which updates or versions are applied.

maintenanceWindow required object

MaintenanceWindow specifies the maintenance window for the cloud configuration. This is a structured representation of the time window during which maintenance can occur.

dayOfWeek required string

DayOfWeek specifies the day of the week for the maintenance window. It should be a string representing the day, e.g., "Monday", "Tuesday", etc.

timeWindow required string

TimeWindow specifies the time window for the maintenance. It should be a string representing the time range in 24-hour format, in UTC, e.g., "02:00-03:00".

costControl required object

CostControl holds the settings related to the Cost Control ROI dashboard and its metrics gathering infrastructure

enabled required boolean

Enabled specifies whether the ROI dashboard should be available in the UI, and if the metrics infrastructure that provides dashboard data is deployed

global required object

Global are settings for globally managed components

metrics required object

Metrics these settings apply to metric infrastructure used to aggregate metrics across all connected clusters

replicas required integer

Replicas is the number of desired replicas.

resources required object

Resources are compute resource required by the metrics backend

limits required object

Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

requests required object

Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

claims required object[]

Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container.

This is an alpha field and requires enabling the DynamicResourceAllocation feature gate.

This field is immutable. It can only be set for containers.

name required string

Name must match the name of one entry in pod.spec.resourceClaims of the Pod where this field is used. It makes that resource available inside a container.

request required string

Request is the name chosen for a request in the referenced claim. If empty, everything from the claim is made available, otherwise only the result of this request.

retention required string

Retention is the metrics data retention period. Default is 1y

storage required object

storageClass required string

StorageClass the storage class to use when provisioning the metrics backend's persistent volume If set to "-" or "" dynamic provisioning is disabled If set to undefined or null (the default), the cluster's default storage class is used for provisioning

size required string

Size the size of the metrics backend's persistent volume

cluster required object

Cluster are settings for each cluster's managed components. These settings apply to all connected clusters unless overridden by modifying the Cluster's spec

metrics required object

Metrics are settings applied to metric infrastructure in each connected cluster. These can be overridden in individual clusters by modifying the Cluster's spec

replicas required integer

Replicas is the number of desired replicas.

resources required object

Resources are compute resource required by the metrics backend

limits required object

Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

requests required object

Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

claims required object[]

Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container.

This is an alpha field and requires enabling the DynamicResourceAllocation feature gate.

This field is immutable. It can only be set for containers.

name required string

Name must match the name of one entry in pod.spec.resourceClaims of the Pod where this field is used. It makes that resource available inside a container.

request required string

Request is the name chosen for a request in the referenced claim. If empty, everything from the claim is made available, otherwise only the result of this request.

retention required string

Retention is the metrics data retention period. Default is 1y

storage required object

storageClass required string

StorageClass the storage class to use when provisioning the metrics backend's persistent volume If set to "-" or "" dynamic provisioning is disabled If set to undefined or null (the default), the cluster's default storage class is used for provisioning

size required string

Size the size of the metrics backend's persistent volume

opencost required object

OpenCost are settings applied to OpenCost deployments in each connected cluster. These can be overridden in individual clusters by modifying the Cluster's spec

replicas required integer

Replicas is the number of desired replicas.

resources required object

Resources are compute resource required by the OpenCost backend

limits required object

Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

requests required object

Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

claims required object[]

Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container.

This is an alpha field and requires enabling the DynamicResourceAllocation feature gate.

This field is immutable. It can only be set for containers.

name required string

Name must match the name of one entry in pod.spec.resourceClaims of the Pod where this field is used. It makes that resource available inside a container.

request required string

Request is the name chosen for a request in the referenced claim. If empty, everything from the claim is made available, otherwise only the result of this request.

settings required object

Settings specify price-related settings that are taken into account for the ROI dashboard calculations.

priceCurrency required string

PriceCurrency specifies the currency.

averageCPUPricePerNode required object

AvgCPUPricePerNode specifies the average CPU price per node.

price required number

Price specifies the price.

timePeriod required string

TimePeriod specifies the time period for the price.

averageRAMPricePerNode required object

AvgRAMPricePerNode specifies the average RAM price per node.

price required number

Price specifies the price.

timePeriod required string

TimePeriod specifies the time period for the price.

gpuSettings required object

GPUSettings specifies GPU related settings.

enabled required boolean

Enabled specifies whether GPU settings should be available in the UI.

averageGPUPrice required object

AvgGPUPrice specifies the average GPU price.

price required number

Price specifies the price.

timePeriod required string

TimePeriod specifies the time period for the price.

controlPlanePricePerCluster required object

ControlPlanePricePerCluster specifies the price of one physical cluster.

price required number

Price specifies the price.

timePeriod required string

TimePeriod specifies the time period for the price.

imageBuilder required object

ImageBuilder holds the settings related to the image builder

enabled required boolean

Enabled specifies whether the remote image builder should be available. If it's not available building ad-hoc images from a devcontainer.json is not supported

replicas required integer

Replicas is the number of desired replicas.

resources required object

Resources are compute resource required by the buildkit containers

limits required object

Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

requests required object

Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

claims required object[]

Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container.

This is an alpha field and requires enabling the DynamicResourceAllocation feature gate.

This field is immutable. It can only be set for containers.

name required string

Name must match the name of one entry in pod.spec.resourceClaims of the Pod where this field is used. It makes that resource available inside a container.

request required string

Request is the name chosen for a request in the referenced claim. If empty, everything from the claim is made available, otherwise only the result of this request.