Home

Awesome

erlcloud: AWS APIs library for Erlang

Build Status Hex.pm Hex.pm

This library is not developed or maintained by AWS thus lots of functionality is still missing comparing to aws-cli or boto. Required functionality is being added upon request.

Service APIs implemented:

The majority of API functions have been implemented. Not all functions have been thoroughly tested, so exercise care when integrating this library into production code. Please send issues and patches.

The libraries can be used two ways. You can:

Roadmap

Below is the library roadmap update along with regular features and fixes.

Major API compatibility changes between 0.13.X and 2.0.x

Supported Erlang versions

At the moment we support the following OTP releases:

This list is determined by ensuring eunit tests and dialyzer checks succeed for these versions, but not all of these versions are in active use by library authors. Please report any issues discovered in actual use.

The Github Actions test runners only support OTP 24+ due to runtime issues, but OTP 19-23 were tested locally with unmodified, official Erlang docker images. Dialyzer checks run against the latest hex-published hackney for OTP 24+, but a previous versions of hackney (1.15.0) and its dependency parse_trans (3.2.0) were used to do dialyzer checks for OTP 19-23 due to newer versions of parse_trans requiring OTP 21+.

Getting started

You need to clone the repository and download rebar/rebar3 (if it's not already available in your path).

git clone https://github.com/erlcloud/erlcloud.git
cd erlcloud
wget https://s3.amazonaws.com/rebar3/rebar3
chmod a+x rebar3

To compile and run erlcloud:

make
make run

To use erlcloud in your application, add it as a dependency in your application's configuration file. erlcloud is also available as a Hex package, refer to the Hex mix usage docs or rebar3 usage docs for more help including dependencies using Hex syntax.

To use erlcloud in the shell, you can start it by calling:

application:ensure_all_started(erlcloud).

Using Temporary Security Credentials

When access to AWS resources is managed through third-party identity providers it is performed using temporary security credentials.

You can provide your AWS credentials in OS environment variables

export AWS_ACCESS_KEY_ID=<Your AWS Access Key>
export AWS_SECRET_ACCESS_KEY=<Your AWS Secret Access Key>
export AWS_SESSION_TOKEN=<Your AWS Security Token>
export AWS_DEFAULT_REGION=<Your region>

If you did not provide your AWS credentials in the OS environment variables, then you need to provide configuration read from your profile:

{ok, Conf} = erlcloud_aws:profile().
erlcloud_s3:list_buckets(Conf).

Or you can provide them via erlcloud application environment variables.

application:set_env(erlcloud, aws_access_key_id, "your key"),
application:set_env(erlcloud, aws_secret_access_key, "your secret key"),
application:set_env(erlcloud, aws_security_token, "your token"),
application:set_env(erlcloud, aws_region, "your region"),

Using Access Key

You can provide your AWS credentials in environmental variables.

export AWS_ACCESS_KEY_ID=<Your AWS Access Key>
export AWS_SECRET_ACCESS_KEY=<Your AWS Secret Access Key>

If you did not provide your AWS credentials in the environment variables, then you need to provide the per-process configuration:

erlcloud_ec2:configure(AccessKeyId, SecretAccessKey [, Hostname]).

Hostname defaults to non-existing "ec2.amazonaws.com" intentionally to avoid mix with US-East-1 Refer to aws_config for full description of all services configuration.

Configuration object usage:

EC2 = erlcloud_ec2:new(AccessKeyId, SecretAccessKey [, Hostname])
erlcloud_ec2:describe_images(EC2).

aws_config

The aws_config record contains many valuable defaults, such as protocols and ports for AWS services. You can always redefine them by making new #aws_config{} record and changing particular fields, then passing the result to any erlcloud function.

But if you want to change something in runtime this might be tedious and/or not flexible enough.

An alternative approach is to set default fields within the app.config -> erlcloud -> aws_config section and rely on the config, used by all functions by default.

Example of such app.config:

[
  {erlcloud, [
      {aws_config, [
          {s3_scheme, "http://"},
          {s3_host, "s3.example.com"}
      ]}
  ]}
].

VPC endpoints

If you want to utilise AZ affinity for VPC endpoints you can configure those in application config via:

{erlcloud, [
    {services_vpc_endpoints, [
        {<<"sqs">>, [<<"myAZ1.sqs-dns.amazonaws.com">>, <<"myAZ2.sqs-dns.amazonaws.com">>]},
        {<<"kinesis">>, {env, "KINESIS_VPC_ENDPOINTS"}}
    ]}
]}

Two options are supported:

Upon config generation, erlcloud will check the AZ of the deployment and match it to one of the pre-configured DNS records. First match is used and if not match found default is used.

Basic use

Then you can start making API calls, like:

erlcloud_ec2:describe_images().
% list buckets of Account stored in config in process dict
% of of the account you are running in.
erlcloud_s3:list_buckets().
erlcloud_s3:list_buckets(erlcloud_aws:default_cfg()).
% List buckets on 3d Account from Conf
erlcloud_s3:list_buckets(Conf).

Creating an EC2 instance may look like this:

start_instance(Ami, KeyPair, UserData, Type, Zone) ->
    Config = #aws_config{
            access_key_id = application:get_env(aws_key),
            secret_access_key = application:get_env(aws_secret)
           },
    InstanceSpec = #ec2_instance_spec{image_id = Ami,
                                      key_name = KeyPair,
                                      instance_type = Type,
                                      availability_zone = Zone,
                                      user_data = UserData},
    erlcloud_ec2:run_instances(InstanceSpec, Config).

For usage information, consult the source code and GitHub repo. For detailed API description refer to the AWS references at:

Notes

Indentation in contributions should follow indentation style of surrounding text. In general it follows default indentation rules of official erlang-mode as provided by OTP team.

Best Practices

Publishing to hex.pm

erlcloud is available as a Hex package. A new version of the package can be published by maintainers using mix or rebar3. A hex-publish make target that uses rebar3 is provided for maintainers to use or reference when publishing a new version of the package.

Github Actions will eventually be used to automatically publish new versions.