Cloudera Docs

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 the Cloudera Data Catalog user interface or CDP CLI 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)

Use one of the following:

Creating a Data Share

Use one of the following:

Creating a Data Share with CDP CLI

Learn how to register external clients in Cloudera on cloud and create Data Shares using CDP CLI commands. This process involves provisioning credentials for external users and managing data sharing through a series of CLI commands. Ensure that prerequisites are met and follow the steps to securely share data assets with external users.

Resource owners or Data Share administrators who want to share their Iceberg tables in Cloudera with external clients must first register the external client in the Cloudera on cloud environment using the cdp datacatalog create-external-users CDP CLI command. This provisions a CLIENT_ID and CLIENT_SECRET for the external user.

After registering the external user, the resource owner creates a Data Share using the cdp datacatalog create-data-share CDP CLI command. The command packages specified data assets (Iceberg tables) into a shareable unit and optionally grants access to registered external users during creation using the --external-users parameter.

The CDP CLI also provides commands to manage the entire Data Share lifecycle, including listing, updating, activating, deactivating, and deleting shares, as well as managing asset membership and external user access.

  • Users who run the token generation commands, must be a part of the Knox admin users and groups configuration. For more information see Knox configuration in gateway-site.xml.

    Having the DataShareAdmin resource role includes the knoxAdmin role. For more information, see Providing access to users.

  • You must run all commands within the network of your Cloudera Runtime or through a VPN.
  • For Cloudera on cloud environments, you can alternatively register external users using the Cloudera Data Catalog user interface. For more information, see Creating external users.
  • CDP CLI must be installed and configured. For more information, see CLI client setup.
  • Configure the CDP CLI profile to authenticate as a non-machine user (an interactive user account). You must run all cdp datacatalog Data Sharing commands with that user, not with a machine user or service principal, even when the machine user has the DataShareAdmin resource role. Your account must have the CDP_DATA_SHARE_ADMIN entitlement. For more information, see Data Sharing overview.
  • The cdp datacatalog create-external-users command registers external users (Data Consumers outside Cloudera who receive a CLIENT_ID and CLIENT_SECRET for Iceberg REST Catalog access). It does not create machine users for automation.
  • You must have the following information before creating a Data Share:
    Share Admin user and password
    Username and password of the Cloudera Administrator. For more information, see Cloudera account administrator.
    Data Lake name
    Go to Management Console > Environments > <***YOUR_ENVIRONMENT_NAME***> > Data Lake Details, copy and record the Data Lake name.
    Figure 1. Data Lake Details

Data Share management commands

