Struct object_store::aws::AmazonS3Builder

pub struct AmazonS3Builder { /* private fields */ }

Configure a connection to Amazon S3 using the specified credentials in the specified Amazon region and bucket.

Example

let s3 = AmazonS3Builder::new()
 .with_region(REGION)
 .with_bucket_name(BUCKET_NAME)
 .with_access_key_id(ACCESS_KEY_ID)
 .with_secret_access_key(SECRET_KEY)
 .build();

Implementations

impl AmazonS3Builder

pub fn new() -> Self

Create a new AmazonS3Builder with default values.

pub fn from_env() -> Self

Fill the AmazonS3Builder with regular AWS environment variables

Variables extracted from environment:

• AWS_ACCESS_KEY_ID -> access_key_id
• AWS_SECRET_ACCESS_KEY -> secret_access_key
• AWS_DEFAULT_REGION -> region
• AWS_ENDPOINT -> endpoint
• AWS_SESSION_TOKEN -> token
• AWS_CONTAINER_CREDENTIALS_RELATIVE_URI -> https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html
• AWS_ALLOW_HTTP -> set to “true” to permit HTTP connections without TLS
• AWS_PROFILE -> set profile name, requires aws_profile feature enabled

Example

use object_store::aws::AmazonS3Builder;

let s3 = AmazonS3Builder::from_env()
    .with_bucket_name("foo")
    .build();

pub fn with_url(self, url: impl Into<String>) -> Self

Parse available connection info form a well-known storage URL.

The supported url schemes are:

• s3://<bucket>/<path>
• s3a://<bucket>/<path>
• https://s3.<bucket>.amazonaws.com
• https://<bucket>.s3.<region>.amazonaws.com

Note: Settings derived from the URL will override any others set on this builder

Example

use object_store::aws::AmazonS3Builder;

let s3 = AmazonS3Builder::from_env()
    .with_url("s3://bucket/path")
    .build();

pub fn try_with_option(
self,
key: impl AsRef<str>,
value: impl Into<String>
) -> Result<Self>

Set an option on the builder via a key - value pair.

This method will return an UnknownConfigKey error if key cannot be parsed into AmazonS3ConfigKey.

pub fn try_with_options<I: IntoIterator<Item = (impl AsRef<str>, impl Into<String>)>>(
self,
options: I
) -> Result<Self>

Hydrate builder from key value pairs

This method will return an UnknownConfigKey error if any key cannot be parsed into AmazonS3ConfigKey.

pub fn with_access_key_id(self, access_key_id: impl Into<String>) -> Self

Set the AWS Access Key (required)

pub fn with_secret_access_key(self, secret_access_key: impl Into<String>) -> Self

Set the AWS Secret Access Key (required)

pub fn with_region(self, region: impl Into<String>) -> Self

Set the region (e.g. us-east-1) (required)

pub fn with_bucket_name(self, bucket_name: impl Into<String>) -> Self

Set the bucket_name (required)

pub fn with_endpoint(self, endpoint: impl Into<String>) -> Self

Sets the endpoint for communicating with AWS S3. Default value is based on region. The endpoint field should be consistent with the field `virtual_hosted_style_request’.

For example, this might be set to "http://localhost:4566: for testing against a localstack instance. If virtual_hosted_style_request is set to true then endpoint should have bucket name included.

pub fn with_token(self, token: impl Into<String>) -> Self

Set the token to use for requests (passed to underlying provider)

pub fn with_allow_http(self, allow_http: bool) -> Self

Sets what protocol is allowed. If allow_http is :

• false (default): Only HTTPS are allowed
• true: HTTP and HTTPS are allowed

pub fn with_virtual_hosted_style_request(
self,
virtual_hosted_style_request: bool
) -> Self

Sets if virtual hosted style request has to be used. If virtual_hosted_style_request is :

• false (default): Path style request is used
• true: Virtual hosted style request is used

If the endpoint is provided then it should be consistent with virtual_hosted_style_request. i.e. if virtual_hosted_style_request is set to true then endpoint should have bucket name included.

pub fn with_retry(self, retry_config: RetryConfig) -> Self

Set the retry configuration

pub fn with_imdsv1_fallback(self) -> Self

By default instance credentials will only be fetched over IMDSv2, as AWS recommends against having IMDSv1 enabled on EC2 instances as it is vulnerable to SSRF attack

However, certain deployment environments, such as those running old versions of kube2iam, may not support IMDSv2. This option will enable automatic fallback to using IMDSv1 if the token endpoint returns a 403 error indicating that IMDSv2 is not supported.

This option has no effect if not using instance credentials

pub fn with_metadata_endpoint(self, endpoint: impl Into<String>) -> Self

Set the instance metadata endpoint, used primarily within AWS EC2.

This defaults to the IPv4 endpoint: http://169.254.169.254. One can alternatively use the IPv6 endpoint http://fd00:ec2::254.

pub fn with_proxy_url(self, proxy_url: impl Into<String>) -> Self

Set the proxy_url to be used by the underlying client

pub fn with_client_options(self, options: ClientOptions) -> Self

Sets the client options, overriding any already set

pub fn with_profile(self, profile: impl Into<String>) -> Self

Set the AWS profile name, see https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html

This makes use of aws-config to provide credentials and therefore requires the aws-profile feature to be enabled

It is strongly encouraged that users instead make use of a credential manager such as aws-vault not only to avoid the significant additional dependencies, but also to avoid storing credentials in plain text on disk

pub fn build(self) -> Result<AmazonS3>

Create a AmazonS3 instance from the provided values, consuming self.

Trait Implementations

impl Clone for AmazonS3Builder

fn clone(&self) -> AmazonS3Builder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AmazonS3Builder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AmazonS3Builder

fn default() -> AmazonS3Builder

Returns the “default value” for a type.