Skip to main content

PutObject

Contributors netapp-pcarriga
PDFs

You can use the S3 PutObject request to add an object to a bucket.

Resolve conflicts

Conflicting client requests, such as two clients writing to the same key, are resolved on a "latest-wins" basis. The timing for the "latest-wins" evaluation is based on when the StorageGRID system completes a given request, and not on when S3 clients begin an operation.

Object size

The maximum recommended size for a single PutObject operation is 5 GiB (5,368,709,120 bytes). If you have objects that are larger than 5 GiB, use multipart upload instead.

The maximum supported size for a single PutObject operation is 5 TiB (5,497,558,138,880 bytes).

Note If you upgraded from StorageGRID 11.6 or earlier, the S3 PUT Object size too large alert will be triggered if you attempt to upload an object that exceeds 5 GiB. If you have a new installation of StorageGRID 11.7 or 11.8, the alert won't be triggered in this case. However, to align with the AWS S3 standard, future releases of StorageGRID won't support uploads of objects larger than 5 GiB.

User metadata size

Amazon S3 limits the size of user-defined metadata within each PUT request header to 2 KB. StorageGRID limits user metadata to 24 KiB. The size of user-defined metadata is measured by taking the sum of the number of bytes in the UTF-8 encoding of each key and value.

UTF-8 characters in user metadata

If a request includes (unescaped) UTF-8 values in the key name or value of user-defined metadata, StorageGRID behavior is undefined.

StorageGRID does not parse or interpret escaped UTF-8 characters included in the key name or value of user-defined metadata. Escaped UTF-8 characters are treated as ASCII characters:

  • PutObject, CopyObject, GetObject, and HeadObject requests succeed if user-defined metadata includes escaped UTF-8 characters.

  • StorageGRID does not return the x-amz-missing-meta header if the interpreted value of the key name or value includes unprintable characters.

Object tag limits

You can add tags to new objects when you upload them, or you can add them to existing objects. Both StorageGRID and Amazon S3 support up to 10 tags for each object. Tags associated with an object must have unique tag keys. A tag key can be up to 128 Unicode characters in length and tag values can be up to 256 Unicode characters in length. Key and values are case sensitive.

Object ownership

In StorageGRID, all objects are owned by the bucket owner account, including objects created by a non-owner account or an anonymous user.

Supported request headers

The following request headers are supported:

  • Cache-Control

  • Content-Disposition

  • Content-Encoding

    When you specify aws-chunked for Content-EncodingStorageGRID does not verify the following items:

    • StorageGRID does not verify the chunk-signature against the chunk data.

    • StorageGRID does not verify the value that you provide for x-amz-decoded-content-length against the object.

  • Content-Language

  • Content-Length

  • Content-MD5

  • Content-Type

  • Expires

  • Transfer-Encoding

    Chunked transfer encoding is supported if aws-chunked payload signing is also used.

  • x-amz-checksum-sha256

  • x-amz-meta-, followed by a name-value pair containing user-defined metadata.

    When specifying the name-value pair for user-defined metadata, use this general format:

    x-amz-meta-name: value

    If you want to use the User defined creation time option as the Reference time for an ILM rule, you must use creation-time as the name of the metadata that records when the object was created. For example:

    x-amz-meta-creation-time: 1443399726

    The value for creation-time is evaluated as seconds since January 1, 1970.

    Note An ILM rule can't use both a User defined creation time for the Reference time and the Balanced or Strict ingest option. An error is returned when the ILM rule is created.

  • x-amz-tagging

  • S3 Object Lock request headers

    • x-amz-object-lock-mode

    • x-amz-object-lock-retain-until-date

    • x-amz-object-lock-legal-hold

      If a request is made without these headers, the bucket default retention settings are used to calculate the object version mode and retain-until-date. See Use S3 REST API to configure S3 Object Lock.

  • SSE request headers:

    • x-amz-server-side-encryption

    • x-amz-server-side-encryption-customer-key-MD5

    • x-amz-server-side-encryption-customer-key

    • x-amz-server-side-encryption-customer-algorithm

      See Request headers for server-side encryption

Unsupported request headers

The following request headers aren't supported:

  • x-amz-acl

  • x-amz-sdk-checksum-algorithm

  • x-amz-trailer

  • x-amz-website-redirect-location

    The x-amz-website-redirect-location header returns XNotImplemented.

Storage class options

The x-amz-storage-class request header is supported. The value submitted for x-amz-storage-class affects how StorageGRID protects object data during ingest and not how many persistent copies of the object are stored in the StorageGRID system (which is determined by ILM).

