buckets

Creates, updates, deletes or gets a bucket resource or lists buckets in a region

Overview

Name	buckets
Type	Resource
Description	The AWS::S3::Bucket resource creates an Amazon S3 bucket in the same AWS Region where you create the AWS CloudFormation stack. To control how AWS CloudFormation handles the bucket when the stack is deleted, you can set a deletion policy for your bucket. You can choose to retain the bucket or to delete the bucket. For more information, see DeletionPolicy Attribute. You can only delete empty buckets. Deletion fails for buckets that have contents.
Id	awscc.s3.buckets

Fields

get (all properties)

Name	Datatype	Description
▶accelerate_configuration	object	Configures the transfer acceleration state for an Amazon S3 bucket. For more information, see Amazon S3 Transfer Acceleration in the Amazon S3 User Guide.
access_control	string	This is a legacy property, and it is not recommended for most use cases. A majority of modern use cases in Amazon S3 no longer require the use of ACLs, and we recommend that you keep ACLs disabled. For more information, see Controlling object ownership in the Amazon S3 User Guide. A canned access control list (ACL) that grants predefined permissions to the bucket. For more information about canned ACLs, see Canned ACL in the Amazon S3 User Guide. S3 buckets are created with ACLs disabled by default. Therefore, unless you explicitly set the AWS::S3::OwnershipControls property to enable ACLs, your resource will fail to deploy with any value other than Private. Use cases requiring ACLs are uncommon. The majority of access control configurations can be successfully and more easily achieved with bucket policies. For more information, see AWS::S3::BucketPolicy. For examples of common policy configurations, including S3 Server Access Logs buckets and more, see Bucket policy examples in the Amazon S3 User Guide.
▶analytics_configurations	array	Specifies the configuration and any analyses for the analytics filter of an Amazon S3 bucket.
▶bucket_encryption	object	Specifies default encryption for a bucket using server-side encryption with Amazon S3-managed keys (SSE-S3), AWS KMS-managed keys (SSE-KMS), or dual-layer server-side encryption with KMS-managed keys (DSSE-KMS). For information about the Amazon S3 default encryption feature, see Amazon S3 Default Encryption for S3 Buckets in the Amazon S3 User Guide.
bucket_name	string	A name for the bucket. If you don't specify a name, AWS CloudFormation generates a unique ID and uses that ID for the bucket name. The bucket name must contain only lowercase letters, numbers, periods (.), and dashes (-) and must follow Amazon S3 bucket restrictions and limitations. For more information, see Rules for naming Amazon S3 buckets in the Amazon S3 User Guide. If you specify a name, you can't perform updates that require replacement of this resource. You can perform updates that require no or some interruption. If you need to replace the resource, specify a new name.
▶cors_configuration	object	Describes the cross-origin access configuration for objects in an Amazon S3 bucket. For more information, see Enabling Cross-Origin Resource Sharing in the Amazon S3 User Guide.
▶intelligent_tiering_configurations	array	Defines how Amazon S3 handles Intelligent-Tiering storage.
▶inventory_configurations	array	Specifies the inventory configuration for an Amazon S3 bucket. For more information, see GET Bucket inventory in the Amazon S3 API Reference.
▶lifecycle_configuration	object	Specifies the lifecycle configuration for objects in an Amazon S3 bucket. For more information, see Object Lifecycle Management in the Amazon S3 User Guide.
▶logging_configuration	object	Settings that define where logs are stored.
▶metrics_configurations	array	Specifies a metrics configuration for the CloudWatch request metrics (specified by the metrics configuration ID) from an Amazon S3 bucket. If you're updating an existing metrics configuration, note that this is a full replacement of the existing metrics configuration. If you don't include the elements you want to keep, they are erased. For more information, see PutBucketMetricsConfiguration.
▶metadata_table_configuration	object	The metadata table configuration of an S3 general purpose bucket.
▶metadata_configuration	object
▶notification_configuration	object	Configuration that defines how Amazon S3 handles bucket notifications.
▶object_lock_configuration	object	This operation is not supported for directory buckets. Places an Object Lock configuration on the specified bucket. The rule specified in the Object Lock configuration will be applied by default to every new object placed in the specified bucket. For more information, see Locking Objects. + The DefaultRetention settings require both a mode and a period. + The DefaultRetention period can be either Days or Years but you must select one. You cannot specify Days and Years at the same time. + You can enable Object Lock for new or existing buckets. For more information, see Configuring Object Lock.
object_lock_enabled	boolean	Indicates whether this bucket has an Object Lock configuration enabled. Enable ObjectLockEnabled when you apply ObjectLockConfiguration to a bucket.
▶ownership_controls	object	Configuration that defines how Amazon S3 handles Object Ownership rules.
▶public_access_block_configuration	object	Configuration that defines how Amazon S3 handles public access.
▶replication_configuration	object	Configuration for replicating objects in an S3 bucket. To enable replication, you must also enable versioning by using the VersioningConfiguration property. Amazon S3 can store replicated objects in a single destination bucket or multiple destination buckets. The destination bucket or buckets must already exist.
▶tags	array	An arbitrary set of tags (key-value pairs) for this S3 bucket.
▶versioning_configuration	object	Enables multiple versions of all objects in this bucket. You might enable versioning to prevent objects from being deleted or overwritten by mistake or to archive objects so that you can retrieve previous versions of them. When you enable versioning on a bucket for the first time, it might take a short amount of time for the change to be fully propagated. We recommend that you wait for 15 minutes after enabling versioning before issuing write operations (PUT or DELETE) on objects in the bucket.
▶website_configuration	object	Information used to configure the bucket as a static website. For more information, see Hosting Websites on Amazon S3.
arn	string	The Amazon Resource Name (ARN) of the specified resource.
domain_name	string
dual_stack_domain_name	string
regional_domain_name	string
website_url	string
region	string	AWS region.

