Skip to main content

compartments

Creates, updates, deletes, gets or lists a compartments resource.

Overview​

Namecompartments
TypeResource
Idoci.identity.compartments

Fields​

The following fields are returned by SELECT queries:

A collection of related resources. Compartments are a fundamental component of Oracle Cloud Infrastructure<br />for organizing and isolating your cloud resources. You use them to clearly separate resources for the purposes<br />of measuring usage and billing, access (through the use of IAM Service policies), and isolation (separating the<br />resources for one project or business unit from another). A common approach is to create a compartment for each<br />major part of your organization. For more information, see<br />[Overview of IAM](//Content/Identity/getstarted/identity-domains.htm) and also<br />[Setting Up Your Tenancy](/Content/GSG/Concepts/settinguptenancy.htm).<br /><br />To place a resource in a compartment, simply specify the compartment ID in the "Create" request object when<br />initially creating the resource. For example, to launch an instance into a particular compartment, specify<br />that compartment's OCID in the LaunchInstance request. You can't move an existing resource from one<br />compartment to another.<br /><br />To use any of the API operations, you must be authorized in an IAM policy. If you're not authorized,<br />talk to an administrator. If you're an administrator who needs to write policies to give users access,<br />see [Get Started with Policies](/Content/Identity/policiesgs/get-started-with-policies.htm).<br /><br />Warning: Oracle recommends that you avoid using any confidential information when you supply string values<br />using the API.<br />

NameDatatypeDescription
idstringThe OCID of the compartment.
namestringThe name you assign to the compartment during creation. The name must be unique across all compartments in the parent. Avoid entering confidential information.
compartmentIdstringThe OCID of the parent compartment containing the compartment.
definedTagsobjectDefined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: &#123;"Operations": &#123;"CostCenter": "42"&#125;&#125;
descriptionstringThe description you assign to the compartment. Does not have to be unique, and it's changeable.
freeformTagsobjectFree-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: &#123;"Department": "Finance"&#125;
inactiveStatusinteger (int64)The detailed status of INACTIVE lifecycleState.
isAccessiblebooleanIndicates whether or not the compartment is accessible for the user making the request. Returns true when the user has INSPECT permissions directly on a resource in the compartment or indirectly (permissions can be on a resource in a subcompartment).
lifecycleStatestringThe compartment's current state. After creating a compartment, make sure its lifecycleState changes from CREATING to ACTIVE before using it. (CREATING, ACTIVE, INACTIVE, DELETING, DELETED)
timeCreatedstring (date-time)Date and time the compartment was created, in the format defined by RFC3339. Example: 2016-08-25T21:10:29.600Z

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
listselectcompartmentId, regionpage, limit, accessLevel, compartmentIdInSubtree, name, sortBy, sortOrder, lifecycleStateLists the compartments in a specified compartment. The members of the list<br />returned depends on the values set for several parameters.<br /><br />With the exception of the tenancy (root compartment), the ListCompartments operation<br />returns only the first-level child compartments in the parent compartment specified in<br />compartmentId. The list does not include any subcompartments of the child<br />compartments (grandchildren).<br /><br />The parameter accessLevel specifies whether to return only those compartments for which the<br />requestor has INSPECT permissions on at least one resource directly<br />or indirectly (the resource can be in a subcompartment).<br /><br />The parameter compartmentIdInSubtree applies only when you perform ListCompartments on the<br />tenancy (root compartment). When set to true, the entire hierarchy of compartments can be returned.<br />To get a full list of all compartments and subcompartments in the tenancy (root compartment),<br />set the parameter compartmentIdInSubtree to true and accessLevel to ANY.<br /><br />See [Where to Get the Tenancy's OCID and User's OCID](/Content/API/Concepts/apisigningkey.htm#five).<br />
createinsertregion, name, compartmentId, descriptionopc-retry-tokenCreates a new compartment in the specified compartment.<br /><br />Specify the parent compartment's OCID as the compartment ID in the request object. Remember that the tenancy<br />is simply the root compartment. For information about OCIDs, see<br />[Resource Identifiers](/Content/General/Concepts/identifiers.htm).<br /><br />You must also specify a name for the compartment, which must be unique across all compartments in<br />your tenancy. You can use this name or the OCID when writing policies that apply<br />to the compartment. For more information about policies, see<br />[How Policies Work](/Content/Identity/policieshow/how-policies-work.htm).<br /><br />You must also specify a description for the compartment (although it can be an empty string). It does<br />not have to be unique, and you can change it anytime with<br />[UpdateCompartment](#/en/identity/20160918/Compartment/UpdateCompartment).<br /><br />After you send your request, the new object's lifecycleState will temporarily be CREATING. Before using the<br />object, first make sure its lifecycleState has changed to ACTIVE.<br />
updateupdatecompartmentId, regionif-matchUpdates the specified compartment's description or name. You can't update the root compartment.
deletedeletecompartmentId, regionif-matchDeletes the specified compartment. The compartment must be empty.<br />
get_compartmentexeccompartmentId, regionGets the specified compartment's information.<br /><br />This operation does not return a list of all the resources inside the compartment. There is no single<br />API operation that does that. Compartments can contain multiple types of resources (instances, block<br />storage volumes, etc.). To find out what's in a compartment, you must call the "List" operation for<br />each resource type and specify the compartment's OCID as a query parameter in the request. For example,<br />call the [ListInstances](#/en/iaas/20160918/Instance/ListInstances) operation in the Cloud Compute<br />Service or the [ListVolumes](#/en/iaas/20160918/Volume/ListVolumes) operation in Cloud Block Storage.<br />
bulk_delete_resourcesexeccompartmentId, region, resourcesopc-request-id, opc-retry-tokenDeletes multiple resources in the compartment. All resources must be in the same compartment. You must have the appropriate<br />permissions to delete the resources in the request. This API can only be invoked from the tenancy's<br />[home region](/Content/Identity/regions/managingregions.htm#Home). This operation creates a<br />[WorkRequest](#/en/workrequests/20160918/WorkRequest/). Use the [GetWorkRequest](#/en/workrequests/20160918/WorkRequest/GetWorkRequest)<br />API to monitor the status of the bulk action.<br />
bulk_move_resourcesexeccompartmentId, region, resources, targetCompartmentIdopc-request-id, opc-retry-tokenMoves multiple resources from one compartment to another. All resources must be in the same compartment.<br />This API can only be invoked from the tenancy's [home region](/Content/Identity/regions/managingregions.htm#Home).<br />To move resources, you must have the appropriate permissions to move the resource in both the source and target<br />compartments. This operation creates a [WorkRequest](#/en/workrequests/20160918/WorkRequest/).<br />Use the [GetWorkRequest](#/en/workrequests/20160918/WorkRequest/GetWorkRequest) API to monitor the status of the bulk action.<br />
move_compartmentexeccompartmentId, region, targetCompartmentIdif-match, opc-request-id, opc-retry-tokenMove the compartment to a different parent compartment in the same tenancy. When you move a<br />compartment, all its contents (subcompartments and resources) are moved with it. Note that<br />the CompartmentId that you specify in the path is the compartment that you want to move.<br /><br />IMPORTANT: After you move a compartment to a new parent compartment, the access policies of<br />the new parent take effect and the policies of the previous parent no longer apply. Ensure that you<br />are aware of the implications for the compartment contents before you move it. For more<br />information, see [Moving a Compartment](/Content/Identity/compartments/managingcompartments.htm#MoveCompartment).<br />
recover_compartmentexeccompartmentId, regionif-match, opc-request-idRecover the compartment from DELETED state to ACTIVE state.<br />

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
compartmentIdstringThe OCID of the compartment.
regionstringOCI region identifier (e.g. us-ashburn-1, ap-sydney-1); resolves from OCI_REGION when not supplied in the query. (default: us-ashburn-1, x-stackQL-envVar: OCI_REGION)
accessLevelstringValid values are ANY and ACCESSIBLE. Default is ANY. Setting this to ACCESSIBLE returns only those compartments for which the user has INSPECT permissions directly or indirectly (permissions can be on a resource in a subcompartment). For the compartments on which the user indirectly has INSPECT permissions, a restricted set of fields is returned. When set to ANY permissions are not checked.
compartmentIdInSubtreebooleanDefault is false. Can only be set to true when performing ListCompartments on the tenancy (root compartment). When set to true, the hierarchy of compartments is traversed and all compartments and subcompartments in the tenancy are returned depending on the the setting of accessLevel.
if-matchstringFor optimistic concurrency control. In the PUT or DELETE call for a resource, set the if-match parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value.
lifecycleStatestringA filter to only return resources that match the given lifecycle state. The state value is case-insensitive.
limitintegerThe maximum number of items to return in a paginated "List" call.
namestringA filter to only return resources that match the given name exactly.
opc-request-idstringUnique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.
opc-retry-tokenstringA token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (e.g., if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected).
pagestringThe value of the opc-next-page response header from the previous "List" call.
sortBystringThe field to sort by. You can provide one sort order (sortOrder). Default order for TIMECREATED is descending. Default order for NAME is ascending. The NAME sort order is case sensitive. Note: In general, some "List" operations (for example, ListInstances) let you optionally filter by Availability Domain if the scope of the resource type is within a single Availability Domain. If you call one of these "List" operations without specifying an Availability Domain, the resources are grouped by Availability Domain, then sorted.
sortOrderstringThe sort order to use, either ascending (ASC) or descending (DESC). The NAME sort order is case sensitive.

SELECT examples​

Lists the compartments in a specified compartment. The members of the list<br />returned depends on the values set for several parameters.<br /><br />With the exception of the tenancy (root compartment), the ListCompartments operation<br />returns only the first-level child compartments in the parent compartment specified in<br />compartmentId. The list does not include any subcompartments of the child<br />compartments (grandchildren).<br /><br />The parameter accessLevel specifies whether to return only those compartments for which the<br />requestor has INSPECT permissions on at least one resource directly<br />or indirectly (the resource can be in a subcompartment).<br /><br />The parameter compartmentIdInSubtree applies only when you perform ListCompartments on the<br />tenancy (root compartment). When set to true, the entire hierarchy of compartments can be returned.<br />To get a full list of all compartments and subcompartments in the tenancy (root compartment),<br />set the parameter compartmentIdInSubtree to true and accessLevel to ANY.<br /><br />See [Where to Get the Tenancy's OCID and User's OCID](/Content/API/Concepts/apisigningkey.htm#five).<br />

SELECT
id,
name,
compartmentId,
definedTags,
description,
freeformTags,
inactiveStatus,
isAccessible,
lifecycleState,
timeCreated
FROM oci.identity.compartments
WHERE compartmentId = '{{ compartmentId }}' -- required
AND region = '{{ region }}' -- required
AND page = '{{ page }}'
AND limit = '{{ limit }}'
AND accessLevel = '{{ accessLevel }}'
AND compartmentIdInSubtree = '{{ compartmentIdInSubtree }}'
AND name = '{{ name }}'
AND sortBy = '{{ sortBy }}'
AND sortOrder = '{{ sortOrder }}'
AND lifecycleState = '{{ lifecycleState }}'
;

INSERT examples​

Creates a new compartment in the specified compartment.<br /><br />Specify the parent compartment's OCID as the compartment ID in the request object. Remember that the tenancy<br />is simply the root compartment. For information about OCIDs, see<br />[Resource Identifiers](/Content/General/Concepts/identifiers.htm).<br /><br />You must also specify a name for the compartment, which must be unique across all compartments in<br />your tenancy. You can use this name or the OCID when writing policies that apply<br />to the compartment. For more information about policies, see<br />[How Policies Work](/Content/Identity/policieshow/how-policies-work.htm).<br /><br />You must also specify a description for the compartment (although it can be an empty string). It does<br />not have to be unique, and you can change it anytime with<br />[UpdateCompartment](#/en/identity/20160918/Compartment/UpdateCompartment).<br /><br />After you send your request, the new object's lifecycleState will temporarily be CREATING. Before using the<br />object, first make sure its lifecycleState has changed to ACTIVE.<br />

INSERT INTO oci.identity.compartments (
compartmentId,
definedTags,
description,
freeformTags,
name,
region,
opc-retry-token
)
SELECT 
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ description }}' /* required */,
'{{ freeformTags }}',
'{{ name }}' /* required */,
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
name,
compartmentId,
definedTags,
description,
freeformTags,
inactiveStatus,
isAccessible,
lifecycleState,
timeCreated
;

UPDATE examples​

Updates the specified compartment's description or name. You can't update the root compartment.

UPDATE oci.identity.compartments
SET 
definedTags = '{{ definedTags }}',
description = '{{ description }}',
freeformTags = '{{ freeformTags }}',
name = '{{ name }}'
WHERE 
compartmentId = '{{ compartmentId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
RETURNING
id,
name,
compartmentId,
definedTags,
description,
freeformTags,
inactiveStatus,
isAccessible,
lifecycleState,
timeCreated;

DELETE examples​

Deletes the specified compartment. The compartment must be empty.<br />

DELETE FROM oci.identity.compartments
WHERE compartmentId = '{{ compartmentId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match }}'
;

Lifecycle Methods​

Gets the specified compartment's information.<br /><br />This operation does not return a list of all the resources inside the compartment. There is no single<br />API operation that does that. Compartments can contain multiple types of resources (instances, block<br />storage volumes, etc.). To find out what's in a compartment, you must call the "List" operation for<br />each resource type and specify the compartment's OCID as a query parameter in the request. For example,<br />call the [ListInstances](#/en/iaas/20160918/Instance/ListInstances) operation in the Cloud Compute<br />Service or the [ListVolumes](#/en/iaas/20160918/Volume/ListVolumes) operation in Cloud Block Storage.<br />

EXEC oci.identity.compartments.get_compartment 
@compartmentId='{{ compartmentId }}' --required, 
@region='{{ region }}' --required
;