Oracle Cloud Infrastructure Documentation

Manually Creating OS Management Hub Policies

For OS Management Hub, you must identify which resources the service can manage and which users can manage those resources.

To enable OS Management Hub, define the following:

Important

To enable the Resource Discovery and Monitoring feature, you must configure policies in addition to those outlined in the following sections. See Getting Started with Resource Discovery and Monitoring.

You can configure IAM policies in various ways. The following sections outline how to set the IAM policy statements for a group of OS Management Hub administrators by using a dynamic group of resources. See Example Policies for additional non-administrator use cases.

Tip

Instead of manually creating groups and policy statements, use the policy advisor to quickly enable OS Management Hub for a compartment.

User Group

Create a user group (such as osmh-admins) or identify an existing user group to administer the OS Management Hub service in the tenancy. The required policy statements then grant this administrator user group the ability to manage OS Management Hub resources.

If you need to further restrict access, you can create additional user groups and set more restrictive policy statements to limit access to specific resources. See Example Policies for non-administrator use cases. For more information about user groups, see Managing Groups.

Dynamic Group

Create a dynamic group (such as osmh-instances) to specify the resources OS Management Hub will manage by defining rule statements for OCI and on-premises or third-party cloud instances (non-OCI).

Ensure you understand the following:

What does the dynamic group do?

The dynamic group identifies the instances that OS Management Hub will manage. You add rule statements for the compartments and subcompartments that contain instances you want managed by the service. The dynamic group grows and shrinks dynamically based on these rule statements. As instances are provisioned or retired, the dynamic group changes accordingly. The required policy statements then grant OS Management Hub the ability to access the instances within the dynamic group.

For more information on dynamic groups, see Managing Dynamic Groups .

Why are there different statements for OCI and non-OCI?

Each instance type uses a different agent which corresponds to a different resource object.

  • OCI instances use the Oracle Cloud Agent (OCA) so the OCI statement specifies instance resources within a compartment.

  • On-premises and third-party cloud instances use Management Agent Cloud Service (MACS) so the non-OCI statement specifies managementagent resources within a compartment. Each Management Agent resource corresponds to a non-OCI instance. Therefore by including the Management Agent in the group, you're including the associated instance.

See also Understanding the Agent.

When to use ANY and ALL for a dynamic group?

Before writing dynamic group rule statements, it's important to understand the difference between ANY and ALL.

When defining a dynamic group, you set how the group matches the rules defined within the group:

  • Match any rules defined below includes resources that match any of the rules within the dynamic group. Select this if defining a group that includes rules for multiple compartments or multiple instance types (such as OCI and non-OCI instances). This setting tells the group to include resources that match rule 1 OR rule 2 OR rule 3, and so on.
  • Match all rules defined below includes resources that match all the rules within the dynamic group. Select this when defining a vary narrow dynamic group that includes only one compartment. This setting tells the group to include resources that match rule 1 AND rule 2 AND rule 3, and so on.

When defining individual rule statements within the dynamic group, you set the conditions for each statement:

  • All of the following (ALL) includes only resources that match all the conditions in the rule. ALL statements requires each condition to be true. Otherwise, resources aren't included for the rule.

  • Any of the following (ANY) includes resources that match any of the conditions in the rule.

Examples of ANY and ALL for an individual rule statement

Consider the rule used for non-OCI instances.

Correct usage:
ALL {resource.type='managementagent', resource.compartment.id='<compartment_ocid>'}

When using ALL, the rule includes only Management Agent resources in the specified compartment. The statement tells the dynamic group to include resources that match the management agent type AND are within the specified compartment.

Incorrect usage. Do not use:
ANY {resource.type='managementagent', resource.compartment.id='<compartment_ocid>'}

When using ANY, the rule includes every Management Agent resource in the entire tenancy and every OCI resource present in the specified compartment. While the statement will include the resources needed for OS Management Hub, it's very broad and typically not preferable.

