Creating and Managing Dynamic Groups

Dynamic groups are groups of compute instances that meet the criteria defined for the group. The membership of the group changes as instances newly satisfy the criteria or no longer satisfy the criteria. For example, if the members of a dynamic group are defined to be all instances in a specified compartment, the group membership changes when instances are created in or removed from that compartment.

Policies permit applications that are running on instances that are members of dynamic groups to make API calls to perform actions on service resources. Instances authenticate by using certificates that are assigned to each member instance.

Creating a Dynamic Group

When you create a dynamic group, the group is automatically created in the tenancy. You cannot specify a different compartment for the dynamic group.

Using the Compute Web UI

1. In the navigation menu, click Identity, and then click Dynamic Groups.

2. Click the Create Dynamic Group button.

3. In the Create Dynamic Group dialog, enter the following information:

   • Name: A name for this dynamic group. Names have the following characteristics:

     • Must be unique within the tenancy. You can create a dynamic group with the same name as a dynamic group that has been deleted.

     • Are case insensitive.

     • Cannot be changed later.

     • Can be no more than 100 characters.

     • Can contain only alphanumeric characters, period (.), hyphen (-), and underscore (_).

   • Description: A description for this dynamic group. The description has the following characteristics:

     • Must be 1-400 characters.

     • Does not need to be unique.

     • Can be changed later.

   • Matching rules: Select either "Match any rules defined below" or "Match all rules defined below."

     Matching Rule1: Enter a matching rule. See Writing Matching Rules for information about how to define a matching rule.

     Click the + Another Matching Rule button to add another matching rule.

   • Tagging: (Optional) Add defined or free-form tags for this group as described in Adding Tags at Resource Creation. Tags can also be applied later.

4. Click the Create Dynamic Group button on the dialog.

   The details page of the new dynamic group is displayed.

5. Create access policies for this dynamic group or add this dynamic group to existing policies. The member instances have no permissions unless the group is the subject of at least one policy. See Managing Policies.

Using the OCI CLI

1. Get the following information:

   • A name and description for the group. See the Compute Web UI procedure for limitations. In the OCI CLI, a description must be provided but its value can be an empty string.

   • OCID of the tenancy. On your user menu, click the Tenancy option.

2. Create a matching rule to specify conditions for membership in the group.

   The matching rule is a single text string. Multiple rules are comma separated, enclosed in braces, and preceded by the keyword any or all. See the syntax for a rule with multiple conditions in Writing Matching Rules.

3. Run the create dynamic group command.

   Syntax:

   oci iam dynamic-group create --name text --description "text" \
   --compartment-id tenancy_OCID --matching-rule text

   Example:

   $ oci iam dynamic-group create --name Project-A --description "Instances for Project A." \
   --compartment-id ocid1.tenancy.unique_ID \
   --matching-rule "instance.compartment.id = 'ocid1.compartment.unique_ID'"

   The output of this command is the same as the output of the dynamic-group get command.

4. Create an access policy for this dynamic group or add this dynamic group to an existing policy. The group has no permissions unless it is the subject of at least one policy. See Managing Policies.

Writing Matching Rules

A rule specifies one or more conditions for membership in the group. Type the rule into the text box. To add another rule, click the +Another Matching Rule button.

A rule with a single condition has the following syntax:

variable = | != value

A rule with multiple conditions has the following syntax:

any | all {variable =|!= value, variable =|!= value,...}

variable is one of the following:

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

• instance.id. The OCID of the instance.

• tag.tagnamespace.tagkey.value = tagvalue. The tagnamespace, tagkey, and tagvalue all must match to include this resource in the group.

• tag.tagnamespace.tagkey.value. Only the tagnamespace and tagkey must match to include this resource in the group. The value of the tag is not considered.

The following matching rule includes all instances in the specified compartment:

instance.compartment.id = 'ocid1.compartment.unique_ID'

The following matching rule includes all instances in the specified compartment except for the two instances specified with instance.id !=:

all {instance.compartment.id = 'ocid1.compartment.unique_ID',
 instance.id != 'ocid1.instance.unique_ID1', instance.id != 'ocid1.instance.unique_ID2'}

The following matching rule includes all instances that have a tag applied that has tag namespace Product1, key ProjectA, and value abc123:

tag.Product1.ProjectA.value = abc123

Updating a Dynamic Group

You can change the description and matching rules (members) for a dynamic group. You can add, change, or remove tags as described in Applying Tags to an Existing Resource.

Using the Compute Web UI

1. In the navigation menu, click Identity, and then click Dynamic Groups.

2. (Optional) Modify the description.

   1. In the dynamic groups list, for the dynamic group that you want to modify, click the Actions menu, and click the Edit option.

   2. In the Edit groupname dialog, modify the dynamic group's description or tags.

   3. Click Save Changes.

3. (Optional) Modify the matching rules.

   1. In the dynamic groups list, click the name of the dynamic group that you want to modify.

   2. On the details page, click the Edit All Matching Rules button.

   3. Edit the matching rule in the text box.

   4. Click Save Changes.

Using the OCI CLI

1. Get the OCID of the dynamic group that you want to modify: oci iam dynamic-group list

2. Run the update dynamic group command.

   Syntax:

   oci iam dynamic-group update --dynamic-group-id dynamic_group_OCID

   Example:

   $ oci iam dynamic-group update --dynamic-group-id ocid1.dynamicGroup.unique_ID \
   --matching-rule "instance.compartment.id = 'ocid1.compartment.unique_ID'"

   The output of this command is the same as the output of the dynamic-group get command.

Deleting a Dynamic Group

When you delete a dynamic group, the compute instances that had been members of the group no longer have the authorizations that they had through the policies applied to the dynamic group.

Using the Compute Web UI

1. In the navigation menu, click Identity, and then click Dynamic Groups.

2. For the dynamic group that you want to delete, click the Actions menu, and click the Delete option.

3. Confirm the deletion.

Using the OCI CLI

1. Get the OCID of the dynamic group that you want to modify: oci iam dynamic-group list

2. Run the delete dynamic group command.

   Syntax:

   oci iam dynamic-group delete --dynamic-group-id dynamic_group_OCID

   Example:

   $ oci iam dynamic-group delete --dynamic-group-id ocid1.dynamicGroup.unique_ID \
   --force