The following additional CDP CLI commands are available for Data Share management:

  • cdp datacatalog create-external-users — Creates external user accounts for individuals outside Cloudera, generating a CLIENT_ID and CLIENT_SECRET for each user.
  • cdp datacatalog list-external-users — Lists external users registered for data sharing, with optional filtering and pagination.
  • cdp datacatalog revoke-external-user-credentials — Revokes the active credentials for an external user.
  • cdp datacatalog regenerate-external-user-credentials — Issues a new set of credentials for an external user, invalidating the old ones.
  • cdp datacatalog delete-external-user — Permanently deletes an external user and removes their access to all data shares.
  • cdp datacatalog create-data-share — Creates a new data share and packages specified data assets into a shareable unit.
  • cdp datacatalog list-data-shares — Lists all available data shares within a specified Data Lake.
  • cdp datacatalog get-data-share — Retrieves the full details of a specific data share, including its assets and user access list.
  • cdp datacatalog update-data-share — Updates the metadata for an existing data share, such as its name, keywords, or expiration.
  • cdp datacatalog delete-data-share — Permanently deletes a data share.
  • cdp datacatalog share-data-share — Activates a data share, making its assets available to the configured external users.
  • cdp datacatalog unshare-data-share — Deactivates a data share, making its assets temporarily unavailable.
  • cdp datacatalog add-assets-to-data-share — Adds new data assets, such as tables or views, to an existing data share.
  • cdp datacatalog remove-assets-from-data-share — Removes one or more assets from an existing data share by resource ID.
  • cdp datacatalog get-fgac-status-by-assets — Checks whether one or more assets being added to a data share are protected by Apache Ranger fine-grained access control (FGAC) policies, such as column masking or row-level filtering.
  • cdp datacatalog grant-access-to-external-users-on-data-share — Grants one or more external users access to a data share, with an optional expiration.
  • cdp datacatalog update-access-of-external-users-on-data-share — Adds external users to a data share or updates their access expiration time.
  • cdp datacatalog remove-access-of-external-users-on-data-share — Removes one or more external users' access from a specific data share.
  1. Register external users directly using the cdp datacatalog create-external-users CDP CLI command.

    Run the following command to create one or more external users:

    cdp datacatalog create-external-users \
    --datalake-crn "[***DATALAKE-CRN***]" \
    --environment-crn "[***ENVIRONMENT-CRN***]" \
    --external-users email=[***EMAIL***],username=[***USERNAME***],companyName=[***COMPANY***]
    The command accepts the following parameters for each entry in the --external-users list:
    • email – Email address of the external user.
    • username – Username for the external user account.
    • companyName – Name of the organization of the external user.

    On success, the command returns the created user objects including the generated credentials:

    {
    "externalUsers": [
        {
            "userId": 51,
            "username": "[***USERNAME***]",
            "email": "[***EMAIL***]",
            "companyName": "[***COMPANY***]",
            "clientId": "[***CLIENT_ID***]",
            "secret": "[***SECRET***]",
            "createdAt": "2025-07-29T14:07:05.742000+00:00",
            "error": ""
        }
    ]
}
  2. Verify the CLIENT_ID generation using one of the following methods:

    • Verify using Ranger Audits.

      1. TGo to Cloudera Management Console > [***ENVIRONMENT-NAME***] > [***DATALAKE-NAME***] > Ranger > Audits > Admin. Your external user creation events are displayed as User created [***CLIENTID***].
        Figure 2. Client ID verification in Ranger

    • Verify using the Data Catalog UI.

      1. In Cloudera Data Catalog, go to Manage Users.
      2. Select the target Data Lake from the drop-down menu at the top of the page. The user list displays all existing external users for the selected Data Lake, including their Client ID, email address, company name, associated shares, and registration date.
        Figure 3. List of external users
    • Verify using the Knox user interface.

      External user Client IDs are also visible in Knox under Cloudera Manager > Environment > [***YOUR_DATALAKE***] > Token Integration > Token Management

  3. After verifying the Client IDs, create a Data Share using the following command: 
    cdp datacatalog create-data-share \
    --datalake-crn "[***DATALAKE-CRN***]" \
    --environment-crn "[***ENVIRONMENT-CRN***]" \
    --data-share-name "[***DATA-SHARE-NAME***]" \
    --assets databaseName=[***DATABASE-NAME***],tableName=[***TABLE-NAME***],guid=[***ASSET-GUID***]
    The command requires the following configuration parameters:
    • --datalake-crn – The CRN of the source Data Lake.
    • --environment-crn – The CRN of the associated CDP environment.
    • --data-share-name – A unique name for the new data share (maximum 512 characters).
    • --assets – The list of data tables to include in the data share, specified using the databaseName=[***DATABASE-NAME***],tableName=[***TABLE-NAME***],guid=[***ASSET-GUID***] shorthand. Separate multiple entries with spaces.
    You can also specify the following optional parameters:
    • --summary – A brief description of the Data Share.
    • --terms-of-use – The legal or usage constraints for the shared data.
    • --keywords – Searchable tags associated with the Data Share.
    • --expiry-time – An expiration timestamp for the entire Data Share.
    • --external-users – Authorization for one or more external users at creation time. Each entry uses the externalUserId=[***USER-ID***],expiryTime=[***YYYY-MM-DDTHH:MM:SS***] shorthand format. Separate multiple entries with spaces.

      The externalUserId is the userId returned when creating external users using the cdp datacatalog create-external-users command.

    The following example creates a marketing Data Share and grants access to a specific external user:

    cdp datacatalog create-data-share \
    --datalake-crn "crn:cdp:datalake:us-west-1:..." \
    --environment-crn "crn:cdp:environments:us-west-1:..." \
    --data-share-name "q3_marketing_data" \
    --assets databaseName=marketing,tableName=campaign_results,guid=5eb2d66b-d47d-402b-a26c-de77b403ef6a \
    --summary "Q3 marketing campaign results" \
    --expiry-time 2025-08-20T06:30:00 \
    --external-users externalUserId=344

    On success, the command returns a JSON object with the identifiers for the new share:

    {
    "dataShareId": 1,
    "dataShareName": "q3_marketing_data",
    "datalakeCrn": "crn:cdp:datalake:us-west-1:..."
}
  4. Verify the Data Share generation by using one of the following methods:

    • Verify using Ranger Audits.

      1. Go to Cloudera Management Console > [***ENVIRONMENT-NAME***] > [***DATALAKE-NAME***] > Ranger > Audits > Admin. Your Data Share creation events are displayed as the following consecutive Ranger audit events:
        • DataShare in Dataset created
        • Data Share created ***DATASET SERVICE NAME***
        • Dataset create ***DATASHARE NAME***
        Figure 4. Data Share verification in Ranger

    • Verify using the Data Catalog UI.

      1. In Cloudera Data Catalog, go to Data Sharing. The new Data Share is listed on the All Shares page in Not Shared status until you publish it.
        Figure 5. All Shares page

