Oracle Cloud Infrastructure Documentation

Managing Dynamic Groups

This topic describes how to manage dynamic groups and define the rules to determine a dynamic group's members.

About Dynamic Groups

Dynamic groups allow you to group Oracle Cloud Infrastructure computer instances as "principal" actors (similar to user groups). You can then create policies to permit instances to make API calls against Oracle Cloud Infrastructure services. When you create a dynamic group, rather than adding members explicitly to the group, you instead define a set of matching rules to define the group members. For example, a rule could specify that all instances in a particular compartment are members of the dynamic group. The members can change dynamically as instances are launched and terminated in that compartment.

Required IAM Policy

If you're in the Administrators group, then you have the required access for managing dynamic groups.

If you're new to policies, see Getting Started with Policies and Common Policies. If you want to dig deeper into writing policies for dynamic groups or other IAM components, see Details for IAM.

Tagging Resources

You can apply tags to your resources to help you organize them according to your business needs. You can apply tags at the time you create a resource, or you can update the resource later with the desired tags. For general information about applying tags, see Resource Tags.

Working with Dynamic Groups

When creating a dynamic group, you must provide a unique, unchangeable name for the dynamic group. The name must be unique across all groups within your tenancy. You must also provide the dynamic group with a description (although it can be an empty string), which is a non-unique, changeable description for the group. Oracle will also assign the group a unique ID called an Oracle Cloud ID (OCID). For more information, see Resource Identifiers.

Note

If you delete a dynamic group and then create a new dynamic group with the same name, they'll be considered different groups because they'll have different OCIDs.

A dynamic group has no permissions until you write at least one An IAM document that specifies who has what type of access to your resources. It is used in different ways: to mean an individual statement written in the policy language; to mean a collection of statements in a single, named "policy" document (which has an Oracle Cloud ID (OCID) assigned to it); and to mean the overall body of policies your organization uses to control access to resources. that gives that dynamic group permission to either the tenancy or a compartment. When writing the policy, you can specify the dynamic group by using either the unique name or the dynamic group's OCID. Per the preceding note, even if you specify the dynamic group name in the policy, IAM internally uses the OCID to determine the dynamic group. For information about writing policies, see Managing Policies.

You can delete a dynamic group, but only if the group is empty.

Updating Dynamic Groups

You can update the matching rules that define the members of a dynamic group. For example, you might change a matching rule that includes all instances in a compartment to exclude a particular instance. Or, you might update a rule to include a new tag value.

Important

When you make a change to a matching rule you must allow about one hour for the updated policy to take effect. For example, if you update tags on an instance to either include or exclude that instance from a dynamic group, you must wait for that policy to take effect to include or exclude the instance.

Limits on Instances in Dynamic Groups

A single compute instance can belong to a maximum of 5 dynamic groups.

Using the Console

Warning

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

To create a dynamic group
To delete a dynamic group
To update a dynamic group's description
To update a dynamic group's matching rules

Writing Matching Rules to Define Dynamic Groups

Matching rules define the resources that belong to the dynamic group. In the Console, you can either enter the rule manually in the provided text box, or you can use the rule builder. The rule builder lets you make selections and entries in a dialog, then writes the rule for you, based on your entries.

You can define the members of the dynamic group based on the following:

  • compartment ID - include (or exclude) the instances that reside in that compartment based on compartment OCID
  • instance ID - include (or exclude) an instance based on its instance OCID
  • tag namespace and tag key - include (or exclude) instances tagged with a specific tag namespace and tag key. All tag values are included. For example, include all instances tagged the with tag namespace department and the tag key operations.
  • tag namespace, tag key, and tag value - include (or exclude) instances tagged with a specific value for the tag namespace and tag key. For example include all instances tagged with the tag namespace department and the tag key operations and with the value '45'.

A matching rule has the following syntax:

For a single condition:

variable =|!= 'value'

For multiple conditions:

any|all {<condition>,<condition>,...}

Supported variables are:

  • instance.compartment.id - the OCID of the compartment where the instance resides

  • instance.id - the OCID of the instance

  • tag.<tagnamespace>.<tagkey>.value - the tag namespace and tag key. For example, tag.operations.department.value.

  • tag.<tagnamespace>.<tagkey>.value='<tagvalue>' - the tag namespace, tag key, and tag value. For example, tag.operations.department.value='45'

Here are some examples:

Include All Instances in a Specific Compartment in the Dynamic Group
Include All Instances in Any of Two or More Compartments
Include All Instances Tagged with a Specific Namespace and Tag Key
Include All Instances In a Specific Compartment with a Specific Tag Namespace, Tag Key, and Tag Value
Include Instances in a Specific Compartment Except Those with a Specific Tag

Using the Rule Builder

The rule builder is a tool available from the Console to help you write matching rules. The rule builder provides menus and text boxes for you to make entries and then writes the rule for you. The rule builder does have some limitations, so you can't use it for all cases.

Limitations of the Rule Builder

The rule builder does not support the following:

  • Exclusion rules - the rule builder lets you select compartment IDs and instance IDs to include only.
  • Rules based on tags - the rule builder does not allow you to select tags to include in your rule. To add a rule based on tag values, you need to enter the rule in the Rule text box using the syntax above.

Launching the Rule Builder

When you click Create Dynamic Group, the Rule Builder is displayed in the Create Dynamic Group dialog.

To create a matching rule using the rule builder

  1. Select Any or All from the menu.

    Any includes instances that match any of the statements in the rule.

    All includes only instances that match all of the statements in the rule.

  2. Select the Attribute type for the statement and enter the value:

    in Compartment ID includes instances in the compartment you specify.

    with Instance ID includes instances with the OCID you specify.

  3. Click +Additional line to add more statements to this rule.

    When you add multiple statements to a rule, remember that Any includes instances that match any of the statements. If you choose All, instances must match all of the specifications in the statements to be included in the group.

Examples Using the Rule Builder

Include All Instances in a Specific Compartment in the Dynamic Group
Include All Instances in Any of Two or More Compartments

Using the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use these API operations to manage dynamic groups: