Creating a Data Share

Learn how resource owners or Data Share administrators can share Iceberg tables in the by registering external clients and creating Data Shares using Knox and Ranger API commands.

Resource owners or Data Share administrators who want to share their Iceberg tables in Cloudera with external clients must first register the external client (Data Consumer) in the Cloudera on cloud environment. This provisions a CLIENT_ID and CLIENT_SECRET for the external user.

After registering the external user, the resource owner creates a Data Share. A Data Share packages specified data assets (Iceberg tables) into a shareable unit and optionally grants access to registered external users at creation time.

Registering external users (Data Consumers)

For more information, see Registering external clients for on premises deployments.

Creating a Data Share

For more information, see Managing Ranger policies.

Registering external clients for Cloudera on premises

For Cloudera on premises deployments, generate a CLIENT_ID and CLIENT_SECRET for an external client through the cdp-share-management Knox topology, and then create the Ranger group and role that represent the external client.

In Cloudera on premises deployments, external clients are registered directly against the cdp-share-management Knox topology gateway rather than a Cloudera on cloud Data Lake. The registration provisions a CLIENT_ID and CLIENT_SECRET, which the external client later uses in an OAuth client credentials flow to authenticate to Cloudera Iceberg REST Catalog. You then create a Ranger group named after the CLIENT_ID and add it to a Ranger role. To grant that role SELECT access to the Iceberg tables you want to share, create a Data Share policy as described in Managing Ranger policies for Data Shares.

Declare the cdp-datashare-access and cdp-share-management Knox topologies, as described in Declaring Knox topologies for on premises Data Sharing.
The user that runs the following commands:
- Must exist in the cluster
- Must be configured as a Knox proxy (impersonation) user in the cdp-share-management topology
- Must be granted the Ranger administrator role
Run all commands within the network of your Cloudera Runtime deployment or through a VPN.

Generate the CLIENT_ID and CLIENT_SECRET by calling the cdp-share-management Knox token service on the Knox Gateway:
This CLIENT_ID acts as the unique principal identity for the external client (such as Snowflake or EMR) when it requests an OAuth token. The CLIENT_SECRET is the password that the external client uses to authenticate.
```
curl -k -u [***RANGER-ADMIN-USER***]:[***PASSWORD***] "https://[***KNOX-GATEWAY-HOST***]:8443/gateway/cdp-share-management/knoxtoken/api/v1/token?doAs=external.user&comment=[***ADDITIONAL-INFO***]&md_contact=[***EMAIL_ID***]&md_role=[***ROLE_OF_THE_CLIENT***]&md_type=CLIENT_ID" | jq -r '"CLIENT_ID: \(.token_id) SECRET: \(.passcode)"'
```
- doAs=external.user - Sets the value of the external.user.
- comment - Additional comments on the CLIENT.
- md_contact - Client contact metadata, for example, an email address.
- md_role - [***Role for the CLIENT_ID***].
- md_type - Token metadata type; set to CLIENT_ID for external client credentials.
note
Replace [***KNOX-GATEWAY-HOST***] with the hostname of the Knox Gateway node.
```
curl -k -u systest:[***PASSWORD***] "https://my-knox-gateway-host.root.comops.site:8443/gateway/cdp-share-management/knoxtoken/api/v1/token?doAs=external.user&comment=carriers&md_contact=client_name@company.com&md_role=UnitedAirlinesRole&md_type=CLIENT_ID" | jq -r '"CLIENT_ID: \(.token_id) SECRET: \(.passcode)"'
```

Create a Ranger group whose name is the CLIENT_ID generated in the previous step:

When the external client authenticates via the REST Catalog, Ranger evaluates its permissions based on its CLIENT_ID. By creating a Ranger group that exactly matches the UUID string of the CLIENT_ID, you can manage its access in the Ranger ecosystem.

curl -k -u [***RANGER-ADMIN-USER***]:[***PASSWORD***] -H "Accept: application/json" -H "Content-Type: application/json" -X POST "https://[***KNOX-GATEWAY-HOST***]:8443/gateway/cdp-share-management/ranger/service/xusers/groups/" -d '{"name": "[***CLIENT_ID***]", "description": "group representing a share for a CLIENT_ID"}'

curl -k -u systest:[***PASSWORD***] -H "Accept: application/json" -H "Content-Type: application/json" -X POST "https://my-knox-gateway-host.root.comops.site:8443/gateway/cdp-share-management/ranger/service/xusers/groups/" -d '{"name": "9a18e31e-c70d-4f84-8a5a-22d7fbce6124", "description": "group representing a share for a CLIENT_ID"}'

Create a new Ranger role for the external client, and add the group (the CLIENT_ID) to it.

Instead of assigning table permissions directly to the unreadable CLIENT_ID group, best practice is to assign permissions to a human-readable role (such as SalesDeptRole). This step creates that role and links the external client to it so that it inherits the role's access.

