Organization Management Overview

Use Organization Management to centrally manage many tenancies, invite and create child tenancies, view and map subscriptions, and create and attach governance rules to tenancies in an organization.

With Organization Management, you can add tenancies to an organization, and have those tenancies consume from the primary funded subscription. You can create an isolated tenancy to build workloads, without needing to book a new order.

Two types of tenancies are involved when mapping and using a subscription in Organization Management:

Parent: Tenancy that's associated with the primary funded subscription.
Child: Tenancies that join an organization, whereby the parent manages the child's cost and governance. Child tenancies can either be created as entirely new tenancies, or, existing tenancies can be invited to join the same organization and to change your default subscription.

An organization can have multiple child tenancies, which are managed by the parent tenancy. The parent tenancy can use Subscription Mapping to assign subscriptions to any child tenancy in the organization.

Benefits of Organization Management include the following:

Share a single commitment to help avoid cost overages and enable multitenancy cost management. You can analyze, report, and monitor across all linked tenancies in an organization. The parent tenancy can analyze and report across each of its tenancies through Cost Analysis and Cost and usage reports, and you can receive alerts through Budgets.
Customers with strict data isolation requirements can use a multitenancy strategy to isolate data and restrict resources across their tenancies.
Use governance rules to enforce and govern resources on specific child tenancies, or the entire organization.

Important

SaaS subscription services can be provisioned in the tenancy where the SaaS subscription was activated, which also includes child tenancies.

The remainder of this topic provides an overview of how to use Organization Management to create child tenancies, invite existing tenancies, view and revoke invitations, and how to remap subscriptions to tenancies. Cost reporting features are also described, which you can use to centrally manage cost and usage information across all tenancies in an organization. Using these features you can better manage a multitenancy environment.

Planning Considerations

Before you add more tenancies, evaluate your needs to ensure that a multi-tenancy approach is best for your workloads. The main reason to have multiple tenancies is for strong isolation, to help isolating workloads.

Because managing multiple tenancies can create extra management overhead, ensure that the isolation is worth it. If you don't require a strong level of isolation, you can instead consider using compartments to separate workloads.

By default, each parent and child tenancy comes with:

A distinct set of IAM users (which can be federated to another identity system).
A distinct set of IAM policies (permissions).
A distinct tenancy administrator.
Its own service limits.
Isolated Virtual Cloud Networks (VCNs).
Separate security and governance settings.

A tenancy can be a parent tenancy, and add child tenancies if the tenancy meets the following criteria:

The parent has enough organization child tenancy limits. These limits are initially granted based on the subscription the parent was activated with. By default, Oracle Universal Credits annual commit and funded allocation subscriptions are enabled for creating or inviting extra tenancies. Pay As You Go or Trial subscriptions have a limit of 0 child tenancies. If you need a service limit increase, these can be requested through a support ticket. For more information, see Organizations Service Limits and Requesting a Service Limit Increase.
The parent tenancy must be subscribed to the superset of child-subscribed regions.
Despite whatever region will be assigned as the home region to a child tenancy, the parent tenancy must be signed in to their home region to create a child tenancy, regardless of how many regions the parent tenancy is already subscribed to. The child tenancy home region selection can be any of multiple (if multiple exist) parent subscribed regions.

Invited tenancies can be a child of an organization if they meet the following criteria:

