Creating and Managing Compartments

Compartments contain resources such as cloud instances, virtual cloud networks, and block volumes. Your tenancy is the root compartment where you can create cloud resources and other compartments. You can create hierarchies of compartments that are up to six levels deep. You can limit access to compartment resources to specified user groups. Most resources can be moved between compartments later if your business needs change.

The compartments that you create in your tenancy are your primary building blocks for organizing and controlling access to your cloud resources. Before you create compartments and resources, see "Organizing Resources in Compartments" in the Identity and Access Management Overview in the Oracle Private Cloud Appliance Concepts Guide.

Understanding the Tenancy

A tenancy is a special compartment. The tenancy is the root compartment where you create and administer all of your cloud resources, including other compartments.

Users, groups, and identity providers are always attached directly to the tenancy, not to any compartment of the tenancy. You cannot specify a different compartment when you create a user, group, or identity provider. When you use the OCI CLI to operate on a user, group, or identity provider, the OCID of the tenancy from the config file is used by default.

Other resources can reside in the tenancy or in any other compartment. Operating on these resources often requires you to select the correct compartment in the Compute Web UI or specify the compartment OCID in the OCI CLI.

Use the following procedures to get the OCID of the tenancy.

Using the Compute Web UI

Click your user profile menu in the top right of the page.
Click the Tenancy option.
On the tenancy details page, use the Show or Copy button under OCID.

Using the OCI CLI

Use the compartment list command.
```
$ oci iam compartment list
```
Look for the ocid1.tenancy.unique_ID OCID.
- With no options, the compartment list command lists all compartments that are direct child compartments of the tenancy. The tenancy is the value of the first property listed (compartment-id) for every compartment in the list.
- If you specify the --include-root option, the tenancy is listed first, and the tenancy OCID is the value of the id property (the value of the compartment-id property is null).
As is true for other resources, in a compartment list or get, the compartment-id compartment is the parent compartment of the id compartment.

Listing Compartments

Using the Compute Web UI

In the navigation menu, click Identity and then click Compartments.

The list shows all compartments that are direct child compartments of the tenancy.
To view a compartment that is a subcompartment of a listed compartment, click the name of the listed compartment. On the details page for that compartment, scroll to the Resources section, and click Child Compartments.

You might need to click the name of a compartment in the Child Compartments list, and repeat this step.

To find the compartment where a particular resource is located, navigate to a list of those resources. Above the resource list, use the Compartment drop-down menu to select the compartment.

Using the OCI CLI

Use the --help option to learn about the --access-level option and about options that are common to list commands such as --lifecycle-state and --sort-by.

To list all compartments and subcompartments in the tenancy, specify the --compartment-id-in-subtree option with a value of true.
```
$ oci iam compartment list --compartment-id-in-subtree true
```
Specifying the --compartment-id option, described in the next step, does not change this output: You cannot list just the compartment tree of a particular compartment other than the tenancy.
To list all compartments that are direct child compartments of another compartment, specify the OCID of that parent compartment:
```
$ oci iam compartment list --compartment-id ocid1.compartment.unique_ID
```
This output does not list the specified parent compartment and does not list compartments that are deeper in the hierarchy of this parent compartment. This output only lists the direct child compartments of the specified parent compartment.

If you do not specify a parent compartment, all compartments that are direct child compartments of the tenancy are listed. To list the tenancy in addition to the direct child compartments of the tenancy, specify the --include-root option.
To list just one particular compartment, you can specify the compartment name.
```
$ oci iam compartment list --name Acompartment
```
The output is the same as a get of that compartment.
```
$ oci iam compartment get --compartment-id OCID_of_Acompartment
```

Creating a Compartment

You can create a compartment in your tenancy or in another compartment. You can create hierarchies of compartments that are up to six levels deep.

Using the Compute Web UI

