terraconstructs 0.0.11 → 0.0.12

package/lib/aws/storage/bucket.d.ts

@@ -1,7 +1,8 @@
-import { s3Bucket, s3BucketCorsConfiguration, s3BucketWebsiteConfiguration } from "@cdktf/provider-aws";
+import { s3Bucket, s3BucketCorsConfiguration, s3BucketWebsiteConfiguration, dataAwsS3Bucket } from "@cdktf/provider-aws";
 import { Construct } from "constructs";
-import { WebsiteConfig, CorsConfig, LifecycleConfigurationRule, BucketPolicy, IBucketNotificationDestination } from ".";
-import { AwsConstructBase, IAwsConstruct, AwsConstructProps } from "..";
+import { WebsiteConfig, CorsConfig, LifecycleConfigurationRule, OriginAccessIdentity, BucketPolicy, IBucketNotificationDestination } from ".";
+import { AwsConstructBase, IAwsConstruct, AwsConstructProps } from "../aws-construct";
+import * as kms from "../encryption";
 import * as iam from "../iam";
 export interface CloudfrontAccessConfig {
     /**
@@ -15,7 +16,129 @@ export interface CloudfrontAccessConfig {
      */
     readonly keyPatterns?: string[];
 }
+/**
+ * A reference to a bucket outside this stack
+ */
+export interface BucketAttributes {
+    /**
+     * The ARN of the bucket. At least one of bucketArn or bucketName must be
+     * defined in order to initialize a bucket ref.
+     */
+    readonly bucketArn?: string;
+    /**
+     * The name of the bucket. If the underlying value of ARN is a string, the
+     * name will be parsed from the ARN. Otherwise, the name is optional, but
+     * some features that require the bucket name such as auto-creating a bucket
+     * policy, won't work.
+     */
+    readonly bucketName?: string;
+    /**
+     * The domain name of the bucket.
+     *
+     * @default - Inferred from bucket name
+     */
+    readonly bucketDomainName?: string;
+    /**
+     * The website URL of the bucket (if static web hosting is enabled).
+     *
+     * @default - Inferred from bucket name and region
+     */
+    readonly bucketWebsiteUrl?: string;
+    /**
+     * The regional domain name of the specified bucket.
+     */
+    readonly bucketRegionalDomainName?: string;
+    /**
+     * The IPv6 DNS name of the specified bucket.
+     */
+    readonly bucketDualStackDomainName?: string;
+    /**
+     * KMS encryption key associated with this bucket.
+     *
+     * @default - no encryption key
+     */
+    readonly encryptionKey?: kms.IKey;
+    /**
+     * If this bucket has been configured for static website hosting.
+     *
+     * @default false
+     */
+    readonly isWebsite?: boolean;
+    /**
+     * The account this existing bucket belongs to.
+     *
+     * @default - it's assumed the bucket belongs to the same account as the scope it's being imported into
+     */
+    readonly account?: string;
+    /**
+     * The region this existing bucket is in.
+     * Features that require the region (e.g. `bucketWebsiteUrl`) won't fully work
+     * if the region cannot be correctly inferred.
+     *
+     * @default - it's assumed the bucket is in the same region as the scope it's being imported into
+     */
+    readonly region?: string;
+    /**
+     * Whether the bucket is public or not.
+     *
+     * @default false
+     */
+    readonly public?: boolean;
+    /**
+     * Whether the bucket has versioning enabled
+     *
+     * If you are enabling versioning on the bucket for the first time, AWS recommends that
+     * you wait for 15 minutes after enabling versioning before issuing write operations
+     * (PUT or DELETE) on objects in the bucket.
+     *
+     * This will cause 15m delay if `path` is configured.
+     *
+     * @default false
+     */
+    readonly versioned?: boolean;
+    /**
+     * Special CloudFront user that you can associate with Amazon S3 origins, so that you can secure all or just some of
+     * your Amazon S3 content.
+     *
+     * Required to use the imported bucket in a CloudFront distribution.
+     */
+    readonly originAccessIdentity?: OriginAccessIdentity;
+}
 export interface BucketProps extends AwsConstructProps {
+    /**
+     * The kind of server-side encryption to apply to this bucket.
+     *
+     * If you choose KMS, you can specify a KMS key via `encryptionKey`. If
+     * encryption key is not specified, a key will automatically be created.
+     *
+     * @default - `KMS` if `encryptionKey` is specified, or `UNENCRYPTED` otherwise.
+     * But if `UNENCRYPTED` is specified, the bucket will be encrypted as `S3_MANAGED` automatically.
+     */
+    readonly encryption?: BucketEncryption;
+    /**
+     * External KMS key to use for bucket encryption.
+     *
+     * The `encryption` property must be either not specified or set to `KMS` or `DSSE`.
+     * An error will be emitted if `encryption` is set to `UNENCRYPTED` or `S3_MANAGED`.
+     *
+     * @default - If `encryption` is set to `KMS` and this property is undefined,
+     * a new KMS key will be created and associated with this bucket.
+     */
+    readonly encryptionKey?: kms.IKey;
+    /**
+     * Whether Amazon S3 should use its own intermediary key to generate data keys.
+     *
+     * Only relevant when using KMS for encryption.
+     *
+     * - If not enabled, every object GET and PUT will cause an API call to KMS (with the
+     *   attendant cost implications of that).
+     * - If enabled, S3 will use its own time-limited key instead.
+     *
+     * Only relevant, when Encryption is not set to `BucketEncryption.UNENCRYPTED`.
+     *
+     * @default - false
+     */
+    readonly bucketKeyEnabled?: boolean;
     /**
      * The path(s) to static directories or files to upload, relative to the Stack file.
      *
@@ -190,6 +313,11 @@ export interface BucketOutputs {
      * @attribute
      */
     readonly originAccessIdentity?: string;
+    /**
+     * Kms Key outputs, if bucket has encryption.
+     * @attribute
+     */
+    readonly encryptionKey?: kms.KeyOutputs;
 }
 /**
  * Imported or created Bucket attributes
@@ -211,20 +339,19 @@ export interface IBucket extends IAwsConstruct {
     readonly hostedZoneId: string;
     /**
      * The Domain name of the static website.
+     *
+     * This is used to create Route 53 alias records.
      * @attribute
      */
     readonly websiteDomainName?: string;
     /**
-     * Enable public read access for all the files in the bucket.
-     *
-     * This explicitly disables the default S3 bucket security settings. This
-     * should be done with caution, as all bucket objects become publicly exposed.
-     *
-     * You don't need to enable this if you're using CloudFront to serve files from the bucket.
-     *
-     * @default `false`
+     * Whether the bucket is public or not.
+     */
+    readonly public?: boolean;
+    /**
+     * Optional KMS encryption key associated with this bucket.
      */
