LATEST VERSION: 1.10 - CHANGELOG
Pivotal Cloud Foundry v1.10

Managing Isolation Segments

Page last updated:

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

Requirements

You must have the most recent version of the Cloud Foundry Command Line Interface (cf CLI) installed to manage isolation segments.

Target the API endpoint of your deployment with cf api and log in with cf login before performing the procedures in this topic. For more information, see the Identifying the API Endpoint for your Elastic Runtime Instance topic.

Overview

To enable isolation segments, an operator must install the PCF Isolation Segment tile by performing the procedures in the Installing PCF Isolation Segment topic. Installing the tile creates a single isolation segment.

To manage the isolation segment, an operator uses the cf curl command in the cf CLI to send requests to the Cloud Controller API (CAPI) endpoint with the GUID of the isolation segment.

Operators can perform the following operations on isolation segments:

Isolation Segment Contents

An isolation segment object in the Cloud Controller Database (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.

List Isolation Segment Information

The cf 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.
  • Other users see the isolation segments that their orgs have been added to.

List Isolation Segments

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

$ cf curl "/v3/isolation_segments" \
  -X GET 

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:

$ cf curl "/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913/relationships/organizations" \
  -X GET 

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:

$ cf curl "/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913/relationships/spaces" \
  -X GET \

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" } ] }

Retrieve an Isolation Segment

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

$ cf curl "/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913" \
  -X GET \

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" } } }

Manage an Isolation Segment

The cf 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:

$ cf curl "/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913" \
  -X PATCH \
  -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:

$ cf curl "/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913" \
  -X DELETE 

The request outputs the following:

HTTP/1.1 204 No Content

Manage Isolation Segment Relationships

The cf curl requests listed in the sections below add and remove orgs and spaces from isolation segments.

Add Orgs to an Isolation Segment

Only admins can add orgs to isolation segments.

In the data field of the cf 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:

$ cf curl "/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913/relationships/organizations" \
  -X POST \
  -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" } } }

If an org is entitled to only one isolation segment, that isolation segment does not automatically become the default isolation segment for the org. You must explicitly set the default isolation segment of an org.

Remove Orgs from an Isolation Segment

The following example removes two orgs from an isolation segment:

$ cf curl "/v3/isolation_segments/323f211e-fea3-4161-9bd1-615392327913/relationships/organizations" \
  -X DELETE \
  -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

Only admins and org managers can set the default isolation segment of an org.

When an org has a default isolation segment, new spaces created within the org will be in this 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:

$ cf curl "/v2/organizations/45a66ed9-cb76-46c3-92dd-b29187b50bfb" \
  -X PUT \
  -d '{ \
    "default_isolation_segment_guid":"323f211e-fea3-4161-9bd1-615392327913" \
  }'

Add or Remove Spaces in an Isolation Segment

Only admins and org managers can add or remove space 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:

$ cf curl "/v2/spaces/68d54d31-9b3a-463b-ba94-e8e4c32edbac" \
  -X PUT \
  -d '{ \
    "isolation_segment_guid":"323f211e-fea3-4161-9bd1-615392327913" \
  }'

For an example of how to remove a space from an isolation segment, see the following command:

$ cf curl "/v2/spaces/68d54d31-9b3a-463b-ba94-e8e4c32edbac/isolation_segment" \
  -X DELETE 
Create a pull request or raise an issue on the source for this page in GitHub