Multitenancy

You can create multiple accounts, also called tenants, on a cluster.

Each account has its own namespaces, teams, and users.

An account can have multiple teams. Each team has users, user groups, or service IDs as its members. You assign role-based access control (RBAC) to the team members. Based on the assigned roles, members can access resources that are assigned to the team.

For more information about RBAC for team members, see IAM roles and actions.

The cluster administrator has full access to the cluster, and can create accounts. For more information about cluster administrator role, see Platform roles and actions.

The account administrator creates teams and namespaces, and assigns namespaces and members to the teams.

Configuring multitenancy is optional. By default, a single tenant is configured in your cluster. For more information, see Single tenancy.

Key concepts

Following concepts provide clarity on how multitenancy works:

Account

An account represents a tenant.

Account roles and team roles

Account roles are roles that are assigned to users when they are added to an account. The account roles are PRIMARY_OWNER and MEMBER.

Team roles are assigned to users when they are added to a team. The team roles are ClusterAdministrator, Administrator, Operator, Editor, Viewer, Auditor, and AccountAdministrator. For more information, see IAM roles and actions.

In a multitenant cluster, the PRIMARY_OWNER is the AccountAdministrator in the default team that is associated with the account. In a single-tenant cluster, the PRIMARY_OWNER is the ClusterAdministrator in the default team that is associated with the account.

PRIMARY_OWNER

PRIMARY_OWNER is a role that is assigned to a user in an account. A user with a PRIMARY_OWNER role can perform all actions that are related to the management of the account of the user. The PRIMARY_OWNER is an account administrator.

MEMBER

MEMBER is a role that is assigned to a user in an account. A user with a MEMBER role can view information that is related to only the account of the user. A user with MEMBER role gets access to the cluster only after the PRIMARY_OWNER onboards the user to the account.

AccountAdministrator

AccountAdministrator is a role that is assigned to a user in a team. A user with AccountAdministrator role can perform all actions that are related to the management of the account and the teams that are associated with the account of the user. The AccountAdministrator has all the privileges of the Administrator IAM role. The AccountAdministrator has additional privilege of creating namespaces in the cluster.

Default team

A default team is a system-generated team that is automatically created when you create an account. Each account has a default team. The name of a default team has a <hash(accountId)>-default format. For example, 4b974267a20ab08b47fa7d0a597d258a-default.

Default account

A default account is a system-generated account that is automatically created when you configure your cluster. The default account is associated with the cluster.

Namespace types

There are two types of namespaces: System type namespaces and Custom type namespaces.

Namespaces that are created in a cluster have additional annotations.

• You can use mcm.ibm.com/AccountID to view information about which account the namespace belongs to. The AccountID is 9-character length unique string to identity the account.

• You can use mcm.ibm.com/type to view information about the type of namespace. The namespace type can be either System or Custom. A System type namespace means that the namespace is created by either by a ClusterAdministrator or by a ServiceAccount that has the privileges to do so. A Custom type namespace means that the namespace is created by an AccountAdministrator, and the active account of the AccountAdministrator is set as AccountID in the annotations.

Account types

Accounts that are created in a cluster have a type to identify whether the account is a default account or is created by a ClusterAdministrator after cluster installation. When you install a cluster, a default account with ID that has the format of ID-<cluster name>-account is automatically created during installation, and the account type is set as System. Accounts that a ClusterAdministrator creates after cluster installation have the type as Custom.

Team types

An account can have multiple teams. When a user creates a team, that team resides in the active account of the user.

Teams that are created in a cluster have a type to identify whether the team is a default team or not.

When you create an account, a default team is automatically created with a teamId that is generated based on a hash of the AccountID. Each account has a default team. When you install your cluster, a default team is created for the default account.

When a ClusterAdministrator creates accounts after installation, a default team is automatically generated for each account and has the type as System.

When account members create teams, such teams have the type as Custom. Only a Clusteradministrator can access teams of type System. No other user role has access to teams of type System.

In a default account, the default team contains information about the cluster administrators that onboard to the account. In an account that is not a default account, the default team contains information about the account administrators that onboard to the account. It also contains information about the namespaces that the account administrators create in that particular account.

