Struct: aws.Config

import "../ibm-cos-sdk-go/aws"

Overview

A Config provides service configuration for service clients. By default, all clients will use the defaults.DefaultConfig structure.

// Create Session with MaxRetries configuration to be shared by multiple
// service clients.
sess := session.Must(session.NewSession(&aws.Config{
    MaxRetries: aws.Int(3),
}))

// Create S3 service client with a specific Region.
svc := s3.New(sess, &aws.Config{
    Region: aws.String("us-west-2"),
})

Implemented Interfaces

s3crypto.Cipher, s3manager.ReadSeekerWriteTo, s3manager.WriterReadFrom

Structure Field Summary collapse

Constructor Functions collapse

Method Summary collapse

Structure Field Details

Credentials *credentials.Credentials

The credentials object to use when signing requests. Defaults to a chain of credential providers to search for credentials in environment variables, shared credential file, and EC2 Instance Roles.

CredentialsChainVerboseErrors *bool

Enables verbose error printing of all credential chain errors. Should be used when wanting to see all errors while attempting to retrieve credentials.

DisableComputeChecksums *bool

Disables the computation of request and response checksums, e.g., CRC32 checksums in Amazon DynamoDB.

DisableEndpointHostPrefix *bool

DisableEndpointHostPrefix will disable the SDK's behavior of prefixing request endpoint hosts with modeled information.

Disabling this feature is useful when you want to use local endpoints for testing that do not support the modeled host prefix pattern.

DisableParamValidation *bool

Disables semantic parameter validation, which validates input for missing required fields and/or other semantic request input errors.

DisableRestProtocolURICleaning *bool

DisableRestProtocolURICleaning will not clean the URL path when making rest protocol requests. Will default to false. This would only be used for empty directory names in s3 requests.

Example: sess := session.Must(session.NewSession(&aws.Config{ DisableRestProtocolURICleaning: aws.Bool(true), }))

