Oracle Cloud Infrastructure Documentation

Organization Management Overview

This topic describes how you can use Organization Management to manage tenancies and view subscription mappings in your organization. With Organization Management, you can add tenancies to your organization, and have those tenancies consume from your primary funded subscription. This allows you to create an isolated tenancy to build your workloads, without needing to book a new order.

Two types of tenancies are involved when mapping and using a subscription in the Organization Management:
  • The parent tenancy (the one that is associated with the primary funded subscription).
  • Child tenancies (tenancies that are consuming from a subscription that is not their own). Child tenancies can be created as entirely new tenancies, or, existing tenancies can be invited to join with the parent tenancy to become part of the same organization.
Note

Parent subscribed regions should be a superset of child subscribed regions.

Notable benefits of sharing a subscription include:

  • Sharing a single commitment helps avoid cost overages, and allows consolidating your billing.
  • Enabling multi-tenancy cost management. You can analyze, report, and monitor across all linked tenancies. The parent tenancy can analyze and report across each of your tenancies through Cost Analysis and Cost and usage reports, and you can receive alerts through Budgets.
  • Isolation of data. Customers with strict data isolation requirements can use a multi-tenancy strategy to continue restricting resources across their tenancies.

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

Planning Considerations

Before you get additional tenancies you should evaluate your needs to make sure that a multi-tenancy approach is best for your workloads. The main reason to have multiple tenancies is for strong isolation. 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).
  • Its own service limits.
  • Isolated Virtual Cloud Networks (VCNs).
  • Separate security and governance settings.

The main point to be aware of is that multiple tenancies make it easier to isolate workloads, but that comes at the cost of needing to manage multiple tenancies. Additional tenancies, however, do create additional management overhead, so you need to ensure that the isolation is worth it. If you don't require a strong level of isolation, you should consider using compartments to separate workloads.

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 other linked child tenancies in your organization. The newly created child tenancy consumes from your 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.

To create a child tenancy, you provide the necessary information, and then sign-in instructions are provided 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.

  1. Open the navigation menu and click Governance & Administration. Under Organization Management, click Tenancies.
  2. Click Add Tenancy. The Add Tenancy panel is displayed. Ensure Create New Child Tenancy is selected.
  3. In Tenancy Name, enter a name for the new child tenancy. The tenancy name must be unique and all lowercase without any special characters. Avoid entering confidential information.
  4. From Home Region, select a region from the list. The home region can only be a subset of the parent’s subscribed regions.
  5. In Administrator Email, enter the email address of the tenancy administrator.
  6. Click Add 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 will receive instructions to sign in. Use the temporary password provided to sign in to the tenancy the first time. You will be required to change the password.

Note

When a child tenancy is created, the tenancy is not automatically federated to Oracle Identity Cloud Service. For more information, see Federating with Oracle Identity Cloud Service. Use the following URL to access My Oracle Services: https://myservices-<account name>.console.oraclecloud.com/mycloud/cloudportal/gettingStarted.

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 Tenancy 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, in order to accept the invitation. For more information, see Required IAM Policy.

An invited tenancy (also referred to as the recipient tenancy) automatically consumes from the default subscription in the organization, so all usage will be charged against the default subscription's rate card. If you do not want the invited, recipient tenancy to consume from the default subscription, you can remap the subscription back to the original Pay As You Go subscription after the invited tenancy has joined the organization.