list (identifiers only)

Name	Datatype	Description
bucket_name	string	A name for the bucket. If you don't specify a name, AWS CloudFormation generates a unique ID and uses that ID for the bucket name. The bucket name must contain only lowercase letters, numbers, periods (.), and dashes (-) and must follow Amazon S3 bucket restrictions and limitations. For more information, see Rules for naming Amazon S3 buckets in the Amazon S3 User Guide. If you specify a name, you can't perform updates that require replacement of this resource. You can perform updates that require no or some interruption. If you need to replace the resource, specify a new name.
region	string	AWS region.

For more information, see AWS::S3::Bucket.

Methods

Name	Resource	Accessible by	Required Params
create_resource	buckets	INSERT	BucketName, region
delete_resource	buckets	DELETE	Identifier, region
update_resource	buckets	UPDATE	Identifier, PatchDocument, region
list_resources	buckets_list_only	SELECT	region
get_resource	buckets	SELECT	Identifier, region

SELECT examples

get (all properties)

Gets all properties from an individual bucket.

SELECT
  region,
  accelerate_configuration,
  access_control,
  analytics_configurations,
  bucket_encryption,
  bucket_name,
  cors_configuration,
  intelligent_tiering_configurations,
  inventory_configurations,
  lifecycle_configuration,
  logging_configuration,
  metrics_configurations,
  metadata_table_configuration,
  metadata_configuration,
  notification_configuration,
  object_lock_configuration,
  object_lock_enabled,
  ownership_controls,
  public_access_block_configuration,
  replication_configuration,
  tags,
  versioning_configuration,
  website_configuration,
  arn,
  domain_name,
  dual_stack_domain_name,
  regional_domain_name,
  website_url
FROM awscc.s3.buckets
WHERE
  region = '{{ region }}' AND
  Identifier = '{{ bucket_name }}';

list (identifiers only)

Lists all buckets in a region.

SELECT
  region,
  bucket_name
FROM awscc.s3.buckets_list_only
WHERE
  region = '{{ region }}';

INSERT example

Use the following StackQL query and manifest file to create a new bucket resource, using stack-deploy.

Required Properties

/*+ create */
INSERT INTO awscc.s3.buckets (
  BucketName,
  region
)
SELECT
  '{{ bucket_name }}',
  '{{ region }}'
RETURNING
  ErrorCode,
  EventTime,
  Identifier,
  Operation,
  OperationStatus,
  RequestToken,
  ResourceModel,
  RetryAfter,
  StatusMessage,
  TypeName
;

All Properties

