Managing Isolation Segments

Page last updated:

This topic describes how Cloud Foundry operators can isolate deployment workloads to dedicated resource pools called isolation segments.

To enable isolation segments, an admin must first assign placement tags to Diego cells in BOSH. Then an admin can create isolation segments matching these placement tags.

When an admin creates a new isolation segment, the CCDB outputs a GUID for the new isolation segment object.

To manage the isolation segment, an operator sends curl requests to the Cloud Controller API (CAPI) endpoint with the GUID of the isolation segment and an authorization token. For more information, see the Identifying your Cloud Foundry API Endpoint and Version topic.

Operators can perform the following operations on isolation segments:

Isolation Segment Contents

An isolation segment object in the CCDB includes the following:

  • The unique name of the isolation segment
  • A unique GUID
  • Timestamps for the object’s creation and most recent update
  • Links to API endpoints for isolation segment requests

In the CCDB, an isolation segment object does not identify the orgs and spaces that it includes. Instead, the org and space objects define this relationship by including the GUIDs of the isolation segments that they belong to.

Enable Isolation Segments

To enable isolation segments for a deployment, you first assign Diego cells a placement_tags property in your Diego manifest. Later, you create isolation segments in the Cloud Controller Database (CCDB), and give each one the name of a placement_tag in BOSH.

Step 1. Prepare BOSH to Support Isolation Segments

  1. In your Diego manifest, for each Diego cell that you want to include in an isolation segment, add a placement_tags attribute with the name of the isolation segment as its value. Isolation segment names must be unique across the entire system, and are not case-sensitive. Only admins can create isolation segments. Specify the value in a single-value array. For example, in releases/diego.yml, you tag a Diego cell with my_segment as follows:

    - instances: 1
      name: cell_z2
      networks:
      - name: diego2
      properties:
        diego:
         rep:
           [...] 
              placement_tags:
              - my_segment
    
  2. Apply the changes (BOSH Deployer only)

    $ bosh deploy
    

Step 2. Create Isolation Segments

For any placement_tag value in the Diego manifest, an admin can create an isolation segment with the same name. They do this by sending a curl command to the CAPI. The following example uses a CAPI endpoint and authorization token to create an isolation segment named my_segment:

curl "https://api.example.org/v3/isolation_segments" \
  -X POST \
  -H "Authorization: bearer 7h15154l0n64lph4num3r1c57r1n6" \
  -d '{
    "name": "my_segment"
  }'

This example request returns the contents of the new isolation segment object, which includes its GUID, 323f211e-fea3-4161-9bd1-615392327913:

HTTP/1.1 200 OK
{ "guid": "323f211e-fea3-4161-9bd1-615392327913", "name": "my_segment", "created_at": "2016-10-19T20:25:04Z", "updated_at": "2016-11-08T16:41:26Z", "links": { "self": { "href": "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913" }, "spaces": { "href": "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913/relationships/spaces" }, "organizations": { "href": "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913/relationships/organizations" } } }

Retrieve an Isolation Segment

To retrieve an isolation segment by its GUID, send a curl command like the following to the isolation_segments/GUID endpoint of your CAPI:

curl "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913" \
  -X GET \
  -H "Authorization: bearer 7h15154l0n64lph4num3r1c57r1n6"

This example request returns the contents of the isolation segment:

HTTP/1.1 200 OK
{ "guid": "323f211e-fea3-4161-9bd1-615392327913", "name": "my_segment", "created_at": "2016-10-19T20:25:04Z", "updated_at": "2016-11-08T16:41:26Z", "links": { "self": { "href": "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913" }, "spaces": { "href": "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913/relationships/spaces" }, "organizations": { "href": "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913/relationships/organizations" } } }

List Isolation Segment Information

The curl requests listed in the sections below retrieve information for the isolation segments that you have access to, filtered by parameters that you can include. The isolation segments you can see information for depends on your role, as follows:

  • Admins see all isolation segments in the system.
  • Org Managers see isolation segments containing orgs that they belong to.
  • Other users see isolation segments containing spaces that they belong to.

List Isolation Segments

The following request returns a filtered list of the isolation segment objects that you can access:

curl "https://api.example.org/v3/isolation_segments" \
  -X GET \
  -H "Authorization: bearer 7h15154l0n64lph4num3r1c57r1n6"

The list returns as a resources property structured in a paginated format.

List Orgs for an Isolation Segment

The following example request returns a list of orgs in the isolation segment with the given GUID. The request only returns orgs that you can access:

curl "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913/relationships/organizations" \
  -X GET \
  -H "Authorization: bearer 7h15154l0n64lph4num3r1c57r1n6"

The request returns a list of orgs in the following format:

HTTP/1.1 200 OK
{ "data": [ { "name": "my_org", "guid": "45a66ed9-cb76-46c3-92dd-b29187b50bfb", "link": "/v2/organizations/45a66ed9-cb76-46c3-92dd-b29187b50bfb" }, { "name": "my_other_org", "guid": "d0540a63-3bec-42ff-abd9-8a30328ba296", "link": "/v2/organizations/d0540a63-3bec-42ff-abd9-8a30328ba296" } ] }