To invite a tenancy:

  1. Sign in to the (sender) tenancy that will send the invitation, as a user that has permissions to manage subscription sharing.
  2. Open the navigation menu and click Governance & Administration. Under Organization Management, click Tenancies.
  3. Click Add Tenancy. The Add Tenancy panel is displayed. Ensure Invite Existing Tenancy is selected.
  4. 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 attempt. Such a convention allows the invitations to be more readable to the Console user, without having to access the Invitation Detail page to view sender and recipient details. See Viewing Invitations for more information.
  5. In Recipient Tenancy OCID, enter the recipient's OCID. You can find the OCID on the Tenancy Details page.
  6. In Recipient Email, enter 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.
  7. Click Show Advanced Options and enter any tagging details. See Resource Tags for more information.
  8. Click Add Tenancy. The invitation is sent to the tenancy you are inviting to add to your organization and share the subscription with. A notification is displayed that you’ve successfully requested to invite a tenancy to join the organization. If the request completes successfully, then the recipient tenancy will receive an invitation to accept.
    Note

    Parent tenancies and tenancies that are not already in a sharing relationship can send invitations. Child tenancies cannot 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. If you want to stop sharing your subscription with the recipient tenancy after the invitation has been accepted, your technical contacts can access live telephone support using the phone numbers and contact information on Oracle’s support website at https://www.oracle.com/support/contact.html.

  9. On the recipient (child) tenancy: Open the navigation menu and click Governance & Administration. Under Organization Management, click Invitations. The Invitations page is displayed.
  10. The invitation from the other tenancy is displayed in the list, with the following information:
    • Invitation Name: Click this linked name to go to the Invitation Detail page.
    • Status: Displays the invitation status. For example, the status is Active when the invitation is received but not yet accepted. From the parent tenancy, 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 or Received.
    • Created: The UTC creation date and time of the invitation.
  11. Click the Actions menu and select Accept Invitation. A confirmation acceptance message is displayed, which indicates that you are about to accept an invitation from 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.

    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. Going forward, however, all usage in the child tenancy will be metered against the parent tenancy's subscription. In addition, after linking tenancies, it is recommended that you wait for a few hours before launching 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, it cannot invite another tenancy to become a child tenancy.
  12. Open the child tenancy's Tenancies page, you cannot view any tenancy details, since the page is only available for a parent tenancy that belongs to an organization. A message is displayed to indicate this status. The Subscription Mapping page is also not available for the child tenancy that just joined the parent tenancy's organization.
    Note

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

    Meanwhile on the parent tenancy's Tenancies page, you can view the linking between the child 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: Displays the invitation status.
    • Join Date: 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 tenancy.

To view invitations:

  1. Open the navigation menu and click Governance & Administration. Under Organization Management, click Invitations. The Invitations page is displayed.
  2. Click the linked invitation name from the Invitation Name field, or click the Actions menu and select View Invitation Details. The Invitation Detail page is displayed.
  3. This page displays the invitation status, along with the following details on the Invitation Information tab:
    • Sent from Tenancy OCID
    • Type (whether a sent or received invitation)
    • Last Status Change
    • Sent to Tenancy OCID
    • Sent Date

    You can also click Add Tags to add tagging information, and view it 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:

  1. Sign in to the primary (parent) tenancy as a user that has permissions to manage invitations and subscription sharing.
  2. As the parent tenancy, open the navigation menu and click Governance & Administration. Under Organization Management, click Invitations. The Invitations page is displayed.
  3. For the invitation you want to revoke, click the Actions menu and select Revoke Invitation. A Revoke Invitation confirmation is displayed. To cancel the invitation, click Revoke.
  4. On the Invitations page, the invitation's Status changes to Canceled.

Subscription Mapping

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

Tenancies mapped to a subscription will consume from the subscription’s credits (for Universal Credits Commitment subscriptions) and will use its rate card. By remapping your 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 subscriptions contract.

To map subscriptions:

  1. Open the navigation menu and click Governance & Administration. Under Organization Management, click Subscription Mapping. The Subscription Mapping page is displayed.
  2. Click the subscription name from the Subscription ID field. The Subscription Mapping Detail page is displayed.

    This 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
  3. 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 will stop consuming from the previously mapped subscription.
  4. In the Map subscription panel, make your selections and click Map subscription.

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 the following operations in the Organizations API for organization management:

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 to hone in on your organization's spending by using:

  • The Tenant ID and Tenant Name grouping dimensions; and
  • The Subscription ID grouping dimension to filter by a specific subscription and determine 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.
Note

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 of its children. Budgets are only supported in the parent tenancy.

Note

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 is snapshot in 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 have to look at "subscription1" for consumption until October 15, and "subscription2" after October 15.

The following table describes the impact of Organization Management on cost reporting.

Parent Tenancy Child Tenancies
Cost Analysis Reports on all usage and cost in the parent, and all children 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 cannot 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 children. Not available.
Budgets Budgets can be created against compartments or tags in the primary tenancy but not against child tenancies. Not supported.

Support

Depending on how you created your tenancy, you either have:
  • Separate CSI (Customer Support Identifier) numbers, and support accounts for each tenancy.
  • Or, a combination of both.
If you want to ensure that you get multiple CSI numbers, work with your account team to create tenancies in a way that creates new CSIs.