/*+ create */
INSERT INTO awscc.s3.buckets (
  AccelerateConfiguration,
  AccessControl,
  AnalyticsConfigurations,
  BucketEncryption,
  BucketName,
  CorsConfiguration,
  IntelligentTieringConfigurations,
  InventoryConfigurations,
  LifecycleConfiguration,
  LoggingConfiguration,
  MetricsConfigurations,
  MetadataTableConfiguration,
  MetadataConfiguration,
  NotificationConfiguration,
  ObjectLockConfiguration,
  ObjectLockEnabled,
  OwnershipControls,
  PublicAccessBlockConfiguration,
  ReplicationConfiguration,
  Tags,
  VersioningConfiguration,
  WebsiteConfiguration,
  region
)
SELECT
  '{{ accelerate_configuration }}',
  '{{ access_control }}',
  '{{ analytics_configurations }}',
  '{{ bucket_encryption }}',
  '{{ bucket_name }}',
  '{{ cors_configuration }}',
  '{{ intelligent_tiering_configurations }}',
  '{{ inventory_configurations }}',
  '{{ lifecycle_configuration }}',
  '{{ logging_configuration }}',
  '{{ metrics_configurations }}',
  '{{ metadata_table_configuration }}',
  '{{ metadata_configuration }}',
  '{{ notification_configuration }}',
  '{{ object_lock_configuration }}',
  '{{ object_lock_enabled }}',
  '{{ ownership_controls }}',
  '{{ public_access_block_configuration }}',
  '{{ replication_configuration }}',
  '{{ tags }}',
  '{{ versioning_configuration }}',
  '{{ website_configuration }}',
  '{{ region }}'
RETURNING
  ErrorCode,
  EventTime,
  Identifier,
  Operation,
  OperationStatus,
  RequestToken,
  ResourceModel,
  RetryAfter,
  StatusMessage,
  TypeName
;

Manifest

version: 1
name: stack name
description: stack description
providers:
- aws
globals:
- name: region
  value: '{{ vars.AWS_REGION }}'