Consider the rule used for OCI instances when specifying multiple compartments.

Correct usage:
ANY {instance.compartment.id='<compartment_ocid>',instance.compartment.id='<subcompartment_ocid>'}

When using ANY, the rule includes every instance in each of the specified compartments. The statement tells the dynamic group to include instances in <compartment_ocid> OR <subcompartment_ocid>.

Incorrect usage. Do not use:
ALL {instance.compartment.id='<compartment_ocid>',instance.compartment.id='<subcompartment_ocid>'}

When using ALL, the rule tells the dynamic group to include instances that are in <compartment_ocid> AND <subcompartment_ocid>. This rule won't include any instances because it's impossible for an instance to be in more than one compartment at the same time. Don't use ALL with a rule statement that specifies multiple compartments.

Creating the dynamic group

  1. Follow the steps to create a dynamic group or update an existing dynamic group and configure the matching rules as follows.

    Tip

    Reuse the same dynamic group wherever possible across services instead of creating new dynamic groups because a single resource can only belong to a maximum of five dynamic groups.

  2. For the overall matching rule setting select: Match any rules defined below.

  3. Create rule statements for the instances that OS Management Hub will manage.

    Important

    Dynamic group rules don't use compartment inheritance. You must specify a rule statement for every compartment and subcompartment that contains instances you want managed by the service.

    Rule for OCI instances

    Add a rule statement that includes each compartment (and subcompartment) that will contain instances.

    ANY {instance.compartment.id='<compartment_ocid>',instance.compartment.id='<subcompartment_ocid>'}

    This rule will include all OCI instances in the specified compartments.

    Rule for non-OCI instances

    Add a separate rule statement for each compartment (and subcompartment) that will contain a Management Agent used by an instance.

    ALL {resource.type='managementagent', resource.compartment.id='<compartment_ocid>'}
ALL {resource.type='managementagent', resource.compartment.id='<subcompartment_ocid>'}

    Each rule statement will include every Management Agent resource in the specified compartment. Each non-OCI instance has a corresponding agent resource and therefore the statement will include the non-OCI instances in the compartment.

  4. Click Create (if creating) or Save (if updating).

Policy Statements

Create a policy (such as osmh-policies) with statements that allow instances to register with OS Management Hub and users to manage and operate the service.

Important

Policy statements use the default identity domain unless you define the identity domain before the group or dynamic group name (for example, <identity_domain_name>/<dynamic_group_name>). For more information, see Policy Syntax.
Prerequisites

Before creating the policy, ensure you have the following:

Using the Policy Builder

The policy builder provides templates for common policies used for OS Management Hub. Select a use case and then fill in the required information such as dynamic group or compartment to complete the policy statements. See Writing Policy Statements with the Policy Builder.

  1. Follow the steps in Creating a Policy, noting the following exceptions.
  2. For Policy use cases, select OS Management Hub.
  3. For Common policy templates, select one of the OS Management Hub common policies.

Common Policy Templates

The policy builder provides the following OS Management Hub common policy templates.

Let OS Management Hub manage instances in the dynamic group

Type of access: Allows the service agent on the managed instances to interact with OS Management Hub.

Where to create the policy: In the root compartment.

Policy statements: Replace <osmh-instances> with the dynamic group name.

Allow dynamic-group <osmh-instances> to {OSMH_MANAGED_INSTANCE_ACCESS} in tenancy where request.principal.id = target.managed-instance.id
Let users manage OS Management Hub resources in the tenancy

Type of access: Allows the admin user group with tenancy access to:

  • Manage all OS Management Hub resources in the tenancy.
  • Create, update, and delete Management Agents and install keys in the tenancy.

Where to create the policy: In the root compartment.

Policy statements: Replace <osmh-admins> with the user group name.

Allow group <osmh-admins> to manage osmh-family in tenancy
Allow group <osmh-admins> to manage management-agents in tenancy
Allow group <osmh-admins> to manage management-agent-install-keys in tenancy
Let users manage OS Management Hub resources in a compartment

