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