resources:
- name: bucket
  props:
    - name: accelerate_configuration
      value:
        acceleration_status: '{{ acceleration_status }}'
    - name: access_control
      value: '{{ access_control }}'
    - name: analytics_configurations
      value:
        - tag_filters:
            - value: '{{ value }}'
              key: '{{ key }}'
          storage_class_analysis:
            data_export:
              s3_bucket_destination:
                output_schema_version: '{{ output_schema_version }}'
                format: '{{ format }}'
                account_id: '{{ account_id }}'
                prefix: '{{ prefix }}'
                encryption: {}
                arn: '{{ arn }}'
              cloud_watch_metrics:
                is_enabled: '{{ is_enabled }}'
          id: '{{ id }}'
          prefix: '{{ prefix }}'
    - name: bucket_encryption
      value:
        server_side_encryption_configuration:
          - bucket_key_enabled: '{{ bucket_key_enabled }}'
            server_side_encryption_by_default:
              kms_master_key_id: '{{ kms_master_key_id }}'
              sse_algorithm: '{{ sse_algorithm }}'
    - name: bucket_name
      value: '{{ bucket_name }}'
    - name: cors_configuration
      value:
        cors_rules:
          - allowed_headers:
              - '{{ allowed_headers[0] }}'
            allowed_methods:
              - '{{ allowed_methods[0] }}'
            allowed_origins:
              - '{{ allowed_origins[0] }}'
            exposed_headers:
              - '{{ exposed_headers[0] }}'
            id: '{{ id }}'
            max_age: '{{ max_age }}'
    - name: intelligent_tiering_configurations
      value:
        - id: '{{ id }}'
          prefix: '{{ prefix }}'
          status: '{{ status }}'
          tag_filters:
            - null
          tierings:
            - access_tier: '{{ access_tier }}'
              days: '{{ days }}'
    - name: inventory_configurations
      value:
        - destination:
            bucket_arn: '{{ bucket_arn }}'
            bucket_account_id: '{{ bucket_account_id }}'
            format: '{{ format }}'
            prefix: '{{ prefix }}'
          enabled: '{{ enabled }}'
          id: '{{ id }}'
          included_object_versions: '{{ included_object_versions }}'
          optional_fields:
            - '{{ optional_fields[0] }}'
          prefix: '{{ prefix }}'
          schedule_frequency: '{{ schedule_frequency }}'
    - name: lifecycle_configuration
      value:
        rules:
          - abort_incomplete_multipart_upload:
              days_after_initiation: '{{ days_after_initiation }}'
            expiration_date: '{{ expiration_date }}'
            expiration_in_days: '{{ expiration_in_days }}'
            expired_object_delete_marker: '{{ expired_object_delete_marker }}'
            id: '{{ id }}'
            noncurrent_version_expiration_in_days: '{{ noncurrent_version_expiration_in_days }}'
            noncurrent_version_expiration:
              noncurrent_days: '{{ noncurrent_days }}'
              newer_noncurrent_versions: '{{ newer_noncurrent_versions }}'
            noncurrent_version_transition:
              storage_class: '{{ storage_class }}'
              transition_in_days: '{{ transition_in_days }}'
              newer_noncurrent_versions: '{{ newer_noncurrent_versions }}'
            noncurrent_version_transitions:
              - null
            prefix: '{{ prefix }}'
            status: '{{ status }}'
            tag_filters:
              - null
            object_size_greater_than: '{{ object_size_greater_than }}'
            object_size_less_than: '{{ object_size_less_than }}'
            transition:
              storage_class: '{{ storage_class }}'
              transition_date: null
              transition_in_days: '{{ transition_in_days }}'
            transitions:
              - null
        transition_default_minimum_object_size: '{{ transition_default_minimum_object_size }}'
    - name: logging_configuration
      value:
        destination_bucket_name: '{{ destination_bucket_name }}'
        log_file_prefix: '{{ log_file_prefix }}'
        target_object_key_format: {}
    - name: metrics_configurations
      value:
        - access_point_arn: '{{ access_point_arn }}'
          id: '{{ id }}'
          prefix: '{{ prefix }}'
          tag_filters:
            - null
    - name: metadata_table_configuration
      value:
        s3_tables_destination:
          table_bucket_arn: '{{ table_bucket_arn }}'
          table_name: '{{ table_name }}'
          table_namespace: '{{ table_namespace }}'
          table_arn: '{{ table_arn }}'
    - name: metadata_configuration
      value:
        destination:
          table_bucket_type: '{{ table_bucket_type }}'
          table_bucket_arn: '{{ table_bucket_arn }}'
          table_namespace: '{{ table_namespace }}'
        journal_table_configuration:
          table_name: '{{ table_name }}'
          table_arn: '{{ table_arn }}'
          record_expiration:
            expiration: '{{ expiration }}'
            days: '{{ days }}'
          encryption_configuration:
            sse_algorithm: '{{ sse_algorithm }}'
            kms_key_arn: '{{ kms_key_arn }}'
        inventory_table_configuration:
          table_name: '{{ table_name }}'
          table_arn: '{{ table_arn }}'
          configuration_state: '{{ configuration_state }}'
          encryption_configuration: null
    - name: notification_configuration
      value:
        event_bridge_configuration:
          event_bridge_enabled: '{{ event_bridge_enabled }}'
        lambda_configurations:
          - event: '{{ event }}'
            filter:
              s3_key:
                rules:
                  - name: '{{ name }}'
                    value: '{{ value }}'
            function: '{{ function }}'
        queue_configurations:
          - event: '{{ event }}'
            filter: null
            queue: '{{ queue }}'
        topic_configurations:
          - event: '{{ event }}'
            filter: null
            topic: '{{ topic }}'
    - name: object_lock_configuration
      value:
        object_lock_enabled: '{{ object_lock_enabled }}'
        rule:
          default_retention:
            years: '{{ years }}'
            days: '{{ days }}'
            mode: '{{ mode }}'
    - name: object_lock_enabled
      value: '{{ object_lock_enabled }}'
    - name: ownership_controls
      value:
        rules:
          - object_ownership: '{{ object_ownership }}'
    - name: public_access_block_configuration
      value:
        restrict_public_buckets: '{{ restrict_public_buckets }}'
        block_public_policy: '{{ block_public_policy }}'
        block_public_acls: '{{ block_public_acls }}'
        ignore_public_acls: '{{ ignore_public_acls }}'
    - name: replication_configuration
      value:
        role: '{{ role }}'
        rules:
          - delete_marker_replication:
              status: '{{ status }}'
            destination:
              access_control_translation:
                owner: '{{ owner }}'
              account: '{{ account }}'
              bucket: '{{ bucket }}'
              encryption_configuration:
                replica_kms_key_id: '{{ replica_kms_key_id }}'
              metrics:
                event_threshold:
                  minutes: '{{ minutes }}'
                status: '{{ status }}'
              replication_time:
                status: '{{ status }}'
                time: null
              storage_class: '{{ storage_class }}'
            filter:
              and:
                prefix: '{{ prefix }}'
                tag_filters:
                  - null
              prefix: '{{ prefix }}'
              tag_filter: null
            id: '{{ id }}'
            prefix: '{{ prefix }}'
            priority: '{{ priority }}'
            source_selection_criteria:
              replica_modifications:
                status: '{{ status }}'
              sse_kms_encrypted_objects:
                status: '{{ status }}'
            status: '{{ status }}'
    - name: tags
      value:
        - key: '{{ key }}'
          value: '{{ value }}'
    - name: versioning_configuration
      value:
        status: '{{ status }}'
    - name: website_configuration
      value:
        error_document: '{{ error_document }}'
        index_document: '{{ index_document }}'
        routing_rules:
          - redirect_rule:
              host_name: '{{ host_name }}'
              http_redirect_code: '{{ http_redirect_code }}'
              protocol: '{{ protocol }}'
              replace_key_prefix_with: '{{ replace_key_prefix_with }}'
              replace_key_with: '{{ replace_key_with }}'
            routing_rule_condition:
              key_prefix_equals: '{{ key_prefix_equals }}'
              http_error_code_returned_equals: '{{ http_error_code_returned_equals }}'
        redirect_all_requests_to:
          host_name: '{{ host_name }}'
          protocol: '{{ protocol }}'

