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. Most resources can be moved between compartments. However, 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 tenancy-wide, across regions. When you create a compartment, it is available in every region that your tenancy is subscribed to.

Creating Compartments

When creating a 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, from 1 through 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 in compartments to create hierarchies that are six levels deep.

Figure showing compartment hierarchy six levels deep

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 permissions set at the tenancy level). 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) and can't be created in or managed from a specific compartment.

Moving Resources to a Different Compartment

Most resources can be moved after they are created. There are a few resources that you can't move from one compartment to another.

Some resources have attached resource dependencies and some don’t. Not all attached dependencies behave the same way when the parent resource moves.

For some resources, the attached dependencies move with the parent resource to the new compartment. The parent resource moves immediately, but in some cases attached dependencies move asynchronously and are not visible in the new compartment until the move is complete.

For other resources, the attached resource dependencies do not move to the new compartment. You can move these attached resources independently.

After you move the resource to the new compartment, the policies that govern the new compartment apply immediately and affect access to the resource. Depending on the structure of your compartment organization, metering, billing, and alarms can also be affected.

See the service documentation for individual resources to familiarize yourself with the behavior of each resource and its attachments.

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

In the Console, Search allows you to get a list of resources in a compartment, with some limitations. Search can only return results for your currently selected region. Not all resources support Search. For more information, see Overview of Search.

Deleting Compartments

Note

Deleting compartments is not available in Oracle Cloud Infrastructure Government Cloud.

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 moved, 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. A resource type that can't be deleted is:

  • 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.

Adding Tag Defaults for a Compartment

Tag defaults let you specify tags to be applied automatically to all resources, at the time of creation, in the current compartment. For more information, see Managing Tag Defaults.

Moving a Compartment to a Different Parent Compartment

You can move a compartment to a different parent compartment within the same tenancy. When you move a compartment, all its contents (subcompartments and resources) are moved with it. Moving a compartment has implications for the contents. These implications are described in the following sections. Ensure that you are aware of these before you move a compartment.

Required IAM Policy

To move a compartment, 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.

Restrictions on Moving Compartments

  • You can't move a compartment to a destination compartment with the same name as the compartment being moved.

    For example, assume compartment A and compartment B are both under the root compartment. Under compartment A is a subcompartment, also called compartment B. You cannot move the compartment B to the parent compartment B.

    Compartment B can't be moved to a parent compartment also named Compartment B

  • Two compartments within the same parent cannot have the same name. Therefore you can't move a compartment to a destination compartment where a compartment with the same name already exists.

Understanding the Policy Implications When You Move a Compartment

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. Before you move a compartment, ensure that:

  • You are aware of the policies that govern access to the compartment in its current position.
  • You are aware of the polices in the new parent compartment that will take effect when you move the compartment.

In some cases, when moving nested compartments with policies that specify the hierarchy, the polices are automatically updated to ensure consistency.

Policy Examples

Groups with Permissions in the Current Compartment Lose Access; Groups with Permissions in the Destination Compartment Gain Access

The following figure shows a compartment hierarchy in which compartment C, a child of A:B is moved to the hierarchy A:D.

Compartment C is moved from A:B to A:D

The tenancy has the following policies defined for compartments B and D:

Policy1: Allow group G1 to manage instance-family in compartment A:B

Policy2: Allow group G2 to manage instance-family in compartment A:D

Impact when compartment C is moved from B to D:

Group G1 can no longer manage instance-families in compartment C.

Group G2 can now manage instance-families in compartment C.

Ensure that you are aware not only of what groups lose permissions when you move a compartment, but also what groups will gain permissions.

Automatic Update of Policies

When you move a compartment, some polices will be automatically updated. Policies that specify the compartment hierarchy down to the compartment being moved will automatically be updated when the policy is attached to a shared ancestor of the current and target parent. Consider the following examples:

Example 1: Policy automatically updated

Policy is automatically updated when the policy is attached to a shared ancestor

In this example, you move compartment A from Operations:Test to Operations:Dev. The policy that governs compartment A is attached to the shared parent, Operations. When the compartment is moved, the policy statement is automatically updated by the IAM service to specify the new compartment location.

The policy

Allow group G1 to manage buckets in compartment Test:A 

is updated to

Allow group G1 to manage buckets in compartment Dev:A

No manual intervention is required to allow group G1 to continue to access compartment A in its location.

Example 2: Policy not updated

Policy is not updated

In this example, you move compartment A from Operations:Test to Operations:Dev. However, the policy that governs compartment A here is attached directly to the Test compartment. When the compartment is moved, the policy is not automatically updated. The policy that specifies compartment A is no longer valid and must be manually removed. Group G1 no longer has access to compartment A in its new location under Dev. Unless another existing policy grants access to group G1, you must create a new policy to allow G1 to continue to manage buckets in compartment A.

Example 3: Policy attached to the tenancy is updated

Policy is automatically updated when the policy is attached to a shared ancestor

In this example, you move compartment A from Operations:Test to HR:Prod. The policy that governs compartment A is attached to the tenancy, which is a shared ancestor by the original parent compartment and the new parent compartment. Therefore, when the compartment is moved, the policy statement is automatically updated by the IAM service to specify the new compartment location.

The policy statement:

Allow group G1 to manage buckets in compartment Operations:Test:A 

is updated to

Allow group G1 to manage buckets in compartment HR:Prod:A

No manual intervention is required to allow group G1 to continue to access compartment A.

Understanding Compartment Quota Implications When You Move a Compartment

When you move one compartment to another, resource quotas in the destination compartment are not verified and are not enforced. Therefore, if the compartment move results in a quota violation in the destination compartment, the move is not blocked. After the move is complete, the destination compartment will be in an over-quota state. You will not be able to create new resources that are over-quota until you either adjust the quotas for the destination compartment or remove resources to comply with the existing quota. For more information on managing compartment quotas, see Compartment Quotas.

Understanding Tagging Implications When You Move a Compartment

Tags are not automatically updated after a compartment move. If you have implemented a tagging strategy based on compartment, you must update the tags on the resources after the move. For example, assume CompartmentA has a child compartment, CompartmentB. CompartmentA is set up with tag defaults so that every resource in CompartmentA is tagged with TagA. Therefore CompartmentB and all its resources are tagged with default tag, TagA. When you move CompartmentB to CompartmentC, it will still have the default tags from CompartmentA. If you have set up default tags for CompartmentC, you'll need to add those to the resources in the moved compartment.

Tag defaults are not updated after a compartment is moved

Using the Console

Warning

Avoid entering confidential information when assigning descriptions, tags, or friendly names to your cloud resources through the Oracle Cloud Infrastructure Console, API, or CLI.

To create a compartment
To update a compartment's name
To update a compartment's description
To view the contents of a compartment
To move a compartment
To move a resource to a different 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.