Oracle Cloud Infrastructure Documentation

Resource Principals

DB systems can use resource principals to authenticate and access other Oracle Cloud Infrastructure resources. To use resource principals, you or your tenancy administrator must define the Oracle Cloud Infrastructure policies and dynamic groups that allows principals to access Oracle Cloud Infrastructure resources.

Resource principal is used in the following HeatWave Service features:

  • Bring your own certificate: Allows DB systems to read the certificates defined in Oracle Cloud Infrastructure (OCI) Certificates Service.
  • Network Security Groups: Allows DB systems or read replicas to use network security rules specified in one or more network security groups.
  • HeatWave Lakehouse: Allows DB systems to read data from Object Storage.
  • Exporting query results to Object Storage: Allows HeatWave service to export query results to Object Storage.
  • Accessing OCI Generative AI Service: Allows HeatWave GenAI to use any pretrained foundational models available in OCI Generative AI Service.

Resource principals have two components:

Dynamic Groups

Dynamic groups allow you to group HeatWave Service DB systems as principal actors, similar to user groups.

You can then create policies to permit DB systems in the dynamic groups to make API calls against Oracle Cloud Infrastructure services, such as Certificates or Object Storage. Membership in the group is determined by a set of criteria you define, called matching rules.

The following example shows a matching rule including all DB systems in the defined compartment:
"ALL{resource.type='mysqldbsystem', resource.compartment.id = 'ocid1.compartment.oc1..alphanumericString'}"

For more information, see Writing Matching Rules to Define Dynamic Groups.

Dynamic groups require a name, description, and matching rule. See Creating a Dynamic Group.

Policies

Policies define what your groups or dynamic groups can and cannot do.

Defining a Policy for Bring Your Own Certificate

For DB systems to access certificates from the Certificates Service, you must define a policy which allows the dynamic group to read the certificates.

For example, the following policy grants the dynamic group MYSQL_DG to read the security certificates in compartment C8: 
Allow dynamic-group MYSQL_DG to read leaf-certificate-family in compartment C8

Defining a Policy for Network Security Groups

To add Network Security Groups to DB systems or read replicas, you must define a policy which allows the dynamic group to use the following permissions:
  • NETWORK_SECURITY_GROUP_UPDATE_MEMBERS in the compartment containing the Network Security Groups
  • VNIC_CREATE, VNIC_UPDATE, VNIC_ASSOCIATE_NETWORK_SECURITY_GROUP, VNIC_DISASSOCIATE_NETWORK_SECURITY_GROUP, VNIC_ASSOCIATE_NETWORK_SECURITY_GROUP in the compartment of the DB system's subnet.
For example, the following policies grant the dynamic group MYSQL_DG to the required permissions to use the Network Security Groups in compartment C8 with the DB system's subnet in compartment C9:
Allow dynamic-group MYSQL_DG to {NETWORK_SECURITY_GROUP_UPDATE_MEMBERS} 
    in compartment C8
Allow dynamic-group MYSQL_DG to {VNIC_CREATE, VNIC_UPDATE, VNIC_ASSOCIATE_NETWORK_SECURITY_GROUP, 
    VNIC_DISASSOCIATE_NETWORK_SECURITY_GROUP} in compartment C9
Alternatively, you can create the following policies that incorporate the principals without using a dynamic group:
Allow any-user to {NETWORK_SECURITY_GROUP_UPDATE_MEMBERS} in compartment C8 where all 
    {request.principal.type='mysqldbsystem', request.resource.compartment.id='ocid1.compartment.oc1..alphanumericString'}
Allow any-user to {VNIC_CREATE, VNIC_UPDATE, VNIC_ASSOCIATE_NETWORK_SECURITY_GROUP, 
    VNIC_DISASSOCIATE_NETWORK_SECURITY_GROUP} in compartment C9 where all 
    {request.principal.type='mysqldbsystem', request.resource.compartment.id='ocid1.compartment.oc1..alphanumericString'}

Defining a Policy for HeatWave Lakehouse

For HeatWave Lakehouse to access Object Storage, you must define a policy which allows the dynamic group to access to buckets and their contents.

For example, the following policy grants the dynamic group MYSQL_DG read-only access to the buckets and objects contained in those buckets in compartment C8: 
Allow dynamic-group MYSQL_DG to read buckets in compartment C8
Allow dynamic-group MYSQL_DG to read objects in compartment C8

Defining a Policy for Exporting Query Results to Object Storage

To allow HeatWave to export query results to Object Storage, the policy must grant permissions to create and delete objects in the bucket to the dynamic group.

For example, the following policy grants the dynamic group MYSQL_DG with permissions to create, inspect, and delete objects in any bucket in compartment C8:
Allow dynamic-group MYSQL_DG to read buckets in compartment C8
Allow dynamic-group MYSQL_DG to manage objects in compartment C8 where 
  any {request.permission='OBJECT_CREATE', request.permission='OBJECT_INSPECT', 
       request.permission='OBJECT_DELETE'}
You can restrict the permissions to a specific bucket. The following policy grants the dynamic group MYSQL_DG with permissions to create, inspect, and delete objects in the BucketA bucket in compartment C8:
Allow dynamic-group MYSQL_DG to read buckets in compartment C8
Allow dynamic-group MYSQL_DG to manage objects in compartment C8 where 
  all {target.bucket.name='BucketA',
    any {request.permission='OBJECT_CREATE', request.permission='OBJECT_INSPECT', 
         request.permission='OBJECT_DELETE'} }

Defining a Policy for Accessing OCI Generative AI Service

For HeatWave GenAI to use any pretrained foundational models available in OCI Generative AI, you must define a policy which allows the dynamic group to access OCI Generative AI service.

For example, the following policy grants the dynamic group MYSQL_DG to access OCI Generative AI service in compartment C8: 
Allow dynamic-group MYSQL_DG to use generative-ai-chat in compartment C8
Allow dynamic-group MYSQL_DG to use generative-ai-text-embedding in compartment C8
Note

The usage of OCI Generative AI will be metered and billed on the selected compartment.
For more information, see Writing Policies for Dynamic Groups.