UPDATE example

Use the following StackQL query and manifest file to update a bucket resource, using stack-deploy.

/*+ update */
UPDATE awscc.s3.buckets
SET PatchDocument = string('{{ {
    "AccelerateConfiguration": accelerate_configuration,
    "AccessControl": access_control,
    "AnalyticsConfigurations": analytics_configurations,
    "BucketEncryption": bucket_encryption,
    "CorsConfiguration": cors_configuration,
    "IntelligentTieringConfigurations": intelligent_tiering_configurations,
    "InventoryConfigurations": inventory_configurations,
    "LifecycleConfiguration": lifecycle_configuration,
    "LoggingConfiguration": logging_configuration,
    "MetricsConfigurations": metrics_configurations,
    "NotificationConfiguration": notification_configuration,
    "ObjectLockConfiguration": object_lock_configuration,
    "ObjectLockEnabled": object_lock_enabled,
    "OwnershipControls": ownership_controls,
    "PublicAccessBlockConfiguration": public_access_block_configuration,
    "ReplicationConfiguration": replication_configuration,
    "Tags": tags,
    "VersioningConfiguration": versioning_configuration,
    "WebsiteConfiguration": website_configuration
} | generate_patch_document }}')
WHERE
  region = '{{ region }}' AND
  Identifier = '{{ bucket_name }}'
RETURNING
  ErrorCode,
  EventTime,
  Identifier,
  Operation,
  OperationStatus,
  RequestToken,
  ResourceModel,
  RetryAfter,
  StatusMessage,
  TypeName
;

DELETE example

/*+ delete */
DELETE FROM awscc.s3.buckets
WHERE
  Identifier = '{{ bucket_name }}' AND
  region = '{{ region }}'
RETURNING
  ErrorCode,
  EventTime,
  Identifier,
  Operation,
  OperationStatus,
  RequestToken,
  ResourceModel,
  RetryAfter,
  StatusMessage,
  TypeName
;

Additional Parameters

Mutable resources in the Cloud Control provider support additional optional parameters which can be supplied with INSERT, UPDATE, or DELETE operations. These include:

Parameter	Description
ClientToken	A unique identifier to ensure the idempotency of the resource request. This allows the provider to accurately distinguish between retries and new requests. A client token is valid for 36 hours once used. After that, a resource request with the same client token is treated as a new request. If you do not specify a client token, one is generated for inclusion in the request.
RoleArn	The ARN of the IAM role used to perform this resource operation. The role specified must have the permissions required for this operation. If you do not specify a role, a temporary session is created using your AWS user credentials.
TypeVersionId	For private resource types, the type version to use in this resource operation. If you do not specify a resource version, the default version is used.