After you create the Data Share, publish it so external users can access its assets. Run the cdp datacatalog share-data-share command with the same --datalake-crn and --environment-crn values you used for the cdp datacatalog create-data-share command, and the dataShareId value from the create command response. The command calls POST /api/v1/datacatalog/shareDataShare with those three values in the request body.

cdp datacatalog share-data-share \
    --datalake-crn "[***DATALAKE-CRN***]" \
    --environment-crn "[***ENVIRONMENT-CRN***]" \
    --data-share-id "[***DATA-SHARE-ID***]"

On success, the command returns a JSON object that matches ShareDataShareResponse:

{
    "success": true
}

For example, if you created the share in the previous step, you can publish it using the same environment and Data Lake CRNs along with the returned identifier:

cdp datacatalog share-data-share \
    --datalake-crn "crn:cdp:datalake:us-west-1:..." \
    --environment-crn "crn:cdp:environments:us-west-1:..." \
    --data-share-id "1"

Registering external clients in Cloudera on cloud

Learn how to register external clients in Cloudera on cloud to provision a CLIENT_ID and CLIENT_SECRET.

Ensure that you have the following information before performing the steps:
Share Admin user and password
Username and password of the Cloudera Administrator. For more information, see Cloudera account administrator.
Knox hostname
To get the Knox hostname, go to Cloudera Manager > Knox > Instances, and copy the hostname for the Knox Gateway role.
Data Lake name
Go to Management Console > Environments > <***YOUR_ENVIRONMENT_NAME***> > Data Lake Details and copy and make a note of the Data Lake name.
  1. Create the CLIENT_ID and SECRET in Knox by running the following command: 
    curl -k -u [***CLOUDERA_ADMIN_USER***]:"[***PASSWORD***] https://[***KNOX-HOST-NAME***]:8443/[***DATALAKE-NAME***]/cdp-share-management/knoxtoken/api/v1/token?doAs=external.user&comment=[***<ADDITION INFO>***]s&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, email_id
    • md_role - [***Role for the CLIENT_ID***]
    • md_type - Sets the value of CLIENT_ID
    curl -k -u [***CLOUDERA_ADMIN_USER***]:"[***PASSWORD***] "https://my-datalake-name.int.cldr.work:8443/my-datalake-name/cdp-share-management/knoxtoken/api/v1/token?doAs=external.user&comment=carriers&md_contact=client_name@companay.com&md_role=UnitedAirlinesRole&md_type=[***CLIENT_ID***]" |  jq -r '"CLIENT_ID: \(.token_id) SECRET: \(.passcode)"'

