Package cloud/aws

The cloud/aws package

Configuration

The AWS SDK v2 based services use the following default settings for region and endpoint, meaning you get those values for every requested client if you don't specify anything else for the client.

cloud:
  aws:
    defaults:
      region: "eu-central-1"
      endpoint: "http://localhost:4566" #localstack

General service config

AWS service clients are created and configured by name. The pattern here is:

func ProvideClient(ctx context.Context, config cfg.Config, logger log.Logger, name string, optFns ...ClientOption) (*serviceX.Client, error)

ClientOption belongs to the selected service package and configures that service's ClientConfig, including its AWS SDK load options. The resulting client can be configured by:

cloud:
    aws:
        serviceX:
            clients:
                default: # name of the client
                    assume_role: ""
                    backoff:
                        cancel_delay: 0s
                        initial_interval: 50ms
                        max_attempts: 10
                        max_elapsed_time: 10m0s
                        max_interval: 10s
                    credentials:
                        access_key_id: ""
                        secret_access_key: ""
                        session_token: ""
                    credentials_cache:
                        expiry_window: 5m
                        expiry_window_jitter_frac: 0.1
                    endpoint: http://localhost:4566
                    http_client:
                        timeout: 0s
                    profile: ""
                    region: eu-central-1

Setting	Description	Default
assume_role	If defined, this role will be used to gain access	""
backoff.cancel_delay	If the request gets canceled, how long cancellation should be delayed	0s
backoff.initial_interval	The initial duration to wait before retrying the request on error	50ms
backoff.max_attempts	How many attempts should be done	10 (0 means retry forever)
backoff.max_interval	Max duration between 2 calls when retrying	10s
backoff.max_elapsed_time	For how long the service should retry the request	10m (0m means retry forever)
credentials_cache.expiry_window	The duration before cached credentials expire	5m
credentials_cache.expiry_window_jitter_frac	The fraction of the expiry window to use as jitter	0.1
endpoint	Which service endpoint should be called	http://localhost:4566
http_client.timeout	After what duration the request should be canceled, if the server doesn't respond	0s (no timeout)
profile	If defined, this aws profile will be used to fetch credentials	""
region	The region in use	eu-central-1

Cloudwatch

Call

import(
    gosoCloudwatch "github.com/justtrackio/gosoline/pkg/cloud/aws/cloudwatch"
)

cloudwatchClient, err := gosoCloudwatch.ProvideClient(ctx, config, logger, "default")
if err != nil {
    return err
}

to get the default cloudwatch client. You don't have to provide any config if you want to go with the default settings. The default settings are:

cloud:
    aws:
        cloudwatch:
            clients:
                default:
                    assume_role: ""
                    backoff:
                        cancel_delay: 0s
                        initial_interval: 50ms
                        max_attempts: 10
                        max_elapsed_time: 10m0s
                        max_interval: 10s
                    credentials:
                        access_key_id: ""
                        secret_access_key: ""
                        session_token: ""
                    credentials_cache:
                        expiry_window: 5m
                        expiry_window_jitter_frac: 0.1
                    endpoint: http://localhost:4566
                    http_client:
                        timeout: 0s
                    profile: ""
                    region: eu-central-1

These are the default values which are used if you don't provide any config by yourself.

In ordinary builds, empty credentials leave credential resolution to the AWS SDK's default chain. The integration build tag supplies test credentials instead. Set endpoint: "" when using AWS endpoints rather than LocalStack. See the released client settings and credential selection.

Different Client Names

You can specify different client names to customize specific fields for a particular client while inheriting the rest of the configuration. For example:

cloud:
  aws:
    dynamodb:
      clients:
        someClientName:
          naming:
            table_pattern: "{app.namespace}-{name}"

The configuration for a specific client name (e.g., someClientName) is resolved by merging settings in the following order of precedence:

Client-specific settings for the given service (e.g., cloud.aws.dynamodb.clients.someClientName)
Client-specific settings from the defaults (e.g., cloud.aws.defaults.clients.someClientName)
Service-wide default settings for the given service (e.g., cloud.aws.dynamodb.clients.default)
Global defaults for all clients (e.g., cloud.aws.defaults.clients.default)
Global defaults for all AWS clients (e.g., cloud.aws.defaults)

For example, if you specify:

cloud:
  aws:
    defaults:
      region: "eu-west-1"
      credentials:
        access_key_id: "default-access-key"
        secret_access_key: "default-secret"
      clients:
        default:
          region: "eu-west-2"
        clientWithoutEnvInName:
          backoff:
            type: infinite
    dynamodb:
      clients:
        default:
          region: "eu-central-1"
          naming:
            table_pattern: "{app.namespace}-{name}"
        clientWithoutEnvInName:
          naming:
            table_pattern: "{app.tags.group}-{name}"
    sqs:
      clients:
        clientWithoutEnvInName:
          naming:
            queue_pattern: "{app.tags.group}-{queueId}"

Then, the dynamodb client clientWithoutEnvInName will use:

region: eu-central-1 (from cloud.aws.dynamodb.clients.default since region is not explicitly set for clientWithoutEnvInName).
naming.table_pattern: {app.tags.group}-{name} (from cloud.aws.dynamodb.clients.clientWithoutEnvInName).
credentials: default-access-key and default-secret (from cloud.aws.defaults).
backoff.type: infinite (from cloud.aws.defaults.clients.clientWithoutEnvInName).

The sqs client clientWithoutEnvInName will use:

region: eu-west-2 (from cloud.aws.defaults.clients.default since region is not explicitly set for clientWithoutEnvInName).
naming.queue_pattern: {app.tags.group}-{queueId} (from cloud.aws.sqs.clients.clientWithoutEnvInName).
credentials: default-access-key and default-secret (from cloud.aws.defaults).
backoff.type: infinite (from cloud.aws.defaults.clients.clientWithoutEnvInName).

Full reference

cloud:
  aws:
    defaults:
      assume_role: "arn:aws:iam::123456789012:role/gosoline-test-role"
      credentials:
        access_key_id: "justtrack"
        secret_access_key: "justtrack"
        session_token: "justtrack"
      credentials_cache:
        expiry_window: 5m
        expiry_window_jitter_frac: 0.1
      profile: "sdlc-dev-account"
      endpoint: "http://localhost:4566"
      region: "eu-central-1"
    cloudwatch:
      clients:
        default:
          assume_role: "arn:aws:iam::123456789012:role/gosoline-test-role"
          credentials:
            access_key_id: "justtrack"
            secret_access_key: "justtrack"
            session_token: "justtrack"
          profile: "sdlc-dev-account"
          endpoint: "http://localhost:4566"
          region: "eu-central-1"
          http_client:
            timeout: 0s
          backoff:
            cancel_delay: 1s
            initial_interval: 50ms
            max_attempts: 10
            max_elapsed_time: 15m0s
            max_interval: 10s
    dynamodb:
      clients:
        default:
          naming:
            table_pattern: "{app.namespace}-{name}"
    kinesis:
      clients:
        default:
          credentials:
            access_key_id: "*******************"
            secret_access_key: "****************************************"
            session_token: "********************************************************************"
    s3:
      clients:
        default:
          usePathStyle: false
          endpoint: "https://s3.eu-central-1.amazonaws.com"
    sqs:
      clients:
        default:
          naming:
            queue_pattern: "{app.namespace}-{queueId}"

The cloud/aws package​

Configuration​

General service config​

Cloudwatch​

Different Client Names​

Full reference​