Managing organisations, spaces and users

Regions

The GOV.UK PaaS is hosted in 2 independent regions, London and Ireland.

GOV.UK PaaS accounts, credentials and resources belong to a single region.

If you have a London region account, your app domain is APPNAME.london.cloudapps.digital.

If you have an Ireland region account, your app domain is APPNAME.cloudapps.digital.

Organisations

An organisation, or org, represents a group of users, applications and environments. Each org shares the same resource, quota and custom domain.

Run cf orgs to list the orgs your user account can access.

To see quota information about an org, you can select the appropriate org using the GOV.UK PaaS admin tool for the London region or the Ireland region (requires sign in), and check the Memory total in the top right corner of the screen. The amount of information you can see depends on your user role within the org. For example, org managers can see all quota information, whereas space developers can only see information on spaces that they are members of.

You can also run cf org ORGNAME to see quota information about an org, where ORGNAME is the name of the org.

Your user account will be initially assigned to one org by the PaaS team and then you can choose to belong to additional orgs. You can contact gov-uk-paas-support@digital.cabinet-office.gov.uk to request more orgs.

Spaces

An org is divided into one or more spaces. A space is a shared location for developing, deploying and running apps and backing services.

For example, you might have separate spaces for the development and production versions of your app. When we set up your org, we create a default sandbox space you can use for experimenting with the PaaS.

To see the spaces you can access in your current org, you can either:

run cf spaces in the command line
sign in to the GOV.UK PaaS admin tool for either the London region or the Ireland region and select the appropriate org

Org managers can create new spaces within an org.

Refer to the case studies documentation for information on common structures for orgs, spaces and apps.

Users and user roles

Users are members of your team who can access or manage apps and backing services on the PaaS.

Users are assigned roles which have different permissions for accessing and managing orgs and spaces. A user can have one or multiple roles within the same or different orgs and spaces.

To see a list of users and their roles in your org, you can view the appropriate org’s Members screen in the GOV.UK PaaS admin tool for either the London region or the Ireland region (requires sign in). Your user account must have the org manager role or the org auditor role to see this information in the admin tool.

You can also run cf org-users ORGNAME to see a list of users and their roles in your org, where ORGNAME is the name of the org.

Although there are multiple roles, the 6 most common are:

Org manager
Org auditor
Billing manager
Space developer
Space manager
Space auditor

Refer to the Cloud Foundry documentation on roles and permissions for more information.

Org manager

This role applies within an org.

Every org must have at least one org manager. Org managers are primary contacts for the org.

Org managers manage spaces, users and user roles, and approve org changes such as requesting new quotas and enabling paid services.

Org managers can use the GOV.UK PaaS admin tool to invite new users to an org, without needing to contact the GOV.UK PaaS team. This is possible for either the London region or the Ireland region (requires sign in).

We create at least one user account with the org manager role as part of your onboarding process. We recommend you have at least 2 org managers in case one is unavailable.

If you need the org manager role added to a user account, contact us at gov-uk-paas-support@digital.cabinet-office.gov.uk.

Org auditor

This role applies within an org.

Org auditors can view user account information and org quota information, but cannot edit that information.

Billing manager

This role applies within an org.

Billing managers create and manage billing account and payment information. They can also view users and roles using the command line, or the GOV.UK PaaS admin tool for either the London region or the Ireland region (requires sign in).

You should assign a billing manager to your org before your service moves to production. We will send all payment requests to the billing manager. An org manager can also be a billing manager.

Space developer

This role applies within a space.

A space developer can deploy, run and manage apps, and create and bind services. This is the default role for any user who is not assigned a manager role.

For example, a space developer granted access to the testing space only can change apps in this space. However, that developer cannot do anything in the production space because they do not have access to this space.

Space manager

This role applies within a space.

A space manager grants user roles within a space and can change space properties using the command line. A space manager cannot deploy, run, or manage apps or services.

For example, a team member needs to change apps in both the testing and production spaces, and manage users in the testing space. The org manager grants this team member the space manager role in the testing space, and the space developer role in both the testing and production spaces. That team member can add users to testing but not to production (as a space manager), and can change apps in both spaces (as a space developer).

Space auditor

This role applies within a space.

Space auditors can view apps, users and resources used within a space using the command line, but cannot edit them. This role is useful for viewing app data without modifying it.

Manage orgs, spaces and user roles

There are several common tasks to manage spaces and user roles.

Create a new space

Org managers can create spaces.

Run the following to create a new space:

cf create-space SPACE -o ORGNAME

where SPACE is the name of the space, and ORGNAME is the name of the org.

You can then add users to that space.

Add users to a space

After a user has been added to an org, org managers can use the GOV.UK PaaS admin tool for the London region or the Ireland region (requires sign in) to grant a user access to a space by assigning a role to that user.