CLIENT_ID : 462babd3-fe5a-4abf-8b47-526897677ad5 SECRET: TkRZeVltRmlaRE10Wm1VMVlTMDBZV0ptTFRoaU5EY3ROVEkyT0RrM05qYzNZV1ExOjpaalV4WWpReFkyWXRObVV6WlMwME4yTm1MVGcyWWpFdE9XSXhZekE0T1RZMU9XTmw='
    By Enterprise Data Lakes, use the following command:
    curl -k -u [***CLOUDERA_ADMIN_USER***]:"[***PASSWORD***]] https://[***LOAD BALANCER***]/[***DATALAKE-NAME***]/cdp-share-management/knoxtoken/api/v1/token?doAs=external.user&comment=[***<ADDITION INFO>***]s&md_contact=[***EMAIL_ID***]&md_role=[***ROLE OF THE CLIENT***] &md_type=[***CLIENT_ID***]" |  jq -r '"CLIENT_ID: \(.token_id) SECRET: \(.passcode)"'
    curl -k -u [***CLOUDERA_ADMIN_USER***]:[***PASSWORD***]:"https://my-loadbalancer-1745504451479-b5765eaee5b22d08.elb.us-west-2.amazonaws.com/dldamedi-28qgc9/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)"'
  1. After verifying the Client IDs, you need to create a Ranger group representing the data share. Create a Ranger Group with Client ID as the name of that Group with the following command: 
    curl -k -u [***CLOUDERA_ADMIN_USER***]:"[***PASSWORD***] -H "Accept: application/json" -H "Content-Type: application/json" -X POST "https://[***RANGER-HOST-NAME***]:8443/[***DATALAKE-NAME***]/cdp-share-management/ranger/service/xusers/groups/" -d '{"name": "[***CLIENT_ID***]", "description": "group representing a share for a CLIENT_ID"}'
    curl -k -u [***CLOUDERA_ADMIN_USER***]:"[***PASSWORD***] -H "Accept: application/json" -H "Content-Type: application/json" -X POST "https://my-datalake.int.cldr.work:8443/my-datalake-name/cdp-share-management/ranger/service/xusers/groups/" -d '{"name": "462babd3-fe5a-4abf-8b47-526897677ad5", "description": "group representing a share for a CLIENT_ID"}'
    By Enterprise Data Lakes, use the following command:
    curl -k -u [***CLOUDERA_ADMIN_USER***]:"[***PASSWORD***]  -H "Accept: application/json" -H "Content-Type: application/json" -X POST "https://[***RANGER-HOST-NAME***]/[***DATALAKE-NAME***]/cdp-share-management/ranger/service/xusers/groups/" -d '{"name": "[***CLIENT_ID***]", "description": "group representing a share for a CLIENT_ID"}'
    curl -k -u [***CLOUDERA_ADMIN_USER***]:[***PASSWORD***] -H "Accept: application/json" -H "Content-Type: application/json" -X POST "https://my-gateway-hostname.cldr.work:8443/my-datalake-name/cdp-share-management/ranger/service/xusers/groups/" -d '{"name": "462babd3-fe5a-4abf-8b47-526897677ad5", "description": "group representing a share for a CLIENT_ID"}'
  2. Create a new Role and add the created Group to the Role in Ranger with the following command: 
    curl -k -u [***CLOUDERA_ADMIN_USER***]:"[***PASSWORD***]  -H "Accept: application/json" -H "Content-Type: application/json" -X POST "https://[***RANGER-HOST-NAME***]:8443/[***DATALAKE-NAME***]/cdp-share-management/ranger/service/public/v2/api/roles/" -d '{ "name": "***CLIENT_ROLE***", "description": "***CLIENT_ROLE DESCRIPTION******", "groups": [ { "name": "***CLIENT_ID CREATED***", "isAdmin": false } ] }'

    curl -k -u [***CLOUDERA_ADMIN_USER***]:"[***PASSWORD***] -H "Accept: application/json" -H "Content-Type: application/json" -X POST "https://my-ranger-hostname.int.cldr.work:8443/my-datalake-name/cdp-share-management/ranger/service/public/v2/api/roles/" -d '{ "name": "SalesDeptRole", "description": "SalesRole description", "groups": [ { "name": "462babd3-fe5a-4abf-8b47-526897677ad5", "isAdmin": false } ] }'
    By Enterprise Data Lakes and, use the following command:
    curl -k -u [***CLOUDERA_ADMIN_USER***]:"[***PASSWORD***]  -H "Accept: application/json" -H "Content-Type: application/json" -X POST "https://[***GATEWAY-HOST-NAME***]/[***DATALAKE-NAME***]/cdp-share-management/ranger/service/public/v2/api/roles/" -d '{ "name": "***CLIENT_ROLE***", "description": "***CLIENT_ROLE DESCRIPTION***", "groups": [ { "name": "***CLIENT_ID CREATED***", "isAdmin": false } ] }'
    curl -k -u [***CLOUDERA_ADMIN_USER***]:[***PASSWORD***] -H "Accept: application/json" -H "Content-Type: application/json" -X POST "https://my-gateway-hostname.int.cldr.work:8443/my-datalake-name/cdp-share-management/ranger/service/public/v2/api/roles/" -d '{ "name": "TestRole1", "description": "TestRole1 description", "groups": [ { "name": "test-group1", "isAdmin": false } ] }'

    After running the commands, you can see the roles in Ranger:

    Figure 6. Cloudera Management Console > Environments > ***YOUR_ENVIRONMENT**** > > Apache Ranger > Settings > Roles
  3. Optional: Add the Group to an existing Role with the following commands:

    • Get the RoleId for the RoleName from Ranger Admin via API:

      curl -k -u [***CLOUDERA_ADMIN_USER***]:"[***PASSWORD***] -H "Accept: application/json" -H "Content-Type: application/json" -X GET "https://[***RANGER-HOST-NAME***]:8443/[***DATALAKE-NAME***]/cdp-share-management/ranger/service/public/v2/api/roles/name/<name>"| jq -r '"RoleId: \(.id)"'

    • Add the Group to the Role using RoleId

      curl -k -u [***CLOUDERA_ADMIN_USER***]:"[***PASSWORD***] -H "Accept: application/json" -H "Content-Type: application/json" -X PUT "https://[***RANGER-HOST-NAME***]:8443/[***DATALAKE-NAME***]/cdp-share-management/ranger/service/public/v2/api/roles/<RoleId>" -d '{ "name": "***CLIENT_ROLE***", "description": "***CLIENT_ROLE DESCRIPTION***", "groups": [ { "name": "***CLIENT_ID CREATED***", "isAdmin": false } ] }'

