@pulumi/aws
Version:
A Pulumi package for creating and managing Amazon Web Services (AWS) cloud resources.
247 lines • 13.3 kB
JavaScript
;
// *** WARNING: this file was generated by pulumi-language-nodejs. ***
// *** Do not edit by hand unless you're certain you know what you are doing! ***
Object.defineProperty(exports, "__esModule", { value: true });
exports.Permissions = void 0;
const pulumi = require("@pulumi/pulumi");
const utilities = require("../utilities");
/**
* Grants permissions to the principal to access metadata in the Data Catalog and data organized in underlying data storage such as Amazon S3. Permissions are granted to a principal, in a Data Catalog, relative to a Lake Formation resource, which includes the Data Catalog, databases, tables, LF-tags, and LF-tag policies. For more information, see [Security and Access Control to Metadata and Data in Lake Formation](https://docs.aws.amazon.com/lake-formation/latest/dg/security-data-access.html).
*
* !> **WARNING:** Lake Formation permissions are not in effect by default within AWS. Using this resource will not secure your data and will result in errors if you do not change the security settings for existing resources and the default security settings for new resources. See Default Behavior and `IAMAllowedPrincipals` for additional details.
*
* > **NOTE:** In general, the `principal` should _NOT_ be a Lake Formation administrator or the entity (e.g., IAM role) that is running the deployment. Administrators have implicit permissions. These should be managed by granting or not granting administrator rights using `aws.lakeformation.DataLakeSettings`, _not_ with this resource.
*
* ## Default Behavior and `IAMAllowedPrincipals`
*
* **_Lake Formation permissions are not in effect by default within AWS._** `IAMAllowedPrincipals` (i.e., `IAM_ALLOWED_PRINCIPALS`) conflicts with individual Lake Formation permissions (i.e., non-`IAMAllowedPrincipals` permissions), will cause unexpected behavior, and may result in errors.
*
* When using Lake Formation, choose ONE of the following options as they are mutually exclusive:
*
* 1. Use this resource (`aws.lakeformation.Permissions`), change the default security settings using `aws.lakeformation.DataLakeSettings`, and remove existing `IAMAllowedPrincipals` permissions
* 2. Use `IAMAllowedPrincipals` without `aws.lakeformation.Permissions`
*
* This example shows removing the `IAMAllowedPrincipals` default security settings and making the caller a Lake Formation admin. Since `createDatabaseDefaultPermissions` and `createTableDefaultPermissions` are not set in the `aws.lakeformation.DataLakeSettings` resource, they are cleared.
*
* ```typescript
* import * as pulumi from "@pulumi/pulumi";
* import * as aws from "@pulumi/aws";
*
* const current = aws.getCallerIdentity({});
* const currentGetSessionContext = current.then(current => aws.iam.getSessionContext({
* arn: current.arn,
* }));
* const test = new aws.lakeformation.DataLakeSettings("test", {admins: [currentGetSessionContext.then(currentGetSessionContext => currentGetSessionContext.issuerArn)]});
* ```
*
* To remove existing `IAMAllowedPrincipals` permissions, use the [AWS Lake Formation Console](https://console.aws.amazon.com/lakeformation/) or [AWS CLI](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lakeformation/batch-revoke-permissions.html).
*
* `IAMAllowedPrincipals` is a hook to maintain backwards compatibility with AWS Glue. `IAMAllowedPrincipals` is a pseudo-entity group that acts like a Lake Formation principal. The group includes any IAM users and roles that are allowed access to your Data Catalog resources by your IAM policies.
*
* This is Lake Formation's default behavior:
*
* * Lake Formation grants `Super` permission to `IAMAllowedPrincipals` on all existing AWS Glue Data Catalog resources.
* * Lake Formation enables "Use only IAM access control" for new Data Catalog resources.
*
* For more details, see [Changing the Default Security Settings for Your Data Lake](https://docs.aws.amazon.com/lake-formation/latest/dg/change-settings.html).
*
* ### Problem Using `IAMAllowedPrincipals`
*
* AWS does not support combining `IAMAllowedPrincipals` permissions and non-`IAMAllowedPrincipals` permissions. Doing so results in unexpected permissions and behaviors. For example, this configuration grants a user `SELECT` on a column in a table.
*
* ```typescript
* import * as pulumi from "@pulumi/pulumi";
* import * as aws from "@pulumi/aws";
*
* const example = new aws.glue.CatalogDatabase("example", {name: "sadabate"});
* const exampleCatalogTable = new aws.glue.CatalogTable("example", {
* name: "abelt",
* databaseName: test.name,
* storageDescriptor: {
* columns: [{
* name: "event",
* type: "string",
* }],
* },
* });
* const examplePermissions = new aws.lakeformation.Permissions("example", {
* permissions: ["SELECT"],
* principal: "arn:aws:iam:us-east-1:123456789012:user/SanHolo",
* tableWithColumns: {
* databaseName: exampleCatalogTable.databaseName,
* name: exampleCatalogTable.name,
* columnNames: ["event"],
* },
* });
* ```
*
* The resulting permissions depend on whether the table had `IAMAllowedPrincipals` (IAP) permissions or not.
*
* | Result With IAP | Result Without IAP |
* | ---- | ---- |
* | `SELECT` column wildcard (i.e., all columns) | `SELECT` on `"event"` (as expected) |
*
* ## `ALLIAMPrincipals` group
*
* AllIAMPrincipals is a pseudo-entity group that acts like a Lake Formation principal. The group includes all IAMs in the account that is defined.
*
* resource "aws.lakeformation.Permissions" "example" {
* permissions = ["SELECT"]
* principal = "123456789012:IAMPrincipals"
*
* tableWithColumns {
* databaseName = aws_glue_catalog_table.example.database_name
* name = aws_glue_catalog_table.example.name
* columnNames = ["event"]
* }
* }
*
* ## Using Lake Formation Permissions
*
* Lake Formation grants implicit permissions to data lake administrators, database creators, and table creators. These implicit permissions cannot be revoked _per se_. If this resource reads implicit permissions, it will attempt to revoke them, which causes an error when the resource is destroyed.
*
* There are two ways to avoid these errors. First, and the way we recommend, is to avoid using this resource with principals that have implicit permissions. A second, error-prone option, is to grant explicit permissions (and `permissionsWithGrantOption`) to "overwrite" a principal's implicit permissions, which you can then revoke with this resource. For more information, see [Implicit Lake Formation Permissions](https://docs.aws.amazon.com/lake-formation/latest/dg/implicit-permissions.html).
*
* If the `principal` is also a data lake administrator, AWS grants implicit permissions that can cause errors using this resource. For example, AWS implicitly grants a `principal`/administrator `permissions` and `permissionsWithGrantOption` of `ALL`, `ALTER`, `DELETE`, `DESCRIBE`, `DROP`, `INSERT`, and `SELECT` on a table. If you use this resource to explicitly grant the `principal`/administrator `permissions` but _not_ `permissionsWithGrantOption` of `ALL`, `ALTER`, `DELETE`, `DESCRIBE`, `DROP`, `INSERT`, and `SELECT` on the table, this resource will read the implicit `permissionsWithGrantOption` and attempt to revoke them when the resource is destroyed. Doing so will cause an `InvalidInputException: No permissions revoked` error because you cannot revoke implicit permissions _per se_. To workaround this problem, explicitly grant the `principal`/administrator `permissions` _and_ `permissionsWithGrantOption`, which can then be revoked. Similarly, granting a `principal`/administrator permissions on a table with columns and providing `columnNames`, will result in a `InvalidInputException: Permissions modification is invalid` error because you are narrowing the implicit permissions. Instead, set `wildcard` to `true` and remove the `columnNames`.
*
* ## Example Usage
*
* ### Grant Permissions For A Lake Formation S3 Resource
*
* ```typescript
* import * as pulumi from "@pulumi/pulumi";
* import * as aws from "@pulumi/aws";
*
* const example = new aws.lakeformation.Permissions("example", {
* principal: workflowRole.arn,
* permissions: ["DATA_LOCATION_ACCESS"],
* dataLocation: {
* arn: exampleAwsLakeformationResource.arn,
* },
* });
* ```
*
* ### Grant Permissions For A Glue Catalog Database
*
* ```typescript
* import * as pulumi from "@pulumi/pulumi";
* import * as aws from "@pulumi/aws";
*
* const example = new aws.lakeformation.Permissions("example", {
* principal: workflowRole.arn,
* permissions: [
* "CREATE_TABLE",
* "ALTER",
* "DROP",
* ],
* database: {
* name: exampleAwsGlueCatalogDatabase.name,
* catalogId: "110376042874",
* },
* });
* ```
*
* ### Grant Permissions Using Tag-Based Access Control
*
* ```typescript
* import * as pulumi from "@pulumi/pulumi";
* import * as aws from "@pulumi/aws";
*
* const test = new aws.lakeformation.Permissions("test", {
* principal: salesRole.arn,
* permissions: [
* "CREATE_TABLE",
* "ALTER",
* "DROP",
* ],
* lfTagPolicy: {
* resourceType: "DATABASE",
* expressions: [
* {
* key: "Team",
* values: ["Sales"],
* },
* {
* key: "Environment",
* values: [
* "Dev",
* "Production",
* ],
* },
* ],
* },
* });
* ```
*/
class Permissions extends pulumi.CustomResource {
/**
* Get an existing Permissions resource's state with the given name, ID, and optional extra
* properties used to qualify the lookup.
*
* @param name The _unique_ name of the resulting resource.
* @param id The _unique_ provider ID of the resource to lookup.
* @param state Any extra arguments used during the lookup.
* @param opts Optional settings to control the behavior of the CustomResource.
*/
static get(name, id, state, opts) {
return new Permissions(name, state, { ...opts, id: id });
}
/**
* Returns true if the given object is an instance of Permissions. This is designed to work even
* when multiple copies of the Pulumi SDK have been loaded into the same process.
*/
static isInstance(obj) {
if (obj === undefined || obj === null) {
return false;
}
return obj['__pulumiType'] === Permissions.__pulumiType;
}
constructor(name, argsOrState, opts) {
let resourceInputs = {};
opts = opts || {};
if (opts.id) {
const state = argsOrState;
resourceInputs["catalogId"] = state?.catalogId;
resourceInputs["catalogResource"] = state?.catalogResource;
resourceInputs["dataCellsFilter"] = state?.dataCellsFilter;
resourceInputs["dataLocation"] = state?.dataLocation;
resourceInputs["database"] = state?.database;
resourceInputs["lfTag"] = state?.lfTag;
resourceInputs["lfTagPolicy"] = state?.lfTagPolicy;
resourceInputs["permissions"] = state?.permissions;
resourceInputs["permissionsWithGrantOptions"] = state?.permissionsWithGrantOptions;
resourceInputs["principal"] = state?.principal;
resourceInputs["region"] = state?.region;
resourceInputs["table"] = state?.table;
resourceInputs["tableWithColumns"] = state?.tableWithColumns;
}
else {
const args = argsOrState;
if (args?.permissions === undefined && !opts.urn) {
throw new Error("Missing required property 'permissions'");
}
if (args?.principal === undefined && !opts.urn) {
throw new Error("Missing required property 'principal'");
}
resourceInputs["catalogId"] = args?.catalogId;
resourceInputs["catalogResource"] = args?.catalogResource;
resourceInputs["dataCellsFilter"] = args?.dataCellsFilter;
resourceInputs["dataLocation"] = args?.dataLocation;
resourceInputs["database"] = args?.database;
resourceInputs["lfTag"] = args?.lfTag;
resourceInputs["lfTagPolicy"] = args?.lfTagPolicy;
resourceInputs["permissions"] = args?.permissions;
resourceInputs["permissionsWithGrantOptions"] = args?.permissionsWithGrantOptions;
resourceInputs["principal"] = args?.principal;
resourceInputs["region"] = args?.region;
resourceInputs["table"] = args?.table;
resourceInputs["tableWithColumns"] = args?.tableWithColumns;
}
opts = pulumi.mergeOptions(utilities.resourceOptsDefaults(), opts);
super(Permissions.__pulumiType, name, resourceInputs, opts);
}
}
exports.Permissions = Permissions;
/** @internal */
Permissions.__pulumiType = 'aws:lakeformation/permissions:Permissions';
//# sourceMappingURL=permissions.js.map