In Upbound, Control Plane Groups (or just, ‘groups’) are a logical grouping of one or more control planes with shared resources like secrets or backups. It’s a mechanism for isolating these groups of resources within a single Space. All role-based access control in Upbound happens at the control plane group-level.
When to use multiple groups
You should use groups in environments where there’s a need to have Crossplane manage infrastructure across multiple cloud accounts or projects. For users who only need to deploy and manage resources in a couple cloud accounts, you shouldn’t need to think about groups at all.
Groups are a way to divide access in Upbound between multiple teams. Think of a group as being analogous to a Kubernetes namespace.
The ‘default’ group
Every Cloud Space in Upbound has a group named default available.
Working with groups
View groups
You can list groups in a Space using:
up group list
If you’re operating in a single-tenant Space and have access to the underlying cluster, you can list namespaces that have the group label:
kubectl get namespaces -l spaces.upbound.io/group=true
Set the group for a request
Several commands in up have a group context. To set the group for a request, use the --group flag:
up ctp list --group=team1
up ctp create new-ctp --group=team2
Set the group preference
The up CLI operates upon a single Upbound context. Whatever context gets set is then used as the preference for other commands. An Upbound context is capable of pointing at a variety of altitudes:
- A Space in Upbound
- A group within a Space
- a managed control plane within a group
To set the group preference, use up ctx to choose a group as your preferred Upbound context. For example:
# This sets the context for the up CLI to the default group in an Upbound-managed Cloud Space (gcp-us-west-1) for an organization called 'acmeco'
up ctx acmeco/upbound-gcp-us-west-1/default/
Create a group
To create a group, login to Upbound and set your context to your desired Space:
up login
up ctx '<your-org>/<your-space>'
# Example: up ctx acmeco/upbound-gcp-us-west-1
Create a group:
up group create my-new-group
Delete a group
To delete a group, login to Upbound and set your context to your desired Space:
up login
up ctx '<your-org>/<your-space>'
# Example: up ctx acmeco/upbound-gcp-us-west-1
Delete a group:
up group delete my-new-group
Protected groups
Once a managed control plane gets created in a group, Upbound enforces a protection policy on the group. Upbound prevents accidental deletion of the group. To delete a group that has control planes in it, you should first delete all control planes in the group.
Groups in the context of single-tenant Spaces
Upbound offers a variety of deployment models to use the product. If you deploy your own single-tenant Upbound Space (whether connected or disconnected), you’re self-hosting Upbound software in a Kubernetes cluster. In these environments, a control plane group maps to a corresponding namespace in the cluster which hosts the Space.
Most Kubernetes clusters come with some set of predefined namespaces. Because a group maps to a corresponding Kubernetes namespace, whenever a group gets created, there too must be a Kubernetes namespace accordingly. When the Spaces software is newly installed, no groups exist. You can elevate a Kubernetes namespace to become a group by doing the following:
- Creating a group with the same name as a preexisting Kubernetes namespace
- Creating a managed control plane in a preexisting Kubernetes namespace
- Labeling a Kubernetes namespace with the label
spaces.upbound.io/group=true