Active account ID

An account administrator can onboard a user to multiple accounts. The active account ID of the user is the account to which the user was last onboarded. Based on the active account ID, all operations that the user performs are recorded only under that account and are not reflected in any other account of the user. Teams and namespaces that a user creates are part of only the active account of the user even if the user belongs to multiple accounts. If a user needs to work in an account that is not the active account, the user must explicitly change the active account to the account in which the user wants to work.

User onboarding to an account

User onboarding is a process in which the users are associated to an account either as a PRIMARY_OWNER or a MEMBER by the cluster administrator. Onboarding a user to the default account is optional and is implicitly done if the user is part of existing teams or if the user is directly assigned to teams by using console. To onboard a user to an account, the cluster administrator or the account administrator must first search and import the user from the configured LDAP directory, then onboard the user.

Multitenancy overview

Following descriptions provide an overview of how multitenancy works.

Account overview

The cluster administrator creates accounts, configures LDAP connection for the account, searches and imports users to the cluster, adds users to the account, and assigns roles to the users.

• A default System account is created when you configure your cluster.
• A cluster administrator can create multiple accounts in your cluster.
• Each account is associated with a unique alphanumeric name, which is a 9-charcter UID that is generated for each account.
• A cluster administrator must configure an LDAP connection for the cluster. The cluster administrator can add users from the LDAP directory that is configured.
• A cluster administrator can add users to an account and assign either of the following roles to the users:
  • PRIMARY_OWNER, which is the account administrator role.
  • MEMBER, which is the account member role.
• When the cluster administrator onboards a user as a PRIMARY_OWNER, the user is automatically added to the default System account as an account administrator.
• An account can have multiple teams.
• Only the users that are onboarded to an account can be assigned to a team in that account.
• Onboarded users can be added to teams and assigned an identity and access management (IAM) role.

Account administrator overview

The account administrator can complete the following tasks:

• Create teams.
• Add users to a team that were onboarded to the account by the cluster administrator.
• Assign IAM roles to team members.
• Create namespaces for the account.
• Assign namespaces that were created for the account to the teams of that account.
• Edit or delete namespaces that are associated only with the accounts of the account administrator.

User and account association overview

When the cluster administrator onboards a user to an account, the account becomes active for the user. The last account to which the cluster administrator onboards a user becomes the active account of that user.

Configuring multitenancy

You can use the console, cloudctl CLI, or APIs to configure multitenancy in your hub cluster. However, not all operations are supported by the console and cloudctl CLI. In the following instructions, each step lists the configuration options that you can use for that step.

Prerequisites

• The cluster administrator must set up a single or multiple LDAP connections by using the default OpenID Connect (OIDC) provider. For more information about setting up an LDAP connection, see Configuring LDAP connection.
• If you plan to use cloudctl CLI for configuring multitenancy, install the cloudctl CLI. For more information, see Installing IBM Cloud Pak CLI (cloudctl). The instructions also include the step to install kubectl CLI. You might need to use the kubectl CLI to complete some steps.

Steps to be completed by the cluster administrator

1. Create an account. You can create multiple accounts, as required.

   • To use the API, see Create an account.

   • To use cloudctl CLI, see cloudctl iam account-create.

     Note: A default team is created when you create an account.

2. Assign a namespace to the account. If needed, first create a namespace, then assign the namespace resource to the account.

   • You can use the Kubernetes API to create a namespace. See Running Kubernetes API commands and create a Namespace .
   • To use the console, see Creating a namespace.

   • To use kubectl CLI, run the following command:

     kubectl create ns <name>
     

     Note: If no namespace is assigned to the account, and you use the cloudctl login command to access the cluster, you might see the following error message:

     User needs access to at least (1) namespace in order to login
     