Permissions

To operate on the buckets resource, the following permissions are required:

Create

s3:CreateBucket,
s3:PutBucketTagging,
s3:PutAnalyticsConfiguration,
s3:PutEncryptionConfiguration,
s3:PutBucketCORS,
s3:PutInventoryConfiguration,
s3:PutLifecycleConfiguration,
s3:PutMetricsConfiguration,
s3:PutBucketNotification,
s3:PutBucketReplication,
s3:PutBucketWebsite,
s3:PutAccelerateConfiguration,
s3:PutBucketPublicAccessBlock,
s3:PutReplicationConfiguration,
s3:PutObjectAcl,
s3:PutBucketObjectLockConfiguration,
s3:GetBucketAcl,
s3:ListBucket,
iam:PassRole,
s3:DeleteObject,
s3:PutBucketLogging,
s3:PutBucketVersioning,
s3:PutObjectLockConfiguration,
s3:PutBucketOwnershipControls,
s3:PutIntelligentTieringConfiguration,
s3:GetBucketMetadataTableConfiguration,
s3:CreateBucketMetadataTableConfiguration,
s3tables:CreateNamespace,
s3tables:CreateTable,
s3tables:CreateTableBucket,
s3tables:GetTable,
s3tables:PutTableEncryption,
s3tables:PutTablePolicy,
s3tables:GetTableMetadataLocation,
s3tables:UpdateTableMetadataLocation

Read

s3:GetAccelerateConfiguration,
s3:GetLifecycleConfiguration,
s3:GetBucketPublicAccessBlock,
s3:GetAnalyticsConfiguration,
s3:GetBucketCORS,
s3:GetEncryptionConfiguration,
s3:GetInventoryConfiguration,
s3:GetBucketLogging,
s3:GetMetricsConfiguration,
s3:GetBucketNotification,
s3:GetBucketVersioning,
s3:GetReplicationConfiguration,
S3:GetBucketWebsite,
s3:GetBucketPublicAccessBlock,
s3:GetBucketObjectLockConfiguration,
s3:GetBucketTagging,
s3:GetBucketOwnershipControls,
s3:GetIntelligentTieringConfiguration,
s3:GetBucketMetadataTableConfiguration,
s3:ListBucket

Update

s3:PutBucketAcl,
s3:PutBucketTagging,
s3:PutAnalyticsConfiguration,
s3:PutEncryptionConfiguration,
s3:PutBucketCORS,
s3:PutInventoryConfiguration,
s3:PutLifecycleConfiguration,
s3:PutMetricsConfiguration,
s3:PutBucketNotification,
s3:PutBucketReplication,
s3:PutBucketWebsite,
s3:PutAccelerateConfiguration,
s3:GetBucketMetadataTableConfiguration,
s3:DeleteBucketMetadataTableConfiguration,
s3:CreateBucketMetadataTableConfiguration,
s3:UpdateBucketMetadataJournalTableConfiguration,
s3:UpdateBucketMetadataInventoryTableConfiguration,
s3tables:CreateNamespace,
s3tables:CreateTable,
s3tables:CreateTableBucket,
s3tables:GetTable,
s3tables:PutTableEncryption,
s3tables:PutTablePolicy,
s3tables:GetTableMetadataLocation,
s3tables:UpdateTableMetadataLocation,
s3:PutBucketPublicAccessBlock,
s3:PutReplicationConfiguration,
s3:PutBucketOwnershipControls,
s3:PutIntelligentTieringConfiguration,
s3:DeleteBucketWebsite,
s3:PutBucketLogging,
s3:PutBucketVersioning,
s3:PutObjectLockConfiguration,
s3:PutBucketObjectLockConfiguration,
s3:DeleteBucketAnalyticsConfiguration,
s3:DeleteBucketCors,
s3:DeleteBucketMetricsConfiguration,
s3:DeleteBucketEncryption,
s3:DeleteBucketLifecycle,
s3:DeleteBucketReplication,
iam:PassRole,
s3:ListBucket

Delete

s3:DeleteBucket,
s3:ListBucket

List

s3:ListAllMyBuckets