curl -k -u [***RANGER-ADMIN-USER***]:[***PASSWORD***] -H "Accept: application/json" -H "Content-Type: application/json" -X POST "https://[***KNOX-GATEWAY-HOST***]:8443/gateway/cdp-share-management/ranger/service/public/v2/api/roles/" -d '{"name": "[***CLIENT_ROLE***]", "description": "[***CLIENT_ROLE_DESCRIPTION***]", "groups": [ { "name": "[***CLIENT_ID***]", "isAdmin": false } ] }'

curl -k -u systest:[***PASSWORD***] -H "Accept: application/json" -H "Content-Type: application/json" -X POST "https://my-knox-gateway-host.root.comops.site:8443/gateway/cdp-share-management/ranger/service/public/v2/api/roles/" -d '{"name": "SalesDeptRole", "description": "SalesRole description", "groups": [ { "name": "9a18e31e-c70d-4f84-8a5a-22d7fbce6124", "isAdmin": false } ] }'

Optional: Alternatively, if you already have an existing Ranger role that manages access for this Data Share, add the group to that existing role instead.

Use this alternative if you do not want to create a new role.

Get the RoleId for the role name:

curl -k -u [***RANGER-ADMIN-USER***]:[***PASSWORD***] -H "Accept: application/json" -H "Content-Type: application/json" -X GET "https://[***KNOX-GATEWAY-HOST***]:8443/gateway/cdp-share-management/ranger/service/public/v2/api/roles/name/[***CLIENT_ROLE***]" | jq -r '"RoleId: \(.id)"'

Add the group to the role by using the RoleId:

curl -k -u [***RANGER-ADMIN-USER***]:[***PASSWORD***] -H "Accept: application/json" -H "Content-Type: application/json" -X PUT "https://[***KNOX-GATEWAY-HOST***]:8443/gateway/cdp-share-management/ranger/service/public/v2/api/roles/[***ROLE_ID***]" -d '{"name": "[***CLIENT_ROLE***]", "description": "[***CLIENT_ROLE_DESCRIPTION***]", "groups": [ { "name": "[***CLIENT_ID***]", "isAdmin": false } ] }'

The external client is registered with a CLIENT_ID and CLIENT_SECRET, and a Ranger role that contains the CLIENT_ID group represents the Data Share. The client uses the CLIENT_ID and CLIENT_SECRET in an OAuth client credentials flow to authenticate to Cloudera Iceberg REST Catalog.

Create the Data Share policy that grants the Ranger role SELECT access to the shared Iceberg tables, as described in Managing Ranger policies.

Managing Ranger policies for Data Shares

Learn how to manage your Ranger policies to authenticate your external users.

The Ranger Administrator must maintain policies for the set of databases and tables for the Ranger role and group to enable read access for these assets.

Create a Data Share policy in Ranger that grants the Ranger role SELECT access to the databases and tables you want to share.

Create the policy for the role created in Registering external clients and creating a Data Share for on premises deployments:

curl -k -u [***RANGER-ADMIN-USER***]:[***PASSWORD***] -H "Accept: application/json" -H "Content-Type: application/json" -X POST "https://[***KNOX-GATEWAY-HOST***]:8443/gateway/cdp-share-management/ranger/service/public/v2/api/policy/" -d '{"service":"cm_hive", "policyType": 0, "name": "[***DATA_SHARE_NAME***]", "description": "Policy for SELECT access to the shared Iceberg tables", "isEnabled": true, "resources": { "database": { "values": ["[***DATABASE_NAME***]"] }, "table": { "values": ["[***TABLE_NAME***]"] }, "column": { "values": ["*"] } }, "policyItems": [ { "accesses": [ { "type": "select" } ], "users": [], "groups": [], "roles": ["[***CLIENT_ROLE***]"], "conditions": [] } ] }'

Instead of managing access separately for every shared table, you define a central Ranger policy that groups the relevant tables together into a unified Data Share. This policy grants the required read access to the Ranger role you previously created, ensuring that any external client linked to that role can query the shared data.

The following policy grants the SalesDeptRole role SELECT access to the employees, departments, and dept_emp Iceberg tables, which together form the datashare1 Data Share:

curl -k -u systest:[***PASSWORD***] -H "Accept: application/json" -H "Content-Type: application/json" -X POST "https://my-knox-gateway-host.root.comops.site:8443/gateway/cdp-share-management/ranger/service/public/v2/api/policy/" -d '{"service":"cm_hive", "policyType": 0, "name": "datashare1", "description": "Policy for SELECT access to the shared Iceberg tables", "isEnabled": true, "resources": { "database": { "values": ["emp_data"] }, "table": { "values": ["employees", "departments", "dept_emp"] }, "column": { "values": ["*"] } }, "policyItems": [ { "accesses": [ { "type": "select" } ], "users": [], "groups": [], "roles": ["SalesDeptRole"], "conditions": [] } ] }'