Templates For Cluster Accounts

Account Templates are a way to automatically create an account in a connected cluster for a new team or user and optionally create other resources that belong to such an account. Account Templates have a sync functionality and provide an easy way to manage multiple accounts and resources in multiple clusters with just a single resource.

Since cluster access is determined in Loft by who has an account in which cluster, creating an account in a cluster is equivalent of giving a user or team access to a cluster. Account templates are particularly useful when using single sign-on because users are being created when they log in for the first time and without any cluster accounts, a new user will not automatically be able to do anything. Account templates can solve this by automatically creating accounts for such users.

A cluster account template is a Custom Resource in Kubernetes and consists of 3 components:

1. Cluster Selector: A label selector to select clusters to define in which clusters a new account will be created.
2. Account Template: An account template that specifies how the created account should look like.
3. Templates For Additional Account Resources: An array of owned resources (e.g. AccountQuota, ClusterRoleBinding etc.), which the account owns and an owner reference to the account is set to. This has the advantage that if the account is deleted, all of its owned resources are deleted as well and ownership of resources can be easily identified.

Create Account Templates

You can create cluster account templates either via kubectl or the Loft UI.

UI

Navigate to the Account Templates section under Users and press Add Cluster Account Template.

Create a new Cluster Account Template

You will be presented with several options how the Cluster Account Template can be configured:

Create a new Cluster Account Template

At first, you can optionally specify the Kubernetes Metadata of Cluster Account Template such as annotations or labels for this Account Template object.

Then, you can specify what the account template should do:

1. Select Clusters: Labels in the form of label1=value1 that specify which clusters an account should be created in. If empty, all clusters are selected. You will see which clusters are selected in the account templates table under the column 'Selected Clusters'
2. Create Account in Clusters: Account settings for the account that will be created in the cluster. This section is very similar to the Space Creation Settings section in the Clusters -> Accounts drawer.
3. Create Account Resources in Clusters:
   • Account Quota: Here, you can define the hard limits for an account quota that will be created for the account. Leave empty to create no AccountQuota for the account.
   • Cluster Role Bindings: For each of these cluster roles, a ClusterRoleBinding is created for the account. Use this, for example, if you want to grant a user full cluster access.
   • Other Resources: Other custom Kubernetes resources that should be created in the target cluster for the account. This can be any Kubernetes resource yaml. Bear in mind that:
     • No metadata section required: Loft will automatically set metadata.generateName if no metadata for a resource is provided
     • You can use ${LOFT_ACCOUNT_NAME} as a placeholder for the account name. For example, in an AccountQuota you can set spec.account: ${LOFT_ACCOUNT_NAME}. This will be replaced by the correct account name when the account is actually created.
     • An ownerReference will be set automatically for the resource that references the account. This means that deleting the account will also delete all its resources.

After you are done configuring the ClusterAccountTemplate, press Create to create the resource. This will not create any accounts yet.

kubectl

Create file clusteraccounttemplate.yaml:

apiVersion: storage.loft.sh/v1
kind: ClusterAccountTemplate
metadata:
  name: my-cluster-account-template
spec:
  accountTemplate:
    spec:
      space:
        clusterRole: loft-cluster-space-default
  owns:
   - apiVersion: config.kiosk.sh/v1alpha1
     kind: AccountQuota
     # No metadata needed, generateName will be set automatically
     spec:
       account: '${LOFT_ACCOUNT_NAME}'
       quota:
         hard:
           limits.cpu: '8'
           limits.memory: '16Gi'
           requests.cpu: '2'
           requests.memory: '4Gi'
    - apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRoleBinding
      # No subjects needed, kiosk automatically syncs those based on the ownerReference
      roleRef:
        apiGroup: rbac.authorization.k8s.io
        kind: ClusterRole
        name: cluster-admin

Create the Cluster Account Template using kubectl:

# IMPORTANT: Run this command inside the Loft management cluster
kubectl create -f clusteraccounttemplate.yaml

Use Account Templates

Applying cluster account templates to a user or team can be done either via kubectl or the Loft UI. For automatically applying account templates to users on single sign-on, please see the next section.

UI

Apply Cluster Account Templates

In the Account Templates section, you are able to select one or multiple cluster account templates to apply to a user or team when creating or editing it.

Preselect Account Templates

Some account templates might be preselected, these are the templates that have the label loft.sh/default-template: "true" specified.

How Templates are applied

The account templates will be applied in the order that they are specified, if multiple account templates target the same cluster, only ONE account is created for the cluster and templates are skipped for a cluster if an account for that user or team does already exist. If an error during applying the account templates is encountered, the error message can be viewed in the Status column of the user or team.

Reapply Templates

By default, Loft will try to reapply the Cluster Account Template as soon as it changes. If a new cluster is created that matches the label selector of the Cluster Account Template, an account for all users and teams that use this Template will be created.

