Last modified May 2, 2022

Authorization in the Management API

Once your users are authenticated for the Management API, you want to define which permissions they will have assigned. That’s what we’ll explain in more detail in this article.

Some remarks before we dive in:

As authorization in the management cluster is based on some fundamental Kubernetes concepts, we assume basic knowledge of:

Also be aware that this article deals with permissions in the management cluster only. Handling authorization in workload clusters is not covered here, however we provide a comprehensive article on RBAC and PSPs in workload clusters.

If you are mostly interested in how to set up access for certain types of users, we recommend to skip to the typical use cases section. You can always catch up on the basics later, as needed. Alternatively, if you work through this page from top to bottom, you’ll pick up the pieces in a more logical order and put them together later.

Where resources reside

For controlling access to resources in a management cluster, it is vital to understand

  1. whether a resource is cluster-scoped or namespace-scoped
  2. if it is namespace-scoped, in which namespace they are to be found

We’ll explain next which resources are to be found in which scope or namespace.

Cluster scope

In Giant Swarm management clusters in particular, two resource types are cluster-scoped, so they are not residing in any namespace:

  • Organization defines, well, an organization
  • Release defines a workload cluster release to use when creating a new workload cluster, or to upgrade a workload cluster to.

Namespace default

Next, the following resources reside in the default namespace:

Organization namespaces

For each organization there is a namespace to be used as the standard location for storing resources. In these namespaces you will usually find:

Workload cluster namespaces

For every workload cluster, there is a namespace with a name identical to the workload cluster name. In this namespace, resources related to apps installed in the workload cluster are located. The resources are of these types:

  • App which defines an app to be installed in a workload clusters
  • ConfigMap which optionally provides configuration for such an app
  • Secret which provides additional (confidential) configuration for such an app

Pre-defined roles

Giant Swarm provides some pre-defined cluster roles (ClusterRole resources) which allow to grant certain permissions to common sets of resources. The most important ones are:

  • cluster-admin: Grants all permissions to all resource types. When bound to a subject in an organization namespace, the subject will also get full permissions to resources in all workload cluster namespaces belonging to that organization.
  • read-all: Grants read permissions (verbs: get, list, watch) to most known resource types, with the exception of Secret and ConfigMap. When bound to a subject in an organization namespace, the subject will also get read (get, list, watch) permissions to resources in all workload cluster namespaces belonging to that organization.

Since these are ClusterRole resources, they can be bound either in a namespace or in the cluster scope, depending on the use case. In the typical use cases section we will show some examples.

In addition there are two special cluster roles which don’t define any permissions by themselves, but which allow to assign certain permissions for resources in a workload cluster namespace.

  • read-in-cluster-ns: Used to assign read permissions to resources in all workload cluster namespaces belonging to the organization.
  • write-in-cluster-ns: Used to assign full permissions to resources in all workload cluster namespaces belonging to the organization.

We’ll explain the effect of binding these roles in the next section on RBAC automation.

RBAC automation

As explained previously, various resources reside in different scopes and namespaces, and in the case of the workload cluster namespaces, they even come and go as clusters are created and deleted. To simplify authorization under these circumstances, we have some automation in place, provided by rbac-operator running in the management cluster. Here is what it does.

Grant admin permissions to a default group. Where customers own a Giant Swarm installation exclusively (which is the opposite case of using a shared installation), they name a group from their identity provider to gain admin permissions. This group will automatically be bound to the cluster-admin role in all namespaces and in the cluster scope.

Provide service accounts with admin privileges. Service accounts named automation are created in the default namespace and in all organization namespaces, bound to the pre-defined cluster-admin role.

Grant access to releases and app catalogs. For every subject (user, group, service account) bound to any role (Role or ClusterRole) in an organization namespace, we ensure that read permissions are granted to workload cluster releases (in the cluster scope) and app catalogs provided by Giant Swarm (in the default namespace).

Grant access to resources in workload cluster namespaces. For every subject bound to the read-in-cluster-ns role in an organization namespace, we ensure read access to App, ConfigMap and Secret resources in the workload cluster namespaces belonging to the organization. Likewise, for subjects bound to the role write-in-cluster-ns, we ensure full permissions to these resources.

Grant access to the organization. For every subject bound to any role in an organization’s namespace, we ensure that the subject also has get permission to the Organization resource defining that organization. (Why? As this allows clients like our web UI to detect which organizations a user has access to, without requiring list permissions for organizations.)

Typical use cases

For the purpose of this documentation article we’ll introduce a few example cases and then explain how to configure access for them, starting with the least permissions and ending with the highest privileges. Chances are that you can use them as a starting point for your own requirements.

  1. Read-only user: allowed to “browse” most resources in specific organizations.

  2. App developer: allowed to install, configure, upgrade and uninstall certain apps in/from workload clusters of a certain organization. In order to discovers clusters and navigate the web UI, users of this type also require read permission to various resources like clusters, node pools, releases, and app catalogs.

  3. Organization admin: users who have full permissions to resources belonging to a specific organization.

  4. Admin: a type of user that has permission to create, modify, and delete most types of resources in the management cluster.

Next we show how to configure access for these example cases. Please take into account these remarks for all example manifests:

  • You can set the resource names (for RoleBinding and ClusterRoleBinding resources) to whatever suits you and is available.
  • Make sure to replace GROUPNAME with the exact name of your group as defined in your identity provider.
  • Replace ORGANIZATION with the name of your organization (without org- prefix).
  • To assign a user instead of a group, replace kind: Group with kind: User in the subject entry and set name the exact email address of the users as set in your identity provider.

Configure access for read-only users

A read-only user in the sense of the Management API is one that can discover or, in the Giant Swarm web UI, browse resources in order to find out about existing clusters and their configuration, as well as apps installed and available.

To enable a group or user for read access to resources of one organization, you only have to bind them to the read-all cluster roles within the namespace of the organization.

More details on this role are given in the pre-defined roles section.

The manifest below shows how the according role bindings could be created.

---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: bind-read-all-to-group
  namespace: org-ORGANIZATION
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: read-all
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: Group
  name: customer:GROUPNAME

Our web UI makes it easy to create these role bindings interactively. Go to Organizations, select the organization, and navigate to the Access control tab. Then, one by one, select the pre-defined roles in the left column and add the user or group in the Subjects tab on the right.

Configure access for app developers

Compared to a read-only user, this type of user would gain permission to install apps in workload clusters, change any app’s configuration, and remove the app. To achieve this, we bind the pre-defined role write-in-cluster-ns in addition.

The according example manifest:

---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: bind-read-all-to-group
  namespace: org-ORGANIZATION
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: read-all
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: Group
  name: customer:GROUPNAME
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: bind-write-in-cluster-ns-to-group
  namespace: org-ORGANIZATION
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: write-in-cluster-ns
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: Group
  name: customer:GROUPNAME

Like in the case of the read-only user, these bindings can be set up easily via the web UI.

Configure access for organization admins

To grant full permissions to a group of users in the context of a particular organization, bind the pre-defined cluster-admin role to that group. Here is an example manifest:

---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: bind-cluster-admin-to-group
  namespace: org-ORGANIZATION
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: Group
  name: customer:GROUPNAME

Again, this can be achieved easily via our web UI.

Configure access for admins

As explained in RBAC automation, one default group is automatically assigned to the cluster-admin role.

In case you want to configure additional groups or users from your identity provider with admin privileges, you’ll have to create an additional ClusterRoleBinding like this:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: assign-group-to-cluster-admin-role
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: Group
  name: customer:GROUPNAME

Be aware that it is currently not possible to configure additional admins via our web UI.