dynamic_groups

Creates, updates, deletes, gets or lists a dynamic_groups resource.

Overview

Name	`dynamic_groups`
Type	Resource
Id	`oci.identity.dynamic_groups`

Fields

The following fields are returned by SELECT queries:

get
list

The dynamic group was retrieved.

Name	Datatype	Description
`id`	`string`	The OCID of the group.
`name`	`string`	The name you assign to the group during creation. The name must be unique across all groups in the tenancy and cannot be changed.
`compartmentId`	`string`	The OCID of the tenancy containing the group.
`definedTags`	`object`	Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: `{"Operations": {"CostCenter": "42"}}`
`description`	`string`	The description you assign to the group. Does not have to be unique, and it's changeable. (For tenancies that support identity domains) You can have an empty description.
`freeformTags`	`object`	Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: `{"Department": "Finance"}`
`inactiveStatus`	`integer (int64)`	The detailed status of INACTIVE lifecycleState.
`lifecycleState`	`string`	The group's current state. After creating a group, make sure its `lifecycleState` changes from CREATING to ACTIVE before using it. (CREATING, ACTIVE, INACTIVE, DELETING, DELETED)
`matchingRule`	`string`	A rule string that defines which instance certificates will be matched. For syntax, see [Managing Dynamic Groups](/Content/Identity/dynamicgroups/managingdynamicgroups.htm).
`timeCreated`	`string (date-time)`	Date and time the group was created, in the format defined by RFC3339. Example: `2016-08-25T21:10:29.600Z`

A dynamic group defines a matching rule. Every bare metal or virtual machine instance is deployed with an instance certificate. The certificate contains metadata about the instance. This includes the instance OCID and the compartment OCID, along with a few other optional properties. When an API call is made using this instance certificate as the authenticator, the certificate can be matched to one or multiple dynamic groups. The instance can then get access to the API based on the permissions granted in policies written for the dynamic groups. This works like regular user/group membership. But in that case, the membership is a static relationship, whereas in a dynamic group, the membership of an instance certificate to a dynamic group is determined during runtime. For more information, see [Managing Dynamic Groups](/Content/Identity/dynamicgroups/managingdynamicgroups.htm). Warning: Oracle recommends that you avoid using any confidential information when you supply string values using the API.