3. Onboard users and user groups to the account.

   1. Search for users or user groups in the LDAP server.
   2. To use the APIs, See Search for users in your LDAP directory and Search for user groups in your LDAP directory.
   3. To use the cloudctl CLI, see cloudctl iam user-import and cloudctl iam group-import. The import commands have an option to search for users and user groups.
   4. Import users or user groups from the LDAP server.
   5. To use the APIs, see Import users from your LDAP directory and Import user groups from your LDAP directory.
   6. To use the cloudctl CLI, see cloudctl iam user-import and cloudctl iam group-import.
   7. Get information about all accounts. You need the account ID when you add users to an account.
   8. To use the APIs, see Get information about all accounts.
   9. To use the cloudctl CLI, see cloudctl iam accounts.
   10. Add users to the account and assign account roles to the users. The account roles that can be assigned are PRIMARY_OWNER and MEMBER. The PRIMARY_OWNER is the account administrator.
   11. To use the APIs, see Add users to an account.

   12. To use the cloudctl CLI, see cloudctl iam user-onboard.

       Note: When you assign the PRIMARY_OWNER role to a user, the user is automatically assigned to the default team.

4. (Optional) View default team information.
   • To use the API, see Get information about all teams.
   • To use the cloudctl CLI, see cloudctl iam teams.

5. Assign a namespace as a resource to the default team of an account. This is to ensure that the account administrator who is onboarded to the account can log in by using cloudctl.

   1. Get the account ID and assign it to a variable.

      export ACCOUNT_ID=$(cloudctl iam accounts | grep <account_name> | awk -c '{print $1}')
      

   2. Get the default team of an account and assign it to a variable.

      export DEFAULT_TEAM=$(cloudctl iam teams | grep $ACCOUNT_ID | awk -c '{print $1}')
      

   3. Get the cloud resource name (CRN) of the namespace to be assigned to the account, and assign the CRN to a variable.

      export DEFAULT_NS=$(cloudctl iam resources | grep <namespace>)
      

   4. Assign the namespace to the default team.

      cloudctl iam resource-add $DEFAULT_TEAM -r $DEFAULT_NS
      

After the cluster administrator creates an account and adds users to the account, the users that are assigned the PRIMARY_OWNER role can log in to the cluster and view the assigned accounts and resources.

Steps that can be completed by the cluster administrator or account administrator

1. Log in to the cluster.
   • To use the cloudctl CLI, see cloudctl login.
2. (Optional). Change the account that you want to work in. You might need to switch between the default account and your active account.
   1. Get a list of accounts that you are assigned to. You see the account IDs and names.
   2. To use the API, see Get information about all accounts.
   3. To use the cloudctl CLI, see cloudctl iam accounts.
   4. Change the account that you want to work in. Specify the account ID or name in which you want to log in when you run the command. See cloudctl login.
3. Create namespaces. The namespace is automatically assigned to your default team.

4. You can use the Kubernetes API to create a namespace. See Running Kubernetes API commands and create a Namespace .

   • To use the console, see Creating a namespace.

   • To use kubectl CLI, run the following command:

     kubectl create ns <name>
     

5. Create teams.

   • To use the API, see Create a team.
   • To use the cloudctl CLI, see cloudctl iam team-create.
   • To use the console, see Create teams.
6. Assign namespaces to teams.
   • To use the API, see Assign resources to a team.
   • To use the console, see Add resources to a team.
7. Assign users and user groups to teams.
   1. View the users and user groups that are added to the account.
   2. To use the APIs, see Get information about all users and Get all user groups.
   3. To use the cloudctl CLI, see cloudctl iam users and cloudctl iam groups.
   4. Assign users and user groups to teams, and assign IAM roles to team members. For more information about roles for team members, see IAM roles and actions.
   5. To use the API, see Assign users and user groups to a team.
   6. To use the cloudctl CLI, see cloudctl iam team-add-users and cloudctl iam team-add-groups.
   7. To use the console, see Add users to a team and Add groups to a team.

Multitenancy account member actions

Account members can log in to the cluster and view the assigned resources. The account members can perform actions based on the IAM role that was assigned to the members when they were added to teams.

Managing multitenancy

You can manage multitenancy by using the Multitenancy APIs.

Note: Only the cluster administrator can create, edit, and delete accounts.

Single tenancy

