AWS clean-rooms documentation change
Summary
Complete restructuring of collaboration creation documentation from three collaboration types to a unified step-by-step guide with expanded configuration details, analytics engine comparisons, cryptographic computing parameters, and payment management instructions
Security assessment
Added documentation for cryptographic computing parameters and service role permissions, but no evidence of addressing a specific security vulnerability. Changes focus on explaining security features rather than fixing issues.
Diff
diff --git a/clean-rooms/latest/userguide/create-collaboration.md b/clean-rooms/latest/userguide/create-collaboration.md index 54d85541d..83e991a57 100644 --- a/clean-rooms/latest/userguide/create-collaboration.md +++ b/clean-rooms/latest/userguide/create-collaboration.md @@ -7 +7 @@ -There are three ways to create a collaboration in AWS Clean Rooms. +In this procedure, the [collaboration creator](./glossary.html#glossary-collaboration-creator) does the following tasks: @@ -9 +9 @@ There are three ways to create a collaboration in AWS Clean Rooms. -The most basic form is the collaboration for queries. This collaboration focuses on SQL query analysis and maintains a simple structure with two main roles: one member who can run queries and another who can receive results. This basic collaboration setup works well for simple data analysis tasks. + * Creates a collaboration. @@ -11 +11 @@ The most basic form is the collaboration for queries. This collaboration focuses -The second form, collaboration for queries and jobs, extends functionality by incorporating both SQL queries and PySpark jobs and requires Spark as its analytics engine. This collaboration setup maintains the same basic role structure but expands permissions to include job execution. A notable requirement is that the member who creates PySpark analysis templates must also be the one receiving results, ensuring clear accountability in the analysis process. + * Invites one or more [members](./glossary.html#glossary-member) to the [collaboration](./glossary.html#glossary-collaboration). @@ -13 +13 @@ The second form, collaboration for queries and jobs, extends functionality by in -The third form is, collaboration for ML modeling, is built for machine learning workflows and requires Spark as its analytics engine. This collaboration setup adds two more roles: one for users who need the results from trained models, and another for users who need the results from using those models to make predictions. This collaboration setup helps collaboration members work together on complex data projects while keeping everyone's roles and permissions clear. + * Assigns abilities to members, such as the [member who can query](./glossary.html#glossary-member-who-can-query) and the [member who can receive results](./glossary.html#glossary-member-who-can-receive-results). @@ -15 +15 @@ The third form is, collaboration for ML modeling, is built for machine learning -The following topics explain how to create collaborations for queries, jobs, and ML modeling. +If the collaboration creator is also the member who can receive results, they specify the query results destination and format. They also provide a service role Amazon Resource Name (ARN) to write the results to the query results destination. @@ -17 +17 @@ The following topics explain how to create collaborations for queries, jobs, and -###### Topics + * Configures which [member is responsible for paying for query compute costs in the collaboration](./glossary.html#glossary-member-paying-for-query-compute). @@ -19 +18,0 @@ The following topics explain how to create collaborations for queries, jobs, and - * [Creating a collaboration for queries](./create-collab-queries.html) @@ -21 +19,0 @@ The following topics explain how to create collaborations for queries, jobs, and - * [Creating a collaboration for queries and jobs](./create-collab-queries-and-jobs.html) @@ -23 +21,261 @@ The following topics explain how to create collaborations for queries, jobs, and - * [Creating a collaboration for ML modeling](./create-collab-ml-modeling.html) + +Before you begin, make sure that you have completed the following prerequisites: + + * You have the name and AWS account ID for each member that you want to invite to the collaboration. + + * You have permission to share the name and AWS account ID for each member with all members of the collaboration. + +###### Note + +You can’t add more members after the collaboration is created. + + * You've determined the type of analytic engine you want to use. + +You can use the following charts to compare the **Spark** analytics engine with the **AWS Clean Rooms SQL** analytics engine and determine which one suits your use case. + +SQL type | Spark analytics engine | AWS Clean Rooms SQL analytics engine +---|---|--- +Spark SQL | Yes | No +AWS Clean Rooms SQL | No | Yes + +Analysis rule | Spark analytics engine | AWS Clean Rooms SQL analytics engine +---|---|--- +Aggregation analysis rule | No | Yes +List analysis rule | No | Yes +Custom analysis rule without AWS Clean Rooms Differential Privacy | Yes | Yes +Custom analysis rule with AWS Clean Rooms Differential Privacy | No | Yes + +Data source | Spark analytics engine | AWS Clean Rooms SQL analytics engine +---|---|--- +Amazon S3 | Yes | Yes +Amazon Athena | Yes | No +Snowflake | Yes | No + + + + +For information about Spark SQL queries, see the _[AWS Clean Rooms Spark SQL Reference](https://docs.aws.amazon.com/clean-rooms/latest/sql-reference/sql-reference-spark.html)_. + +For information about AWS Clean Rooms SQL queries, see the _[AWS Clean Rooms SQL Reference](https://docs.aws.amazon.com/clean-rooms/latest/sql-reference/sql-reference-acr.html)_. + +For information about how to create a collaboration using the AWS SDKs, see the _[AWS Clean Rooms API Reference](https://docs.aws.amazon.com/clean-rooms/latest/apireference/Welcome.html)_. + +###### To create a collaboration using the AWS Clean Rooms console + + 1. Sign in to the AWS Management Console and open the [AWS Clean Rooms console](https://console.aws.amazon.com/cleanrooms/home) with the AWS account that will function as the collaboration creator. + + 2. In the left navigation pane, choose **Collaborations**. + + 3. In the upper right corner, choose **Create collaboration**. + + 4. For **Step 1: Define collaboration** , do the following: + + 1. For **Details** , enter the **Name** and **Description** of the collaboration. + +This information will be visible to collaboration members who are invited to participate in the collaboration. The **Name** and **Description** helps them understand what the collaboration is in reference to. + + 2. Choose the **Analytics engine** you want to use, based on your goal. + +Your goal | Recommended option +---|--- +Query data stored in Amazon S3, Amazon Athena, or Snowflake using SQL functions supported in Apache Spark SQL | **Spark** +Query data stored in Amazon S3 using SQL functions supported in AWS Clean Rooms SQL and use differential privacy | **AWS Clean Rooms SQL** +Query data that has differential privacy configured and is stored in Amazon S3 using SQL functions supported in AWS Clean Rooms SQL | **AWS Clean Rooms SQL** + +###### Note + +If you want to change the analytic engine after the collaboration is created, you must either re-create the collaboration or submit a support ticket. + + 3. For **Members** : + + 1. For **Member 1: You** , enter your **Member display name** as you want it to appear for the collaboration. + +###### Note + +Your AWS account ID is included automatically for **Member AWS account ID**. + + 2. For **Member 2** , enter the **Member display name** and **Member AWS account ID** for the member that you want to invite to the collaboration. + +The **Member display name** and **Member AWS account ID** will be visible to everyone invited to the collaboration. After you enter and save the values for these fields, you can't edit them. + +###### Note + +You must inform the collaboration member that their **Member AWS account ID** and **Member display name** will be visible to all invited and active collaborators in the collaboration. + + 3. If you want to add another member, choose **Add another member**. Then enter the **Member display name** and **Member AWS account ID** for each member who can contribute data that you want to invite to the collaboration. + + 4. If you want to enable **Query logging** , select the **Support query logging for this collaboration** check box. + + 5. If you want to enable the **Cryptographic computing** capability, select the **Support cryptographic computing in this collaboration** check box and choose the following **Cryptographic computing parameters** : + + * **Allow cleartext columns** + +Choose **No** if you don't want cleartext columns allowed in the encrypted table. + +Choose **Yes** if you want cleartext columns allowed in the encrypted table. + +To run SUM or AVG on certain columns, the columns must be in cleartext. + + * **Allow duplicates** + +Choose **No** if you don't want duplicate entries allowed in a fingerprint column. + +Choose **Yes** if you want duplicate entries allowed in a fingerprint column. + + * **Allow JOIN of columns with different names** + +Choose **No** if you don't want to join fingerprint columns with different names. + +Choose **Yes** if you want to join fingerprint columns with different names. + + * **Preserve NULL values** + +Choose **No** if you don't want to preserve NULL values. NULL values won't appear as NULL in an encrypted table. + +Choose **Yes** if you want to preserve NULL values. NULL values will appear as NULL in an encrypted table. + +For more information about **Cryptographic computing parameters** , see [Cryptographic computing parameters](./crypto-computing-parameters.html). + +For more information about how to encrypt your data for use in AWS Clean Rooms, see [Preparing encrypted data tables with Cryptographic Computing for Clean Rooms](./prepare-encrypted-data.html). + +###### Note + +Verify these configurations carefully before completing the next step. After you create the collaboration, you can only edit the collaboration name, description, and whether the query logs are stored in Amazon CloudWatch Logs. + + 6. If you want to enable **Tags** for the collaboration resource, choose **Add new tag** and then enter the **Key** and **Value** pair. + + 7. Choose **Next**. + + 5. For **Step 2: Specify member abilities** , do the following. + + 1. For **Analysis using queries** , take one of the following actions based on your goal. + +Your goal | Recommended action +---|--- +Query the data in the collaboration and receive the results | + 1. Choose yourself as the member who can **Run queries**. + 2. Leave the default setting of the member who can **Receive results** is the **Same as who runs queries**. +Query the data in the collaboration and assign a different member to receive results | + 1. Choose yourself as the member who can **Run queries**. + 2. Select the member who can **Receive results** from the dropdown list. +Receive the results of the query in the collaboration and assign a different member to query the data | + 1. Select the member who can **Run queries** from the dropdown list. + 2. Choose yourself as member who can **Receive results** from the dropdown list. +Create and manage the collaboration, assign a different member to query the data, and assign a different member to receive results | + 1. Select the member who can **Run queries** from the dropdown list. + 2. Select the member who can **Receive results** from the dropdown list. + + 2. View the member abilities under **ID resolution using AWS Entity Resolution**. + + 3. Choose **Next**. + + 6. For **Step 3: Configure payment** , do the following: + + 1. For **Analysis using queries** , take one of the following actions based on your goal. + +Your goal | Recommended action +---|--- +Assign the member who can **Run queries** to be the member who pays for the query compute costs | Leave the default setting of the member who will **Pay for queries** is the **Same as who runs queries**. +Assign a different member to pay for the query compute costs | Select the member who will **Pay for queries** from the dropdown list. + + 2. View the member payment abilities under **ML modeling using purpose-build workflows**. + + 3. View the member payment abilities under **ID resolution using AWS Entity Resolution**. + + 4. Choose **Next**. + + 7. For **Step 4: Configure membership** , do the following: + + 1. Choose one option: + +Option | Result +---|---