The invited tenancy must have a paid subscription, such as Oracle Universal Credits, Pay As You Go, commit, or funded allocation.
The invited tenancy can't be Free Tier or Trial.
The invited tenancy must have a home region within the same realm.
The invited tenancy must be standalone (it can't be a parent tenancy or be part of another organization).

In regards to sharing a subscription in the organization:

Oracle Universal Credits subscriptions can be shared across multiple tenancies, while SaaS subscriptions can't be shared.
When a subscription is shared, the tenancy usage is metered against the subscription. Usage costs are computed based on the subscription's rate card and currency. Costs are consumed from the subscriptions credits.
Subscriptions can be shared regardless of the contractual country.
Using Subscription Mapping, you can map a particular subscription to one or multiple tenancies.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be granted security access in a policy by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don't have permission or are unauthorized, verify with your administrator what type of access you have and which compartment to work in.

If you're new to policies, see Getting Started with Policies and Common Policies.

To use Organization Management, the following policy statements are required:

Allow group linkUsers to use organizations-family in tenancy
Allow group linkAdmins to manage organizations-family in tenancy

To accept an invitation but not create one use the following:

allow group linkAccepters to manage organizations-recipient-invitations in tenancy

To view the current linked tenancies but not the invitations:

allow group linkViewers to read organizations-links in tenancy

Creating a New Child Tenancy

As the parent tenancy, you can create new child tenancies or invite existing tenancies to your organization. Newly created child tenancies consume from your organization's default subscription. If you want the new child tenancy to consume from another subscription, you can remap the created tenancy to another subscription on the Subscription Mapping page.

You can attach governance rules to the new child tenancy during creation, or you can come back later and attach rules. To attach governance rules before child tenancy creation, you can create any governance rules first on the Governance Rules page, so they're available for selection during new child tenancy creation.

Created child tenancies inherit the current default limits of the parent tenancy. Child tenancies receive their own set of limits, which aren't shared with other tenancies.

Note

Free Tier or Trial tenancies can't add new child tenancies, or be invited to be part of an organization, unless they're converted to paid first. For more information on upgrading, see Account Upgrade Overview.

The following table describes the child tenancy creation and invitation actions that can be performed based on pricing model:


Pricing Model	Can Create Tenancies	Can Invite Tenancies	Can be invited
Pay As You Go	No	Yes	Yes
Annual Commit	Yes	Yes	Yes
Funded Allocation	Yes	Yes	Yes
Custom	Yes	Yes	Yes
Trial/Free Tier	No	No	No

To create a child tenancy, you will be required to provide the necessary information, such as tenancy name and designated administrator email, and then sign-in instructions are provided in an email notification to the child tenancy administrator. The created (child) tenancy automatically consumes from the default subscription of the organization, so all usage is charged based on the rate card of the subscription. The parent tenancy is also responsible for the child tenancy's usage.

Open the navigation menu and click Governance & Administration. Under Organization Management, click Tenancies.
On the Tenancies page, click Create new tenancy.
In the Create new tenancy panel's Tenancy details step, enter a name for the new child tenancy in Tenancy name.

The tenancy name must be unique and all lowercase without any special characters. Avoid entering confidential information.
From Home region, select a region from the list. The home region is one of the parent's subscribed regions.
In Administrator email and Confirm Email, enter and confirm the email address of the tenancy administrator.
Click Next. In the Governance rules step, select governance rules to attach to the tenancy, or skip and attach them later. You can always attach or detach rules later, or opt the tenancy out of organization governance in the future if preferred.

If selecting governance rules now, select them from the table. You can filter the table by the rule type (tag, allowed regions, quotas), or the targeted tenancy. For any rule, click the down arrow () to expand the rule entry and view its details.

Otherwise, if no governance rules are selected, a message indicates that you are choosing to skip attaching governance rules for now.
Click Next.
In the Review summary step, review the new child tenancy settings that you specified are correct. Tenancy details shows the tenancy name, home region, and administrator email, while the Governance rules section shows the rule names, rule type, and targeted tenancies.
Click Create tenancy. A notification is displayed, indicating that you have successfully requested to create a child tenancy. If the request completes successfully, then your authentication credentials are sent by email momentarily.

The child tenancy administrator receives instructions to activate the tenancy, and set up a password and MFA.

Inviting an Existing Tenancy

If you have the correct limits, you can invite another tenancy to join your organization. If the tenancy joins your organization, its subscription will be managed by the parent tenancy.

See Organization Limits for more information on the limits related to inviting another tenancy.

The recipient tenancy needs to have the proper permissions to manage subscription sharing in the child tenancy, to accept the invitation. For more information, see Required IAM Policy. The recipient tenancy also needs to be in a home region within the same realm.

Note

Parent tenancies and tenancies that aren't already in a sharing relationship can send invitations. Child tenancies can't send invitations.

If the invitation is accepted by an authorized user in the recipient tenancy, and the recipient tenancy is subscribed to a Pay As You Go subscription, all usage in the recipient tenancy will be metered against your subscription. To stop sharing your subscription with the recipient tenancy after the invitation has been accepted, you can remap the subscription.

You can attach governance rules to the invited tenancy during creation, or you can attach rules later. To attach governance rules before sending the invitation, you can create any governance rules first on the Governance Rules page, so they're available for selection during the invite tenancy process.

Invited tenancies will continue to retain their own distinct service limits. For a limits increase, they can request it through support requests. For more information, see Requesting a Service Limit Increase.

Important

An invited tenancy (also referred to as the recipient tenancy) is automatically mapped to the default subscription in the organization, so all usage will be computed and charged against the default subscription's rate card . If you don't want the invited, recipient tenancy to consume from the default subscription, you can remap the subscription back to the original subscription after the invited tenancy has joined the organization.

To invite a tenancy:

Sign in to the sender tenancy (the one that will send the invitation), as a user that has permissions to manage Organization Management functions.
Open the navigation menu and click Governance & Administration. Under Organization Management, click Tenancies.
Click Invite tenancy.
On the Invite tenancy panel, in Invitation name, enter the name of the invite that will be visible to the recipient. Avoid entering confidential information.

Note

For the invitation name, it can be helpful to use notation that signifies the direction and number of sending invitation attempts. For example, entering a1 to b1 v1 can signify that tenancy a1 is sending an invitation to b1, and v1 as the first try. Such a convention allows the invitations to be more readable to the Console user, without having to access the invitation details page to view sender and recipient details. See Viewing Invitations for more information.
In Recipient tenancy OCID, enter the recipient's OCID. You can find the OCID on the tenancy details page.
In Recipient email, enter and confirm the recipient's email address.

Note

The recipient needs to have the proper permissions to manage subscription sharing in the recipient tenancy, to accept the invitation. For more information, see Required IAM Policy.
Click Show advanced options and enter any tagging details. See Resource Tags for more information.
Click Next. In the Governance rules step, you can select governance rules to attach to the tenancy, or skip and attach them later. By default, the Require tenancy to join organization governance option is selected for the tenancy. If this option is disabled, a message indicates that have chosen to disable organization governance for this tenancy. To attach governance rules to this tenancy in the future, you will need to request the invited tenancy to use governance rules, and have the tenancy accept (opt in to) the request.
Under Governance rules, if selecting governance rules now, select them from the table. You can filter the table by the rule type (All, Allowed regions, Quota policies, Tags), or the targeted tenancy. For any rule, click the down arrow () to expand the rule entry and view its details.

Note

Some rules are set by the entire organization, and so such rules are already selected, and can't be disabled.

Select one or more extra rules and click Next. If you don't select any rules, a message indicates that you have chosen to skip attaching governance rules, but you can still select and attach governance rules later.
Review the summary step to ensure the invited tenancy settings you specified are correct. Tenancy details shows the invitation name and recipient tenancy OCID, while the Governance rules section shows the rule names, rule type, and targeted tenancies if governance rules were attached. Whether rules were attached or not, the Require tenancy to join organization governance field indicates whether the invited tenancy is required to join organization governance with Yes or No. Rules can be created, attached, and detached later.
Click Invite tenancy. The invitation is sent to the tenancy you're inviting to add to your organization, and share its subscription and any governance rules (if selected). A notification is displayed that you have successfully requested to invite a tenancy (with the associated OCID) to join the organization. If the request completes successfully, then the recipient tenancy will receive an invitation to accept. The invitation expires in 30 days.
On the recipient invited tenancy: Open the navigation menu and click Governance & Administration. Under Organization Management, click Invitations.
On the Invitations page, the invitation from the tenancy that sent the invite is displayed in the Invitations page list, with the following information:
- Invitation Name: Click the linked name to go to the invitation details page.
- Status: Displays the invitation status. For example, the status is Active when the invitation is received but not yet accepted. This field shows Pending for an invitation that has been sent but not yet accepted.
  The possible status states for a sender and recipient invitation are the following:
  Sender Invitation Recipient Invitation
  
  PENDING
  
  CANCELED
  
  ACCEPTED
  
  EXPIRED
  
  FAILED
  
  PENDING
  
  CANCELED
  
  ACCEPTED
  
  IGNORED
  
  EXPIRED
  
  FAILED
- Type: The invitation type, whether Sent invitation or Received invitation. A Sent request or Received request invitation, meanwhile, means an invitation to join organization governance was sent or received.
- Created: The UTC creation date and time of the invitation.
On the recipient invited tenancy: On the Invitations page, click the Actions menu () for the received invitation and select Accept Invitation. An Accept Invitation confirmation message is displayed, which indicates that you're about to accept an invitation from the tenancy.

By joining the organization, the parent tenancy can manage cost management and reporting (oversee spending), governance rules (create and attach governance rules to the tenancy), and subscription mapping (map and unmap subscriptions to the tenancy).

After clicking Accept, the invitation is processed, and the invitation's Status field changes to Accepted. The tenancy then becomes a child tenancy under the parent tenancy in the organization.

After the sharing invitation is accepted, it will take one to two hours for metering to start flowing to the subscription in the parent tenancy. In future, however, all usage in the child tenancy will be metered against the parent tenancy's subscription. In addition, after the new tenancy joins the organization, we recommend that you wait a few hours before creating resources (that is, if you want to be sure that all spending will accrue against the subscription of the parent tenancy).

If a remaining subscription balance exists, contact your sales representative to move it to a primary subscription in the sending tenancy.

Note

After the tenancy becomes a child tenancy in the organization, it can't invite another tenancy to become a child tenancy. Also, when a tenancy joins your organization, its subscription is managed by the parent tenancy. To remap a child tenancy back to the original subscription, you can use Subscription Mapping.

Sender Invitation	Recipient Invitation
PENDING CANCELED ACCEPTED EXPIRED FAILED	PENDING CANCELED ACCEPTED IGNORED EXPIRED FAILED

On both the child tenancy's and parent tenancy's Tenancies page, the child tenancy is shown, along with the parent tenancy. On the parent tenancy's Tenancies page, you can view the child tenancy and parent tenancy, and other child tenancies that are being metered against the organization's subscription. The following is shown:

Tenancy name
Tenancy OCID
Status: (Parent tenancy only) Displays the invitation status.
Organization governance: Specifies whether the tenancy is using governance rules (Joined) or not (Not joined).
Join Date: (Parent tenancy only) The UTC date and time that the tenancy joined and subscription sharing began.

Viewing Invitations

Invitation details can be viewed from both the parent, and child (or recipient) tenancy.

To view invitations:

Open the navigation menu and click Governance & Administration. Under Organization Management, click Invitations.
On the Invitations page, click the invitation name from the Invitation Name field, or click the Actions menu () and select View Invitation Details.
The invitation details page displays the invitation status, along with the following details on the Invitation Information tab:
- Sent to/from tenancy OCID
- Type: This field shows both invitations (a parent tenancy wants a tenancy to become a child tenancy to join the organization), or requests (to use governance rules). Governance invitation details pages are entitled as Request details: Join organization governance.
- Status
- Sent date
- Request (governance joining invitations only)
- Cost Management (tenancy invitation only)
- Organization governance (tenancy invitation only)
- Subscription mapping (tenancy invitation only)
You can also click Add tags to add tagging information, to be viewed on the Tags tab. See Resource Tags for more information.

Revoking Invitations

A parent tenancy that sends an invitation to another tenancy to join the organization, can choose to later revoke such an invitation on the Invitations page.

To revoke an invitation:

Sign in to the parent tenancy as a user that has permissions to manage invitations and subscription sharing.
As the parent tenancy, open the navigation menu and click Governance & Administration. Under Organization Management, click Invitations.
On the Invitations page, for the invitation you want to revoke, click the Actions menu () and select Revoke Invitation. On the invitation details page, you can also click Revoke.

A Revoke Invitation confirmation is displayed. To cancel the invitation, click Revoke. Confirm the revocation in the Revoke Invitation dialog by clicking Revoke.
The invitation details page reloads and changes to a canceled status. On the Invitations page, the invitation's Status changes to Canceled.

Removing an Invited Tenancy

As a parent tenancy, you can remove an invited child tenancy from the organization. Only invited child tenancies can be removed.

Invited tenancy removal unlinks the tenancy from the organization so that the parent doesn't have cost or governance access. For created child tenancies, you can transfer the tenancy to another organization using the CLI. For more information on using the oci organizations organization-tenancy approve-organization-tenancy-for-transfer and oci organizations organization-tenancy unapprove-organization-tenancy-for-transfer commands, see Transfer a Created Child Tenancy to Another Organization.

By removing the child tenancy, the parent tenancy can no longer manage the child tenancy. The parent tenancy can't view the child's future cost and usage information, nor manage the child's subscription mapping. If you wanted the child tenancy to consume from another subscription that's within the organization, you don't need to remove the tenancy. Instead, you can use subscription mapping to remap the tenancy to another subscription.

To remove an invited child tenancy, you first need to remove it from organization governance, use the Subscription Mapping page to assign the tenancy back to its original subscription, and then remove the tenancy from the Tenancies page after the tenancy has been remapped to its original subscription.

To remove an invited child tenancy:

Open the navigation menu and click Governance & Administration. Under Organization Management, click Tenancies.
On the Tenancies page under Tenancy name, click the invited tenancy that will be removed, to remove it from organization governance. For more information on opting into and out of organization governance, and detaching governance rules, see To opt in tenancies to use governance rules and To opt out existing tenancies from governance rules.
Open the navigation menu and click Governance & Administration. Under Organization Management, click Subscription Mapping.
On the Subscription Mapping page, select the child tenancy's original Universal Credits subscription from the Subscription ID column.
On the subscription mapping details page, under Mapped Tenancies, click Map subscription.
On the Map subscription panel, click Map subscription and select the child tenancy to be remapped. Click Map subscription. A notification message is displayed, informing you that you successfully mapped the subscription to the tenancy. The tenancy then appears under Mapped Tenancies on the subscription mapping details page.

Note

If other tenancies are mapped to this subscription, you need to unmap any other tenancies from the subscription. See Subscription Mapping for more information.
In Organization Management, click Tenancies.
On the Tenancies page, open the Actions menu () for the tenancy you want to remove and select Remove Tenancy.

In the Remove Tenancy confirmation, confirm that you do want to remove the tenancy, and click Remove Tenancy. Any subscriptions mapped to this tenancy will move with the tenancy, and will no longer be associated with your organization. You might also need to reload the Tenancies page to verify that the invited tenancy has been removed.

If you see an error in the Remove Tenancy dialog that states Child isn't consuming from its own UCM subscription, ocid1.tenancy.oc1..<unique_ID>, it means that you haven't yet remapped the child tenancy back to its own Oracle Universal Credits subscription.

The child tenancy is removed from the organization with its original subscription. Because you mapped the child tenancy back to its original subscription, the tenancy will consume from its own subscription going forward, and is responsible for paying for the subscription usage. Furthermore, because the tenancy has been removed from the organization, it now becomes a standalone parent tenancy of its own, which will be indicated on the removed tenancy's own Tenancies page (under Tenancy name, Parent tenancy is indicated).

Transfer a Created Child Tenancy to Another Organization

Use the oci organizations organization-tenancy approve-organization-tenancy-for-transfer command to transfer a created child tenancy to another organization.

The following example scenario assumes you have a created child tenancy that you want to transfer from an existing MyOldParentTenancy tenancy, to the new Pay As You Go MyNewParentTenancy tenancy. After the child tenancy has been transferred out of MyOldParentTenancy, you can invite the child tenancy to join the new MyNewParentTenancy tenancy. Lastly, you must update the subscription mapping in the new MyNewParentTenancy tenancy to ensure all tenancies (including future tenancies) use the existing subscription from the MyOldParentTenancy tenancy.

Tenancy details are the following:


Tenancy Name	OCID
MyOldParentTenancy	ocid1.tenancy.oc1..`<old-parent-tenancy-unique_ID>`
MyNewParentTenancy	ocid1.tenancy.oc1..`<new-parent-tenancy-unique_ID>`
childtenancy1	ocid1.tenancy.oc1..`<child-tenancy1-unique_ID>`

To transfer a created child tenancy:

While signed in as an administrator to MyOldParentTenancy, make a note of the subscription ID, because you will need it later to change the subscription mapping.

Open the navigation menu and click Governance & Administration. Under Organization Management, click Subscription Mapping. On the Subscription Mapping page, copy the subscription ID from the Subscription ID field.
Transfer childtenancy1 to MyNewParentTenancy. While signed in as the administrator to MyOldParentTenancy, select your home region and open Cloud Shell.

Run the following command:

oci organizations organization-tenancy approve-organization-tenancy-for-transfer --compartment-id ocid1.tenancy.oc1..<old-parent-tenancy-unique_ID> --organization-tenancy-id ocid1.tenancy.oc1..<child-tenancy1-unique_ID>

You can verify command success by examining the output:

{
 "data": {
  "is-approved-for-transfer": true,
  "lifecycle-state": "ACTIVE",
  "name": null,
  "role": "CHILD",
  "tenancy-id": "ocid1.tenancy.oc1..<unique_ID>"
  "time-joined": "<date-time>",
  "time-left": null
 }
}

For more information on the CLI, see oci organizations organization-tenancy approve-organization-tenancy-for-transfer.

Sign out of MyOldParentTenancy, and then sign in to MyNewParentTenancy.
Follow the steps in Inviting an Existing Tenancy to invite childtenancy1.

In Recipient tenancy OCID, enter the OCID for childtenancy1 (ocid1.tenancy.oc1..<child-tenancy1-unique_ID>).
Click Next and skip selection of any governance rules.
Review the summary step to ensure the invited tenancy settings you specified are correct. Click Invite tenancy to invite childtenancy1.

Check the recipient email and follow the instructions to accept the invitation and complete the transfer process.
You can repeat the previous steps for any extra tenancies, adjusting the oci organizations organization-tenancy approve-organization-tenancy-for-transfer command and the tenancy invitation to reflect the OCIDs for further tenancies.
After the child tenancy has been transferred out of the old parent tenancy, the old parent tenancy can also be invited to become a child tenancy of the new parent tenancy. Follow the steps in Inviting an Existing Tenancy to invite MyOldParentTenancy to join MyNewParentTenancy.

In Recipient tenancy OCID, enter the OCID for MyOldParentTenancy (ocid1.tenancy.oc1..<old-parent-tenancy-unique_ID>).
Click Next and skip selection of any governance rules.
Review the summary step to ensure the invited tenancy settings you specified are correct. Click Invite tenancy to invite MyOldParentTenancy.

Check the recipient email and follow the instructions to accept the invitation and complete the transfer process.
Follow the instructions in Subscription Mapping to remap the subscription that was used by MyOldParentTenancy to MyNewParentTenancy, ensuring that you map the subscription to all tenancies.

Deleting a Child Tenancy

An OCI administrator can delete a child tenancy, depending on the type of child tenancy.

Child tenancies created from an organization, and standalone tenancies that were invited into an organization and which later become child tenancies, can both be deleted, but the procedures differ for these two types of child tenancies.

If the tenancy was created from the Organization, follow the steps in Delete a Created Child Tenancy of an Organization to delete a created child tenancy.
If the tenancy was originally a standalone tenancy and was invited to became a part of the organization, the tenancy must first be removed from the organization before it can be deleted. See Removing an Invited Tenancy for more information on removal.
After removal, see Delete an Invited Child Tenancy of an Organization to delete the tenancy, which deletes the tenancy and its associated subscription.

Subscription Mapping

You can view and remap tenancies to the subscriptions within Organization Management.

An organization can have multiple subscriptions, which are managed by the parent tenancy. For example, an organization always starts out with only a single subscription (subscription "A"), but a child tenancy with its own subscription (subscription "B") that later joins the organization can bring its own subscription B. The parent tenancy can then use Subscription Mapping to map subscription B to other tenancies in the organization. As a result, an organization's subscriptions can be mapped to any tenancy in the organization.

Tenancies mapped to a subscription consume from the subscription's credits (for Universal Credits Commitment subscriptions) and use its rate card. By remapping a tenancy to a subscription, the tenancy's usage applies to the terms and conditions of the subscription, including its rate card, credit consumption, and other agreements within the subscription's contract.

To map subscriptions:

From the parent tenancy, open the navigation menu and click Governance & Administration. Under Organization Management, click Subscription Mapping.
On the Subscription Mapping page, click the subscription name from the Subscription ID field. The subscription mapping detail page opens.
The detail page displays the subscription details, along with tenancies that are assigned to the subscription, in terms of the following:
- Subscription ID
- Subscription OCID
- Subscription type
- Subscription start date
- Subscription end date
- Subscription description
Under Mapped tenancies, you can click Map subscription to open the Map subscription panel, and add other tenancies to be mapped to this subscription. When you remap the selected subscription to a tenancy, the tenancy stops consuming from the previously mapped subscription.
In the Map subscription panel, make your selections and click Map subscription.

Using Governance Rules

Use governance rules to configure and attach controls to tenancies in your organization. When a governance rule is attached to a tenancy, a corresponding resource gets created and locked in the target tenancy.

A governance rule is a type of enforcement that a parent tenancy creates, which allows governing a resource on the child tenancy. The parent tenancy creates the governance rules, whereby they can be targeted to one or more child tenancies. After being set, the governance rule enforcements become locked, so that users within the child tenancy are not permitted to modify the rule. As a result, a lock icon appears in the interface of such resources. For example, if a parent tenancy created an allowed regions governance rule for a child tenancy, the quota name has an adjacent lock icon on the child tenancy's Quota Policies page. When viewing a quota policy details page, a message is displayed, indicating that the resource was created and locked by the parent tenancy using governance rules. To change the rule, the parent must unlock it and change it. For more information, see Resource Locking.

Using governance rules, you can enforce the following:

Allowed regions: One or more regions that the targeted tenancies are allowed to subscribe to. Set an allowable list of regions as permitted by your compliance standards.
Note

If a targeted tenancy is already subscribed to a region not on the allowed regions list, the tenancy remains subscribed to that region, and resources can still be deployed in that region.
Quota policies: Set a resource quota to limit the number of resources within a service, or disable certain services. Such quotas can be set at the tenancy level, for example:
```
zero compute-core quotas in tenancy
set compute-core quota to 20 in tenancy
```
Tags: Define tags throughout your organization. You can share a tag namespace for consistent tagging, or define a tag default to ensure that all resources are tagged.
Note

When you update a resource (such as a tag namespace) in a parent tenancy that was used to create a governance rule, you need to also update the governance rule, or the changes will not propagate to child tenancies.

To create a governance rule and attach it to one or more tenancies:

Open the navigation menu and click Governance & Administration. Under Organization Management, click Governance Rules.
Click Create rule. The Create rule panel opens.
In Name, enter a name for the new governance rule. Avoid entering confidential information.
From Type, select a governance rule type, whether: Allowed regions, Quota policy, or Tags.
1. If Allowed regions is selected, under Rule configuration, select one or more regions that the targeted tenancies are allowed to subscribe to.
  
  In Description, enter a name for the allowed region rule configuration. Avoid entering confidential information. From Regions, select the regions you want to allow.
2. If Quota policy is selected, under Rule configuration, create a quota policy to be attached to the targeted tenancies.
  
  In Description, enter a name for the quota policy rule configuration. Avoid entering confidential information. Add the quota policy statements that you want to set in Quota policy statements. See Managing Quota Policies, Quota Policy Syntax, and Sample Quotas for more information on quota creation, syntax, and samples.
3. If Tags is selected, under Rule configuration, create a tag namespace from your root compartment to clone onto the targeted tenancies, or define a default tag.
  
  Select the tag namespace from the Tag namespace list. Click View details to view more information about the namespace in the Tag namespace details panel. In the panel, you can view the Tag key, Value type, and Cost tracking tag detail, and the tag key description.
  
  To add a default tag, selecting the corresponding Add default tag option, and then select a tag key from the list. You can also set Required Tag Value Options. Use the Default value option and enter the value in the Default value field, or select a User-applied value.
Under Attach rule, you can choose to attach the rule to specific tenancies, or attach the rule to all current and future tenancies that have joined organization governance (using governance rules).

If Attach to specific tenancies is selected, select one or more tenancies from the Tenancies field. You can also choose to not select any tenancies at this point (such rules have 0 in the Targeted tenancies field on the associated governance rule details page).

If Attach to entire organization is selected, the rule is attached to your tenancy and all your organization's tenancies that join organization governance. The rule attachment applies to both current and future tenancies.
Click Show advanced options to specify any tagging settings to organize and track resources in your tenancy.
Click Create rule. A new governance rule details page opens for the rule you created.
The governance rule details page shows the overall rule status. You can edit or delete the rule, change the attachment method (target specific tenancies or the entire organization), add tags, view rule details, and you can attach or detach the rule from tenancies. For each tenancy, you can also view the rule attachment work request progress. If the attachment failed, select Retry attaching from the Actions menu ().

The governance rule details page Rule details tab shows the following information. Under General information:
- OCID: OCID of the governance rule.
- Created: Created time in UTC format.
- Targeted tenancies: The number of targeted tenancies.
- Attachment method: Attached to specific tenancies or the entire organization.
Under Rule configuration, some information changes depending on whether the rule is for allowed regions, quota policies, or tags:
- Rule type
- (Allowed region rule only) Allowed regions: Lists the allowed regions in the rule.
- (Quota policy rule only) Statement: Click the View details link to see the statements in the Quota policy statements panel.
- (Tags rule only) Tag namespace: Lists the namespace and you can click the View details link to see the tag namespace in the Tag namespace details panel.
- (Tags rule only) Tag defaults: Lists the number of tag defaults, and you can click the View details link to see the tag defaults in the Tag default details panel.
Under the Tenancies section, you can select one or more tenancies to attach (or detach) from the governance rule.
The Tenancies section of the governance rule details page lists the following for every tenancy:
- Tenancy: The tenancy name.
- Rule status: The rule status, whether Not attached or Attached.
- Organization governance: Indicates whether the tenancy has Joined or Not joined organization governance. Only tenancies that have joined organization governance can be attached to rules.
To attach tenancies, select one or more tenancies under Tenancies, and click Attach. A confirmation is displayed to confirm the attachment of the rule to which tenancies. Click Attach rule. The governance rule detail page reloads and a new work request is started. After the work request completes, the rule is attached to the tenancy, and the Rule Status changes to Attached.

The governance rule is now configured and enforces its restrictions on the child tenancies (or if specified, the entire organization and future tenancies that join the organization). You can also view the associated governance rules by accessing the Tenancies page in Organization Management. On the Tenancies page, click the tenancy name to open the tenancy details page.

Under Governance rules, you can view the list of governance rules attached to the tenancy (to include their name and rule type). Click the governance rule name to go to the associated governance rule details page.

Meanwhile, the child tenancy that has attached governance rules can also view the rules on the Governance rules page, but can't interact with the rule, and can only view basic information about it, because the parent tenancy controls the rule configuration.

After the governance rule is created, you can edit or delete the rule, attach or detach the rule, or change the rule attachment method (specific tenancies or entire organization). From the parent tenancy, you can also choose to opt a tenancy in to or out of organization governance, or from a child tenancy, you can request to opt in to organization governance.

To edit a governance rule

Open the navigation menu and click Governance & Administration. Under Organization Management, click Governance Rules.
On the governance rule details page, click Edit rule configuration. The Edit rule configuration panel opens.
Edit the rule configuration and click Save.

To delete a governance rule

Open the navigation menu and click Governance & Administration. Under Organization Management, click Governance Rules.
On the governance rule details page, click Delete rule. A Delete rule confirmation is displayed.
Click Delete rule. Deletion is permanent and the rule's associated resource in the targeted tenancies is also deleted.

To attach a governance rule

Open the navigation menu and click Governance & Administration. Under Organization Management, click Governance Rules.
On the Governance Rules page, click the governance rule under Name, which opens the governance rule details page.
On the governance rule details page, select one or more tenancies under Tenancies, and click Attach tenancies. A confirmation is displayed to confirm you're sure you want to attach the rule to the tenancy.
Click Attach rule. The governance rule detail page reloads and a new work request is initiated. After the work request completes, the rule is no longer attached to the tenancy, and the Rule Status changes to Detached.

To change the governance rule attachment method from the parent tenancy

On the parent tenancy, open the navigation menu and click Governance & Administration. Under Organization Management, click Governance Rules.
On the governance rule details page, click Change attachment method. A Change attachment method confirmation is displayed.
Choose the preferred attachment method, whether Attach to specific tenancies or Attach to entire organization.
Choose the preferred attachment method, and click Attach rule.

To detach a governance rule

Open the navigation menu and click Governance & Administration. Under Organization Management, click Governance Rules.
On the Governance Rules page, click the governance rule under Name, which opens the governance rule details page.
On the governance rule details page, select one or more tenancies under Tenancies, and click Detach tenancies. A confirmation is displayed, indicating that the rule will no longer be applied to the targeted tenancy, and the rule's associated resource in the target tenancy will be deleted.
Click Detach rule. The governance rule detail page reloads and a new work request is started. You can click the Actions menu () for the tenancy and click View work requests to view the status and progress. After the work request completes, the rule is no longer attached to the tenancy, and the Rule Status changes to Detached.
Note

This process only detaches the governance rule, but doesn't opt the tenancy out of organization governance, because the Organization governance field will still indicate Joined.

To opt in tenancies to use governance rules

Certain types of tenancies that are already part of the organization can opt in to use governance rules.

A parent tenancy can both opt itself in or out.
A parent tenancy can request that a child tenancy agree to opt in, or opt out a child tenancy.
A child tenancy can be opted in by the parent tenancy or opt itself in, but a child tenancy can't opt itself out.

You can opt in a child tenancy either while signed in as the parent tenancy, or while signed in as the child tenancy.

To opt in a child tenancy to governance rules from the parent tenancy:

Open the navigation menu and click Governance & Administration. Under Organization Management, click Tenancies.
From the Tenancies page, click the tenancy from the Tenancy name field to open its details page.
Click Request to join organization governance. The Request to join organization governance panel opens, where you can request the tenancy to opt in. The recipient must have access to the child tenancy, and has 14 days to respond before the request expires.
Optionally, in Recipient Email, enter the recipient email address.
In Governance Rules, select the chosen governance rules now, or skip and select governance rules later.
Click Send request. A message is displayed, indicating that your governance invite request has been sent, and the child tenancy will use organization governance soon if they decide to accept the request.
On the sending tenancy's Invitations page, you can view the new governance invitation, which has Sent request in the Type field. Click the invitation in Invitation Name to view the invitation details page, where you can view its status (initially Pending in the Status field), until the receiving tenancy accepts the governance invitation.
The Request field indicates that you requested the tenancy to join organization governance, and that after the recipient tenancy accepts the request, you can create and attach governance rules to the tenancy.
You can also choose to revoke the governance invitation by clicking Revoke. A Revoke Invitation confirmation is displayed asking if you're sure you want to revoke the request to join organization governance. To revoke the request, click Revoke. The invitation details page reloads and switches to a canceled state. The invitation's Status field on the Invitations page also changes to Canceled.
On the recipient child tenancy, open the navigation menu and click Governance & Administration. Under Organization Management, click Invitations. The new governance invitation has a Status of Pending, and its Type is Received request.
Click the invitation to go to the Request details: Join organization governance details page. The invitation Type is Received request, and the Request field indicates that by accepting the request, you're joining organization governance and agreeing to allow the parent tenancy to create and attach governance rules to your tenancy. After joining, only the parent tenancy can remove your tenancy from organization governance.
On the invitation details page, click Accept. In the Accept Invitation confirmation, click Accept if you're sure you want to accept the request to join organization governance.
You can also accept the governance invitation directly from the main Invitations page by clicking Accept request or Decline request directly from the Actions menu ().
If you click Decline, the invitation is rejected and the sending tenancy can send another governance invitation later.
If accepting, after a few minutes the invitation status changes to Accepted. The invitation status can be viewed on both the sending (parent) tenancy, and the recipient (child) tenancy.
On the sending tenancy Tenancies page, the Organization governance field displays Joined, to indicate that the tenancy is now using governance rules. The Governance state field on the tenancy's details page also shows Organization governance, to indicate that the tenancy is using governance rules.

To opt in a child tenancy from the child tenancy:

Open the navigation menu and click Governance & Administration. Under Organization Management, click Tenancies.
From the Tenancies page, click the tenancy from the Tenancy name field to open its details page.
Click Join organization governance. The Join organization governance panel opens, where you can request the tenancy to opt in. By joining organization governance, you agree to allow the parent tenancy to create and attach governance rules to your child tenancy. After joining, only the parent tenancy can opt the child tenancy out of governance rule usage.
Click Join organization governance. A notification message is displayed, indicating that your request to opt in to governance has been accepted, and that your tenancy will be joined and participate in organization governance soon.
Under Work requests, an opt-in work request is started and indicates the status. You can click the request under Operation to view more details.
After the child tenancy is joined, under Settings on the tenancy information details page, the Governance state field shows Organization governance, and the Tenancies page indicates a Joined value under Organization Governance.

To opt out existing tenancies from governance rules

To opt a tenancy out of governance rules:

Open the navigation menu and click Governance & Administration. Under Organization Management, click Tenancies.
From the Tenancies page, click the tenancy from the Tenancy name field and open its details page.
Click Remove from organization governance.
In the confirmation, click Remove from organization governance. A message is displayed, indicating that your request to opt out of governance has been accepted, and your tenancy will be removed from organization governance soon.
After removing the tenancy from governance rules, you can no longer attach governance rules to the tenancy. To attach rules in the future, you need to request the tenancy to opt in again.
On the Tenancies page, the Organization governance field displays Not joined, to indicate that the tenancy isn't using governance rules. The Governance state field on the tenancy's details page also shows Cost management only, to indicate that the tenancy is no longer using governance rules, and is instead only sharing cost management details.

Troubleshooting Rules that Need Attention

Sometimes governance rules require attention while attaching to one or many tenancies in the organization. The work request for a specific tenancy gives detailed logs and error messages about the issue. Some typical scenarios include:

Creating a Tags governance rule and applying it to a tenancy, but the tenancy already has a tag namespace with the same name. For example, if you apply this kind of a rule to the parent tenancy, the template tag namespace prevents creation of another tag namespace with a matching name.
Syntax errors or mistakes in the quota policy statement still allow Quota policy governance rule creation, but such rules fail to attach to any of the tenancies.

Using the API

For information about using the API and signing requests, see REST API documentation and Security Credentials. For information about SDKs, see SDKs and the CLI.

Use the following in the Organizations API for organization management.

To manage subscriptions and subscription mapping:

To manage tenancies and the organization:

To manage child tenancy reactivation:

RestoreOrganizationTenancy

To move a child tenancy from one organization to another:

ApproveOrganizationTenancyForTransfer
Note

This API must be called as an administrator in the parent tenancy. Also see the related oci organizations organization-tenancy approve-organization-tenancy-for-transfer command for more information. The parent tenancy ID is passed as the compartmentId, and the child tenancy ID as the organizationTenancyId. For more information on tenancies and compartments, see Understanding Compartments.

To manage invitations:

To manage work requests:

To manage governance rules:

Cost Reporting Integration

You can use the Oracle billing and cost reporting features to centrally manage the cost and usage information across all tenancies in your organization.

After a tenancy has been created or joins your organization, you can filter or group by spending in your organization through the reporting options in Cost Analysis. As the parent tenancy, you can use Cost Analysis Overview to analyze your organization's spending by using:

The Tenant ID and Tenant Name grouping dimensions.
The Subscription ID grouping dimensions to filter by a specific subscription and find which subscription a tenancy's usage was attributed against. As a result, you can view the cost and usage associated solely with a particular subscription. See Viewing Subscription Details and Costs for more information on viewing costs in an organization.

Child tenancies can also group by Tenant ID, Tenant Name, and Subscription ID, but the costs shown are only for the child tenancy (in contrast to a parent tenancy that can see its costs, plus the child tenancy costs).

You can also view granular cost and usage information using cost and usage reports, where you can get hourly level information to gain insights on your spending.

All spending against the subscription (in the parent and all child tenancies) is included in cost reporting in the parent tenancy, and child tenancies are limited to seeing spending in their own tenancy. Cost and usage reports are generated only in the parent tenancy, and include all usage for the parent and all its children. Both parent and child tenancies can create budgets. Parent tenancies can create budgets both for themselves and child tenancies, while child tenancies can only create budgets for themselves.

Important

A tenancy that has had its subscription reassigned will have data split across two subscriptions going forward (that is, before and after being reassigned). In Cost Analysis and Cost and usage reports, the data corresponds to a particular time, and impacts query filtering and grouping choices. For example, if "tenancy1" was reporting data to "subscription1" until October 15, and "subscription2" from October 16, then you must look at "subscription1" for consumption until October 15, and "subscription2" after October 15.

Note

Also see Viewing Billing Details for more information on billing details that can be viewed on the Console home page.

The following table describes the impact of Organization Management on cost reporting, in terms of all Oracle Cloud Infrastructure Billing and Cost Management features.


	Parent Tenancy	Child Tenancies
Cost Analysis Overview	Reports on all usage and cost in the parent, and all child tenancies with the ability to group by tenancy or subscription ID. Parent tenancies can also view the subscription details for the parent and all child tenancies.	Reports on all usage and cost in the child tenancy. Child tenancies can't view subscription details within Cost Analysis (they can only be viewed from the parent tenancy perspective). Note: If a child tenancy wants to use Cost Analysis from the Console, you must subscribe to the parent tenancy's home region.
Cost and usage reports (CSVs)	Includes all usage and costs in the parent and all child tenancies.	Not available.
Budgets	Budgets can be created against child tenancies, compartments, and tags in the primary tenancy.	Budgets can be created against compartments, or tags within the child tenancy.
Cloud Advisor	Recommendations can be viewed by the parent across all child tenancies. The parent can view the recommendation, but can't implement the recommendation.	Child tenancies can view their own recommendations.

Support

Depending on how you created your tenancy, you have separate CSI (Customer Support Identifier) numbers, and support accounts for each tenancy. Created child tenancies inherit the parent subscription CSI.

To ensure that you get unique CSIs per tenancy, work with your account team to create tenancies in a way that creates new CSIs.

Oracle Cloud Infrastructure Documentation