When you install your cluster, the installer creates a single account by default. A default team for the account is also created.

The cluster administrator has full access to the cluster.

Steps to be completed by the cluster administrator in a single-tenancy environment

1. Set up a single or multiple LDAP connections by using the default OpenID Connect (OIDC) provider. For more information about setting up an LDAP connection, see Configuring LDAP connection.

2. Onboard users and user groups to the account.

   1. Search for users or user groups in the LDAP server.
   2. To use the APIs, See Search for users in your LDAP directory and Search for user groups in your LDAP directory.
   3. To use the cloudctl CLI, see cloudctl iam user-import and cloudctl iam group-import. The import commands have an option to search for users and user groups.
   4. Import users or user groups from the LDAP server.
   5. To use the APIs, see Import users from your LDAP directory and Import user groups from your LDAP directory.
   6. To use the cloudctl CLI, see cloudctl iam user-import and cloudctl iam group-import.
   7. Get the ID of the default account.
   8. To use the APIs, see Get information about all accounts.
   9. To use the cloudctl CLI, see cloudctl iam accounts.
   10. Add users to the default account and assign account roles to the users. The account roles that can be assigned are PRIMARY_OWNER and MEMBER. The PRIMARY_OWNER is the account administrator. In a single-tenancy environment, the account owner is also the cluster administrator.
   11. To use the APIs, see Add users to an account.

   12. To use the cloudctl CLI, see cloudctl iam user-onboard.

       Note: When you assign the PRIMARY_OWNER role to a user, the user is automatically assigned to the default team. Note: The default account is the active account of all users.

3. (Optional) View default team information.
   • To use the API, see Get information about all teams.
   • To use the cloudctl CLI, see cloudctl iam teams.

After the cluster administrator adds users to the default account, the users that are assigned as account administrators can log in to the cluster and view the assigned resources.

Steps that can be completed by the account administrator, who is also a cluster administrator in a single-tenancy environment

1. Log in to the cluster. By default, you are logged in to the default account.
   • To use the cloudctl CLI, see cloudctl login.

2. Create namespaces. The namespace is automatically assigned to your default team.

   • You can use the Kubernetes API to create a namespace. See Running Kubernetes API commands and Write Operations .
   • To use the console, see Creating a namespace.

   • To use kubectl CLI, run the following command:

     kubectl create ns <name>
     

3. Create teams.

   • To use the API, see Create a team.
   • To use the cloudctl CLI, see cloudctl iam team-create.
   • To use the console, see Create teams.
4. Assign namespaces to teams.
   • To use the API, see Assign resources to a team.
   • To use the console, see Add resources to a team.
5. Assign users and user groups to teams.
   1. View the users and user groups that are added to the account.
   2. To use the APIs, see Get information about all users and Get all user groups.
   3. To use the cloudctl CLI, see cloudctl iam users and cloudctl iam groups.
   4. Assign users and user groups to teams, and assign IAM roles to team members. For more information about roles for team members, see IAM roles and actions.
   5. To use the API, see Assign users and user groups to a team.
   6. To use the cloudctl CLI, see cloudctl iam team-add-users and cloudctl iam team-add-groups.
   7. To use the console, see Add users to a team and Add groups to a team.

Single tenancy account member actions

Account members can log in to the cluster and view the assigned resources. The account members can perform actions based on the IAM role that was assigned to the members when they were added to teams.

Known issues

• Kubernetes namespaces are global resources. When you run the kubectl get namespaces command, you might see system namespaces, and namespaces that belong to other accounts. Because of this Kubernetes behavior, do not use sensitive information in the namespace name. The namespace name might be visible to other account administrators and members.

• When account administrators attempt to create namespaces with the same name, they might see an error. For example, administrators of two separate accounts might attempt to create namespaces with the name production. The account administrator who creates the namespace first succeeds. However, the other account administrator fails to create the namespace and sees an error that the name exists. This issue is because of Kubernetes behavior. To avoid the issue, account administrators can use a naming scheme for namespaces such that each namespace has a unique name across all accounts. For example, prefix a namespace name with a unique string, such as acme-production.