Managing Tenancy Units

This page shows you how to manage tenancy units for your service. A tenancy unit is a lightweight resource that represents the relationship between a service consumer and a managed service. Each service consumer can have only one active tenancy unit for a managed service. This is a feature provided by Service Infrastructure.

The resource name of a tenancy unit has the following format:

services/{your service name}/projects/{consumer project number}/tenancyUnits/{id}

The ID of a tenancy unit is auto-generated when you create it. You can also provide an ID when you call the services.tenancyUnits.create method. If you provide an ID, it must be globally unique within the scope of your managed service across all service consumers.

The examples on this page use direct calls to the Service Consumer Management REST API. For production usage, we recommend you use Google-provided client libraries for better usability and reliability.

Before you begin

  • The Service Consumer Management API is intended for use with managed services and service producer projects. You'll need to already have a Google Cloud project and a managed service (such as a service created using Cloud Endpoints) in that project.
  • To use tenancy units, the Service Consumer Management API needs to create tenant projects in your service producer organization. Make sure that you have enough quota for the necessary number of tenant projects for your service's consumers.
  • Each tenant project created in a tenancy unit must also be in a folder that you specify as part of the tenant project configuration. Because of this, you need an Organization to use tenancy units.

Authentication

Cloud APIs like the Service Consumer Management API only accept authenticated calls. If you don't have one already, find out how to create a service account and get a JSON key for authenticating to Cloud APIs in Getting Started with Authentication. If you're using a Google client library, you can set up your environment so that it uses your service account credentials by default. For direct calls to the REST API you'll need to provide an access token in each header, as in the following example:

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" --header 'Content-Type: application/json' --data '{"tag":"tag1", "project_config":{"folder":"folders/9876543210", "tenant_project_policy": {"policy_bindings":{"role":"roles/owner", "members":"user:user1@company.com"}}, "billing_config":{"billing_account":"billingAccounts/123456-472F22-28F9AA"}}}' -X POST "https://serviceconsumermanagement.googleapis.com/v1/services/your-service.example.com/consumers/12345678901/tenancyUnits/tu-hello:addProject"

To create and delete tenancy units you need to follow the initial setup instructions in Getting Started with the Service Consumer Management API.

Creating a tenancy unit

Tenancy units and the tenant projects in them are normally created when resources in your own service are created that depend on additional Google Cloud resources to be provisioned for the consumers.

You create a tenancy unit as follows:

POST https://serviceconsumermanagement.googleapis.com/v1/services/service.example.com/projects/12345678901/tenancyUnits

Here, 'projects/12345678901' represents the service consumer, and service.example.com is the name of your service.

The returned data structure has the name of the tenancy unit, with a generated unique id that can be used to access it. In this example, the generated name is services/your-service.example.com/projects/12345678901/tenancyUnits/absdef.

Adding a tenant project

You can now add a project for the user. To add a new tenant project to the tenancy unit created in the previous step call the following method:

POST https://serviceconsumermanagement.googleapis.com/v1/services/your-service.example.com/projects/12345678901/tenancyUnits/absdef:addProject

with the following data:

{"tag":"tag1", "project_config":{"folder":"folders/9876543210", "tenant_project_policy":{"policy_bindings":{"role":"roles/owner", "members":"user:bob@example.com"}}, "billing_config":{"billing_account":"billingAccounts/123456-472F22-28F9AA"}}}

The tag value is an identifier you provide for the project within the tenancy unit: this can be anything you like (here it's tag1), such as a region, a consumer network, or just a string ID.

This call returns a long running operation that you can query to find if the project creation was successful.

If you need to apply a different configuration, for example to add new managed services, you can call the services.tenancyUnits.applyProjectConfig method.

Searching your tenancy units

Find a tenancy unit for a service consumer

To find a tenancy unit for a particular service consumer, use the services.tenancyUnits.ListTenancyUnits method, specifying their service consumer project number:

GET https://serviceconsumermanagement.googleapis.com/v1/services/your-service.example.com/projects/12345678901/tenancyUnits

Search tenancy units

You can use the services.tenancyUnits.SearchTenancyUnits method to search for tenancy units defined for your service. For example, the following query will return all units that contain a project with the tag 'tag1':

GET https://serviceconsumermanagement.googleapis.com/v1/services/your-service.example.com:search?query=tenant_resources.tag=tag1

Cleaning up tenancy units

When a service consumer stops using your service, you need to remove its tenancy unit to free up resources and ensure the user data is deleted.

Remove tenant projects

You need to delete all tenant projects before you delete the correpsonding tenancy unit. You should use the services.tenancyUnits.removeProject method to delete a tenant project and all resources in it:

POST https://serviceconsumermanagement.googleapis.com/v1/services/your-service.example.com/projects/12345678901/tenancyUnits/absdef:removeProject

Delete a tenancy unit

After you have deleted all tenant projects in a tenancy unit, or all of them are in the DELETED state, you can delete the tenancy unit:

DELETE https://serviceconsumermanagement.googleapis.com/v1/services/your-service.example.com/projects/12345678901/tenancyUnits/absdef