svc := s3.New(sess) out, err := svc.GetObject(&s3.GetObjectInput { Bucket: aws.String(“bucketname”), Key: aws.String(“//foo//bar//moo”), })

DisableSSL *bool

Set this to true to disable SSL when sending requests. Defaults to false.

EC2MetadataDisableTimeoutOverride *bool

Set this to true to disable the EC2Metadata client from overriding the default http.Client's Timeout. This is helpful if you do not want the EC2Metadata client to create a new http.Client. This options is only meaningful if you're not already using a custom HTTP client with the SDK. Enabled by default.

Must be set and provided to the session.NewSession() in order to disable the EC2Metadata overriding the timeout for default credentials chain.

Example: sess := session.Must(session.NewSession(aws.NewConfig() .WithEC2MetadataDisableTimeoutOverride(true)))

svc := s3.New(sess)

EC2MetadataEnableFallback *bool

Set this to false to disable EC2Metadata client from falling back to IMDSv1. By default, EC2 role credentials will fall back to IMDSv1 as needed for backwards compatibility. You can disable this behavior by explicitly setting this flag to false. When false, the EC2Metadata client will return any errors encountered from attempting to fetch a token instead of silently using the insecure data flow of IMDSv1.

Example: sess := session.Must(session.NewSession(aws.NewConfig() .WithEC2MetadataEnableFallback(false)))

svc := s3.New(sess)

See configuring IMDS for more information.

EnableEndpointDiscovery *bool

EnableEndpointDiscovery will allow for endpoint discovery on operations that have the definition in its model. By default, endpoint discovery is off. To use EndpointDiscovery, Endpoint should be unset or set to an empty string.

Example: sess := session.Must(session.NewSession(&aws.Config{ EnableEndpointDiscovery: aws.Bool(true), }))

svc := s3.New(sess) out, err := svc.GetObject(&s3.GetObjectInput { Bucket: aws.String(“bucketname”), Key: aws.String(“/foo/bar/moo”), })

Endpoint *string

An optional endpoint URL (hostname only or fully qualified URI) that overrides the default generated endpoint for a client. Set this to nil or the value to "" to use the default generated endpoint.

Note: You must still provide a Region value when specifying an endpoint for a client.

EndpointResolver endpoints.Resolver

The resolver to use for looking up endpoints for AWS service clients to use based on region.

EnforceShouldRetryCheck *bool

EnforceShouldRetryCheck is used in the AfterRetryHandler to always call ShouldRetry regardless of whether or not if request.Retryable is set. This will utilize ShouldRetry method of custom retryers. If EnforceShouldRetryCheck is not set, then ShouldRetry will only be called if request.Retryable is nil. Proper handling of the request.Retryable field is important when setting this field.

HTTPClient *http.Client

The HTTP client to use when sending requests. Defaults to http.DefaultClient.

LogLevel *LogLevelType

An integer value representing the logging level. The default log level is zero (LogOff), which represents no logging. To enable logging set to a LogLevel Value.

Logger Logger

The logger writer interface to write logging messages to. Defaults to standard out.

LowerCaseHeaderMaps *bool

Set this to true to enable the SDK to unmarshal API response header maps to normalized lower case map keys.

For example S3's X-Amz-Meta prefixed header will be unmarshaled to lower case Metadata member's map keys. The value of the header in the map is unaffected.

The AWS SDK for Go v2, uses lower case header maps by default. The v1 SDK provides this opt-in for this option, for backwards compatibility.

MaxRetries *int

The maximum number of times that a request will be retried for failures. Defaults to -1, which defers the max retry setting to the service specific configuration.

Region *string

The region to send requests to. This parameter is required and must be configured globally or on a per-client basis unless otherwise noted. A full list of regions is found in the “Regions and Endpoints” document.

See docs.aws.amazon.com/general/latest/gr/rande.html for AWS Regions and Endpoints.

Retryer RequestRetryer

Retryer guides how HTTP requests should be retried in case of recoverable failures.

When nil or the value does not implement the request.Retryer interface, the client.DefaultRetryer will be used.

When both Retryer and MaxRetries are non-nil, the former is used and the latter ignored.

To set the Retryer field in a type-safe manner and with chaining, use the request.WithRetryer helper function:

cfg := request.WithRetryer(aws.NewConfig(), myRetryer)

S3Disable100Continue *bool

Set this to true to disable the SDK adding the Expect: 100-Continue header to PUT requests over 2MB of content. 100-Continue instructs the HTTP client not to send the body until the service responds with a continue status. This is useful to prevent sending the request body until after the request is authenticated, and validated.

docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUT.html

100-Continue is only enabled for Go 1.6 and above. See http.Transport's ExpectContinueTimeout for information on adjusting the continue wait timeout. golang.org/pkg/net/http/#Transport

You should use this flag to disable 100-Continue if you experience issues with proxies or third party S3 compatible services.

S3DisableContentMD5Validation *bool

S3DisableContentMD5Validation config option is temporarily disabled, For S3 GetObject API calls, #1837.

Set this to true to disable the S3 service client from automatically adding the ContentMD5 to S3 Object Put and Upload API calls. This option will also disable the SDK from performing object ContentMD5 validation on GetObject API calls.

S3ForcePathStyle *bool

Set this to true to force the request to use path-style addressing, i.e., http://s3.amazonaws.com/BUCKET/KEY. By default, the S3 client will use virtual hosted bucket addressing when possible (http://BUCKET.s3.amazonaws.com/KEY).

Note: This configuration option is specific to the Amazon S3 service.

See docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html for Amazon S3: Virtual Hosting of Buckets

S3UsEast1RegionalEndpoint endpoints.S3UsEast1RegionalEndpoint

S3UsEast1RegionalEndpoint will enable regional or legacy endpoint resolving

S3UseARNRegion *bool

Set this to true to have the S3 service client to use the region specified in the ARN, when an ARN is provided as an argument to a bucket parameter.

S3UseAccelerate *bool

Set this to true to enable S3 Accelerate feature. For all operations compatible with S3 Accelerate will use the accelerate endpoint for requests. Requests not compatible will fall back to normal S3 requests.

The bucket must be enable for accelerate to be used with S3 client with accelerate enabled. If the bucket is not enabled for accelerate an error will be returned. The bucket name must be DNS compatible to also work with accelerate.

SleepDelay func(time.Duration)

UseFIPSEndpoint specifies the resolver must resolve a FIPS endpoint. IBM Unsupported UseFIPSEndpoint endpoints.FIPSEndpointState SleepDelay is an override for the func the SDK will call when sleeping during the lifecycle of a request. Specifically this will be used for request delays. This value should only be used for testing. To adjust the delay of a request see the aws/client.DefaultRetryer and aws/request.Retryer.

SleepDelay will prevent any Context from being used for canceling retry delay of an API operation. It is recommended to not use SleepDelay at all and specify a Retryer instead.

UseDualStack *bool

Instructs the endpoint to be generated for a service client to be the dual stack endpoint. The dual stack endpoint will support both IPv4 and IPv6 addressing.

Setting this for a service which does not support dual stack will fail to make requests. It is not recommended to set this value on the session as it will apply to all service clients created with the session. Even services which don't support dual stack endpoints.

If the Endpoint config value is also provided the UseDualStack flag will be ignored.

Only supported with.

sess := session.Must(session.NewSession())

svc := s3.New(sess, &aws.Config{
    UseDualStack: aws.Bool(true),
})

Deprecated: This option will continue to function for S3 and S3 Control for backwards compatibility. UseDualStackEndpoint should be used to enable usage of a service's dual-stack endpoint for all service clients moving forward. For S3 and S3 Control, when UseDualStackEndpoint is set to a non-zero value it takes higher precedence then this option.

UseDualStackEndpoint endpoints.DualStackEndpointState

Sets the resolver to resolve a dual-stack endpoint for the service.

Function Details

func NewConfig() *Config

NewConfig returns a new Config pointer that can be chained with builder methods to set multiple configuration values inline without using pointers.

// Create Session with MaxRetries configuration to be shared by multiple
// service clients.
sess := session.Must(session.NewSession(aws.NewConfig().
    WithMaxRetries(3),
))

// Create S3 service client with a specific Region.
svc := s3.New(sess, aws.NewConfig().
    WithRegion("us-west-2"),
)



309
310
311
 
// File 'aws/config.go', line 309


func NewConfig() *Config {
	return &Config{}
}

Method Details

func (c *Config) Copy(cfgs ...*Config) *Config

Copy will return a shallow copy of the Config object. If any additional configurations are provided they will be merged into the new config returned.



630
631
632
633
634
635
636
637
638
639
 
// File 'aws/config.go', line 630


func (c *Config) Copy(cfgs ...*Config) *Config {
	dst := &Config{}
	dst.MergeIn(c)

	for _, cfg := range cfgs {
		dst.MergeIn(cfg)
	}

	return dst
}

func (c *Config) MergeIn(cfgs ...*Config)

MergeIn merges the passed in configs into the existing config object.



497
498
499
500
501
 
// File 'aws/config.go', line 497


func (c *Config) MergeIn(cfgs ...*Config) {
	for _, other := range cfgs {
		mergeInConfig(c, other)
	}
}

func (c *Config) WithCredentials(creds *credentials.Credentials) *Config

WithCredentials sets a config Credentials value returning a Config pointer for chaining.



322
323
324
325
 
// File 'aws/config.go', line 322


func (c *Config) WithCredentials(creds *credentials.Credentials) *Config {
	c.Credentials = creds
	return c
}

func (c *Config) WithCredentialsChainVerboseErrors(verboseErrs bool) *Config

WithCredentialsChainVerboseErrors sets a config verbose errors boolean and returning a Config pointer.



315
316
317
318
 
// File 'aws/config.go', line 315


func (c *Config) WithCredentialsChainVerboseErrors(verboseErrs bool) *Config {
	c.CredentialsChainVerboseErrors = &verboseErrs
	return c
}

func (c *Config) WithDisableComputeChecksums(disable bool) *Config

WithDisableComputeChecksums sets a config DisableComputeChecksums value returning a Config pointer for chaining.



378
379
380
381
 
// File 'aws/config.go', line 378


func (c *Config) WithDisableComputeChecksums(disable bool) *Config {
	c.DisableComputeChecksums = &disable
	return c
}

func (c *Config) WithDisableEndpointHostPrefix(t bool) *Config

WithDisableEndpointHostPrefix will set whether or not to use modeled host prefix when making requests.



470
471
472
473
 
// File 'aws/config.go', line 470


func (c *Config) WithDisableEndpointHostPrefix(t bool) *Config {
	c.DisableEndpointHostPrefix = &t
	return c
}

func (c *Config) WithDisableParamValidation(disable bool) *Config

WithDisableParamValidation sets a config DisableParamValidation value returning a Config pointer for chaining.



371
372
373
374
 
// File 'aws/config.go', line 371


func (c *Config) WithDisableParamValidation(disable bool) *Config {
	c.DisableParamValidation = &disable
	return c
}

func (c *Config) WithDisableRestProtocolURICleaning(t bool) *Config

WithDisableRestProtocolURICleaning sets a config DisableRestProtocolURICleaning value returning a Config pointer for chaining.



491
492
493
494
 
// File 'aws/config.go', line 491


func (c *Config) WithDisableRestProtocolURICleaning(t bool) *Config {
	c.DisableRestProtocolURICleaning = &t
	return c
}

func (c *Config) WithDisableSSL(disable bool) *Config

WithDisableSSL sets a config DisableSSL value returning a Config pointer for chaining.



350
351
352
353
 
// File 'aws/config.go', line 350


func (c *Config) WithDisableSSL(disable bool) *Config {
	c.DisableSSL = &disable
	return c
}

func (c *Config) WithEC2MetadataDisableTimeoutOverride(enable bool) *Config

WithEC2MetadataDisableTimeoutOverride sets a config EC2MetadataDisableTimeoutOverride value returning a Config pointer for chaining.



443
444
445
446
 
// File 'aws/config.go', line 443


func (c *Config) WithEC2MetadataDisableTimeoutOverride(enable bool) *Config {
	c.EC2MetadataDisableTimeoutOverride = &enable
	return c
}

func (c *Config) WithEC2MetadataEnableFallback(v bool) *Config

WithEC2MetadataEnableFallback sets a config EC2MetadataEnableFallback value returning a Config pointer for chaining.



450
451
452
453
 
// File 'aws/config.go', line 450


func (c *Config) WithEC2MetadataEnableFallback(v bool) *Config {
	c.EC2MetadataEnableFallback = &v
	return c
}

func (c *Config) WithEndpoint(endpoint string) *Config

WithEndpoint sets a config Endpoint value returning a Config pointer for chaining.



329
330
331
332
 
// File 'aws/config.go', line 329


func (c *Config) WithEndpoint(endpoint string) *Config {
	c.Endpoint = &endpoint
	return c
}

func (c *Config) WithEndpointDiscovery(t bool) *Config

WithEndpointDiscovery will set whether or not to use endpoint discovery.



463
464
465
466
 
// File 'aws/config.go', line 463


func (c *Config) WithEndpointDiscovery(t bool) *Config {
	c.EnableEndpointDiscovery = &t
	return c
}

func (c *Config) WithEndpointResolver(resolver endpoints.Resolver) *Config

WithEndpointResolver sets a config EndpointResolver value returning a Config pointer for chaining.



336
337
338
339
 
// File 'aws/config.go', line 336


func (c *Config) WithEndpointResolver(resolver endpoints.Resolver) *Config {
	c.EndpointResolver = resolver
	return c
}

func (c *Config) WithHTTPClient(client *http.Client) *Config

WithHTTPClient sets a config HTTPClient value returning a Config pointer for chaining.



357
358
359
360
 
// File 'aws/config.go', line 357


func (c *Config) WithHTTPClient(client *http.Client) *Config {
	c.HTTPClient = client
	return c
}

func (c *Config) WithLogger(logger Logger) *Config

WithLogger sets a config Logger value returning a Config pointer for chaining.



392
393
394
395
 
// File 'aws/config.go', line 392


func (c *Config) WithLogger(logger Logger) *Config {
	c.Logger = logger
	return c
}

func (c *Config) WithLogLevel(level LogLevelType) *Config

WithLogLevel sets a config LogLevel value returning a Config pointer for chaining.



385
386
387
388
 
// File 'aws/config.go', line 385


func (c *Config) WithLogLevel(level LogLevelType) *Config {
	c.LogLevel = &level
	return c
}

func (c *Config) WithLowerCaseHeaderMaps(t bool) *Config

WithLowerCaseHeaderMaps sets a config LowerCaseHeaderMaps value returning a Config pointer for chaining.



484
485
486
487
 
// File 'aws/config.go', line 484


func (c *Config) WithLowerCaseHeaderMaps(t bool) *Config {
	c.LowerCaseHeaderMaps = &t
	return c
}

func (c *Config) WithMaxRetries(max int) *Config

WithMaxRetries sets a config MaxRetries value returning a Config pointer for chaining.



364
365
366
367
 
// File 'aws/config.go', line 364


func (c *Config) WithMaxRetries(max int) *Config {
	c.MaxRetries = &max
	return c
}

func (c *Config) WithRegion(region string) *Config

WithRegion sets a config Region value returning a Config pointer for chaining.



343
344
345
346
 
// File 'aws/config.go', line 343


func (c *Config) WithRegion(region string) *Config {
	c.Region = ®ion
	return c
}

func (c *Config) WithS3Disable100Continue(disable bool) *Config

WithS3Disable100Continue sets a config S3Disable100Continue value returning a Config pointer for chaining.



406
407
408
409
 
// File 'aws/config.go', line 406


func (c *Config) WithS3Disable100Continue(disable bool) *Config {
	c.S3Disable100Continue = &disable
	return c
}

func (c *Config) WithS3DisableContentMD5Validation(enable bool) *Config

WithS3DisableContentMD5Validation sets a config S3DisableContentMD5Validation value returning a Config pointer for chaining.



421
422
423
424
425
 
// File 'aws/config.go', line 421


func (c *Config) WithS3DisableContentMD5Validation(enable bool) *Config {
	c.S3DisableContentMD5Validation = &enable
	return c

}

func (c *Config) WithS3ForcePathStyle(force bool) *Config

WithS3ForcePathStyle sets a config S3ForcePathStyle value returning a Config pointer for chaining.



399
400
401
402
 
// File 'aws/config.go', line 399


func (c *Config) WithS3ForcePathStyle(force bool) *Config {
	c.S3ForcePathStyle = &force
	return c
}

func (c *Config) WithS3UseAccelerate(enable bool) *Config

WithS3UseAccelerate sets a config S3UseAccelerate value returning a Config pointer for chaining.



413
414
415
416
417
 
// File 'aws/config.go', line 413


func (c *Config) WithS3UseAccelerate(enable bool) *Config {
	c.S3UseAccelerate = &enable
	return c

}

func (c *Config) WithS3UseARNRegion(enable bool) *Config

WithS3UseARNRegion sets a config S3UseARNRegion value and returning a Config pointer for chaining



429
430
431
432
 
// File 'aws/config.go', line 429


func (c *Config) WithS3UseARNRegion(enable bool) *Config {
	c.S3UseARNRegion = &enable
	return c
}

func (c *Config) WithS3UsEast1RegionalEndpoint(sre endpoints.S3UsEast1RegionalEndpoint) *Config

WithS3UsEast1RegionalEndpoint will set whether or not to use regional endpoint flag when resolving the endpoint for a service



477
478
479
480
 
// File 'aws/config.go', line 477


func (c *Config) WithS3UsEast1RegionalEndpoint(sre endpoints.S3UsEast1RegionalEndpoint) *Config {
	c.S3UsEast1RegionalEndpoint = sre
	return c
}

func (c *Config) WithSleepDelay(fn func(time.Duration)) *Config

WithSleepDelay overrides the function used to sleep while waiting for the next retry. Defaults to time.Sleep.



457
458
459
460
 
// File 'aws/config.go', line 457


func (c *Config) WithSleepDelay(fn func(time.Duration)) *Config {
	c.SleepDelay = fn
	return c
}

func (c *Config) WithUseDualStack(enable bool) *Config

WithUseDualStack sets a config UseDualStack value returning a Config pointer for chaining.



436
437
438
439
 
// File 'aws/config.go', line 436


func (c *Config) WithUseDualStack(enable bool) *Config {
	c.UseDualStack = &enable
	return c
}