isolation-segments.html.md.erb

---
title: Managing Isolation Segments
owner: CAPI
---

In this topic:

* <a href="#requirements">Requirements</a>
* <a href="#overview">Overview</a>
<% if vars.product_name == 'CF' %>
* <a href="#bosh-segments">Prepare BOSH to Support Isolation Segments</a>
<% else %>
<% end %>
* <a href="#create-isolation-segment">Create an Isolation Segment</a>
* <a href="#lists">Retrieve Isolation Segment Information</a>
* <a href="#delete_is">Delete an Isolation Segment</a>
* <a href="#relationships">Manage Isolation Segment Relationships</a>

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

## <a name='requirements'></a> Requirements

You must have the [v.6.26.0](https://github.com/cloudfoundry/cli/releases/tag/v6.26.0) version or later of the [Cloud Foundry Command Line Interface (cf CLI)](../cf-cli/install-go-cli.html) 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. <%= vars.api_endpoint_book %>

## <a name='overview'></a> Overview

<%= vars.isolation_segments_intro %>

After an admin creates a new isolation segment, the admin can then create and manage relationships between the orgs and spaces of a Cloud Foundry deployment and the new isolation segment.

To manage the isolation segment, an operator uses cf CLI commands.

Operators can perform the following operations on isolation segments:

* [Create an isolation segment](#create-an-is)
* [List isolation segments](#list_is)
* [Display isolation segments enabled for an org](#list_is_org)
* [Show the isolation segment assigned to a space](#list_is_space)
* [Delete an isolation segment](#delete_is)
* [Enable isolation segments for an org](#enable_org_is)
* [Disable isolation segments for an org](#remove_org_is)
* [Set the default isolation segment for an org](#set_org_default_is)
* [Assign an isolation segment to a space](#assign_iso_seg)
* [Reset the isolation segment assignment for a space](#reset_space)

<% if vars.product_name == 'CF' %>
## <a name="bosh-segments"></a>Prepare BOSH to Support Isolation Segments

To enable isolation segments for a deployment, you must first assign Diego cells a `placement_tags` property in your Diego manifest by following the steps below:

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 `diego.yml`, you tag a Diego cell with `my_segment` as follows:

    <pre>
    <span>-</span> instances: 1
      name: cell_z2
      networks:
      <span>-</span> name: diego2
      properties:
        diego:
         rep:
           [...] 
            placement_tags:
            <span>-</span> my_segment
    </pre>

2. Apply the changes (BOSH Deployer only):
<pre class="terminal">
$ bosh deploy
</pre>
<% else %>
<% end %>

## <a name="create-an-is"></a>Create an Isolation Segment

<%= vars.isolation_segments_create %>

To register an isolation segment with Cloud Controller, use the cf CLI. 

<%= vars.isolation_segments_note %>

The following command creates an isolation segment named `my_segment`:

<pre class="terminal">
$ cf create-isolation-segment my_segment
</pre>

If successful, the command returns an `OK` message:

<pre class="terminal">
Creating isolation segment my_segment as admin...
OK
</pre>

## <a name="lists"></a> Retrieve Isolation Segment Information

The `cf isolation-segments`, `cf org`, and `cf space` commands retrieve information about isolation segments. The isolation segments you can see depends on your role, as follows:

* **Admins** see all isolation segments in the system.
* **Other users** only see the isolation segments that their orgs are entitled to.

### <a name="list_is"></a> List Isolation Segments

The following request returns a list of the isolation segments that are available to you:
<pre class="terminal">
$ cf isolation-segments
</pre>

For example, the command returns results similar to the following:

<pre class="terminal">
Getting isolation segments as admin...
OK

name     	   orgs
my_segment     org1, org2
</pre>

### <a name="list_is_org"></a> Display Isolation Segments Enabled for an Org

An admin can entitle an org to multiple isolation segments.

Run `cf org ORG-NAME` command to view the isolation segments that are available to an org. Replace `ORG-NAME` with the name of your org. 

For example:

<pre class="terminal">
$ cf org my-org
</pre>

The command returns results similar to the following:

<pre class="terminal">
Getting info for org my-org as user@example.com...

name:                 my-org
domains:              example.com, apps.example.com
quota:                paid
spaces:               development, production, sample-apps, staging
isolation segments:   my_segment, my_other_segment
</pre>

### <a name="list_is_space"></a> Show the Isolation Segment Assigned to a Space

Only one isolation segment can be assigned to a space. 

Run `cf space SPACE-NAME` to view the isolation segment assigned to a space. Replace `SPACE-NAME` with the name of the space. 

For example:

<pre class="terminal">
$ cf space staging
</pre>

The command returns results similar to the following:

<pre class="terminal">
name:                staging
org:                 my-org
apps:
services:
isolation segment:   my_segment
space quota:
security groups:     dns, p-mysql, p.mysql, pcf-redis, public_networks, rabbitmq, ssh-logging
</pre>

## <a name="delete_is"></a> Delete an Isolation Segment

<p class="note"><strong>Note</strong>: An isolation segment with deployed apps cannot be deleted.</p>

Only admins can delete isolation segments.

Run `cf delete-isolation-segment SEGMENT-NAME` to delete an isolation segment. Replace `SEGMENT-NAME` with the name of the isolation segment. If successful, the command returns an `OK` message.

For example: 
<pre class="terminal">
$ cf delete-isolation-segment my_segment
Deleting isolation segment my_segment as admin...
OK
</pre>

## <a name="relationships"></a> Manage Isolation Segment Relationships

The commands listed in the sections below manage the relationships between isolation segments, orgs, and spaces. 

### <a name="enable_org_is"></a> Enable an Org to Use Isolation Segments

Only admins can enable orgs to use isolation segments. Run `cf enable-org-isolation ORG-NAME SEGMENT-NAME` to enable the use of an isolation segment. Replace `ORG-NAME` with the name of your org, and `SEGMENT-NAME` with the name of the isolation segment.

For example:
<pre class="terminal">
$ cf enable-org-isolation org2 my_segment
</pre>

If an org is entitled to use 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](#set_org_default_is) of an org.

### <a name="remove_org_is"></a> Disable an Org from Using Isolation Segments

<p class="note"><strong>Note</strong>: You cannot disable an org from using an isolation segment if a space within that org is assigned to the isolation segment. Additionally, you cannot disable an org from using an isolation segment if the isolation segment is configured as the default for that org.</p>

Run `cf disable-org-isolation ORG-NAME SEGMENT-NAME` to disable an org from using an isolation segment. Replace `ORG-NAME` with the name of your org, and `SEGMENT-NAME` with the name of the isolation segment.

For example:
<pre class="terminal">
$ cf disable-org-isolation org1 my_segment
</pre>

If successful, the command returns an `OK` message:

<pre class="terminal">
Removing entitlement to isolation segment my_segment from org org1 as admin...
OK
</pre>

### <a name="set_org_default_is"></a> Set the Default Isolation Segment for an Org

_This section requires [cf CLI v6.29.0](https://github.com/cloudfoundry/cli/releases/tag/v6.29.0) or later._

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

When an org has a default isolation segment, apps in its spaces belong to the default isolation segment
unless you assign them to another isolation segment.
You must restart running applications to move them into the default isolation segment.

Run `cf set-org-default-isolation-segment ORG-NAME SEGMENT-NAME` to set the default isolation segment for an org. Replace `ORG-NAME` with the name of your org, and `SEGMENT-NAME` with the name of the isolation segment.

For example:
<pre class="terminal">
$ cf set-org-default-isolation-segment org1 my\_segment
Setting isolation segment my_segment to default on org org1 as admin...
OK
</pre>

To display the default isolation segment for an org, use the `cf org` command.

### <a name="assign_iso_seg"></a> Assign an Isolation Segment to a Space

Admins and org managers can assign an isolation segment to a space. Apps in that space start in the specified isolation segment.

To assign an isolation segment to a space, you must first enable the space's org to use the isolation segment. See [Enable an Org to Use Isolation Segments](#enable_org_is)

Run `cf set-space-isolation-segment SPACE-NAME SEGMENT-NAME` to assign an isolation segment to a space. Replace `SPACE-NAME` with the name of the space, and `SEGMENT-NAME` with the name of the isolation segment.

For example:
<pre class="terminal">
$ cf set-space-isolation-segment space1 my_segment
</pre>

### <a name="reset_space"></a> Reset the Isolation Segment Assignment for a Space

Admins can reset the isolation segment assigned to a space to use the org's default isolation segment.

Run `cf reset-space-isolation-segment SPACE-NAME` to the assign the default isolation segment for an org to a space. Replace `SPACE-NAME` with the name of the space.

For example:
<pre class="terminal">
$ cf reset-space-isolation-segment space1
</pre>