Configuring the AWS SDK for Go

In the AWS SDK for Go, you can configure settings for service clients,
such as the log level and maximum number of retries. Most settings are
optional. However, for each service client, you must specify a region
and your credentials. The SDK uses these values to send requests to the
correct AWS Region and sign requests with the correct credentials. You
can specify these values as part of a session or as environment
variables.

Specifying the AWS Region

When you specify the region, you specify where to send requests, such as
us-west-2 or us-east-2. For a list of regions for each service, see Regions and Endpoints
in the Amazon Web Services General Reference.

The SDK does not have a default region.
To specify a region:

Set the AWS_REGION environment variable to the default region

Set the AWS_SDK_LOAD_CONFIG environment variable to true
to get the region value from the config file in the .aws/ folder in your home directory

Set the NewSessionWithOptions method argument SharedConfigState to SharedConfigEnable when you create a session
to get the region value from the config file in the .aws/ folder in your home directory

Set the region explicitly when you create a session

If you set a region using all of these techniques, the SDK uses the
region you explicitly specified in the session.

The following examples show you how to configure the environment
variable.

Specifying Credentials

The AWS SDK for Go requires credentials (an access key and secret access
key) to sign requests to AWS. You can specify your credentials in
several different locations, depending on your particular use case. For
information about obtaining credentials, see Setting Up.

When you initialize a new service client without providing any
credential arguments, the SDK uses the default credential provider
chain to find AWS credentials. The SDK uses the first provider
in the chain that returns credentials without an error. The default provider chain
looks for credentials in the following order:

Environment variables.

Shared credentials file.

If your application is running on an Amazon EC2 instance, IAM role for Amazon EC2.

The SDK detects and uses the built-in providers automatically, without
requiring manual configurations. For example, if you use IAM roles for
Amazon EC2 instances, your applications automatically use the
instance's credentials. You don't need to manually configure credentials
in your application.

As a best practice, AWS recommends that you specify credentials in the
following order:

Use IAM roles for Amazon EC2 (if your application is running on an
Amazon EC2 instance).

IAM roles provide applications on the instance temporary security
credentials to make AWS calls. IAM roles provide an easy way to
distribute and manage credentials on multiple Amazon EC2 instances.

Use a shared credentials file.

This credentials file is the same one used by other SDKs and the AWS CLI.
If you're already using a shared credentials file, you can also use
it for this purpose.

Use environment variables.

Setting environment variables is useful if you're doing development
work on a machine other than an Amazon EC2 instance.

Hard-code credentials (not recommended).

Hard-coding credentials in your application can make it difficult to
manage and rotate those credentials. Use this method only for small
personal scripts or testing purposes. Do not submit code with
credentials to source control.

IAM Roles for Amazon EC2 Instances

If you are running your application on an Amazon EC2 instance, you can
use the instance's IAM role
to get temporary security credentials to make calls to AWS.

If you have configured your instance to use IAM roles, the SDK uses
these credentials for your application automatically. You don't need to
manually specify these credentials.

Shared Credentials File

A credential file is a plaintext file that contains your access keys.
The file must be on the same machine on which you're running your
application. The file must be named credentials and located in the
.aws/ folder in your home directory. The home directory can vary by
operating system. In Windows, you can refer to your home directory by
using the environment variable %UserProfile%. In Unix-like systems, you
can use the environment variable $HOME or ~ (tilde).

If you already use this file for other SDKs and tools (like the AWS CLI),
you don't need to change anything to use the files in this SDK. If
you use different credentials for different tools or applications, you
can use profiles to configure multiple access keys in the same
configuration file.

Creating the Credentials File

If you don't have a shared credentials file (.aws/credentials), you
can use any text editor to create one in your home directory. Add the
following content to your credentials file, replacing
<YOUR_ACCESS_KEY_ID> and <YOUR_SECRET_ACCESS_KEY> with your
credentials.

Specifying Profiles

You can include multiple access keys in the same configuration file by
associating each set of access keys with a profile. For example, in your
credentials file, you can declare multiple profiles, as follows.

By default, the SDK checks the AWS_PROFILE environment variable to
determine which profile to use. If no AWS_PROFILE variable is set,
the SDK uses the default profile.

If you have an application named myapp that uses the SDK, you can
run it with the test credentials by setting the variable to
test-account myapp, as shown in the following command.

$ AWS_PROFILE=test-account myapp

You can also use the SDK to select a profile by specifying
os.Setenv("AWS_PROFILE", test-account) before constructing any
service clients or by manually setting the credential provider, as shown
in the following example.

Other Credentials Providers

The SDK provides other methods for retrieving credentials in the
aws/credentials package. For example, you can retrieve temporary
security credentials from AWS Security Token Service or credentials from
encrypted storage. For more information, see Credentials.

Configuring a Proxy

If you cannot directly connect to the internet, you can use Go-supported
environment variables (HTTP_PROXY) or create a custom HTTP client to
configure your proxy. Use the
Config.HTTPClient
struct to specify a custom HTTP client. For more information about how
to create an HTTP client to use a proxy, see the
Transport struct in
the Go http package.

Logging Service Calls

You can enable logging in a client by setting the LogLevel in a configuration instance,
as shown in the following snippet, which sets the log level to LogDebugWithHTTPBody for a new DynamoDB client.

Creating a Custom Endpoint

In most cases you use the endpoint that is pre-configured for a service.
However, you can specify a custom endpoint, such as for pre-release versions of the
service,
as shown in the following snippet,
which sets the Endpoint to https://test.us-west-2.amazonaws.com for a new DynamoDB client.