Entity Management

If you expect other people to use your Fuzzball cluster, you can create new users and manage them by (optionally) setting up new organizations and groups. This allows you to control the resources that users can see and share with one another.

This section will guide you through the process of creating a new organization, a new group within the org, and finally creating a new user and adding them to the newly created group and org.

Creating a New Organization

First you can (optionally) create a new organization called FuzzballTesting.

You will need to repeat the Keycloak configuration steps in each newly created Fuzzball organization since each new org creates a new Keycloak realm.

At the time of this writing, the Fuzzball CLI does not support creating new organizations directly. Instead, use the fuzzball-admin executable that is contained in the synonymous kubernetes pod via the kubectl command.

You need to decide on an email address for the person who will manage the organization and create a UUID. For now, use the same email address that you set previously to the Fuzzball Admin account. The following command serves as an example and generates a random UUID on the fly:

# kubectl exec -n fuzzball fuzzball-admin-0 -- /app/fuzzball-admin organization create \
    FuzzballTesting user@domain.com $(uuidgen)
{
  "id": "f35fcdd4-e702-450e-a060-7d1d51519d07",
  "name": "FuzzballTesting",
  "create_time": {
    "seconds": 1767660288,
    "nanos": 608567000
  },
  "update_time": {
    "seconds": 1767660288,
    "nanos": 608567000
  }
}

You can create your new context and log in to it using the realm ID listed in the output. Based on the information in the example above, this process looks like so:

# fuzzball context create FuzzballTesting api.10.1.96.149.nip.io \
    https://auth.10.1.96.149.nip.io/auth/realms/f35fcdd4-e702-450e-a060-7d1d51519d07 fuzzball-cli
Configuration for "FuzzballTesting" created.
Configuration for "FuzzballTesting" now in use.

# fuzzball context login --direct -u user@domain.com -p 'fbpassword'
Logging into current cluster context...
Account "User Account (user@domain.com)" in use

# fuzzball context list
ACTIVE | NAME            | ADDRESS                    | ACCOUNT NAME                   | ACCOUNT ID
       | default         | api.10.1.96.149.nip.io:443 | User Account (user@domain.com) | 53647021-0e86-4dbd-9940-c85b91fb4b38
   *   | FuzzballTesting | api.10.1.96.149.nip.io:443 | User Account (user@domain.com) | a9a97cba-d35f-45a4-8dec-386a61517c53

Creating a New Group

Second you can (optionally) create a new group called Testers. If applicable, make sure you are logged in to your newly created organization using the commands above, and then create and use the new group like so:

The account subcommand will be deprecated in favor of group in a future release.

# fuzzball account create Testers
Account: Testers created with id: 8f53062a-dec6-42a8-bd66-4c6c7526e539

# fuzzball account use 8f53062a-dec6-42a8-bd66-4c6c7526e539
Account "Testers" in use

You are automatically set as the group owner when creating a new group via the CLI.

Creating a New User

Now you can create a new user named tester1@domain.com. If applicable, make sure that you are logged into the organization where you want your new user to belong.

Before adding any new users, configure keycloak to require new users to change their password on first login by following the steps in the Keycloak Configuration guide.

Use the add-member command to create a new user in combination with the -p flag to set the user’s initial password. (As with most password entry commands, the characters will not echo to the screen as you enter them.)

If you want your new user to be an organization owner, use the add-owner subcommand instead.

# fuzzball organization add-member tester1@domain.com -p
Enter new password:
Confirm password:
Member added with id: 56b9686f-fad8-4016-ad00-da6476d457c7 and email: tester1@domain.com

Now you can securely share the initial password with your user. Assuming you configured keycloak appropriately, your user will be prompted to change their password on their first login.

Adding your New User to the Newly Created Group

Finally, you can add the tester1@domain.com user to the Testers group (assuming you created it). This requires you to enter the user’s UUID that was automatically generated on creation.

You can make your new user a group owner by substituting the add-owner subcommand for the add-member subcommand.

# fuzzball account list
SELECTED | NAME                            | ID                                   | CREATED TIME          | LAST UPDATED
         | User Account (dgodlove@ciq.com) | a9a97cba-d35f-45a4-8dec-386a61517c53 | 2026-01-06 12:44:54AM | 2026-01-06 12:44:54AM
*        | Testers                         | 8f53062a-dec6-42a8-bd66-4c6c7526e539 | 2026-01-06 01:03:20AM | 2026-01-06 01:03:20AM

# fuzzball organization list-members
NAME               | ID                                   | CREATED TIME          | LAST UPDATED          | LAST ACTIVE
tester1@domain.com | 56b9686f-fad8-4016-ad00-da6476d457c7 | 2026-01-06 11:25:24PM | 2026-01-06 11:25:24PM | 2026-01-06 11:25:24PM

# fuzzball account add-member --account 8f53062a-dec6-42a8-bd66-4c6c7526e539 56b9686f-fad8-4016-ad00-da6476d457c7
Added member: tester1@domain.com to account: 8f53062a-dec6-42a8-bd66-4c6c7526e539

If you don’t want to include the group UUID in the command above, you can just make sure that you are logged in and using the group where you want to grant your user membership.