Oracle Cloud Infrastructure Documentation

Managing Compartments

This topic describes the basics of working with compartments.

Required IAM Policy

If you're in the Administrators group, then you have the required access for managing compartments.

For an additional policy related to compartment management, see Let a compartment admin manage the compartment.

If you're new to policies, see Getting Started with Policies and Common Policies. If you want to dig deeper into writing policies for compartments or other IAM components, see Details for IAM.

Tagging Resources

You can apply tags to your resources to help you organize them according to your business needs. You can apply tags at the time you create a resource, or you can update the resource later with the desired tags. For general information about applying tags, see Resource Tags.

Working with Compartments

When you first start working with Oracle Cloud Infrastructure, you need to think carefully about how you want to use compartments to organize and isolate your cloud resources. Compartments are fundamental to that process. Once you put a resource in a compartment, you can't move it, so it's important to think through your compartment design for your organization up front, before implementing anything. For more information, see Setting Up Your Tenancy.

The Console is designed to display your resources by compartment within the current region. When you work with your resources in the Console, you must choose which compartment to work in from a list on the page. That list is filtered to show only the compartments in the tenancy that you have permission to access. If you're an administrator, you'll have permission to view all compartments and work with any compartment's resources, but if you're a user with limited access, you probably won't.

Compartments are global, across regions. When you create a compartment, it is available in every region that your tenancy is subscribed to.

Creating Compartments

When creating a new compartment, you must provide a name for it (maximum 100 characters, including letters, numbers, periods, hyphens, and underscores) that is unique within its parent compartment. You must also provide a description, which is a non-unique, changeable description for the compartment, between 1 and 400 characters. Oracle will also assign the compartment a unique ID called an Oracle Cloud ID. For more information, see Resource Identifiers.

You can create subcompartments inside of compartments to create hierarchies that are six levels deep.

Figure showing compartment hierarchy six levels deep

Like other resources, you can't move subcompartments from one compartment to another.

For information about the number of compartments you can have, see Service Limits.

Access Control for Compartments

After creating a compartment, you need to write at least one An IAM document that specifies who has what type of access to your resources. It is used in different ways: to mean an individual statement written in the policy language; to mean a collection of statements in a single, named "policy" document (which has an Oracle Cloud ID (OCID) assigned to it); and to mean the overall body of policies your organization uses to control access to resources. for it, otherwise no one can access it (except administrators or users who have permission to the tenancy).

When creating a compartment inside another compartment, the compartment inherits access permissions from compartments higher up its hierarchy. For more information, see Policy Inheritance.

When you create an access policy, you need to specify which compartment to attach it to. This controls who can later modify or delete the policy. Depending on how you've designed your compartment hierarchy, you might attach it to the tenancy, a parent, or to the specific compartment itself. For more information, see Policy Attachment.

Putting Resources in a Compartment

To place a new resource in a compartment, you simply specify that compartment when creating the resource (the compartment is one of the required pieces of information to create a resource). If you're working in the Console, you just make sure you're first viewing the compartment where you want to create the resource. Keep in mind that most IAM resources reside in the tenancy (this includes users, groups, compartments, and any policies attached to the tenancy). Notice that you can't move a resource from one compartment to another.

Viewing Resources in a Compartment

It's not possible to get a list of all the resources in a compartment by using a single API call. Instead you can list all the resources of a given type in the compartment (e.g., all the instances, all the block storage volumes, etc.).

Tip

Search allows you to get a list of resources in a compartment, with some limitations. Search lists the resources in the region you are viewing. Not all resources support Search. For more information, see Overview of Search.

Deleting Compartments

To delete a compartment, it must be empty of all resources. Before you initiate deleting a compartment, be sure that all its resources have been deleted or terminated, including any policies attached to the compartment.

Important

Some resource types can't be deleted, therefore, compartments containing these resource types can't be deleted. The resource types that can't be deleted are:

  • Tag namespaces and tag key definitions
  • Data transfer jobs

The delete action is asynchronous and initiates a work request. The state of the compartment changes to Deleting while the work request is executing. It typically takes several minutes for the work request to complete. While it is in the Deleting state it is not displayed on the compartment picker. If the work request fails, the compartment is not deleted and it returns to the Active state.

After a compartment is deleted, its state is updated to Deleted and a random string of characters is appended to its name, for example, CompartmentA might become CompartmentA.qR5hP2BD. Renaming the compartment allows you to reuse the original name for a different compartment. The deleted compartment is displayed on the Compartments page for the number of days specified in your Audit Retention Period setting (90-365 days). The deleted compartment is removed from the compartment picker. If any policy statements reference the deleted compartment, the name in the policy statement is updated to the new name.

Troubleshooting tips for when a compartment fails to delete
Important

There is a known issue causing deleted compartments to continue to count against your service limit of compartments. See Deleted compartments continue to count against service limits.

Using the Console

To create a compartment
To update a compartment's name
To update a compartment's description
To view the contents of a compartment
To delete a compartment

Using the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use these API operations to manage compartments:

You can retrieve the contents of a compartment only by resource type. There's no API call that lists all resources in the compartment. For example, to list all the instances in a compartment, call the Core Services API ListInstances operation and specify the compartment ID as a query parameter.