Oracle Cloud Infrastructure Documentation

Creating an Object Storage Bucket

Create a Object Storage bucket to store objects.

For information on the required permissions to create a bucket in Object Storage, see Required IAM Policy.

    1. On the Buckets list page, select Create bucket. If you need help finding the list page, see Listing Object Storage Buckets.
      The Create bucket panel opens.
    2. Enter the following information:
      • Bucket name: The system generates a default bucket name that reflects the current year, month, day, and time, for example bucket-2019030620230306-1359. If you change this default to any other bucket name, use letters, numbers, dashes, underscores, and periods. Avoid entering confidential information.
      • Default storage tier: Select the default tier in which you want to store your data. When you upload objects, the objects are automatically assigned to and uploaded to this tier.
        • Standard is the primary, default storage tier used for Object Storage service data. Use this tier to store data that requires fast and immediate access. Standard buckets do, however, provide an option to assign and upload objects to different storage tiers (Infrequent Access and Archive) while remaining in the Standard bucket.
        • Archive is the default storage tier used for Archive Storage data. Use the Archive tier for storing data that requires long retention periods but not immediate access. Archived data must be restored before the data is accessible.

        For more information, see Object Storage Storage Tiers.

      • Enable auto-tiering: Enable this option to monitor and automatically move infrequently accessed objects from the Standard tier to the less expensive Infrequent Access storage tier. For more information, see Auto-Tiering.
      • Enable object versioning: Enable this option to create an object version each time the content changes or the object is deleted. For more information, see Object Storage Versioning.
      • Emit object events: Enable this option to allow the bucket to emit events for object state changes. For more information about events, see Overview of Events.
      • Uncommited multipart uploads cleanup: Enable this option to create a lifecycle rule that automatically deletes all uncommitted multipart uploads after 7 days.
      • Encryption: Select one of the following encryption key options:
        • Encrypt using Oracle-managed keys: Select to encrypt your bucket using Oracle-managed keys.
        • Encrypt using customer-managed keys: Select to encrypt your bucket with your own keys. Select the Vault compartment and Vault that contain the master encryption key you want to use. Also select the master encryption key compartment and master encryption key.

        For more information about encryption, see Overview of Vault. For details on how to create a vault, see Managing Vaults.

    Tags

    Add tags: Select if you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace.

    For more information about tagging, see Overview of Tagging. If you're not sure whether to apply tags, skip this option (you can apply tags later) or ask your administrator.

    Resource logging

    Enable to allow tracking, troubleshooting, and data insights of the Object Storage bucket you are creating.

    Select Create bucket.

    The bucket is created immediately and you can start uploading objects to it. Objects added to archive buckets are immediately archived and must be restored before they're available for download.

  • Creating a Standard Default Storage Tier Bucket

    By default, a bucket is created in the Standard Object Storage tier. You don't need to explicitly set --storage-tier. Standard is the primary, default storage tier used for Object Storage service data. Use the Standard tier for storing data that requires fast and immediate access. Standard buckets do, however, provide an option to assign and upload objects to different storage tiers (Infrequent Access and Archive), while remaining in the Standard bucket.

    Use the oci os bucket create command and required parameters to create a bucket:

    oci os bucket create --compartment-id compartment_ocid --name bucket_name [OPTIONS]

    For example:

    oci os bucket create --compartment-id ocid.compartment.oc1..exampleuniqueID --name MyStandardBucket
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "7b7c3dc1-713f-4996-b176-a938345cae8e",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyStandardBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,
    "object-level-audit-mode": "Disabled",
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-12T19:04:05.879000+00:00",
    "versioning": "Disabled"
  },
  "etag": "7b7c3dc1-713f-4996-b176-a938345cae8e"
}
    You can also enable auto-tiering on a Standard bucket at creation time by specifying the optional --auto-tiering InfrequentAccess parameter. See Auto-Tiering for details. For example:
    oci os bucket create --compartment-id ocid.compartment.oc1..exampleuniqueID --name MyStandardBucket --auto-tiering Infrequent Access
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": "InfrequentAccess",
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "7b7c3dc1-713f-4996-b176-a938345cae8e",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyStandardBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,
    "object-level-audit-mode": "Disabled",
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-12T19:04:05.879000+00:00",
    "versioning": "Disabled"
  },
  "etag": "7b7c3dc1-713f-4996-b176-a938345cae8e"
}

    A Standard tier bucket is created immediately and you can start uploading objects.

    For a complete list of parameters and values for CLI commands, see the CLI Command Reference.

    Creating an Archive Default Storage Tier Bucket

    To create an Archive tier bucket, you must explicitly set --storage-tier Archive. Archive is the default storage tier used for Archive Storage service data. Use the Archive tier for storing data that doesn't require immediate access, but requires long retention periods. Access to data in the Archive tier isn't immediate. Archived data must be restored before the data is accessible.

    oci os bucket create --compartment-id compartment_ocid --name archive_bucket_name --storage-tier Archive [OPTIONS]

    For example:

    oci os bucket create --compartment-id ocid.compartment.oc1..exampleuniqueID --name MyArchiveBucket
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "7b7c3dc1-713f-4996-b176-a938345cae8e",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyArchiveBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,
    "object-level-audit-mode": "Disabled",
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Archive",
    "time-created": "2020-06-12T19:04:05.879000+00:00",
    "versioning": "Disabled"
  },
  "etag": "c8889cd1-8414-41fb-84b7-3738c39e62c5"
}

    An Archive Storage bucket is created and you can start uploading objects. Objects uploaded to Archive Storage buckets are immediately archived and must be restored before they're available for download.

    Creating Public Bucket (Listing and Downloading Bucket Objects)

    To create a public bucket that allows listing and downloading bucket objects, you must explicitly set --public-access-type ObjectRead.
    oci os bucket create --compartment-id compartment_ocid --name bucket_name --public-access-type ObjectRead [OPTIONS]

    For example:

    oci os bucket create --compartment-id ocid.compartment.oc1..exampleuniqueID --name MyPublicObjectReadBucket --public-access-type ObjectRead
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "01096e0b-659a-4d9d-a806-d57568cf1b22",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyPublicObjectReadBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,					
    "object-lifecycle-policy-etag": null,
    "public-access-type": "ObjectRead",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-22T19:04:05.879000+00:00",
    "versioning": "Disabled"
  },
  "etag": "01096e0b-659a-4d9d-a806-d57568cf1b22"
}

    Creating Public Bucket (Downloading Bucket Objects)

    To create a public bucket that allows just downloading bucket objects, you must explicitly set --public-access-type ObjectReadWithoutList.
    oci os bucket create --compartment-id compartment_ocid --name bucket_name --public-access-type ObjectReadWithoutList [OPTIONS]

    For example:

    oci os bucket create --compartment-id ocid.compartment.oc1..exampleuniqueID --name MyPublicObjectReadBucket --public-access-type ObjectReadWithoutList
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "ec20c59a-f5ba-4a6d-8a7e-b69bb9bb76ad",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyPublicObjectReadWithoutListBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,
    "object-lifecycle-policy-etag": null,
    "public-access-type": "ObjectReadWithoutList",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-22T20:18:29.203000+00:00",
    "versioning": "Disabled"
  },
  "etag": "ec20c59a-f5ba-4a6d-8a7e-b69bb9bb76ad"
}

    Creating a Bucket with Resource Tags

    You can create standard Object Storage tier or Archive tier buckets with resource tags.

    To add resource tags when creating a bucket, set one or both of the --defined-tags and --freeform-tags options.

    Tip

    The --defined-tags and --freeform-tags options require that the input to be a complex type formatted in valid JSON. See Passing Complex Input and Using a JSON File for Complex Input for information about JSON formatting.

    The following example syntax creates a standard Object Storage tier bucket with a defined tag:

    oci os bucket create --compartment-id compartment_id --name bucket_name --defined-tags 'JSON_formatted_defined_tag'  [OPTIONS]

    Examples of defined tag formatting:

    '{"Operations": {"CostCenter": "42"}'
    '{"Logistics": {"Procurement": "Madrid Center"}},"Financials":{"Production": "Unit 5"}}'
    Note

    If you're running the CLI on a Windows computer, you might need to use the backslash (\) character to escape the strings containing the tag values. For example, a single defined tag is formatted '{\"Logistics\": {\"Procurement\": \"Madrid Center\"}}'

    For example:

    oci os bucket create --compartment-id ocid.compartment.oc1..exampleuniqueID --name MyBucketDefined --defined-tags {"Operations": {"CostCenter": "42"}}
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {
      "operations": {
        "costcenter": "42"				}
    },
    "etag": "ea88f444-842c-462d-965e-d3540b3b54f6",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyBucketDefined",
    "namespace": "MyNamespace",
    "object-events-enabled": false,					
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-23T19:47:51.362000+00:00",
    "versioning": "Disabled"
  },
  "etag": "ea88f444-842c-462d-965e-d3540b3b54f6"
}

    The following example syntax creates a Standard tier bucket with a free-form tag:

    oci os bucket create --compartment-id compartment_ocid --name bucket_name --freeform-tags JSON_formatted_free-form_tag [OPTIONS]

    Examples of free-form tag formatting:

    '{"Chicago_Team": "marketing_videos"}'
    '{"Project": "prototype 3","Manager": "Meadows"}'
    Note

    If you're running the CLI on a Windows computer, you might need to use the backslash (\) character to escape the strings containing the tag values. For example, a single free-form tag is formatted as '{\"Chicago_Team\": {\"marketing_videos\"}}'

    For example:

    oci os bucket create --compartment-id ocid.compartment.oc1..exampleuniqueID --name MyBucketFreeform --freeform-tags {"Chicago_Team": "marketing_videos"}
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "6f4bda10-fc8b-462e-8563-875639fd7294",
    "freeform-tags": {
      "Chicago_Team": "marketing_videos"
    },
    "is-read-only": false,
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "kms-key-id": null,
    "metadata": {},
    "name": "MyBucketFreeform",
    "namespace": "MyNamespace",
    "object-events-enabled": false,					
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "storage-tier": "Standard",
    "time-created": "2020-06-23T20:51:16.260000+00:00"
  },
  "etag": "6f4bda10-fc8b-462e-8563-875639fd7294"
}

    Assigning a Key to the Bucket

    You can assign a Vault key to a bucket you're creating by including the kms_key_id parameter. 

    oci os bucket create --compartment-id ocid.compartment.oc1..exampleuniqueID --name bucket_name --kms-key-id kms_key_id [OPTIONS]

    where kms_key_id is the OCID of the key versions that contain the cryptographic material used to encrypt and decrypt data, protecting the data where the data is stored.

    For example:

    
oci os bucket create --compartment-id ocid.compartment.oc1..exampleuniqueID --name MyKeyBucket --kms-key-id ocid1.key.region1.sea..exampleuniqueID
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "e7f29fdd-b5f5-42e5-a98b-80883f9f2f32",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": "ocid1.key.region1.sea..exampleuniqueID",
    "metadata": {},
    "name": "MyKeyBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,					
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess"
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-29T23:00:35.490000+00:00",
    "versioning": "Disabled"
  },
  "etag": "e7f29fdd-b5f5-42e5-a98b-80883f9f2f32"
}

  • Run the CreateBucket operation to create a bucket.

    When accessing the Object Storage API, the bucket name is used with the Object Storage namespace name to form the request URL:

    n/object_storage_namespace/b/bucket

    Two key properties in the payload are:

    • publicAccessType property controls whether the bucket is private or public and limits the capability to list public bucket contents.
    • objectEventsEnabled property controls if events are emitted for the objects in this bucket.