Skip to content

How to Create an IAM Group#

Learn how to create a group in your organisation's identity provider and manage its members with a Group claim.

Maria, an organisation administrator at ACME Corp, wants to create a group for her engineering team so she can assign project access to all members at once rather than individually.

Prerequisites#

  • Access to your organisation's project
  • The group.iam.cloud.stakater.com API available
  • kubectl configured with your organisation project kubeconfig
  • Sufficient permissions to create Group resources in your project

What Gets Created#

When you create a Group claim, the platform provisions:

  • An organisation group in your organisation's IdP
  • Group memberships if members are provided (adds existing organisation users to the group)

In the Console#

Groups sit next to Users under Identity & Access. The create form asks for one name, Group name, at the top. It is metadata.name in the claim, and the platform uses it as the group's name in your organisation's identity provider:

The Create Group form

Members are added one at a time: type the user's email address in the Members field and press Enter to commit it. A value left as draft text is not part of the group. If the field is not on the form, switch it to Advanced — members are optional, so Standard mode may hide them:

The Create Group form with three members added

The group's detail page then shows the memberships the platform actually applied, which is the console equivalent of the status.memberships check in Step 4:

A group detail page showing its members

Step 1: Define Your Group Claim#

Create a file named group.yaml:

apiVersion: iam.cloud.stakater.com/v1
kind: Group
metadata:
  name: engineering-team
spec:
  parameters: {}

metadata.name is the group's name, both for the Group resource in your project and in your organisation's identity provider. No parameter is required.

Note

Some group names are reserved for platform access and are refused when you create the group: customer-admin, names that start with stakater-, and names that end with -cluster-admin or -stakater-admin.

Note

Older claims may still set parameters.name. The field is deprecated and ignored: the group is always named after metadata.name.

Optional Parameters#

Parameter Description
parameters.members Email addresses of the organisation users to add to the group
parameters.attributes Additional key-value attributes to set on the group

Step 2: Add Group Members (Optional)#

To pre-populate the group with existing users, add a members list:

apiVersion: iam.cloud.stakater.com/v1
kind: Group
metadata:
  name: engineering-team
spec:
  parameters:
    members:
      - alice@acmecorp.example.com
      - bob@acmecorp.example.com
      - charlie@acmecorp.example.com

Note

List members by their email address. A value that is not a user's email address, such as the username from their User claim, never matches: the membership stays not ready and the group never becomes ready. Members must already exist as organisation users before they can be added to a group. Create users first using the IAM User guide.

Step 3: Apply the Claim#

kubectl apply -f group.yaml

Step 4: Verify the Group#

Check that the group claim was accepted:

kubectl get group engineering-team

Expected output once ready:

NAME               READY   SYNCED   AGE
engineering-team   True    True     1m

Check membership status:

kubectl get group engineering-team \
  -o jsonpath='{.status.memberships}'

Full Examples#

Minimal Group#

apiVersion: iam.cloud.stakater.com/v1
kind: Group
metadata:
  name: tenant-group
spec:
  parameters:
    members:
      - user1@tenant.com
      - user2@tenant.com

Group with Attributes#

apiVersion: iam.cloud.stakater.com/v1
kind: Group
metadata:
  name: platform-team
spec:
  parameters:
    attributes:
      department:
        - engineering
      costCentre:
        - cc-1234

Using Groups for Project Access#

Once your group is created, reference it in a Project claim to grant project access:

apiVersion: tenant.cloud.stakater.com/v1
kind: Project
metadata:
  name: my-project
spec:
  parameters:
    name: my-project
    network:
      name: app-network
      cidr: 10.0.0.0/16
    access:
      - role: platform-services-admin
        groups:
          - engineering-team
      - role: platform-services-view
        groups:
          - qa-team

Use only the roles listed in Project Roles. Other role names, such as cluster-admin or edit, are accepted without an error but grant a built-in Kubernetes role with far broader rights.

Deleting a Group or Its Members#

Before you delete a user who is a member of a group, remove them from the group's members list (or delete the group) first. If the user is deleted first, the group can no longer be deleted cleanly, because it keeps trying to remove a member who no longer exists. See Disabling or Removing a User.

What's Next?#