@aws-cdk/aws-glue-alpha 2.263.0-alpha.0 → 2.265.0-alpha.0

package/.warnings.jsii.js

@@ -1,4 +1,26 @@
-const VALIDATORS = { _aws_cdk_aws_glue_alpha_ConnectionOptions: function _aws_cdk_aws_glue_alpha_ConnectionOptions(p) {
+const VALIDATORS = { _aws_cdk_aws_glue_alpha_CatalogEncryptionOptions: function _aws_cdk_aws_glue_alpha_CatalogEncryptionOptions(p) {
+        if (p == null)
+            return;
+        visitedObjects.add(p);
+        try {
+            if (!visitedObjects.has(p.connectionPasswordEncryption))
+                module.exports._aws_cdk_aws_glue_alpha_ConnectionPasswordEncryption(p.connectionPasswordEncryption);
+        }
+        finally {
+            visitedObjects.delete(p);
+        }
+    }, _aws_cdk_aws_glue_alpha_CatalogProps: function _aws_cdk_aws_glue_alpha_CatalogProps(p) {
+        if (p == null)
+            return;
+        visitedObjects.add(p);
+        try {
+            if (!visitedObjects.has(p.connectionPasswordEncryption))
+                module.exports._aws_cdk_aws_glue_alpha_ConnectionPasswordEncryption(p.connectionPasswordEncryption);
+        }
+        finally {
+            visitedObjects.delete(p);
+        }
+    }, _aws_cdk_aws_glue_alpha_ConnectionOptions: function _aws_cdk_aws_glue_alpha_ConnectionOptions(p) {
         if (p == null)
             return;
         visitedObjects.add(p);

package/README.md

@@ -190,7 +190,7 @@ new glue.PySparkStreamingJob(stack, 'PySparkStreamingJob', {
 
 The flexible execution class is appropriate for non-urgent jobs such as
 pre-production jobs, testing, and one-time data loads. Flexible jobs default
-to Glue version 3.0 and worker type `G_2X`. The following best practice
+to Glue version 5.0 and worker type `G_2X`. The following best practice
 features are enabled by default:
 `—enable-metrics, —enable-spark-ui, —enable-continuous-cloudwatch-log`
 
@@ -458,6 +458,13 @@ new glue.Connection(this, "RdsConnection", {
 });
 ```
 
+Connection `properties` are emitted verbatim into the CloudFormation template, so
+any credential placed there in plaintext is stored in plaintext in the template,
+`cdk.out`, and source control. Reference a Secrets Manager secret through
+`SECRET_ID` (as above) instead. If a property key looks like a credential (for
+example `PASSWORD`, `SECRET`, or `TOKEN`) and holds a plaintext literal, the
+construct emits a synthesis-time warning.
+
 If you need to use a connection type that doesn't exist as a static member on `ConnectionType`, you can instantiate a `ConnectionType` object, e.g: `new glue.ConnectionType('NEW_TYPE')`.
 
 See [Adding a Connection to Your Data Store](https://docs.aws.amazon.com/glue/latest/dg/populate-add-connection.html) and [Connection Structure](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-catalog-connections.html#aws-glue-api-catalog-connections-Connection) documentation for more information on the supported data stores and their configurations.
@@ -494,6 +501,158 @@ new glue.SecurityConfiguration(this, 'MySecurityConfiguration', {
 
 See [documentation](https://docs.aws.amazon.com/glue/latest/dg/encryption-security-configuration.html) for more info for Glue encrypting data written by Crawlers, Jobs, and Development Endpoints.
 
+## Catalog
+
+The Glue Data Catalog is a persistent metadata store for your data assets. Every
+account has an implicit, account-wide catalog that always exists, and you can also
+create additional catalogs as `AWS::Glue::Catalog` resources (for example, to
+federate to another metastore).
+
+A catalog's encryption is fixed when the catalog is created: a catalog either
+carries encryption settings or it does not. This keeps its configuration easy to
+reason about — there are no mutation methods that change encryption after the fact.
+
+### The account-wide catalog
+
+Use `Catalog.forAccount(scope)` to obtain the implicit account catalog. It is not
+a CloudFormation resource — it always exists. Repeated calls within the same stack
+return the same instance:
+
+```ts
+const catalog = glue.Catalog.forAccount(this);
+```
+
+To configure Data Catalog encryption for the account, use
+`Catalog.encryptAccount(scope, options)`:
+
+```ts
+declare const key: kms.Key;
+glue.Catalog.encryptAccount(this, {
+  encryptionAtRest: glue.DataCatalogEncryptionAtRest.kms(key),
+});
+```
+
+Because encryption is fixed at construction, `encryptAccount` must be called
+*before* the account catalog is first used in the stack — before any
+`Catalog.forAccount(this)` call, and before any `Database` that uses the account
+catalog. Calling it after the account catalog has been materialized throws.
+
+The account catalog's encryption is an account- and region-wide setting, managed
+through the singleton `PutDataCatalogEncryptionSettings` API. Configure it in
+exactly one stack. Configuring it from multiple stacks in the same account and
+region makes those stacks overwrite one another at deploy time, and the result is
+order-dependent. Unlike duplicate settings within a single stack (which
+CloudFormation rejects), this cross-stack conflict is not caught at synthesis
+time, because each stack synthesizes to its own template.
+
+### Creating a catalog
+
+To create a new catalog resource, use the `Catalog` constructor. Encryption is
+configured through the `encryptionAtRest` and `connectionPasswordEncryption` props:
+
+```ts
+new glue.Catalog(this, 'MyCatalog', {
+  catalogName: 'my-catalog',
+  description: 'my catalog description',
+});
+```
+
+### Encryption at rest
+
+Configure Data Catalog encryption at rest through the `encryptionAtRest` option
+(on `Catalog.encryptAccount`, the `Catalog` constructor, or the import factories).
+It accepts a `DataCatalogEncryptionAtRest` describing the mode:
+
+```ts
+declare const key: kms.Key;
+
+// SSE-KMS with a customer-managed key
+glue.Catalog.encryptAccount(this, {
+  encryptionAtRest: glue.DataCatalogEncryptionAtRest.kms(key),
+});
+
+// SSE-KMS with an AWS-managed key (omit the key)
+new glue.Catalog(this, 'ManagedKeyCatalog', {
+  catalogName: 'managed-key-catalog',
+  encryptionAtRest: glue.DataCatalogEncryptionAtRest.kms(),
+});
+
+// Disable encryption at rest
+new glue.Catalog(this, 'PlaintextCatalog', {
+  catalogName: 'plaintext-catalog',
+  encryptionAtRest: glue.DataCatalogEncryptionAtRest.disabled(),
+});
+```
+
+When you use `SSE-KMS-WITH-SERVICE-ROLE`, AWS Glue accesses the KMS key through a
+service role you provide. If you pass a customer-managed key, the role is
+automatically granted the permissions it needs to encrypt and decrypt catalog data:
+
+```ts
+import * as iam from 'aws-cdk-lib/aws-iam';
+declare const key: kms.Key;
+declare const role: iam.IRole;
+glue.Catalog.encryptAccount(this, {
+  encryptionAtRest: glue.DataCatalogEncryptionAtRest.kmsWithServiceRole(role, key),
+});
+```
+
+The customer-managed key, when configured, is exposed on the catalog as
+`encryptionKey` (and the connection-password key as `connectionPasswordKey`), so
+you can reference it to grant additional access. It is undefined when encryption is
+disabled or an AWS-managed key is used.
+
+### Connection password encryption
+
+Independently from encryption at rest, the Data Catalog can encrypt the passwords
+stored in connection properties. Configure it through the
+`connectionPasswordEncryption` option:
+
+```ts
+declare const key: kms.Key;
+glue.Catalog.encryptAccount(this, {
+  connectionPasswordEncryption: {
+    kmsKey: key,
+    // Whether GetConnection/GetConnections return the password encrypted (default: true)
+    returnConnectionPasswordEncrypted: true,
+  },
+});
+```
+
+The two encryption blocks are independent: enabling one does not require the other,
+and each may use a different KMS key. The customer-managed key for connection
+passwords is exposed as `connectionPasswordKey`.
+
+### Importing a catalog
+
+You can import an existing catalog by ARN or by id. An imported catalog is a pure
+identity handle — it emits no resources and does not manage the catalog's
+encryption:
+
+```ts
+const byId = glue.Catalog.fromCatalogId(this, 'ById', 'my-catalog-id');
+const byArn = glue.Catalog.fromCatalogArn(this, 'ByArn', 'arn:aws:glue:us-east-1:123456789012:catalog/my-catalog-id');
+```
+
+To manage the Data Catalog encryption of a catalog you did not create in this
+stack, add a `CfnDataCatalogEncryptionSettings` resource targeting its id
+directly. Do this from exactly one stack: like the account catalog, a catalog has
+a single encryption configuration, so two settings resources targeting the same id
+race to overwrite one another at deploy time. Within a single stack this is caught
+by CloudFormation template validation (E3019, duplicate primary identifiers);
+across stacks it is not, since each stack synthesizes to its own template.
+
+```ts
+import { CfnDataCatalogEncryptionSettings } from 'aws-cdk-lib/aws-glue';
+
+new CfnDataCatalogEncryptionSettings(this, 'Encryption', {
+  catalogId: 'my-catalog-id',
+  dataCatalogEncryptionSettings: {
+    encryptionAtRest: { catalogEncryptionMode: 'SSE-KMS' },
+  },
+});
+```
+
 ## Database
 
 A `Database` is a logical grouping of `Tables` in the Glue Catalog.
@@ -505,6 +664,19 @@ new glue.Database(this, 'MyDatabase', {
 });
 ```
 
+Because a database is a container for tables and their metadata, it is retained
+by default when removed from the stack, to avoid accidental data loss. Set
+`removalPolicy` to `RemovalPolicy.DESTROY` to have it deleted instead:
+
+```ts
+import { RemovalPolicy } from 'aws-cdk-lib';
+
+new glue.Database(this, 'MyDatabase', {
+  databaseName: 'my_database',
+  removalPolicy: RemovalPolicy.DESTROY,
+});
+```
+
 ## Table
 
 A Glue table describes a table of data in S3: its structure (column names and types), location of data (S3 objects with a common prefix in a S3 bucket), and format for the files (Json, Avro, Parquet, etc.):
@@ -877,6 +1049,8 @@ new glue.ExternalTable(this, 'MyTable', {
 
 ## [Encryption](https://docs.aws.amazon.com/athena/latest/ug/encryption.html)
 
+When the table creates its own S3 bucket (i.e. you do not pass an explicit `bucket`), that bucket enforces SSL: a bucket policy denies any request made over plain HTTP. If you provide your own bucket, enabling `enforceSSL` on it is your responsibility.
+
 You can enable encryption on a Table's data:
 
 * [S3Managed](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingServerSideEncryption.html) - (default) Server side encryption (`SSE-S3`) with an Amazon S3-managed key.

package/awslint.json

@@ -108,6 +108,7 @@
     "interface-extends-ref:@aws-cdk/aws-glue-alpha.IJob",
     "interface-extends-ref:@aws-cdk/aws-glue-alpha.ISecurityConfiguration",
     "interface-extends-ref:@aws-cdk/aws-glue-alpha.ITable",
-    "interface-extends-ref:@aws-cdk/aws-glue-alpha.IWorkflow"
+    "interface-extends-ref:@aws-cdk/aws-glue-alpha.IWorkflow",
+    "prefer-ref-interface:@aws-cdk/aws-glue-alpha.DatabaseProps.catalog"
   ]
 }

package/lib/catalog.d.ts

@@ -0,0 +1,259 @@
+import type { CatalogReference, ICatalogRef } from 'aws-cdk-lib/aws-glue';
+import type * as iam from 'aws-cdk-lib/aws-iam';
+import type * as kms from 'aws-cdk-lib/aws-kms';
+import type { IResource } from 'aws-cdk-lib/core';
+import { Resource } from 'aws-cdk-lib/core';
+import type { Construct } from 'constructs';
+/**
+ * The encryption-at-rest mode for a Glue Data Catalog.
+ *
+ * @see https://docs.aws.amazon.com/glue/latest/webapi/API_EncryptionAtRest.html#Glue-Type-EncryptionAtRest-CatalogEncryptionMode
+ */
+export declare enum CatalogEncryptionMode {
+    /**
+     * Encryption at rest is disabled.
+     */
+    DISABLED = "DISABLED",
+    /**
+     * Server-side encryption (SSE) with an AWS KMS key.
+     */
+    SSE_KMS = "SSE-KMS",
+    /**
+     * Server-side encryption (SSE) with an AWS KMS key, using a service role that
+     * AWS Glue assumes to access the key on your behalf.
+     */
+    SSE_KMS_WITH_SERVICE_ROLE = "SSE-KMS-WITH-SERVICE-ROLE"
+}
+/**
+ * Encryption-at-rest configuration for a Glue Data Catalog.
+ *
+ * The Data Catalog encryption at rest and the connection password encryption
+ * are independent: enabling one does not require the other, and each may use a
+ * different KMS key.
+ *
+ * @see https://docs.aws.amazon.com/glue/latest/webapi/API_EncryptionAtRest.html
+ */
+export declare class DataCatalogEncryptionAtRest {
+    /**
+     * Disable encryption at rest for the Data Catalog.
+     */
+    static disabled(): DataCatalogEncryptionAtRest;
+    /**
+     * Encrypt the Data Catalog at rest with an AWS KMS key.
+     *
+     * @param key the KMS key to use. If omitted, an AWS-managed key is used and
+     * the key is not exposed as a grantable resource.
+     */
+    static kms(key?: kms.IKey): DataCatalogEncryptionAtRest;
+    /**
+     * Encrypt the Data Catalog at rest with an AWS KMS key, accessed through a
+     * service role that AWS Glue assumes on your behalf.
+     *
+     * When a customer-managed `key` is provided, the `role` is automatically
+     * granted `kms:Encrypt`/`kms:Decrypt`/`kms:GenerateDataKey*` on it.
+     *
+     * @param role the service role that AWS Glue assumes to access the key.
+     * @param key the KMS key to use. If omitted, an AWS-managed key is used and
+     * the key is not exposed as a grantable resource.
+     */
+    static kmsWithServiceRole(role: iam.IRole, key?: kms.IKey): DataCatalogEncryptionAtRest;
+    /**
+     * The encryption mode.
+     */
+    readonly mode: CatalogEncryptionMode;
+    /**
+     * The customer-managed KMS key used for encryption at rest, if any.
+     */
+    readonly kmsKey?: kms.IKeyRef;
+    /**
+     * The service role that AWS Glue assumes to access the KMS key, if any.
+     */
+    readonly serviceRole?: iam.IRole;
+    private constructor();
+}
+/**
+ * Connection-password encryption configuration for a Glue Data Catalog.
+ *
+ * When enabled, the Data Catalog encrypts the password as part of
+ * `CreateConnection` or `UpdateConnection` and stores it in the
+ * `ENCRYPTED_PASSWORD` field of the connection properties. This is independent
+ * from catalog encryption at rest, and may use a different KMS key.
+ *
+ * @see https://docs.aws.amazon.com/glue/latest/webapi/API_ConnectionPasswordEncryption.html
+ */
+export interface ConnectionPasswordEncryption {
+    /**
+     * The KMS key used to encrypt connection passwords.
+     *
+     * @default - an AWS-managed key is used and the key is not exposed as a grantable resource.
+     */
+    readonly kmsKey?: kms.IKeyRef;
+    /**
+     * Whether passwords remain encrypted in the responses of `GetConnection` and
+     * `GetConnections`. This takes effect independently from catalog encryption.
+     *
+     * @default true
+     */
+    readonly returnConnectionPasswordEncrypted?: boolean;
+}
+/**
+ * Encryption configuration for a Glue Data Catalog.
+ *
+ * Encryption is fixed at construction: a catalog either carries encryption
+ * settings or it does not, which keeps its configuration easy to reason about
+ * and avoids order-dependent mutation after the catalog is created.
+ */
+export interface CatalogEncryptionOptions {
+    /**
+     * Encryption-at-rest configuration for the catalog.
+     *
+     * @default - encryption at rest is not managed by CDK (the catalog default applies)
+     */
+    readonly encryptionAtRest?: DataCatalogEncryptionAtRest;
+    /**
+     * Connection-password encryption configuration for the catalog.
+     *
+     * @default - connection-password encryption is not managed by CDK
+     */
+    readonly connectionPasswordEncryption?: ConnectionPasswordEncryption;
+}
+/**
+ * A Glue Data Catalog, either the implicit account-wide catalog or one created
+ * as an `AWS::Glue::Catalog` resource.
+ */
+export interface ICatalog extends IResource, ICatalogRef {
+    /**
+     * The id of the catalog (for the account-wide catalog, the AWS account id).
+     * @attribute
+     */
+    readonly catalogId: string;
+    /**
+     * The ARN of the catalog.
+     * @attribute
+     */
+    readonly catalogArn: string;
+    /**
+     * The customer-managed KMS key used for the catalog's encryption at rest, if
+     * one was configured.
+     *
+     * Undefined when encryption is disabled or an AWS-managed key is used. Grant
+     * access to it via `KeyGrants`, e.g.
+     * `if (catalog.encryptionKey) { KeyGrants.fromKey(catalog.encryptionKey).encrypt(grantee); }`.
+     */
+    readonly encryptionKey?: kms.IKeyRef;
+    /**
+     * The customer-managed KMS key used to encrypt connection passwords, if one
+     * was configured.
+     *
+     * Undefined when password encryption uses an AWS-managed key or is not
+     * configured. Grant access to it via `KeyGrants`, e.g.
+     * `if (catalog.connectionPasswordKey) { KeyGrants.fromKey(catalog.connectionPasswordKey).encrypt(grantee); }`.
+     */
+    readonly connectionPasswordKey?: kms.IKeyRef;
+}
+/**
+ * Base class for all `ICatalog` implementations. Materializes the single
+ * `CfnDataCatalogEncryptionSettings` resource (targeting its own `catalogId`)
+ * from the encryption options supplied at construction. Encryption is fixed at
+ * construction, so a catalog either carries settings or it does not.
+ */
+export declare abstract class CatalogBase extends Resource implements ICatalog {
+    abstract readonly catalogId: string;
+    abstract readonly catalogArn: string;
+    private _encryptionKey?;
+    private _connectionPasswordKey?;
+    get encryptionKey(): kms.IKeyRef | undefined;
+    get connectionPasswordKey(): kms.IKeyRef | undefined;
+    get catalogRef(): CatalogReference;
+    /**
+     * Emit the catalog's encryption settings from the options fixed at
+     * construction. Subclasses call this once, after `catalogId`/`catalogArn` are
+     * assigned. When neither block is configured, no resource is emitted, avoiding
+     * an empty settings resource that would reset the catalog on deploy.
+     */
+    protected configureEncryption(options: CatalogEncryptionOptions): void;
+}
+/**
+ * Construction properties for a `Catalog`.
+ */
+export interface CatalogProps extends CatalogEncryptionOptions {
+    /**
+     * The name of the catalog.
+     */
+    readonly catalogName: string;
+    /**
+     * A description of the catalog.
+     *
+     * @default - no description
+     */
+    readonly description?: string;
+}
+/**
+ * A Glue Data Catalog.
+ *
+ * Use `Catalog.forAccount(scope)` to obtain the implicit account-wide catalog,
+ * `Catalog.encryptAccount(scope, options)` to configure its Data Catalog
+ * encryption, or `new Catalog(...)` to create an `AWS::Glue::Catalog` resource.
+ */
+export declare class Catalog extends CatalogBase {
+    /** Uniquely identifies this class. */
+    static readonly PROPERTY_INJECTION_ID: string;
+    /**
+     * Obtain the implicit, account-wide Data Catalog.
+     *
+     * The account catalog is not a CloudFormation resource; it always exists. This
+     * returns a stack-scoped singleton, so repeated calls within the same stack
+     * return the same instance.
+     *
+     * This returns the account catalog without managing its encryption. To
+     * configure Data Catalog encryption for the account, use
+     * `Catalog.encryptAccount(scope, options)` instead - it must be called before
+     * the account catalog is first used in the stack.
+     */
+    static forAccount(scope: Construct): ICatalog;
+    /**
+     * Configure Data Catalog encryption for the implicit, account-wide catalog and
+     * return it.
+     *
+     * The account catalog's encryption is an account/region-wide setting, managed
+     * through the singleton `PutDataCatalogEncryptionSettings` API. Because
+     * encryption is fixed at construction, it must be configured before the
+     * account catalog is first used in the stack: calling this after the account
+     * catalog has already been materialized (for example by `Catalog.forAccount`,
+     * or by a `Database` that uses the account catalog) throws.
+     *
+     * Configure it in exactly one stack. Configuring it from multiple stacks in the
+     * same account and region makes those stacks overwrite one another at deploy
+     * time, and the result is order-dependent. Unlike duplicate settings within a
+     * single stack (which CloudFormation rejects), this cross-stack conflict is not
+     * caught at synthesis time, because each stack synthesizes to its own template.
+     */
+    static encryptAccount(scope: Construct, options: CatalogEncryptionOptions): ICatalog;
+    /**
+     * Import an existing catalog by its ARN.
+     *
+     * The ARN must be a Glue catalog ARN, either the account-wide catalog
+     * (`arn:aws:glue:<region>:<account>:catalog`, whose id is the account) or a
+     * named catalog (`arn:aws:glue:<region>:<account>:catalog/<name>`, whose id is
+     * the name).
+     *
+     * The imported catalog is a pure identity handle and does not manage the
+     * catalog's encryption. To manage an existing catalog's Data Catalog
+     * encryption, add a `CfnDataCatalogEncryptionSettings` resource targeting its
+     * id.
+     */
+    static fromCatalogArn(scope: Construct, id: string, catalogArn: string): ICatalog;
+    /**
+     * Import an existing catalog by its id.
+     *
+     * The imported catalog is a pure identity handle and does not manage the
+     * catalog's encryption. To manage an existing catalog's Data Catalog
+     * encryption, add a `CfnDataCatalogEncryptionSettings` resource targeting its
+     * id.
+     */
+    static fromCatalogId(scope: Construct, id: string, catalogId: string): ICatalog;
+    readonly catalogId: string;
+    readonly catalogArn: string;
+    private readonly resource;
+    constructor(scope: Construct, id: string, props: CatalogProps);
+}