What are Users and Teams
Users and teams are the core identities in vCluster Platform. A user represents an individual or service identity that can authenticate to the platform. A team represents a group of users that should receive the same access, ownership, and platform-level configuration.
They are used throughout the platform, not just during login. Users and teams can receive management roles, become project members, own resources, and consume quota. They can also receive image pull secrets and appear as Kubernetes subjects in reconciled role-based access control (RBAC) objects that Platform automatically creates and keeps up to date.
Users​
A user is the platform record for one authenticated identity that can be human or automated. Platform tracks the identifiers needed to recognize that identity, including a stable platform name, an SSO-matching subject, and the groups associated with it. Beyond identity, a user record can also grant management roles directly and hand out registry credentials for CLI-based image pulls. It can also be disabled to block login without deleting the user or its resources.
Platform also computes each user's current effective team membership. Effective means the fully resolved result right now, not the raw configuration. This lets admins see which teams a user actually belongs to at this moment, not just which teams were configured to include them.
See the User resource reference for the full list of fields.
Teams​
A team is the platform record for a shared identity boundary. Teams do not log in on their own. Instead, they become part of an authenticated user's effective identity when that user is a member.
Membership comes from two places. Some users are explicitly assigned to the team, and others belong because their groups match a token or SSO group name configured on the team. This lets you combine manual team assignment with identity-provider-driven membership. For example, you might add a break-glass admin user (an emergency-access account for when normal login isn't available) directly to a team. The rest of the team's membership can then come from an SSO group, such as OIDC, SAML, GitHub, GitLab, Google, Microsoft, LDAP, or Dex.
Like users, teams can be granted management roles and image pull secrets directly. Those apply to whichever users are currently members of the team.
See the Team resource reference for the full list of fields.
SSO and account provisioning​
With SSO, Platform can create or update users from identity provider claims. The important design choice is usually where to manage group membership:
- Manage membership in the identity provider when your organization already has authoritative groups.
- Manage membership in Platform when teams are platform-specific or short-lived.
- Use both when you need exceptions, such as manually adding a service user to a team whose human members come from SSO.
SSO configuration can also do more than manage membership. It can apply cluster account templates (predefined access configurations for connected clusters) to users when they first sign in. It can also keep those templates synchronized when tokens refresh. This is useful when users or teams should automatically receive access to particular connected clusters after authentication.
How effective identity works​
After a user authenticates, Platform builds a Kubernetes-compatible identity for that request. The resulting identity includes:
- the user's subject as the Kubernetes user name;
- the user's direct groups;
system:authenticated;- platform groups such as
loft:user:<user-name>; - one
loft:team:<team-name>group for every effective team membership.
This is why teams are useful beyond the UI. Platform permissions, project membership, admission policies, and tenant cluster access can all reason about users and teams as Kubernetes-style subjects and groups.
Authentication and authorization →
Permissions and roles​
Platform uses Kubernetes RBAC concepts to authorize users and teams. A management role defines allowed actions, and Platform applies that role to one or more users or teams through reconciled role bindings.
Grant roles to teams when many people should share the same access. Grant roles directly to users only for exceptions, such as platform administrators, automation users, or temporary troubleshooting access. Direct user roles and team-inherited roles are additive, so a user can receive permissions from several places at once.
Users and permissions overview →
Project membership​
Projects are where users and teams usually become operational. A project's member list can include specific users, specific teams, or all users at once. Each member receives a project role that defines what they can do inside that project.
When a team is a project member, all current team members receive the team's project access. Platform's project members API resolves both the direct team entry and the users who belong to that team. This lets project views show the effective member set.
Project ownership is related but separate. A project can have spec.owner.user or spec.owner.team, and the owner is included in the resolved project members list. Owners and members are often the same organizational unit, but they answer different questions. Ownership says who the project belongs to. Membership says who can access it and with which role.
Resource ownership​
Many platform resources can be owned by either a user or a team. Platform records that ownership through owner fields on the resource and through ownership labels applied to resources such as namespaces, space instances, tenant cluster instances, and access keys.
Ownership affects how resources are displayed, who can manage them, how project quota is counted, and how sharing workflows behave. Use team ownership for shared environments and long-lived resources that should survive changes in individual staffing. Use user ownership for personal development environments, individual access keys, or short-lived work that should clearly belong to one person.
Platform labels and annotations →
Quotas​
Project quotas can apply to the whole project or to each user or team inside the project. A project-wide quota caps the total resources that the project can consume across all members. A per-user/team quota caps the resources that a single user or team can consume.
Ownership determines which quota a resource's usage counts against. A team-owned resource counts against that team's quota, and a user-owned resource counts against that user's quota, even when the user also belongs to a team. Team and individual usage are tracked separately, so a team-owned resource never counts against a member's personal quota, and a member's personally owned resource never counts against the team's quota.
Automation and service accounts​
As the Users section noted, a user or team doesn't need a human behind it. For GitOps, CI/CD, or external automation, create a dedicated user and issue an access key for that user. The access key authenticates as that user, and any access key scope can only narrow what the user is already allowed to do.
Access keys can also authenticate as a team. A team access key acts as the team identity, so it receives the team's roles and project memberships rather than a particular user's direct roles. Use this when automation should belong to a shared operational identity instead of an individual user.
Access troubleshooting​
When troubleshooting access, check the actor first. Is the request using a normal user login, a user access key, or a team access key? Then review the user's teams, direct roles, team roles, project memberships, resource ownership, and any access key scope that might be narrowing the request.
Access modeling​
For most installations, start with teams as the primary unit of access. Create teams that match how work is owned, such as platform administrators, application teams, customer accounts, environments, or automation roles. Add those teams to projects, grant project roles to teams, and use direct user permissions only where the exception is intentional.
Use user-owned resources for personal workspaces and use team-owned resources for shared services. This keeps access, ownership, and quota behavior predictable as people join, leave, or move between teams.