Deleting Accounts

Loft will never delete any accounts automatically, as this can have severe consequences like all account spaces and resources getting deleted. If you want to delete a template from a user or team and the corresponding account resources, please remove the template from the user first and then delete the account of the user or team in the cluster. This will delete ALL spaces and resources the account owns in the cluster.

Excluding Clusters for Users or Teams

You can exclude certain clusters for a user or team with the annotation loft.sh/account-templates-ignore-clusters that will prevent any cluster account template to create an account for this user or team in one of the specified clusters. For example:

apiVersion: management.loft.sh/v1
kind: User
metadata:
  name: admin
  annotations:
    # This will exclude the clusters cluster1 and cluster2 for user admin
    # in all specified cluster account templates under spec.clusterAccountTemplates
    loft.sh/account-templates-ignore-clusters: cluster1,cluster2
spec:
  displayName: John Doe
  username: admin
  email: john.doe@test.com
  subject: loft-admin 
  clusterAccountTemplates:
  - name: loft-all-clusters-default
    sync: true

kubectl

# Users
# IMPORTANT: Run this command inside the Loft management cluster
kubectl edit user my-user

# Teams
# IMPORTANT: Run this command inside the Loft management cluster
kubectl edit team my-team

Then change the user or team yaml according to this:

apiVersion: storage.loft.sh/v1
kind: User
[...]
spec:
  [...]
  # The cluster account templates you want to apply
  clusterAccountTemplates:
    - name: loft-all-clusters-default
      sync: true  # <- Set this if you want to update the created accounts automatically as soon as the template changes

Sync Cluster Account Templates

Syncing cluster account templates is done by three-way merging the old cluster account template, the new cluster account template and the already existing account and account resources (see the helm docs for more informations about three-way merges). From these resources, Loft will derive patches (or create and delete requests) that will be applied on the account and the resources, based on what has changed in the cluster account template.

For example, if you only change the space limit for the account in a cluster account template, Loft will look through all users and teams that use this template and try to update their account, by patching just the spec.space.limit field of the account. All other fields, annotations and labels of the account stay untouched. This means you can change the account and its resources without worrying that the sync will revert it back. The only fields that will be changed are the ones that have changed between the old and new cluster account template state.

For account resources such as cluster roles or account quotas that belong to the account, the same principle is applied. The only difference here is that these resources can be created or deleted as well based on if they have been added or removed from the cluster account template.

Enabling Sync

If you assign a cluster account template via the UI to a user or team, cluster account template sync will be enabled by default. If you assign a template manually via kubectl, make sure that the spec.clusterAccountTemplates[*].sync is set to true. If you assign cluster account templates via SSO, please make sure that you enable sync via the clusterAccountTemplates[*].sync or groupClusterAccountTemplates[*].clusterAccountTemplates[*].sync option

For Single Sign-On (SSO)

If you configured single sign-on, you may want to give users access to certain clusters when they sign in for the first time, potentially depending on their groups.

To tell Loft to automatically apply certain account templates to new users when they sign in via SSO for the first time, navigate to Admin > Config in Loft and add the following lines to your auth.oidc section of the config:

auth:
  oidc:
    issuerUrl: 'https://my.issuer.com/'
    clientId: CLIENT_ID
    clientSecret: CLIENT_SECRET
    groupsClaim: groups
    getUserInfo: true
    clusterAccountTemplates:              # Apply these templates to every new user
    - name: loft-all-clusters-default     # Name of template 1
      sync: true                          # If enabled Loft will sync changes in the cluster account template to the created accounts
    - name: some-other-account-template   # Name of template 2
      sync: true                          # If enabled Loft will sync changes in the cluster account template to the created accounts
    groupClusterAccountTemplates:         # Apply templates depending on the user's groups
     - group: admin-group:                # Apply if user has group `admin-group`
       clusterAccountTemplates:
       - name: loft-all-clusters-admin    # Name of the account template to apply
         sync: true                       # If enabled Loft will sync changes in the cluster account template to the created accounts

Configure Automatic Cluster Account Templates

Sync Cluster Account Templates

Usually it is recommended to enable sync via the clusterAccountTemplates[*].sync or groupClusterAccountTemplates[*].clusterAccountTemplates[*].sync option, as this enables you to maintain multiple accounts and resources just with a single cluster account template. Loft will watch the cluster account templates and update all users and teams that use this template automatically as soon as the template changes.

Update Cluster Account Templates

Loft will make sure that the cluster account templates that you specify in clusterAccountTemplates and groupClusterAccountTemplates will be synced to the user every time the users SSO tokens are refreshed (e.g. during login or after a certain time automatically). This means that if you for example add a new cluster account template in auth.oidc.clusterAccountTemplates this will also be set on an already existing user after their credentials were refreshed.