In the navigation menu, click Identity and then click Compartments.
Click the Create Compartment button above the list of compartments.
In the Create Compartment dialog box, enter the following information:
- Name: A name for this compartment. Compartment names have the following characteristics:
  - Must be unique within the tenancy.
  - Are case insensitive.
  - Can be changed later.
  - Can be no more than 100 characters.
  - Can contain only alphanumeric characters, period (.), hyphen (-), and underscore (_).
- Description: A description for this compartment. This description can be no more than 400 characters and can be changed later.
- Create in Compartment: The compartment in which you want to create the new compartment. The new compartment will be a sub-compartment of the selected compartment.
- Tagging: (Optional) Add defined or free-form tags for this compartment as described in Adding Tags at Resource Creation. Tags can also be applied later.
Click the Create Compartment button on the dialog box.

Click the name of the new compartment to view the compartment details, including tags.

Using the OCI CLI

Get the OCID of the compartment in which you want to create the new compartment. The new compartment will be a sub-compartment of the specified compartment.
```
$ oci iam compartment list --compartment-id-in-subtree true
```

Run the compartment create command.

Syntax:

oci iam compartment create --compartment-id compartment_OCID \
--name text --description "text"

See the Compute Web UI procedure for characteristics of the name and description values. See Adding Tags at Resource Creation to add defined and free-form tags.

Example:

$ oci iam compartment create -c ocid1.compartment.parent_compartment_unique_ID \
--name ProductX --description "A child compartment of compartment Products"
{
  "data": {
    "compartment-id": "ocid1.compartment.parent_compartment_unique_ID",
    "defined-tags": {},
    "description": "A child compartment of compartment Products",
    "freeform-tags": {},
    "id": "ocid1.compartment.new_compartment_unique_ID",
    "inactive-status": null,
    "is-accessible": null,
    "lifecycle-state": "ACTIVE",
    "name": "ProductX",
    "time-created": "2021-10-05T22:58:23.216657+00:00"
  },
  "etag": "b212700d-45fa-46a9-90da-bcc016c587bc"
}

To view this output later, use the compartment get command.

Applying Tag Defaults

Compartments can have resources called tag defaults. Tag defaults are defined tags that are inherited by all resources and child compartments that are created after the tag default is added to the parent compartment. To add a tag default to a compartment, see Configuring Tag Defaults.

Adding Policies for Access Control

Child compartments inherit access permissions from their parent compartments. If you want the access to a new compartment to be different from the access to the parent compartment, create an access policy for the new compartment. For example, grant group DevX permission to read all resources in compartment Products and permission to manage all resources in subcompartment ProductX. Grant group DevY permission to read all resources in compartment Products and permission to manage all resources in subcompartment ProductY. Because of inheritance, group DevX will be able to read all resources in compartment ProductY, and group DevY will be able to read all resources in compartment ProductX.

For information about creating and attaching policies, see Managing Policies.

Adding Resources to a Compartment

Use either of the following methods to add resources to a compartment:

Specify the compartment when you create the resource.
Move the resource from a different compartment.

See the documentation for the particular resource for information such as whether attached resources move with the moved resource.

Check whether the moved resources have the correct tags and policies applied. You might need to manually delete and add tags and policies.

The Resources box on a compartment details page in the Compute Web UI, and the compartment list and get commands in the OCI CLI, do not show all of the resources that belong to a compartment. For resources that are not listed, go to the Compute Web UI page for that resource, such as instances, and select the compartment from the Compartment drop-down menu above the resource list. In the OCI CLI, specify the compartment OCID when you list the resources. See also Using the Compute Web UI and Using the OCI CLI.

Updating a Compartment

You can change the name and description of a compartment. You can add, change, or remove tags as described in Applying Tags to an Existing Resource. You cannot change the parent compartment. To change the parent compartment, see Moving a Compartment to a Different Compartment.

Using the Compute Web UI

