AWS clients for Erlang

:rocket: Create, configure, and manage AWS services from Erlang code. :rocket:

Features

This repo only holds generated code :exclamation: All non-generated code is included as part of aws_beam_core. Any changes that need to be made should hence be made through aws_beam_core or aws-codegen :exclamation:

Completely generated by aws-codegen from the same JSON descriptions of AWS services used to build the AWS SDKs (See: aws-sdk-go-v2)
A clean API separated per service. One module per service.
Support for most (almost all!) of the AWS services.
Documentation updated from the official AWS docs.
Type specs generated from the same JSON descriptions as the SDK

Usage

Here is an example of listing Amazon Kinesis streams. First of all, start a shell with rebar3 shell, then:

aws_s3

Here is another example, this time using a temporary client, showing how to upload a file to S3 and how to fetch it back:

> Client = aws_client:make_temporary_client(<<"my-access-key-id">>, <<"my-secret-access-key">>, <<"my-token">>, <<"eu-west-1">>).
[...]
> {ok, Content} = file:read_file("/tmp/erlang-logo.png").
[...]
> aws_s3:put_object(Client, <<"my-bucket">>, <<"my-key">>, #{<<"Body">> => Content}).
[...]
> {ok, Response, _} = aws_s3:get_object(Client, <<"my-bucket">>, <<"my-key">>).
[...]
> Content = maps:get(<<"Body">>, Response).

Support for creating Presigned URLs is provided through the aws_s3_presigned_url module.

aws_kinesis

> Client = aws_client:make_client(<<"my-access-key-id">>, <<"my-secret-access-key">>, <<"eu-west-1">>),
[...]
> {ok, Result, _Response} = aws_kinesis:list_streams(Client, #{}),
[...]
> io:format("~p~n", [Result]).
#{<<"HasMoreStreams">> => false,<<"StreamNames">> => []}

AWS RDS IAM Token Creation

Support for creating IAM Tokens (more info here) has been added as part of the aws_rds_iam_token module as part of aws_beam_core. This allows for easy creation of RDS/Aurora tokens to be used for IAM based authentication instead of username/password combination.

> Client = aws_client:make_temporary_client(<<"AccessKeyID">>, <<"SecretAccessKey">>, <<"Token">>, <<"eu-west-1">>).
[...]
> {ok, Url} = aws_rds_iam_token:rds_token_create(Client, <<"db_endpoint">>, 5432, <<"db_user">>).
[...]

This token can subsequently be used to connect to the database over IAM.

AWS S3 Presigned Url

Support for Presigning S3 urls has been added as part of the aws_s3_presigned_url module as part of aws_beam_core. This allows generating either a get or put presigned s3 url, which can be used by external clients such as cURL to access (get/put) the object in question.

> Client = aws_client:make_temporary_client(<<"AccessKeyID">>, <<"SecretAccessKey">>, <<"Token">>, <<"eu-west-1">>).
[...]
> {ok, Url} = aws_s3_presigned_url:make_presigned_v4_url(Client, put, 3600, <<"bucket">>, <<"key">>)
[...]

retry options

Each API which takes Options allows a retry_options key and can allow for automatic retries. Simple provide the following:

[{retry_options, {exponential_with_jitter, {MaxAttempts, BaseSleepTime, CapSleepTime}}} | <other_options>]

This implementation is based on AWS: Exponential Backoff And Jitter.

Installation

Simply add the library to your rebar.config:

{deps, [{aws, "1.1.0", {pkg, aws_erlang}}]}.

Obtaining Credentials

Credentials can be obtained via the separate aws_credentials application, which can be configured to fetch credentials from:

Erlang environment variables
OS environment variables
An AWS credentials file
ECS task credentials
EC2 metadata (including v2 - IMDS)

Here is an example on how to obtain credentials:

> Credentials = aws_credentials:get_credentials().
[...]
> #{ access_key_id := AccessKeyId
   , token := Token
   , region := Region
   , secret_access_key := SecretAccessKey } = Credentials.

The aws_credentials application is part of aws_beam_core and included in this package.

Development

The service-specific modules are generated using the aws-codegen library from the JSON descriptions of AWS services provided by Amazon.

The rest of the code is manually written and used as support for the generated code.

Documentation

Unfortunately the docs generated are too big for hexdocs.pm. Hence, the docs can be generated locally using:

$ rebar3 ex_doc

The docs will be available in ./doc.

Running Tests

$ rebar3 eunit

$ docker-compose -f test/docker/docker-compose.yml up -d
$ rebar3 ct
$ docker-compose -f test/docker/docker-compose.yml down

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.