Type of access: Allows the admin user group with compartment access to:

  • Manage all OS Management Hub resources in a compartment.
  • Read profiles and software sources in the root compartment. This is required to replicate vendor software sources and use service-provided profiles.
  • Create, update, and delete Management Agents and install keys in a compartment.

Where to create the policy: The easiest approach is to put this policy in the root compartment. If you want the users of the individual compartment to have control over the individual policy statements for their compartment, see Policy Attachment.

Policy statements: Replace <osmh-admins> with the user group name and <compartment> with the compartment name. Use the manual editor to replace <tenancy-ocid> with your tenancy OCID.

Allow group <osmh-admins> to read osmh-profiles in tenancy where target.profile.compartment.id = '<tenancy-ocid>'
Allow group <osmh-admins> to read osmh-software-sources in tenancy where target.softwareSource.compartment.id = '<tenancy-ocid>'
Allow group <osmh-admins> to manage osmh-family in compartment <compartment> 
Allow group <osmh-admins> to manage management-agents in compartment <compartment>
Allow group <osmh-admins> to manage management-agent-install-keys in compartment <compartment>
Let users read OS Management Hub resources in the tenancy

Type of access: Allows the operator user group to read all OS Management Hub resources in the tenancy.

Where to create the policy: In the root compartment.

Policy statements: Replace <osmh-operators> with the user group name.

Allow group <osmh-operators> to read osmh-family in tenancy
Let users read OS Management Hub resources in a compartment

Type of access: Allows the operator user group to read all OS Management Hub resources in a compartment.

Where to create the policy: The easiest approach is to put this policy in the root compartment. If you want the users of the individual compartment to have control over the individual policy statements for their compartment, see Policy Attachment.

Policy statements: Replace <osmh-operators> with the user group name and <compartment> with the compartment name.

Allow group <osmh-operators> to read osmh-family in compartment <compartment>

Manually Defining the Policy Statements

If not using the policy builder, you can manually define the policy statements. Create a new policy or modify an existing policy to include the following policy statements.

The following policy statements provide an example of how to provide administrators access to the service. For other use cases, see Example Policies.

Tenancy-level policy statements

To apply the required IAM policy at the tenancy level, use the following policy statements:

allow dynamic-group <osmh-instances> to {OSMH_MANAGED_INSTANCE_ACCESS} in tenancy where request.principal.id = target.managed-instance.id
allow group <osmh-admins> to manage osmh-family in tenancy

Include the following additional statements if managing on-premises or third-party cloud instances. These aren't required if managing only OCI instances.

allow group <osmh-admins> to manage management-agents in tenancy
allow group <osmh-admins> to manage management-agent-install-keys in tenancy
Compartment-level policy statements (if not using tenancy-level)

If the tenancy administrator doesn't permit setting IAM policies at the tenancy level, you can restrict the use of OS Management Hub resources to a compartment and its subcompartments (policies use compartment inheritance). To allow users to replicate vendor software sources and use service-provided profiles, the user group requires read access to profiles and software sources in the root compartment.

To apply the IAM policy to a compartment inside the tenancy, use the following policy statements:

allow dynamic-group <osmh-instances> to {OSMH_MANAGED_INSTANCE_ACCESS} in compartment <compartment_name> where request.principal.id = target.managed-instance.id
allow group <osmh-admins> to manage osmh-family in compartment <compartment_name>
allow group <osmh-admins> to read osmh-profiles in tenancy where target.profile.compartment.id = '<tenancy_ocid>'
allow group <osmh-admins> to read osmh-software-sources in tenancy where target.softwareSource.compartment.id = '<tenancy_ocid>'

Include the following additional statements if managing on-premises or third-party cloud instances. These aren't required if managing only OCI instances.

allow group <osmh-admins> to manage management-agents in compartment <compartment_name>
allow group <osmh-admins> to manage management-agent-install-keys in compartment <compartment_name>