The registration process results in provisioning a CLIENT_ID and CLIENT_SECRET followed by creating Ranger ROLE and adding CLIENT_ID as a Group to the ROLE. You can verify the creation of your Ranger groups and users in Cloudera Management Console > Environments > ***YOUR_ENVIRONMENT**** > > Apache Ranger > Audits > Admin

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 Creating a Data Share with CDP CLI:

curl -k -u [***CDP_ADMIN_USER***]:[***PASSWORD***] -H "Accept: application/json" -H "Content-Type: application/json" -X POST "https://[***RANGER-HOST-NAME***]:8443/[***DATALAKE-NAME***]/cdp-share-management/ranger/service/public/v2/api/policy/" -d  '{"service":"hive_service_name", "policyType": 0, "name": "Iceberg Table Policy", "description": "Policy for SELECT access to an CLIENT_ID", "isEnabled": true, "resources": { "database": { "values": "[***DATABASE_NAME***]" }, "table": { "values": "[***TABLE_NAME***]" } ,"column": { "values": ["*"] } } , "policyItems": [ { "accesses": [ { "type": "select" } ], "users": [], "groups":[], "roles": "[***CLIENT_ROLE***]", "conditions": [] } ] }'
curl -k -u [***CDP_ADMIN_USER***]:[***PASSWORD***]  -H "Accept: application/json" -H "Content-Type: application/json" -X POST "https://dldanew-vxtt5w-master0.dldanew.svbr-nqvp.int.cldr.work:8443/dldanew-vxtt5w/cdp-share-management/ranger/service/public/v2/api/policy/" -d '{"service":"cm_hive", "policyType": 0, "name": "Hive Table Policy", "description": "Policy for SELECT access to an exteral user", "isEnabled": true, "resources": { "database": { "values": ["emp_data"] }, "table": { "values": ["employees"] } ,"column": { "values": ["*"] } } , "policyItems": [ { "accesses": [ { "type": "select" } ], "users": [], "groups":[], "roles": ["testrole13"], "conditions": [] } ] }'