-    public?: boolean;
+    readonly encryptionKey?: kms.IKey;
     /**
      * The resource policy associated with this bucket.
      *
@@ -418,60 +545,44 @@ export interface IBucket extends IAwsConstruct {
      */
     enableEventBridgeNotification(): void;
 }
-/**
- * The `Bucket` beacon provides an [AWS S3 Bucket](https://aws.amazon.com/s3/).
- *
- * ```ts
- * new storage.Bucket(stack, "MyWebsite", {
- *   path: path.join(__dirname, "dist"),
- * });
- * ```
- *
- * #### Public read access
- *
- * Enables `public` read access for all the files in the bucket. Dangerous and
- * recommended to use edge.Distribution instead.
- *
- * Useful for hosting public files directly from S3.
- *
- * ```ts
- * new storage.Bucket("MyBucket", {
- *   public: true
- * });
- * ```
- *
- * @resource aws_s3_bucket
- * @terraconstruct storage.IBucket
- */
-export declare class Bucket extends AwsConstructBase implements IBucket {
-    protected readonly resource: s3Bucket.S3Bucket;
-    protected readonly websiteConfig?: s3BucketWebsiteConfiguration.S3BucketWebsiteConfiguration;
-    protected readonly corsConfig?: s3BucketCorsConfiguration.S3BucketCorsConfiguration;
-    /** @internal */
-    private readonly sources;
-    /** @internal */
-    private readonly _versioned;
-    get versioned(): boolean;
+export declare abstract class BucketBase extends AwsConstructBase implements IBucket {
+    abstract readonly bucketArn: string;
+    abstract readonly bucketName: string;
+    abstract readonly websiteDomainName?: string;
+    abstract readonly websiteEndpoint?: string;
+    abstract readonly public?: boolean;
+    abstract readonly versioned: boolean;
+    abstract readonly hostedZoneId: string;
+    /**
+     * Optional KMS encryption key associated with this bucket.
+     */
+    abstract readonly encryptionKey?: kms.IKey;
+    get bucketOutputs(): BucketOutputs;
+    get outputs(): Record<string, any>;
+    protected abstract readonly resource: s3Bucket.S3Bucket | dataAwsS3Bucket.DataAwsS3Bucket;
+    protected abstract readonly originAccessIdentity?: OriginAccessIdentity;
     /** @internal */
-    private readonly _isWebsite;
+    protected abstract readonly _isWebsite: boolean;
     /** @internal */
     private sourceSleep?;
     /** @internal */
-    private readonly _outputs;
-    get bucketOutputs(): BucketOutputs;
-    get outputs(): Record<string, any>;
-    get bucketName(): string;
-    get bucketArn(): string;
-    get hostedZoneId(): string;
-    get websiteDomainName(): string | undefined;
-    policy?: BucketPolicy;
+    private readonly sources;
     /**
-     * Whether the bucket is public or not.
+     * The resource policy associated with this bucket.
+     *
+     * If `autoCreatePolicy` is true, a `BucketPolicy` will be created upon the
+     * first call to addToResourcePolicy(s).
+     */
+    abstract policy?: BucketPolicy;
+    /**
+     * Indicates if a bucket resource policy should automatically created upon
+     * the first call to `addToResourcePolicy`.
      */
-    public?: boolean;
+    protected abstract autoCreatePolicy: boolean;
     private notifications?;
-    private readonly eventBridgeEnabled?;
-    constructor(scope: Construct, name: string, props?: BucketProps);
+    protected notificationsHandlerRole?: iam.IRole;
+    protected notificationsSkipDestinationValidation?: boolean;
+    constructor(scope: Construct, id: string, props?: AwsConstructProps);
     /**
      * Adds a statement to the resource policy for a principal (i.e.
      * account/role/service) to perform actions on this bucket and/or its
@@ -638,6 +749,100 @@ export declare class Bucket extends AwsConstructBase implements IBucket {
      */
     arnForObjects(keyPattern: string): string;
     private urlJoin;
+    /**
+     * Adds resource to the Terraform JSON output at Synth time.
+     *
+     * called by TerraformStack.prepareStack()
+     */
+    toTerraform(): any;
+}
+/**
+ * The `Bucket` provides an [AWS S3 Bucket](https://aws.amazon.com/s3/).
+ *
+ * ```ts
+ * new storage.Bucket(stack, "MyWebsite", {
+ *   path: path.join(__dirname, "dist"),
+ * });
+ * ```
+ *
+ * #### Public read access
+ *
+ * Enables `public` read access for all the files in the bucket. Dangerous and
+ * recommended to use edge.Distribution instead.
+ *
+ * Useful for hosting public files directly from S3.
+ *
+ * ```ts
+ * new storage.Bucket("MyBucket", {
+ *   public: true
+ * });
+ * ```
+ *
+ * @resource aws_s3_bucket
+ * @terraconstruct storage.IBucket
+ */
+export declare class Bucket extends BucketBase implements IBucket {
+    static fromBucketName(scope: Construct, id: string, bucketName: string): IBucket;
+    /**
+     * Creates a Bucket construct that represents an external bucket.
+     *
+     * @param scope The parent creating construct (usually `this`).
+     * @param id The construct's name.
+     * @param attrs A `BucketAttributes` object. Can be obtained from a call to
+     * `bucket.export()` or manually created.
+     */
+    static fromBucketAttributes(scope: Construct, id: string, attrs: BucketAttributes): IBucket;
+    /**
+     * Thrown an exception if the given bucket name is not valid.
+     *
+     * @param physicalName name of the bucket.
+     * @param allowLegacyBucketNaming allow legacy bucket naming style, default is false.
+     */
+    static validateBucketName(physicalName: string, allowLegacyBucketNaming?: boolean): void;
+    readonly encryptionKey?: kms.IKey;
+    protected readonly resource: s3Bucket.S3Bucket | dataAwsS3Bucket.DataAwsS3Bucket;
+    protected readonly websiteConfig?: s3BucketWebsiteConfiguration.S3BucketWebsiteConfiguration;
+    protected readonly corsConfig?: s3BucketCorsConfiguration.S3BucketCorsConfiguration;
+    protected readonly originAccessIdentity?: OriginAccessIdentity;
+    /** @internal */
+    protected readonly _isWebsite: boolean;
+    /** @internal */
+    private readonly _versioned;
+    get bucketArn(): string;
+    get bucketName(): string;
+    get websiteDomainName(): string | undefined;
+    get websiteEndpoint(): string | undefined;
+    get versioned(): boolean;
+    get hostedZoneId(): string;
+    policy?: BucketPolicy;
+    protected autoCreatePolicy: boolean;
+    /**
+     * Whether the bucket is public or not.
+     */
+    readonly public?: boolean;
+    private readonly eventBridgeEnabled?;
+    constructor(scope: Construct, name: string, props?: BucketProps);
+    /**
+     * Set up key properties and return the Bucket encryption property from the
+     * user's configuration, according to the following table:
+     *
+     * | props.encryption | props.encryptionKey | props.bucketKeyEnabled | bucketEncryption (return value) | encryptionKey (return value) |
+     * |------------------|---------------------|------------------------|---------------------------------|------------------------------|
+     * | undefined        | undefined           | e                      | undefined                       | undefined                    |
+     * | UNENCRYPTED      | undefined           | false                  | undefined                       | undefined                    |
+     * | undefined        | k                   | e                      | SSE-KMS, bucketKeyEnabled = e   | k                            |
+     * | KMS              | k                   | e                      | SSE-KMS, bucketKeyEnabled = e   | k                            |
+     * | KMS              | undefined           | e                      | SSE-KMS, bucketKeyEnabled = e   | new key                      |
+     * | KMS_MANAGED      | undefined           | e                      | SSE-KMS, bucketKeyEnabled = e   | undefined                    |
+     * | S3_MANAGED       | undefined           | false                  | SSE-S3                          | undefined                    |
+     * | S3_MANAGED       | undefined           | e                      | SSE-S3, bucketKeyEnabled = e    | undefined                    |
+     * | UNENCRYPTED      | undefined           | true                   | ERROR!                          | ERROR!                       |
+     * | UNENCRYPTED      | k                   | e                      | ERROR!                          | ERROR!                       |
+     * | KMS_MANAGED      | k                   | e                      | ERROR!                          | ERROR!                       |
+     * | S3_MANAGED       | undefined           | true                   | ERROR!                          | ERROR!                       |
+     * | S3_MANAGED       | k                   | e                      | ERROR!                          | ERROR!                       |
+     */
+    private parseEncryption;
     /**
      * Adds an iam statement to enforce SSL requests only.
      */
@@ -647,12 +852,6 @@ export declare class Bucket extends AwsConstructBase implements IBucket {
      * version only.
      */
     private minimumTLSVersionStatement;
-    /**
-     * Adds resource to the Terraform JSON output at Synth time.
-     *
-     * called by TerraformStack.prepareStack()
-     */
-    toTerraform(): any;
 }
 export interface AddSourceOptions {
     /**
@@ -723,6 +922,40 @@ export declare enum StorageClass {
      */
     INTELLIGENT_TIERING = "INTELLIGENT_TIERING"
 }
+/**
+ * What kind of server-side encryption to apply to this bucket
+ */
+export declare enum BucketEncryption {
+    /**
+     * Previous option. Buckets can not be unencrypted now.
+     * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html
+     * @deprecated S3 applies server-side encryption with SSE-S3 for every bucket
+     * that default encryption is not configured.
+     */
+    UNENCRYPTED = "UNENCRYPTED",
+    /**
+     * Server-side KMS encryption with a master key managed by KMS.
+     */
+    KMS_MANAGED = "KMS_MANAGED",
+    /**
+     * Server-side encryption with a master key managed by S3.
+     */
+    S3_MANAGED = "S3_MANAGED",
+    /**
+     * Server-side encryption with a KMS key managed by the user.
+     * If `encryptionKey` is specified, this key will be used, otherwise, one will be defined.
+     */
+    KMS = "KMS",
+    /**
+     * Double server-side KMS encryption with a master key managed by KMS.
+     */
+    DSSE_MANAGED = "DSSE_MANAGED",
+    /**
+     * Double server-side encryption with a KMS key managed by the user.
+     * If `encryptionKey` is specified, this key will be used, otherwise, one will be defined.
+     */
+    DSSE = "DSSE"
+}
 /**
  * Notification event types.
  * @link https://docs.aws.amazon.com/AmazonS3/latest/userguide/notification-how-to-event-types-and-destinations.html#supported-notification-event-types