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 policy  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
  1. Open the Console, click Identity, and then click Dynamic Groups. A list of the dynamic groups in your tenancy is displayed.
  2. Click Create Dynamic Group.
  3. Enter the following:
    • Name: A unique name for the group. The name must be unique across all groups in your tenancy (dynamic groups and user groups). You can't change this later.
    • Description: A friendly description. You can't change this in the Console, but you can change it Using the API.
  4. Enter the Matching Rules. Resources that meet the rule criteria are members of the group.
    • Rule 1: Enter a rule following the guidelines in Writing Matching Rules to Define Dynamic Groups. You can manually enter the rule in the text box or launch the rule builder.
    • Enter additional rules as needed. To add a rule, click +Additional Rule.

  5. Optionally, you can apply tags. If you have permissions to create a resource, you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure if you should apply tags, skip this option (you can apply tags later) or ask your administrator.
  6. Click Create Dynamic Group.

    The matching rule syntax is verified, but the OCIDs are not. Be sure that the OCIDs you enter are correct.

Next, to give the dynamic group permissions, you need to write a policy. See Writing Policies for Dynamic Groups.

To delete a dynamic group
  1. Open the Console, click Identity, and then click Dynamic Groups. A list of the dynamic groups in your tenancy is displayed.
  2. Locate the dynamic group in the list.
  3. For the dynamic group you want to delete, click Delete.
  4. Confirm when prompted.
To update a dynamic group's description

This is available only through the API. If you don't have access to the API and need to update a dynamic group's description, contact Oracle Support.

To update a dynamic group's matching rules
  1. Open the Console, click Identity, and then click Dynamic Groups. A list of the dynamic groups in your tenancy is displayed.
  2. Click the dynamic group you want to update. The dynamic group's details are displayed.
  3. Click Edit All Matching Rules.
  4. Edit the matching rule in the text box; or, you can use the rule builder if the change is supported by the rule builder.

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

Here are some examples:

Include All Instances in a Specific Compartment in the Dynamic Group

To include all instances that are in a specific compartment, add a rule with the following syntax:

instance.compartment.id = '<compartment_ocid>'

You can add that rule either directly in the text box, or you can use the rule builder.

Example entry in text box:

instance.compartment.id = 'ocidv1:compartment:oc1:phx:samplecompartmentocid6q6igvfauxmima74jv'

All instances that currently exist or get created in the compartment (identified by the OCID) are members of this group.

Include All Instances in Any of Two or More Compartments

To include all instances that reside in any of two (or more) compartments, add a rule with the following syntax:

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

You can add that rule either directly in the text box, or you can use the rule builder.

Example entry in the text box:

Any {instance.compartment.id = 'ocidv1:compartment:oc1:phx:samplecompartmentocid6q6igvfauxmima74jv', instance.compartment.id = 'ocidv1:compartment:oc1:phx:samplecompartmentocidythksk89ekslsoelu2'}

Instances that currently exist or get created in either of the specified compartments are members of this group.

Include All Instances Tagged with a Specific Namespace and Tag Key

To include all instances that are tagged with a specific tag namespace and tag key, add a rule with the following syntax:

tag.<tagnamespace>.<tagkey>.value

All instances assigned the tagnamespace.tagkey combination are included. Note that the tag value is not evaluated, so all values are included.

Example: Assume you have a tag namespace called department and a tag key called operations. You want to include all instances that are tagged with the namespace and tag key.

Enter the following rule in the text box:

tag.department.operations.value

All instances that currently exist or get created with the tag namespace and tag key department.operations are members of this group.

Include All Instances In a Specific Compartment with a Specific Tag Namespace, Tag Key, and Tag Value

To include all instances in a specific compartment that are tagged with a specific tag namespace, key, and value, add a rule with the following syntax:

All {instance.compartment.id = '<compartment_ocid>', tag.<tagnamespace>.<tagkey>.value='<tagvalue>'}

All instances that are in the identified compartment and that are assigned the tagnamespace.tagkey with the specified tag value are included.

Example: Assume you have a tag namespace called department and a tag key called operations. You want to include all instances that are tagged with the value 45, that are in a particular compartment.

Enter the following statement in the text box:

All {instance.compartment.id='ocidv1:compartment:oc1:phx:oc1:phx:samplecompartmentocid6q6igvfauxmima74jv,',
tag.department.operations.value='45'}
Include Instances in a Specific Compartment Except Those with a Specific Tag

To include all instances in a specific compartment EXCEPT those that are tagged with a specific tag namespace, key, and value, add a rule with the following syntax:

All {instance.compartment.id = '<compartment_ocid>', tag.<tagnamespace>.<tagkey>.value!= '<tagvalue>'}

Example: Assume you have a tag namespace called department and a tag key called operations. You want to include all instances in a specific compartment, except those that are tagged with the value 45.

Enter the following statement in the text box:

All {instance.compartment.id='ocidv1:compartment:oc1:phx:oc1:phx:samplecompartmentocid6q6igvfauxmima74jv,',
tag.department.operations.value!='45'}

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

To include all instances that are in a specific compartment, using the rule builder:

  • Select ALL.
  • Attribute: Select in Compartment ID.
  • Value: Enter ocidv1:compartment:oc1:yourcompartmentocid

All instances that currently exist or get created in the compartment (identified by the OCID) are members of this group.

Include All Instances in Any of Two or More Compartments

To include all instances that reside in any of two (or more) compartments using the rule builder:

  1. Select ANY.
  2. Enter:
    • Attribute: Select in Compartment ID.
    • Value: Enter ocidv1:compartment:oc1:phx:samplecompartmentocid6q6igvfauxmima74jv
  3. Click +Additional Line. Enter the following on the second line:
    • Attribute: Select in Compartment ID.
    • Value: Enter ocidv1:compartment:oc1:phx:samplecompartmentocidythksk89ekslsoelu2
  4. Continue adding additional lines as needed for each compartment you want to include.

Instances that currently exist or get created in any of the specified compartments are members of this group.