Sign in to the GOV.UK PaaS admin tool for either the London region or the Ireland region.
Select the appropriate org.
Select View and manage team members.
Select Invite a new team member.
Complete the form and select Send invitation.

Alternatively, the org manager can run the following in the command line:

cf set-space-role USERNAME ORGNAME SPACE ROLE

where:

USERNAME is the email address the user signs in with when using the command line client
ORGNAME is the name of the org
SPACE is the name of the space
ROLE is the user role you are granting to the user of the email address in the USERNAME field

For example, to grant ana@example.com the space developer role in the test space within the acme org, the org manager would run:

cf set-space-role ana@example.com acme test SpaceDeveloper

Refer to the Cloud Foundry reference guide on cf set-space-role for a complete list of roles.

Remove users from a space

When a team member leaves or stops working on a project, the org manager should revoke that team member’s access rights.

The org manager can use the GOV.UK PaaS admin tool to remove all of the team member’s user roles within the team’s spaces.

Sign in to the GOV.UK PaaS admin tool for either the London region or the Ireland region.
Select the appropriate org.
Select View and manage team members.
Select the appropriate user.
Change the user’s space roles and select Save role changes.

Alternatively, the org manager can run the following in the command line:

cf unset-space-role USERNAME ORGNAME SPACE ROLE

where:

USERNAME is the email address the user signs in with when using the command line client
ORGNAME is the name of the org
SPACE is the name of the space
ROLE is the user role granted to the user of the email address in the USERNAME field

For example, to remove ana@example.com’s space developer role from the sandbox space within the acme org, the org manager would run:

cf unset-space-role ana@example.com acme sandbox SpaceDeveloper

Refer to the Cloud Foundry reference guide on cf unset-space-role for a complete list of roles.

Invite users to an org

Org managers can use the GOV.UK PaaS admin tool to invite users to their org when they join their team.

Sign in to the GOV.UK PaaS admin tool for either the London region or the Ireland region.
Select the appropriate org.
Select View and manage team members.
Select Invite a new team member.
Complete the form and select Send invitation.

Remove users from an org

When a team member leaves or stops working on a project, their org manager must remove all of that team member’s user roles from the team’s spaces.

If the leaving team member has an org role such as org manager or billing manager, either the other org manager or the GOV.UK PaaS team must also remove that team member’s user role from the team’s org.

Sign in to the GOV.UK PaaS admin tool for either the London region or the Ireland region.
Select the appropriate org.
Select View and manage team members.
Select the appropriate user.
Select Remove user from Organisation.
To confirm, select Yes, remove from organisation.

Alternatively, the other org manager or the GOV.UK PaaS team can run the following in the command line:

cf unset-org-role USERNAME ORGNAME ROLE

where:

USERNAME is the email address the user logs in with when using the command line client
ORGNAME is the name of the org
ROLE is the user role granted to the user of the email address in the USERNAME field

For example, to remove ana@example.com’s org manager role from the acme org, either the other org manager or the GOV.UK PaaS team should run:

cf unset-org-role ana@example.com acme OrgManager

If the user still needs access to GOV.UK PaaS to work on other projects, nothing else needs to change.

If the user no longer needs access to GOV.UK PaaS, then your org manager must contact us at gov-uk-paas-support@digital.cabinet-office.gov.uk to ask us to delete the user account.

Refer to the Cloud Foundry documentation on creating and managing users with the CLI for more information.

View bills

Org managers and billing managers can use the GOV.UK PaaS admin tool to view current or past bills within an org.

Sign in to the GOV.UK PaaS admin tool for either the London region or the Ireland region.
Select the appropriate org.
Select Billing.
View your bills. You can filter the bills shown by Month, Space, or Services and apps.

Case studies

This section summarises 2 common models for orgs and spaces.

There are other ways to structure orgs and spaces, and you can change your existing structure to suit the project you’re working on.

Model 1

In this example model, an org represents a service or service team within a government department or business area. Each org has multiple spaces. Spaces represent environments such as development, sandbox, staging or production or can represent different applications. These spaces host apps and backing services.

Departments or government teams that use this structure include:

Department for Business, Energy and Industrial Strategy
GDS Digital Marketplace

This model has the following advantages:

it is easy to manage user permissions within each org because spaces that require higher permissions (such as staging or production) are already separated from other spaces that do not have as high a requirement
developers that do not have security clearances yet can have their access restricted if necessary
each org represents a business area which makes billing administration simple

However, there is no reuse of orgs and spaces in this structure, which incurs a time and resource cost.

Model 2

In this example, an org represents an environment such as development, sandbox, staging or production. Each org has multiple spaces. Spaces represent services or service teams within a government department or business area. These spaces host apps and backing services.

Departments that use this structure include the Department for International Trade.

This model makes it easier to control resources and spending between different environments.