In the navigation menu, click Identity and then click Compartments.
If the compartment that you want to update is not listed, navigate to the compartment that you want to update, as described in Listing Compartments.
For the compartment that you want to update, click the Actions menu, and click the Edit option.
In the Editing compartment_name Compartment dialog, make the changes.
Click the Save Changes button.

Click the compartment name to view the compartment details, including tags.

Using the OCI CLI

Get the OCID of the compartment that you want to update.

$ oci iam compartment list --compartment-id-in-subtree true

Run the compartment update command.

Syntax:
```
oci iam oci iam compartment update --compartment-id compartment_OCID \
options_with_values_to_update
```
Example:

If you specify the --defined-tags or --freeform-tags options, then you must fully specify all defined and free-form tags that you want on this compartment, including tags that already exist on the compartment that you want to keep. Values that you provide for these tag options replace any existing values. See Working with Resource Tags. You will be prompted to confirm unless you specify the --force option.
```
$ oci iam compartment update --compartment-id ocid1.compartment.unique_ID \
--defined-tags '{"Product":{"LMN":"Development"}}' --freeform-tags '{"MyTag":"val-u"}'
WARNING: Updates to freeform-tags and defined-tags will replace any existing values.
Are you sure you want to continue? [y/N]: y
```
The output of this command is the same as the output of the compartment get command.

Moving a Compartment to a Different Compartment

You can move a compartment to a different parent compartment in the same tenancy. When you move a compartment, all subcompartments of the compartment are moved. Some resources of the moved compartment are moved. You can separately move other resources as needed. See the documentation for the particular resource type for more information.

After you move a compartment to a new parent compartment, the access policies of the new parent take effect and the policies of the previous parent no longer apply. Groups who had access to the compartment and its resources in the previous parent compartment lose their access when the compartment is moved. Groups who have access in the new parent compartment gain access to the moved compartment and its resources.

Tag defaults that are automatically applied to all resources created in the new parent are not automatically applied to the newly moved compartment and its resources. You might need to separately delete and add tag defaults to the moved compartment and delete and add tags to moved resources.

See also "Moving a Compartment to a Different Parent Compartment" in the Identity and Access Management Overview in the Oracle Private Cloud Appliance Concepts Guide.

You must belong to a group that has manage all-resources permissions on the lowest shared parent compartment of the current compartment and the destination compartment.

To move a compartment, you must use the OCI CLI.

Using the OCI CLI

Get the OCID of the compartment that you want to move, and the OCID of the destination compartment.
```
$ oci iam compartment list --compartment-id-in-subtree true
```
Run the compartment move command.

Syntax:
```
oci iam compartment move --compartment-id compartment_to_move_OCID \
--target-compartment-id destination_compartment_OCID
```
Use the iam work-request get command to check the status of the compartment move, or view the work request details in the Compute Web UI. Some resources might take longer to move than the compartment.

Deleting a Compartment

To delete a compartment, you must first move, delete, or terminate all of the resources in the compartment, including any policies that are attached to the compartment. Before you begin, check the move and delete capabilities for all resources in the compartment.

Using the Compute Web UI

In the navigation menu, click Identity and then click Compartments.

The compartments in the tenancy are listed.
If the compartment that you want to delete is not listed, navigate to the compartment that you want to update, as described in Listing Compartments.
For the compartment that you want to delete, click the Actions menu, and click the Delete Compartment option.

If the Delete Compartment option is not selectable, then you might not have permission to delete this compartment.
In the Delete Compartment confirmation dialog, click Delete.

The compartment status changes to Deleting.

In the Resources box on the compartment details page, click Work Requests and view the details of the compartment delete. When the work request is completed, the compartment is removed from the compartments list. If the work request fails, the compartment status returns to Active.

Using the OCI CLI

Get the OCID of the compartment that you want to delete.

$ oci iam compartment list --compartment-id-in-subtree true

Run the compartment delete command.

Syntax:
```
oci iam compartment delete --compartment-id compartment_OCID
```
Use the iam work-request get command to check the status of the compartment delete.