# Creating directory buckets in an Availability Zone To start using the Amazon S3 Express One Zone storage class, you create a directory bucket. The S3 Express One Zone storage class can be used only with directory buckets. The S3 Express One Zone storage class supports low-latency use cases and provides faster data processing within a single Availability Zone. If your application is performance sensitive and benefits from single-digit millisecond `PUT` and `GET` latencies, we recommend creating a directory bucket so that you can use the S3 Express One Zone storage class. There are two types of Amazon S3 buckets, general purpose buckets and directory buckets. You should choose the bucket type that best fits your application and performance requirements. General purpose buckets are the original S3 bucket type. General purpose buckets are recommended for most use cases and access patterns and allow objects stored across all storage classes, except S3 Express One Zone. For more information about general purpose buckets, see [General purpose buckets overview](UsingBucket.md). Directory buckets use the S3 Express One Zone storage class, which is designed to be used for workloads or performance-critical applications that require consistent single-digit millisecond latency. S3 Express One Zone is the first S3 storage class where you can select a single Availability Zone with the option to co-locate your object storage with your compute resources, which provides the highest possible access speed. When you create a directory bucket, you can optionally specify an Amazon Web Services Region and an Availability Zone that's local to your Amazon EC2, Amazon Elastic Kubernetes Service, or Amazon Elastic Container Service (Amazon ECS) compute instances to optimize performance. With S3 Express One Zone, your data is redundantly stored on multiple devices within a single Availability Zone. S3 Express One Zone is designed for 99.95 percent availability within a single Availability Zone and is backed by the [Amazon S3 Service Level Agreement](https://www.amazonaws.cn/s3/sla/). For more information, see [Availability Zones](directory-bucket-high-performance.md#s3-express-overview-az) Directory buckets organize data hierarchically into directories, as opposed to the flat storage structure of general purpose buckets. There aren't prefix limits for directory buckets, and individual directories can scale horizontally. For more information about directory buckets, see [Working with directory buckets](directory-buckets-overview.md). **Directory bucket names** Directory bucket names must follow this format and comply with the rules for directory bucket naming: ``` bucket-base-name--zone-id--x-s3 ``` For example, the following directory bucket name contains the Availability Zone ID `usw2-az1`: ``` bucket-base-name--usw2-az1--x-s3 ``` For more information about directory bucket naming rules, see [Directory bucket naming rules](directory-bucket-naming-rules.md). ## Using the S3 console 1. Sign in to the Amazon Web Services Management Console and open the Amazon S3 console at [https://console.amazonaws.cn/s3/](https://console.amazonaws.cn/s3/). 1. In the navigation bar on the top of the page, choose the name of the currently displayed Amazon Web Services Region. Next, choose the Region in which you want to create a bucket. **Note** To minimize latency and costs and address regulatory requirements, choose a Region close to you. Objects stored in a Region never leave that Region unless you explicitly transfer them to another Region. For a list of Amazon S3 Amazon Web Services Regions, see [Amazon Web Services service endpoints](https://docs.amazonaws.cn/general/latest/gr/rande.html#s3_region) in the *Amazon Web Services General Reference*. 1. In the left navigation pane, choose **Directory buckets**. 1. Choose **Create bucket**. The **Create bucket** page opens. 1. Under **General configuration**, view the Amazon Web Services Region where your bucket will be created. Under **Bucket type**, choose **Directory**. **Note** If you've chosen a Region that doesn't support directory buckets, the **Bucket type** option disappears, and the bucket type defaults to a general purpose bucket. To create a directory bucket, you must choose a supported Region. For a list of Regions that support directory buckets and the Amazon S3 Express One Zone storage class, see [S3 Express One Zone Availability Zones and Regions](s3-express-Endpoints.md). After you create the bucket, you can't change the bucket type. **Note** The Availability Zone can't be changed after the bucket is created. 1. For **Availability Zone**, choose a Availability Zone local to your compute services. For a list of Availability Zones that support directory buckets and the S3 Express One Zone storage class, see [S3 Express One Zone Availability Zones and Regions](s3-express-Endpoints.md). Under **Availability Zone**, select the check box to acknowledge that in the event of an Availability Zone outage, your data might be unavailable or lost. **Important** Although directory buckets are stored across multiple devices within a single Availability Zone, directory buckets don't store data redundantly across Availability Zones. 1. For **Bucket name**, enter a name for your directory bucket. The following naming rules apply for directory buckets. + Be unique within the chosen Zone (Amazon Availability Zone or Amazon Local Zone). + Name must be between 3 (min) and 63 (max) characters long, including the suffix. + Consists only of lowercase letters, numbers and hyphens (-). + Begin and end with a letter or number. + Must include the following suffix: `--zone-id--x-s3`. + Bucket names must not start with the prefix `xn--`. + Bucket names must not start with the prefix `sthree-`. + Bucket names must not start with the prefix `sthree-configurator`. + Bucket names must not start with the prefix ` amzn-s3-demo-`. + Bucket names must not end with the suffix `-s3alias`. This suffix is reserved for access point alias names. For more information, see [Access point aliases](access-points-naming.md#access-points-alias). + Bucket names must not end with the suffix `--ol-s3`. This suffix is reserved for Object Lambda Access Point alias names. For more information, see [How to use a bucket-style alias for your S3 bucket Object Lambda Access Point](olap-use.md#ol-access-points-alias). + Bucket names must not end with the suffix `.mrap`. This suffix is reserved for Multi-Region Access Point names. For more information, see [Rules for naming Amazon S3 Multi-Region Access Points](multi-region-access-point-naming.md). A suffix is automatically added to the base name that you provide when you create a directory bucket using the console. This suffix includes the Availability Zone ID of the Availability Zone that you chose. After you create the bucket, you can't change its name. For more information about naming buckets, see [General purpose bucket naming rules](bucketnamingrules.md). **Important** Do not include sensitive information, such as account numbers, in the bucket name. The bucket name is visible in the URLs that point to the objects in the bucket. 1. Under **Object Ownership**, the **Bucket owner enforced** setting is automatically enabled, and all access control lists (ACLs) are disabled. For directory buckets, ACLs can't be enabled. **Bucket owner enforced (default)** – ACLs are disabled, and the bucket owner automatically owns and has full control over every object in the general purpose bucket. ACLs no longer affect access permissions to data in the S3 general purpose bucket. The bucket uses policies exclusively to define access control. 1. Under **Block Public Access settings for this bucket**, all Block Public Access settings for your directory bucket are automatically enabled. These settings can't be modified for directory buckets. For more information about blocking public access, see [Blocking public access to your Amazon S3 storage](access-control-block-public-access.md). 1. To configure default encryption, under **Encryption type**, choose one of the following: + **Server-side encryption with Amazon S3 managed key (SSE-S3)** + **Server-side encryption with Amazon Key Management Service key (SSE-KMS)** For more information about using Amazon S3 server-side encryption to encrypt your data, see [Data protection and encryption](s3-express-data-protection.md). **Important** If you use the SSE-KMS option for your default encryption configuration, you are subject to the requests per second (RPS) quota of Amazon KMS. For more information about Amazon KMS quotas and how to request a quota increase, see [Quotas](https://docs.amazonaws.cn/kms/latest/developerguide/limits.html) in the *Amazon Key Management Service Developer Guide*. When you enable default encryption, you might need to update your bucket policy. For more information, see [Using SSE-KMS encryption for cross-account operations](bucket-encryption.md#bucket-encryption-update-bucket-policy). 1. If you chose **Server-side encryption with Amazon S3 managed keys (SSE-S3)**, under **Bucket Key**, **Enabled** appears. S3 Bucket Keys are always enabled when you configure your directory bucket to use default encryption with SSE-S3. S3 Bucket Keys are always enabled for `GET` and `PUT` operations in a directory bucket and can’t be disabled. S3 Bucket Keys aren't supported, when you copy SSE-KMS encrypted objects from general purpose buckets to directory buckets, from directory buckets to general purpose buckets, or between directory buckets, through [https://docs.amazonaws.cn/AmazonS3/latest/API/API_CopyObject.html](https://docs.amazonaws.cn/AmazonS3/latest/API/API_CopyObject.html), [https://docs.amazonaws.cn/AmazonS3/latest/API/API_UploadPartCopy.html](https://docs.amazonaws.cn/AmazonS3/latest/API/API_UploadPartCopy.html), [the Copy operation in Batch Operations](directory-buckets-objects-Batch-Ops.md), or [the import jobs](create-import-job.md). In this case, Amazon S3 makes a call to Amazon KMS every time a copy request is made for a KMS-encrypted object. S3 Bucket Keys lower the cost of encryption by decreasing request traffic from Amazon S3 to Amazon KMS. For more information, see [Reducing the cost of SSE-KMS with Amazon S3 Bucket Keys](bucket-key.md). 1. If you chose **Server-side encryption with Amazon Key Management Service key (SSE-KMS)**, under ** Amazon KMS key**, specify your Amazon Key Management Service key in one of the following ways or create a new key. + To choose from a list of available KMS keys, choose **Choose from your Amazon KMS keys**, and choose your **KMS key** from **Available Amazon KMS keys**. Only your customer managed keys appear in this list. The Amazon managed key (`aws/s3`) isn't supported in directory buckets. For more information about customer managed keys, see [Customer keys and Amazon keys](https://docs.amazonaws.cn//kms/latest/developerguide/concepts.html#key-mgmt) in the *Amazon Key Management Service Developer Guide*. + To enter the KMS key ARN or alias, choose **Enter Amazon KMS key ARN**, and enter your KMS key ARN or alias in **Amazon KMS key ARN**. + To create a new customer managed key in the Amazon KMS console, choose **Create a KMS key**. For more information about creating an Amazon KMS key, see [Creating keys](https://docs.amazonaws.cn//kms/latest/developerguide/create-keys.html) in the *Amazon Key Management Service Developer Guide*. **Important** Your SSE-KMS configuration can only support 1 [customer managed key](https://docs.amazonaws.cn/kms/latest/developerguide/concepts.html#customer-cmk) per directory bucket for the lifetime of the bucket. The [https://docs.amazonaws.cn/kms/latest/developerguide/concepts.html#aws-managed-cmk](https://docs.amazonaws.cn/kms/latest/developerguide/concepts.html#aws-managed-cmk) (`aws/s3`) isn't supported. Also, after you specify a customer managed key for SSE-KMS, you can't override the customer managed key for the bucket's SSE-KMS configuration. You can identify the customer managed key you specified for the bucket's SSE-KMS configuration, in the following way: You make a `HeadObject` API operation request to find the value of `x-amz-server-side-encryption-aws-kms-key-id` in your response. To use a new customer managed key for your data, we recommend copying your existing objects to a new directory bucket with a new customer managed key. You can use only KMS keys that are available in the same Amazon Web Services Region as the bucket. The Amazon S3 console lists only the first 100 KMS keys in the same Region as the bucket. To use a KMS key that is not listed, you must enter your KMS key ARN. If you want to use a KMS key that is owned by a different account, you must first have permission to use the key and then you must enter the KMS key ARN. For more information on cross account permissions for KMS keys, see [Creating KMS keys that other accounts can use](https://docs.amazonaws.cn//kms/latest/developerguide/key-policy-modifying-external-accounts.html#cross-account-console) in the *Amazon Key Management Service Developer Guide*. For more information on SSE-KMS, see [Specifying server-side encryption with Amazon KMS (SSE-KMS) for new object uploads in directory buckets](s3-express-specifying-kms-encryption.md). When you use an Amazon KMS key for server-side encryption in directory buckets, you must choose a symmetric encryption KMS key. Amazon S3 supports only symmetric encryption KMS keys and not asymmetric KMS keys. For more information, see [Identifying symmetric and asymmetric KMS keys](https://docs.amazonaws.cn//kms/latest/developerguide/find-symm-asymm.html) in the *Amazon Key Management Service Developer Guide*. For more information about using Amazon KMS with Amazon S3, see [Using server-side encryption with Amazon KMS keys (SSE-KMS) in directory buckets](s3-express-UsingKMSEncryption.md). 1. Choose **Create bucket**. After creating the bucket, you can add files and folders to the bucket. For more information, see [Working with objects in a directory bucket](directory-buckets-objects.md). ## Using the Amazon SDKs ------ #### [ SDK for Go ] This example shows how to create a directory bucket by using the Amazon SDK for Go. **Example** ``` var bucket = "..." func runCreateBucket(c *s3.Client) { resp, err := c.CreateBucket(context.Background(), &s3.CreateBucketInput{ Bucket: &bucket, CreateBucketConfiguration: &types.CreateBucketConfiguration{ Location: &types.LocationInfo{ Name: aws.String("usw2-az1"), Type: types.LocationTypeAvailabilityZone, }, Bucket: &types.BucketInfo{ DataRedundancy: types.DataRedundancySingleAvailabilityZone, Type: types.BucketTypeDirectory, }, }, }) var terr *types.BucketAlreadyOwnedByYou if errors.As(err, &terr) { fmt.Printf("BucketAlreadyOwnedByYou: %s\n", aws.ToString(terr.Message)) fmt.Printf("noop...\n") return } if err != nil { log.Fatal(err) } fmt.Printf("bucket created at %s\n", aws.ToString(resp.Location)) } ``` ------ #### [ SDK for Java 2.x ] This example shows how to create an directory bucket by using the Amazon SDK for Java 2.x. **Example** ``` public static void createBucket(S3Client s3Client, String bucketName) { //Bucket name format is {base-bucket-name}--{az-id}--x-s3 //example: doc-example-bucket--usw2-az1--x-s3 is a valid name for a directory bucket created in //Region us-west-2, Availability Zone 2 CreateBucketConfiguration bucketConfiguration = CreateBucketConfiguration.builder() .location(LocationInfo.builder() .type(LocationType.AVAILABILITY_ZONE) .name("usw2-az1").build()) //this must match the Region and Availability Zone in your bucket name .bucket(BucketInfo.builder() .type(BucketType.DIRECTORY) .dataRedundancy(DataRedundancy.SINGLE_AVAILABILITY_ZONE) .build()).build(); try { CreateBucketRequest bucketRequest = CreateBucketRequest.builder().bucket(bucketName).createBucketConfiguration(bucketConfiguration).build(); CreateBucketResponse response = s3Client.createBucket(bucketRequest); System.out.println(response); } catch (S3Exception e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } } ``` ------ #### [ Amazon SDK for JavaScript ] This example shows how to create a directory bucket by using the Amazon SDK for JavaScript. **Example** ``` // file.mjs, run with Node.js v16 or higher // To use with the preview build, place this in a folder // inside the preview build directory, such as /aws-sdk-js-v3/workspace/ import { S3 } from "@aws-sdk/client-s3"; const region = "us-east-1"; const zone = "use1-az4"; const suffix = `${zone}--x-s3`; const s3 = new S3({ region }); const bucketName = `...--${suffix}`; const createResponse = await s3.createBucket( { Bucket: bucketName, CreateBucketConfiguration: {Location: {Type: "AvailabilityZone", Name: zone}, Bucket: { Type: "Directory", DataRedundancy: "SingleAvailabilityZone" }} } ); ``` ------ #### [ Amazon SDK for .NET ] This example shows how to create a directory bucket by using the Amazon SDK for .NET. **Example** ``` using (var amazonS3Client = new AmazonS3Client()) { var putBucketResponse = await amazonS3Client.PutBucketAsync(new PutBucketRequest { BucketName = "DOC-EXAMPLE-BUCKET--usw2-az1--x-s3", PutBucketConfiguration = new PutBucketConfiguration { BucketInfo = new BucketInfo { DataRedundancy = DataRedundancy.SingleAvailabilityZone, Type = BucketType.Directory }, Location = new LocationInfo { Name = "usw2-az1", Type = LocationType.AvailabilityZone } } }).ConfigureAwait(false); } ``` ------ #### [ SDK for PHP ] This example shows how to create a directory bucket by using the Amazon SDK for PHP. **Example** ``` require 'vendor/autoload.php'; $s3Client = new S3Client([ 'region' => 'us-east-1', ]); $result = $s3Client->createBucket([ 'Bucket' => 'doc-example-bucket--use1-az4--x-s3', 'CreateBucketConfiguration' => [ 'Location' => ['Name'=> 'use1-az4', 'Type'=> 'AvailabilityZone'], 'Bucket' => ["DataRedundancy" => "SingleAvailabilityZone" ,"Type" => "Directory"] ], ]); ``` ------ #### [ SDK for Python ] This example shows how to create a directory bucket by using the Amazon SDK for Python (Boto3). **Example** ``` import logging import boto3 from botocore.exceptions import ClientError def create_bucket(s3_client, bucket_name, availability_zone): ''' Create a directory bucket in a specified Availability Zone :param s3_client: boto3 S3 client :param bucket_name: Bucket to create; for example, 'doc-example-bucket--usw2-az1--x-s3' :param availability_zone: String; Availability Zone ID to create the bucket in, for example, 'usw2-az1' :return: True if bucket is created, else False ''' try: bucket_config = { 'Location': { 'Type': 'AvailabilityZone', 'Name': availability_zone }, 'Bucket': { 'Type': 'Directory', 'DataRedundancy': 'SingleAvailabilityZone' } } s3_client.create_bucket( Bucket = bucket_name, CreateBucketConfiguration = bucket_config ) except ClientError as e: logging.error(e) return False return True if __name__ == '__main__': bucket_name = 'BUCKET_NAME' region = 'us-west-2' availability_zone = 'usw2-az1' s3_client = boto3.client('s3', region_name = region) create_bucket(s3_client, bucket_name, availability_zone) ``` ------ #### [ SDK for Ruby ] This example shows how to create an directory bucket by using the Amazon SDK for Ruby. **Example** ``` s3 = Aws::S3::Client.new(region:'us-west-2') s3.create_bucket( bucket: "bucket_base_name--az_id--x-s3", create_bucket_configuration: { location: { name: 'usw2-az1', type: 'AvailabilityZone' }, bucket: { data_redundancy: 'SingleAvailabilityZone', type: 'Directory' } } ) ``` ------ ## Using the Amazon CLI This example shows how to create a directory bucket by using the Amazon CLI. To use the command replace the *user input placeholders* with your own information. When you create a directory bucket you must provide configuration details and use the following naming convention: `bucket-base-name--zone-id--x-s3` ``` aws s3api create-bucket --bucket bucket-base-name--zone-id--x-s3 --create-bucket-configuration 'Location={Type=AvailabilityZone,Name=usw2-az1},Bucket={DataRedundancy=SingleAvailabilityZone,Type=Directory}' --region us-west-2 ``` For more information, see [create-bucket](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/create-bucket.html) in the Amazon Command Line Interface.