Skip to main content
Version: main 🚧

Stack Permissions

Stack permissions use Kubernetes role-based access control (RBAC) in the management.loft.sh API group. StackTemplate resources are cluster-scoped. StackInstance resources and their outputs subresource are project-scoped.

Grant broad access with a ClusterRoleTemplate, as shown below. To share one object with specific users or teams, set its spec.access. A StackTemplate also sets its owner and access in the Management Access section of its form. A StackInstance passes its owner and access settings to every App and Argo CD Application it creates.

Permission map​

Grant only the verbs required by each role:

TaskResourceVerbs
Browse the Stack catalogstacktemplatesget, list. The default management role grants every authenticated user list only. A list returns just the templates the user can get, such as templates they own, templates whose spec.access includes them, or every template through a role such as Template Viewer.
Create Stack templatesstacktemplatescreate
Manage Stack templatesstacktemplatesget, list, watch, create, update, patch, delete
Install a Stackstackinstancescreate
View Stack statusstackinstancesget, list, watch
Change or remove a Stackstackinstancesupdate, patch, delete
Read published outputsstackinstances/outputsget

Reading a StackInstance does not grant access to its published values. Grant get on stackinstances/outputs separately because published values can include data captured from Secrets. The outputs API marks values captured from Secrets as sensitive. A value that one task passes to another is also written to the generated child, which shares the StackInstance's spec.access. See Publish outputs.

Creating a StackInstance also runs checks beyond the resource rules on this page:

  • Destination access. Both the caller and the StackInstance owner need access to the destination: use on the cluster's VirtualClusterInstance, or get on the control plane cluster. A control plane cluster destination must also be in the project's allowed clusters. Tasks read their outputs as the owner, so the owner's access is checked again at every capture. If the owner loses access, those tasks fail with OutputReadForbidden.
  • Allowed templates. A referenced StackTemplate must be in the project's allowed templates.
  • Project secrets. Both the caller and the owner need get on any project secret that an inline App task's chart credentials reference.
  • Licensing. Each task type needs its license feature. See Create a Stack template.

Connectors aren't part of these checks, and the default management role doesn't grant access to them. Assign the Connector Admin or Connector Viewer role to users who manage connectors.

Default roles​

The built-in Template Admin, Template Creator, and Template Viewer global roles include stacktemplates alongside the other template resources. Template Admin grants all verbs, and Template Viewer grants get. Template Creator's rule grants only create, but a StackTemplate defaults its owner to whoever creates it, and owner access separately grants that creator get, update, patch, and delete on templates they created.

The built-in Project Admin role grants all verbs on both stackinstances and stackinstances/outputs. The built-in Project User and Project Viewer roles don't grant StackInstance permissions, so their members don't see a cluster's Stacks tab. Add the required rules to a custom project role when those members need to install or operate Stacks.

Tenant users​

Inside a tenant, the tenant boundary narrows these permissions further:

  • A tenant can't author StackTemplates. It sees only the StackTemplates that its templates capability grants. A template outside that grant reads as missing, so a StackInstance that references it reports TemplateNotFound.
  • A tenant creates and owns its own StackInstances, but never sees StackInstances that a platform admin owns.
  • The project's allowed templates still apply, so a Stack needs both the tenant grant and the project allow-list.
  • A tenant deploys Stacks only to its own clusters. A StackInstance in a tenant's project that targets a control plane cluster is refused with deploying to cluster "<name>" is not allowed, even when the tenant was lent that cluster and even when a platform admin creates the StackInstance.

Custom project role example​

The following rule lets a project member create and monitor StackInstances and read their published outputs. The rule itself doesn't grant update or delete access. StackInstance creation defaults the owner to the caller, though, and owner access separately grants that member get, update, patch, delete, and the outputs subresource on instances they created. It doesn't extend to instances someone else created.

apiVersion: management.loft.sh/v1
kind: ClusterRoleTemplate
metadata:
name: stack-user
labels:
loft.sh/project-role: "true"
spec:
displayName: Stack User
management: true
clusterRoleTemplate:
rules:
- apiGroups:
- management.loft.sh
resources:
- stackinstances
verbs:
- create
- get
- list
- watch
- apiGroups:
- management.loft.sh
resources:
- stackinstances/outputs
verbs:
- get

Assign the custom role to project members as described in Project membership. For API request paths and resource fields, see the StackTemplate, StackInstance, and outputs references.