isolation-segments.html.md.erb

---
title: Managing Isolation Segments in Cloud Foundry
owner: CAPI
---

<%# Reset page title based on platform type %>
<% if vars.platform_code != 'CF' %>

<% set_title("Managing Isolation Segments in", vars.app_runtime_abbr) %>

<% end %>

With <%= vars.app_runtime_abbr %>, you can isolate deployment workloads into dedicated resource pools called isolation segments.

## <a id='overview'></a> Isolation Segments overview
<% if vars.platform_code == 'CF' %>

To enable isolation segments, an admin can pass in a custom operations file with the BOSH CLI. For the example file used in this topic,
see the [cf-deployment](https://github.com/cloudfoundry/cf-deployment/blob/master/operations/test/add-persistent-isolation-segment-diego-cell.yml) repository in GitHub.

<% else %>
<%= vars.isolation_segments_intro %>
<% end %>

After an admin creates a new isolation segment, the admin can then create and manage relationships between the orgs and spaces
of a <%= vars.app_runtime_first %> deployment and the new isolation segment.


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

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 %>


<% if vars.platform_code == 'CF' %>
## <a id="segment-manifest"></a> Add an Isolation Segment to your deployment manifest

To add an isolation segment to your deployment manifest:

1. Write a custom operations file. The operations file defines an instance group that supports isolation segments.
    For a working example, see the [cf-deployment](https://github.com/cloudfoundry/cf-deployment/blob/master/operations/test/add-persistent-isolation-segment-diego-cell.yml) repository in GitHub. The example sets the following instance group properties:
      * Name as `isolated-diego-cell`
      * Placement tag as `persistent_isolation_segment`
        <p> When you use the cf CLI, the name of the isolation segment corresponds to the placement tag you
        specify in the operations file. The commands throughout this topic use <code>SEGMENT-NAME</code> as an example isolation segment name.</p>

1. Apply the custom operations file when you deploy <%= vars.app_runtime_abbr %> by running:

    ```
    bosh -e BOSH-ENVIRONMENT -d cf deploy cf-deployment/cf-deployment.yml \
    -v system_domain=SYSTEM-DOMAIN \
    -o cf-deployment/operations/CUSTOM-OPS-FILE.yml
    ```

    Where:
      * `BOSH-ENVIRONMENT` is your BOSH environment alias. For more information about creating an environment alias for BOSH v2 or later, see [Environments](https://bosh.io/docs/cli-envs/) in the BOSH documentation.
      * `SYSTEM-DOMAIN` is the system domain of your <%= vars.app_runtime_abbr %> deployment.
      * `CUSTOM-OPS-FILE.yml` is your operations file.
<% end %>


## <a id="register-an-is"></a> Register an isolation segment

To register an isolation segment in the Cloud Controller database (CCDB), use the cf CLI.

<% if vars.platform_code != 'CF' %>

If you run smoke tests as a post-deploy errand in the Isolation Segment tile, the smoke tests check if your isolation segment is registered in the CCDB. If the isolation segment is not registered, the smoke tests register it in the CCDB. This eliminates the need to manually register an isolation segment with `cf create-isolation-segment`.

<% end %>

<p>To register an isolation segment in the CCDB:</p>

1. Log in to your deployment by running:

    ```
    cf login
    ```

2. Run:

    ```
    cf create-isolation-segment SEGMENT-NAME
    ```

    <p>Where <code>SEGMENT-NAME</code> is the name you give your isolation segment.</p>
    <br>
    <%= vars.isolation_segments_note %>

    <p>If successful, the command returns an `OK` message:</p>

    <pre class="terminal">
    Creating isolation segment SEGMENT-NAME as admin...
    OK
    </pre>


## <a id="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:

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

### <a id="list_is"></a> List isolation segments

To see a list of the isolation segments that are available to you:

1. Log in to your deployment by running:

    ```
    cf login
    ```

1. Run:

    ```
    cf isolation-segments
    ```

    The command returns results similar to this example output:

    <pre class="terminal">
    Getting isolation segments as admin...
    OK
    name     	   orgs
    SEGMENT-NAME     org1, org2
    </pre>

### <a id="list_is_org"></a> Display isolation segments enabled for an org

An admin can entitle an org to multiple isolation segments.

To view the isolation segments that are available to an org:

1. Log in to your deployment by running:

    ```
    cf login
    ```

1. Run:

    ```
    cf org ORG-NAME
    ```
    Where `ORG-NAME` is the name of your org.

    The command returns results similar to this example output:

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

    name:                 ORG-NAME
    domains:              example.com, apps.example.com
    quota:                paid
    spaces:               development, production, sample-apps, staging
    isolation segments:   SEGMENT-NAME, OTHER-SEGMENT-NAME
    </pre>

### <a id="list_is_space"></a> Showing the isolation segment assigned to a space

Only one isolation segment can be assigned to a space.

To view the isolation segment assigned to a space:

1. Log in to your deployment by running:

    ```
    cf login
    ```

1. Run:

    ```
    cf space SPACE-NAME
    ```
    Where `SPACE-NAME` is the name of the space to which your isolation segment is assigned.

    The command returns results similar to this example output:

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


## <a id="delete_is"></a> Deleting an isolation segment

<p> An isolation segment with deployed apps cannot be deleted.</p>

Only admins can delete isolation segments.

To delete an isolation segment:

1. Log in to your deployment by running:

    ```
    cf login
    ```

1. Run:

    ```
    cf delete-isolation-segment SEGMENT-NAME
    ```
    Where `SEGMENT-NAME` is the name of the isolation segment you want to delete.

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

    <pre class="terminal">
    $ cf delete-isolation-segment SEGMENT-NAME
    Deleting isolation segment SEGMENT-NAME as admin...
    OK
    </pre>


## <a id="relationships"></a> Managing isolation segment relationships

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

### <a id="enable_org_is"></a> Enabling an org to use isolation segments

Only admins can enable orgs to use isolation segments.

To enable the use of an isolation segment:

1. Log in to your deployment by running:

    ```
    cf login
    ```

1. Run:

    ```
    cf enable-org-isolation ORG-NAME SEGMENT-NAME
    ```

    Where:
    <ul>
      <li><code>ORG-NAME</code> is the name of your org.</li>
      <li><code>SEGMENT-NAME</code> is the name of the isolation segment you want your org to use.</li>
    </ul>


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 of an org. For more information, see [Set the Default Isolation Segment for an Org](#set_org_default_is).

### <a id="remove_org_is"></a> Deactivating an org from using isolation segments

<p> You cannot deactivate an org from using an isolation segment if a space within that org is assigned to the isolation
segment. Additionally, you cannot deactivate an org from using an isolation segment if the isolation segment is configured as the default for that org.</p>

To deactivate an org from using an isolation segment:

1. Log in to your deployment by running:

    ```
    cf login
    ```

1. Run:

    ```
    cf disable-org-isolation ORG-NAME SEGMENT-NAME
    ```

    Where:
    <ul>
     <li><code>ORG-NAME</code> is the name of your org.</li>
     <li><code>SEGMENT-NAME</code> is the name of the isolation segment you want to deactivate the org from using.</li>
    </ul>

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

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

### <a id="set_org_default_is"></a> Setting the default isolation segment for an org

<p> This section requires cf CLI v6.29.0 or later. To download cf CLI v6.29.0 or later, go to
the <a href="https://github.com/cloudfoundry/cli/releases/tag/v6.29.0">Releases</a> section of the Cloud Foundry CLI repository on GitHub.</p>

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

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

To set the default isolation segment for an org:

1. Log in to your deployment by running:

    ```
    cf login
    ```

1. Run:

    ```
    cf set-org-default-isolation-segment ORG-NAME SEGMENT-NAME
    ```

    Where:
    <ul>
      <li><code>ORG-NAME</code> is the name of your org.</li>
      <li><code>SEGMENT-NAME</code> is the name of the isolation segment you want to set as your org's default.</li>
    </ul>

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

    <pre class="terminal">
    $ cf set-org-default-isolation-segment org1 SEGMENT-NAME
    Setting isolation segment SEGMENT-NAME to default on org org1 as admin...
    OK
    </pre>

To display the default isolation segment for an org:

1. Run:

    ```
    cf org
    ```

### <a id="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 activate the space's org to use the isolation segment. For more information, see [Enable an Org to Use Isolation Segments](#enable_org_is).

To assign an isolation segment to a space:

1. Log in to your deployment by running:

    ```
    cf login
    ```

1. Run:

    ```
    cf set-space-isolation-segment SPACE-NAME SEGMENT-NAME
    ```

    Where:
    <ul>
      <li><code>SPACE-NAME</code> is the name of your space.</li>
      <li><code>SEGMENT-NAME</code> is the name of the isolation segment you want to assign to your space.</li>
    </ul>

### <a id="reset_space"></a> Resetting 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.

To assign the default isolation segment for an org to a space:

1. Log in to your deployment by running:

    ```
    cf login
    ```

1. Run:

    ```
    cf reset-space-isolation-segment SPACE-NAME
    ```
    Where `SPACE-NAME` is the name of the space to which you want to assign your org's default isolation segment.