Updating cross-account data sharing version settings - Amazon Lake Formation
Main differences between cross-account version settingsOptimize Amazon RAM resource sharesEnable Amazon RAM shares via TBAC or share resources directly to principalsTo enable the new version
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Updating cross-account data sharing version settings

From time to time, Amazon Lake Formation updates the cross-account data sharing settings to distinguish the changes made to the Amazon RAM usage and to support updates made to the cross-account data sharing feature. When Lake Formation does this, it creates a new version of the Cross account version settings.

Main differences between cross-account version settings

For more information about how cross-account data sharing works under different Cross account version settings, see the following sections.

Note

To share data with another account, the grantor must have AWSLakeFormationCrossAccountManager managed IAM policy permissions. This is a prerequisite for all versions.

Updating the Cross account version settings does not impact the permissions the recipient has on shared resources. This is applicable when updating from version 1 to version 2, version 2 to version 3, and version 1 to version 3. See the considerations listed below when updating versions.

Version 1

Named resource method: Maps each cross-account Lake Formation permission grant to one Amazon RAM resource share. User (grantor role or principal) does not require additional permissions.

LF-TBAC method: Cross-account Lake Formation permission grants don't use Amazon RAM to share data. User must have glue:PutResourcePolicy permission.

Benefits from updating versions: Initial version - not applicable.

Considerations when updating versions: Initial version - not applicable

Version 2

Named resource method: Optimizes the number of Amazon RAM resource shares by mapping multiple cross-account permission grants with one Amazon RAM resource share. User does not require additional permissions.

LF-TBAC method: Cross-account Lake Formation permission grants don't use Amazon RAM to share data. User must have glue:PutResourcePolicy permission.

Benefits from updating versions: Scalable cross-account setup by optimal utilization of Amazon RAM capacity.

Considerations when updating versions: Users who want to grant cross-account Lake Formation permissions must have the permissions in the AWSLakeFormationCrossAccountManager Amazon managed policy. Otherwise, you need to have ram:AssociateResourceShare and ram:DisassociateResourceShare permissions to successfully share resources with another account.

Version 3

Named resource method: Optimizes the number of Amazon RAM resource shares by mapping multiple cross-account permission grants with one Amazon RAM resource share. User does not require additional permissions.

LF-TBAC method: Lake Formation uses Amazon RAM for cross-account grants. User must add glue:ShareResource statement to the glue:PutResourcePolicy permission. The recipient must accept resource share invitations from Amazon RAM.

Benefits from updating versions: Supports the following capabilities:

  • Allows sharing resources explicitly with an IAM principal in an external account.

    For more information, see Granting and revoking permissions on Data Catalog resources.

  • Enables cross-account shares using LF-TBAC method to Organizations or organizational units (OUs).

  • Removes the overhead of maintaining additional Amazon Glue policies for cross-account grants.

Considerations when updating versions: If the grantor uses a version lower than version 3, and the recipient is using version 3 or higher, the grantor receives the following error message: "Invalid cross account grant request. Consumer account has opt-in to cross account version: v3. Please update CrossAccountVersion in DataLakeSetting to minimal version v3 (Service: AmazonDataCatalog; Status Code: 400; Error Code: InvalidInputException)". However, if the grantor uses version 3 and the recipient is using version 1 or version 2, the cross-account grants go through successfully.

To share resources directly with IAM principals in another account, only the grantor needs to use version 3.

Cross-account grants made using LF-TBAC method require users to have an Amazon Glue Data Catalog resource policy in the account. When you update to version 3, LF-TBAC grants uses Amazon RAM. To allow Amazon RAM based cross-account grants to succeed, you must add the glue:ShareResource statement to your existing Data Catalog resource policies as shown in the Managing cross-account permissions using both Amazon Glue and Lake Formation section.

Version 4

The grantor needs version 4 or higher to share Data Catalog resources in hybrid access mode.

Optimize Amazon RAM resource shares

New versions (version 2 and above) of cross-account grants optimally utilize Amazon RAM capacity to maximize cross account usage. When you share a resource with an external Amazon Web Services account or an IAM principal, Lake Formation may create a new resource share or associate the resource with an existing share. By associating with existing shares, Lake Formation reduces the number of resource share invitations a consumer needs to accept.

Enable Amazon RAM shares via TBAC or share resources directly to principals

To share resources directly with IAM principals in another account or to enable TBAC cross-account shares to Organizations or organizational units, you need to update the Cross account version settings to version 3. For more information about Amazon RAM resource limits, see Cross-account data sharing best practices and considerations.

Required permissions for updating cross-account version settings

If a cross-account permission grantor has AWSLakeFormationCrossAccountManager managed IAM policy permissions, then there is no extra permission setup required for the cross-account permission grantor role or principal. However, if the cross-account grantor is not using the managed policy, then the grantor role or principal should have following IAM permissions granted for the new version of the cross-account grant to be successful.

  
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor1",
      "Effect": "Allow",
      "Action": [
         "ram:AssociateResourceShare",
         "ram:DisassociateResourceShare",
         "ram:GetResourceShares"
       ],
     "Resource": "*",
     "Condition": {
       "StringLike": {
         "ram:ResourceShareName": "LakeFormation*"
        }
      }
    }
  ]
}

To enable the new version

Follow these steps to update Cross account version settings through the Amazon Lake Formation console or the Amazon CLI.

Console

  1. Choose Version 2, Version 3, or Version 4 under Cross account version settings on the Data catalog settings page. If you select Version 1, Lake Formation will use the default resource sharing mode.

  2. Choose Save.

Amazon Command Line Interface (Amazon CLI)

Use the put-data-lake-settings Amazon CLI command to set the CROSS_ACCOUNT_VERSION parameter. Accepted values are 1, 2, 3, and 4.

aws lakeformation put-data-lake-settings --region us-east-1 --data-lake-settings file://settings
{
    "DataLakeAdmins": [
        {
            "DataLakePrincipalIdentifier": "arn:aws:iam::111122223333:user/test"
        }
    ],
    "CreateDatabaseDefaultPermissions": [],
    "CreateTableDefaultPermissions": [],
    "Parameters": {
        "CROSS_ACCOUNT_VERSION": "3"
    }
}
Important

Once you choose Version 2 or Version 3, all new named resource grants will go through the new cross-account grant mode. To optimally use Amazon RAM capacity for your existing cross-account shares, we recommend you to revoke the grants that were made with the older version, and re-grant in the new mode.