List Spaces for an Isolation Segment

The following example request returns a list of spaces in the isolation segment with the given GUID. The request only returns spaces that you can access:

curl "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913/relationships/spaces" \
  -X GET \
  -H "Authorization: bearer 7h15154l0n64lph4num3r1c57r1n6"

The request returns a list of spaces in the following format:

HTTP/1.1 200 OK
{ "data": [ { "name": "my_space", "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac", "link": "/v2/spaces/68d54d31-9b3a-463b-ba94-e8e4c32edbac" }, { "name": "my_other_space", "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c", "link": "/v2/spaces/b19f6525-cbd3-4155-b156-dc0c2a431b4c" } ] }

Manage an Isolation Segment

The curl requests listed in the sections below make changes to isolation segment objects in the CCDB. Only admins can make these changes.

Update an Isolation Segment

The following example renames the isolation segment with the given GUID to my_isolation_segment:

curl "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913" \
  -X PUT \
  -H "Authorization: bearer 7h15154l0n64lph4num3r1c57r1n6" \
  -d '{
    "name": "my_isolation_segment"
  }'

The request returns the following output:

HTTP/1.1 200 OK
{ "guid": "323f211e-fea3-4161-9bd1-615392327913", "name": "my_isolation_segment", "created_at": "2016-10-19T20:25:04Z", "updated_at": "2016-11-08T16:41:26Z", "links": { "self": { "href": "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913" }, "spaces": { "href": "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913/relationships/spaces" }, "organizations": { "href": "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913/relationships/organizations" } } }

Delete an Isolation Segment

The following example deletes an isolation segment with the given GUID:

curl "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913" \
  -X DELETE \
  -H "Authorization: bearer 7h15154l0n64lph4num3r1c57r1n6" \

The request outputs the following:

HTTP/1.1 204 No Content

Manage Isolation Segment Relationships

The curl requests listed in the sections below add and remove orgs and spaces from isolation segments. Only admins can perform these operations.

Add Orgs to an Isolation Segment

When you add an org to one isolation segment, it becomes the default isolation segment for that org unless another default is already set. This means that new spaces created within the org will be in its default isolation segment unless specified otherwise.

In the data field of the curl command, specify one or more orgs by GUID to add to the isolation segment. The following example adds two orgs to an isolation segment:

curl "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913/relationships/organizations" \
  -X POST \
  -H "Authorization: bearer 7h15154l0n64lph4num3r1c57r1n6" \
  -d '{
    "data": [
      { "guid":"45a66ed9-cb76-46c3-92dd-b29187b50bfb" },
      { "guid":"d0540a63-3bec-42ff-abd9-8a30328ba296" }
    ]
  }' 

The request outputs the following:

HTTP/1.1 201 OK
{ "guid": "323f211e-fea3-4161-9bd1-615392327913", "name": "my_segment", "created_at": "2016-10-19T20:25:04Z", "updated_at": "2016-11-08T16:41:26Z", "links": { "self": { "href": "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913" }, "spaces": { "href": "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913/relationships/spaces" }, "organizations": { "href": "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913/relationships/organizations" } } }

Remove Orgs from an Isolation Segment

The following example removes two orgs from an isolation segment:

curl "https://api.example.org/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913/relationships/organizations" \
  -X DELETE \
  -H "Authorization: bearer 7h15154l0n64lph4num3r1c57r1n6" \
  -d '{
    "data": [
      { "guid":"45a66ed9-cb76-46c3-92dd-b29187b50bfb" },
      { "guid":"d0540a63-3bec-42ff-abd9-8a30328ba296" }
    ]
  }'

The request outputs the following:

HTTP/1.1 204 No Content

Note: You cannot remove an org from an isolation segment if the isolation segment contains a space within that org or if it is the default isolation segment for that org.

Set a Default Isolation Segment for an Org

If an org has resources in multiple isolation segments, one segment serves as the default, and new spaces created within the org will be in its default isolation segment unless specified otherwise.

You set the default isolation segment for an org by sending a request to the endpoint for the organization, setting its default_isolation_segment_guid data property to the GUID of the new default isolation segment. For example:

curl "https\://api.example.org/v2/organizations/45a66ed9-cb76-46c3-92dd-b29187b50bfb" \
  -X PUT \
  -H "Authorization: bearer 7h15154l0n64lph4num3r1c57r1n6" \
  -d '{ \
    "default_isolation_segment_guid":"323f211e-fea3-4161-9bd1-615392327913" \
  }'

Add or Remove Spaces in an Isolation Segment

You add a space to an isolation segment by sending a request to the endpoint for the space, setting its isolation_segment_guid data property to the GUID of the new default isolation segment. For example:

curl "https\://api.example.org/v2/spaces/68d54d31-9b3a-463b-ba94-e8e4c32edbac" \
  -X PUT \
  -H "Authorization: bearer 7h15154l0n64lph4num3r1c57r1n6" \
  -d '{ \
    "isolation_segment_guid":"323f211e-fea3-4161-9bd1-615392327913" \
  }'

To remove a space from an isolation segment, set the isolation_segment_guid for the space to NULL.

View the source for this page in GitHub