If the ILM rule matching an ingested object uses the Strict ingest option, the x-amz-storage-class header has no effect.

The following values can be used for x-amz-storage-class:

  • STANDARD (Default)

    • Dual commit: If the ILM rule specifies the Dual commit option for Ingest Behavior, as soon as an object is ingested a second copy of that object is created and distributed to a different Storage Node (dual commit). When the ILM is evaluated, StorageGRID determines if these initial interim copies satisfy the placement instructions in the rule. If they don't, new object copies might need to be made in different locations and the initial interim copies might need to be deleted.

    • Balanced: If the ILM rule specifies the Balanced option and StorageGRID can't immediately make all copies specified in the rule, StorageGRID makes two interim copies on different Storage Nodes.

      If StorageGRID can immediately create all object copies specified in the ILM rule (synchronous placement), the x-amz-storage-class header has no effect.

  • REDUCED_REDUNDANCY

    • Dual commit: If the ILM rule specifies the Dual commit option for Ingest Behavior, StorageGRID creates a single interim copy as the object is ingested (single commit).

    • Balanced: If the ILM rule specifies the Balanced option, StorageGRID makes a single interim copy only if the system can't immediately make all copies specified in the rule. If StorageGRID can perform synchronous placement, this header has no effect. The REDUCED_REDUNDANCY option is best used when the ILM rule that matches the object creates a single replicated copy. In this case using REDUCED_REDUNDANCY eliminates the unnecessary creation and deletion of an extra object copy for every ingest operation.

    Using the REDUCED_REDUNDANCY option is not recommended in other circumstances. REDUCED_REDUNDANCY increases the risk of object data loss during ingest. For example, you might lose data if the single copy is initially stored on a Storage Node that fails before ILM evaluation can occur.

Caution Having only one replicated copy for any time period puts data at risk of permanent loss. If only one replicated copy of an object exists, that object is lost if a Storage Node fails or has a significant error. You also temporarily lose access to the object during maintenance procedures such as upgrades.

Specifying REDUCED_REDUNDANCY only affects how many copies are created when an object is first ingested. It does not affect how many copies of the object are made when the object is evaluated by the active ILM policies, and does not result in data being stored at lower levels of redundancy in the StorageGRID system.

Note If you are ingesting an object into a bucket with S3 Object Lock enabled, the REDUCED_REDUNDANCY option is ignored. If you are ingesting an object into a legacy Compliant bucket, the REDUCED_REDUNDANCY option returns an error. StorageGRID will always perform a dual-commit ingest to ensure that compliance requirements are satisfied.

Request headers for server-side encryption

You can use the following request headers to encrypt an object with server-side encryption. The SSE and SSE-C options are mutually exclusive.

  • SSE: Use the following header if you want to encrypt the object with a unique key managed by StorageGRID.

    • x-amz-server-side-encryption

      When the x-amz-server-side-encryption header isn't included in the PutObject request, the grid-wide stored object encryption setting is omitted from the PutObject response.

  • SSE-C: Use all three of these headers if you want to encrypt the object with a unique key that you provide and manage.

    • x-amz-server-side-encryption-customer-algorithm: Specify AES256.

    • x-amz-server-side-encryption-customer-key: Specify your encryption key for the new object.

    • x-amz-server-side-encryption-customer-key-MD5: Specify the MD5 digest of the new object's encryption key.

Caution The encryption keys you provide are never stored. If you lose an encryption key, you lose the corresponding object. Before using customer-provided keys to secure object data, review the considerations for using server-side encryption.
Note If an object is encrypted with SSE or SSE-C, any bucket-level or grid-level encryption settings are ignored.

Versioning

If versioning is enabled for a bucket, a unique versionId is automatically generated for the version of the object being stored. This versionId is also returned in the response using the x-amz-version-id response header.

If versioning is suspended, the object version is stored with a null versionId and if a null version already exists it will be overwritten.

Signature calculations for the Authorization header

When using the Authorization header to authenticate requests, StorageGRID differs from AWS in the following ways:

  • StorageGRID doesn't require host headers to be included within CanonicalHeaders.

  • StorageGRID doesn't require Content-Type to be included within CanonicalHeaders.

  • StorageGRID doesn't require x-amz-* headers to be included within CanonicalHeaders.

Note As a general best practice, always include these headers within CanonicalHeaders to ensure they are verified; however, if you exclude these headers, StorageGRID does not return an error.

For details, refer to Signature Calculations for the Authorization Header: Transferring Payload in a Single Chunk (AWS Signature Version 4).

Related information