Name	Datatype	Description
`id`	`string`	The OCID of the group.
`name`	`string`	The name you assign to the group during creation. The name must be unique across all groups in the tenancy and cannot be changed.
`compartmentId`	`string`	The OCID of the tenancy containing the group.
`definedTags`	`object`	Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: `{"Operations": {"CostCenter": "42"}}`
`description`	`string`	The description you assign to the group. Does not have to be unique, and it's changeable. (For tenancies that support identity domains) You can have an empty description.
`freeformTags`	`object`	Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: `{"Department": "Finance"}`
`inactiveStatus`	`integer (int64)`	The detailed status of INACTIVE lifecycleState.
`lifecycleState`	`string`	The group's current state. After creating a group, make sure its `lifecycleState` changes from CREATING to ACTIVE before using it. (CREATING, ACTIVE, INACTIVE, DELETING, DELETED)
`matchingRule`	`string`	A rule string that defines which instance certificates will be matched. For syntax, see [Managing Dynamic Groups](/Content/Identity/dynamicgroups/managingdynamicgroups.htm).
`timeCreated`	`string (date-time)`	Date and time the group was created, in the format defined by RFC3339. Example: `2016-08-25T21:10:29.600Z`

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get`	`select`	`dynamicGroupId`, `region`		Gets the specified dynamic group's information.<br />
`list`	`select`	`compartmentId`, `region`	`page`, `limit`, `name`, `sortBy`, `sortOrder`, `lifecycleState`	Lists the dynamic groups in your tenancy. You must specify your tenancy's OCID as the value for<br />the compartment ID (remember that the tenancy is simply the root compartment).<br />See [Where to Get the Tenancy's OCID and User's OCID](/Content/API/Concepts/apisigningkey.htm#five).<br />
`create`	`insert`	`region`, `name`, `compartmentId`, `matchingRule`, `description`	`opc-retry-token`	Creates a new dynamic group in your tenancy.<br /><br />You must specify your tenancy's OCID as the compartment ID in the request object (remember that the tenancy<br />is simply the root compartment). Notice that IAM resources (users, groups, compartments, and some policies)<br />reside within the tenancy itself, unlike cloud resources such as compute instances, which typically<br />reside within compartments inside the tenancy. For information about OCIDs, see<br />[Resource Identifiers](/Content/General/Concepts/identifiers.htm).<br /><br />You must also specify a name for the dynamic group, which must be unique across all dynamic groups in your<br />tenancy, and cannot be changed. Note that this name has to be also unique across all groups in your tenancy.<br />You can use this name or the OCID when writing policies that apply to the dynamic group. For more information<br />about policies, see [How Policies Work](/Content/Identity/policieshow/how-policies-work.htm).<br /><br />You must also specify a description for the dynamic group (although it can be an empty string). It does not<br />have to be unique, and you can change it anytime with [UpdateDynamicGroup](#/en/identity/20160918/DynamicGroup/UpdateDynamicGroup).<br /><br />After you send your request, the new object's `lifecycleState` will temporarily be CREATING. Before using the<br />object, first make sure its `lifecycleState` has changed to ACTIVE.<br />
`update`	`update`	`dynamicGroupId`, `region`	`if-match`	Updates the specified dynamic group.
`delete`	`delete`	`dynamicGroupId`, `region`	`if-match`	Deletes the specified dynamic group.<br />

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
`compartmentId`	`string`	The OCID of the compartment (remember that the tenancy is simply the root compartment).
`dynamicGroupId`	`string`	The OCID of the dynamic group.
`region`	`string`	OCI region identifier (e.g. us-ashburn-1, ap-sydney-1); resolves from OCI_REGION when not supplied in the query. (default: us-ashburn-1, x-stackQL-envVar: OCI_REGION)
`if-match`	`string`	For optimistic concurrency control. In the PUT or DELETE call for a resource, set the `if-match` parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value.
`lifecycleState`	`string`	A filter to only return resources that match the given lifecycle state. The state value is case-insensitive.
`limit`	`integer`	The maximum number of items to return in a paginated "List" call.
`name`	`string`	A filter to only return resources that match the given name exactly.
`opc-retry-token`	`string`	A token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (e.g., if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected).
`page`	`string`	The value of the `opc-next-page` response header from the previous "List" call.
`sortBy`	`string`	The field to sort by. You can provide one sort order (`sortOrder`). Default order for TIMECREATED is descending. Default order for NAME is ascending. The NAME sort order is case sensitive. Note: In general, some "List" operations (for example, `ListInstances`) let you optionally filter by Availability Domain if the scope of the resource type is within a single Availability Domain. If you call one of these "List" operations without specifying an Availability Domain, the resources are grouped by Availability Domain, then sorted.
`sortOrder`	`string`	The sort order to use, either ascending (`ASC`) or descending (`DESC`). The NAME sort order is case sensitive.

`SELECT` examples

get
list

Gets the specified dynamic group's information.

SELECT
id,
name,
compartmentId,
definedTags,
description,
freeformTags,
inactiveStatus,
lifecycleState,
matchingRule,
timeCreated
FROM oci.identity.dynamic_groups
WHERE dynamicGroupId = '{{ dynamicGroupId }}' -- required
AND region = '{{ region }}' -- required
;

Lists the dynamic groups in your tenancy. You must specify your tenancy's OCID as the value for the compartment ID (remember that the tenancy is simply the root compartment). See [Where to Get the Tenancy's OCID and User's OCID](/Content/API/Concepts/apisigningkey.htm#five).

SELECT
id,
name,
compartmentId,
definedTags,
description,
freeformTags,
inactiveStatus,
lifecycleState,
matchingRule,
timeCreated
FROM oci.identity.dynamic_groups
WHERE compartmentId = '{{ compartmentId }}' -- required
AND region = '{{ region }}' -- required
AND page = '{{ page }}'
AND limit = '{{ limit }}'
AND name = '{{ name }}'
AND sortBy = '{{ sortBy }}'
AND sortOrder = '{{ sortOrder }}'
AND lifecycleState = '{{ lifecycleState }}'
;

`INSERT` examples

create
Manifest

Creates a new dynamic group in your tenancy. You must specify your tenancy's OCID as the compartment ID in the request object (remember that the tenancy is simply the root compartment). Notice that IAM resources (users, groups, compartments, and some policies) reside within the tenancy itself, unlike cloud resources such as compute instances, which typically reside within compartments inside the tenancy. For information about OCIDs, see [Resource Identifiers](/Content/General/Concepts/identifiers.htm). You must also specify a name for the dynamic group, which must be unique across all dynamic groups in your tenancy, and cannot be changed. Note that this name has to be also unique across all groups in your tenancy. You can use this name or the OCID when writing policies that apply to the dynamic group. For more information about policies, see [How Policies Work](/Content/Identity/policieshow/how-policies-work.htm). You must also specify a description for the dynamic group (although it can be an empty string). It does not have to be unique, and you can change it anytime with [UpdateDynamicGroup](#/en/identity/20160918/DynamicGroup/UpdateDynamicGroup). After you send your request, the new object's lifecycleState will temporarily be CREATING. Before using the object, first make sure its lifecycleState has changed to ACTIVE.

INSERT INTO oci.identity.dynamic_groups (
compartmentId,
definedTags,
description,
freeformTags,
matchingRule,
name,
region,
opc-retry-token
)
SELECT 
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ description }}' /* required */,
'{{ freeformTags }}',
'{{ matchingRule }}' /* required */,
'{{ name }}' /* required */,
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
name,
compartmentId,
definedTags,
description,
freeformTags,
inactiveStatus,
lifecycleState,
matchingRule,
timeCreated
;

# Description fields are for documentation purposes
- name: dynamic_groups
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the dynamic_groups resource.
  - name: compartmentId
    value: "{{ compartmentId }}"
    description: |
      The OCID of the tenancy containing the group.
  - name: definedTags
    value: "{{ definedTags }}"
    description: |
      Defined tags for this resource. Each key is predefined and scoped to a namespace.
      For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm).
      Example: `{"Operations": {"CostCenter": "42"}}`
  - name: description
    value: "{{ description }}"
    description: |
      The description you assign to the group during creation. Does not have to be unique, and it's changeable.
      (For tenancies that support identity domains) You can have an empty description.
  - name: freeformTags
    value: "{{ freeformTags }}"
    description: |
      Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace.
      For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm).
      Example: `{"Department": "Finance"}`
  - name: matchingRule
    value: "{{ matchingRule }}"
    description: |
      The matching rule to dynamically match an instance certificate to this dynamic group.
      For rule syntax, see [Managing Dynamic Groups](/Content/Identity/dynamicgroups/managingdynamicgroups.htm).
  - name: name
    value: "{{ name }}"
    description: |
      The name you assign to the group during creation. The name must be unique across all groups
      in the tenancy and cannot be changed.
  - name: opc-retry-token
    value: "{{ opc-retry-token }}"
    description: A token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (e.g., if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected). 
    description: A token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (e.g., if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected). 

`UPDATE` examples

update

Updates the specified dynamic group.

UPDATE oci.identity.dynamic_groups
SET 
definedTags = '{{ definedTags }}',
description = '{{ description }}',
freeformTags = '{{ freeformTags }}',
matchingRule = '{{ matchingRule }}'
WHERE 
dynamicGroupId = '{{ dynamicGroupId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
RETURNING
id,
name,
compartmentId,
definedTags,
description,
freeformTags,
inactiveStatus,
lifecycleState,
matchingRule,
timeCreated;

`DELETE` examples

delete

Deletes the specified dynamic group.

DELETE FROM oci.identity.dynamic_groups
WHERE dynamicGroupId = '{{ dynamicGroupId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match }}'
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​