{"id":13507564,"url":"https://github.com/erlcloud/erlcloud","last_synced_at":"2025-10-21T19:03:05.456Z","repository":{"id":1117304,"uuid":"988103","full_name":"erlcloud/erlcloud","owner":"erlcloud","description":"AWS APIs library for Erlang (Amazon EC2, S3, SQS, DDB,  ELB and etc)","archived":false,"fork":false,"pushed_at":"2025-02-20T16:02:58.000Z","size":5035,"stargazers_count":648,"open_issues_count":37,"forks_count":448,"subscribers_count":46,"default_branch":"master","last_synced_at":"2025-02-20T17:22:33.113Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/erlcloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2010-10-14T20:32:41.000Z","updated_at":"2025-02-20T16:03:03.000Z","dependencies_parsed_at":"2023-07-05T20:17:00.296Z","dependency_job_id":"1a0586d7-5482-4a8c-ab62-25d9f94d2238","html_url":"https://github.com/erlcloud/erlcloud","commit_stats":{"total_commits":1339,"total_committers":214,"mean_commits":6.257009345794392,"dds":0.9044062733383121,"last_synced_commit":"6e36f7f4dc91f229cad1e156020d2a985f3d61d3"},"previous_names":[],"tags_count":155,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erlcloud%2Ferlcloud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erlcloud%2Ferlcloud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erlcloud%2Ferlcloud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erlcloud%2Ferlcloud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/erlcloud","download_url":"https://codeload.github.com/erlcloud/erlcloud/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246301963,"owners_count":20755512,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T02:00:36.248Z","updated_at":"2025-10-21T19:03:05.334Z","avatar_url":"https://github.com/erlcloud.png","language":"Erlang","funding_links":[],"categories":["Cloud Infrastructure and Management","Erlang"],"sub_categories":[],"readme":"# erlcloud: AWS APIs library for Erlang\n\n[![Build Status](https://github.com/erlcloud/erlcloud/workflows/build/badge.svg)](https://github.com/erlcloud/erlcloud/actions/workflows/ci.yml)\n[![Hex.pm](https://img.shields.io/hexpm/v/erlcloud)](https://hex.pm/packages/erlcloud)\n[![Hex.pm](https://img.shields.io/hexpm/l/erlcloud)](COPYRIGHT)\n\n\nThis library is not developed or maintained by AWS thus lots of functionality\nis still missing comparing to [aws-cli](https://aws.amazon.com/cli/) or\n[boto](https://github.com/boto/boto).  Required functionality is being added\nupon request.\n\nService APIs implemented:\n\n- Amazon Elastic Compute Cloud (EC2)\n- Amazon EC2 Container Service (ECS)\n- Amazon Simple Storage Service (S3)\n- Amazon Simple Queue Service (SQS)\n- Amazon SimpleDB\n- Amazon Mechanical Turk\n- Amazon CloudWatch (MON)\n- Amazon CloudSearch\n- Amazon Inspector\n- Amazon Key Management Service (KMS)\n- Amazon DirectConnect\n- Amazon DynamoDB \u0026 DDB streams (ddb2)\n- Amazon Autoscaling (AS)\n- Amazon CloudTrail (CT)\n- Cloud Formation (CFN)\n- Config\n- ElasticLoadBalancing (ELB)\n- Identity and Access Management (IAM)\n- Kinesis\n- Glue (Catalog table, Crawlers and Job APIs support)\n- Athena\n- Step Functions (SF)\n- CloudWatch\n- MechanicalTurk\n- Simple DB (SDB)\n- Relational Data Service (RDS)\n- Simple Email Service (SES)\n- Short Token Service (STS)\n- Simple Notification Service (SNS)\n- Web Application Firewall (WAF)\n- AWS Cost and Usage Report API\n- AWS Secrets Manager\n- AWS Systems Manager (SSM)\n- and more to come\n\nThe majority of API functions have been implemented.  Not all functions have\nbeen thoroughly tested, so exercise care when integrating this library into\nproduction code. Please send issues and patches.\n\nThe libraries can be used two ways.  You can:\n\n- specify configuration parameters in the process dictionary. Useful for simple\n  tasks, or\n- create a configuration object and pass that to each request as the final\n  parameter. Useful for Cross AWS Account access\n\n## Roadmap\n\nBelow is the library roadmap update along with regular features and fixes.\n\n- 3.0.X\n  - ~~Remove R16 support~~ __done__\n  - Support maps\n\n- 3.X.X\n  - Fix dialyzer findings and make it mandatory for the library\n  - Only SigV4 signing and generalised in one module. Keep SigV2 in SBD section only\n  - No more `erlang:error()` use and use of regular tuples as error API.\n    Breaking change.\n\n### Major API compatibility changes between 0.13.X and 2.0.x\n\n- ELB APIs\n- ... list to be filled shortly\n\n### Supported Erlang versions\n\nAt the moment we support the following OTP releases:\n\n- 19.3\n- 20.3\n- 21.3\n- 22.3\n- 23.3\n- 24.3\n- 25.3\n- 26.2\n- 27.1\n\nThis list is determined by ensuring eunit tests and dialyzer checks succeed for these versions, but not all of these\nversions are in active use by library authors. Please report any issues discovered in actual use.\n\nThe Github Actions test runners only support OTP 24+ due to runtime issues, but OTP 19-23 were tested locally with unmodified,\nofficial [Erlang docker images](https://hub.docker.com/_/erlang). Dialyzer checks run against the latest hex-published hackney\nfor 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\nfor OTP 19-23 due to newer versions of parse_trans requiring OTP 21+.\n\n## Getting started\n\nYou need to clone the repository and download rebar/rebar3 (if it's not already\navailable in your path).\n\n```sh\ngit clone https://github.com/erlcloud/erlcloud.git\ncd erlcloud\nwget https://s3.amazonaws.com/rebar3/rebar3\nchmod a+x rebar3\n```\n\nTo compile and run erlcloud:\n\n```sh\nmake\nmake run\n```\n\nTo use erlcloud in your application, add it as a dependency in your\napplication's configuration file.  erlcloud is also available as a [Hex](https://hex.pm) package,  refer to the Hex [`mix` usage docs](https://hex.pm/docs/usage) or [`rebar3` usage docs](https://hex.pm/docs/rebar3-usage) for more help including dependencies using Hex syntax.\n\nTo use erlcloud in the shell, you can start\nit by calling:\n\n```erlang\napplication:ensure_all_started(erlcloud).\n```\n\n### Using Temporary Security Credentials\n\nWhen access to AWS resources is managed through [third-party identity\nproviders](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp.html)\nit is performed using [temporary security\ncredentials](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html).\n\nYou can provide your AWS credentials in OS environment variables\n\n```sh\nexport AWS_ACCESS_KEY_ID=\u003cYour AWS Access Key\u003e\nexport AWS_SECRET_ACCESS_KEY=\u003cYour AWS Secret Access Key\u003e\nexport AWS_SESSION_TOKEN=\u003cYour AWS Security Token\u003e\nexport AWS_DEFAULT_REGION=\u003cYour region\u003e\n```\n\nIf you did not provide your AWS credentials in the OS environment variables,\nthen you need to provide configuration read from your profile:\n\n```erlang\n{ok, Conf} = erlcloud_aws:profile().\nerlcloud_s3:list_buckets(Conf).\n```\n\nOr you can provide them via `erlcloud` application environment variables.\n\n```erlang\napplication:set_env(erlcloud, aws_access_key_id, \"your key\"),\napplication:set_env(erlcloud, aws_secret_access_key, \"your secret key\"),\napplication:set_env(erlcloud, aws_security_token, \"your token\"),\napplication:set_env(erlcloud, aws_region, \"your region\"),\n```\n\n### Using Access Key\n\nYou can provide your AWS credentials in environmental variables.\n\n```sh\nexport AWS_ACCESS_KEY_ID=\u003cYour AWS Access Key\u003e\nexport AWS_SECRET_ACCESS_KEY=\u003cYour AWS Secret Access Key\u003e\n```\n\nIf you did not provide your AWS credentials in the environment variables, then\nyou need to provide the per-process configuration:\n\n```erlang\nerlcloud_ec2:configure(AccessKeyId, SecretAccessKey [, Hostname]).\n```\n\nHostname defaults to non-existing `\"ec2.amazonaws.com\"` intentionally to avoid\nmix with US-East-1 Refer to\n[aws_config](https://github.com/erlcloud/erlcloud/blob/master/include/erlcloud_aws.hrl)\nfor full description of all services configuration.\n\nConfiguration object usage:\n\n```erlang\nEC2 = erlcloud_ec2:new(AccessKeyId, SecretAccessKey [, Hostname])\nerlcloud_ec2:describe_images(EC2).\n```\n\n### aws_config\n\nThe [aws_config](https://github.com/erlcloud/erlcloud/blob/master/include/erlcloud_aws.hrl)\nrecord contains many valuable defaults, such as protocols and ports for AWS\nservices. You can always redefine them by making new `#aws_config{}` record and\nchanging particular fields, then passing the result to any `erlcloud` function.\n\nBut if you want to change something in runtime this might be tedious and/or not\nflexible enough.\n\nAn alternative approach is to set default fields within the `app.config -\u003e\nerlcloud -\u003e aws_config` section and rely on the config, used by all functions\nby default.\n\nExample of such `app.config`:\n\n```erlang\n[\n  {erlcloud, [\n      {aws_config, [\n          {s3_scheme, \"http://\"},\n          {s3_host, \"s3.example.com\"}\n      ]}\n  ]}\n].\n```\n\n### VPC endpoints\n\nIf you want to utilise AZ affinity for VPC endpoints you can configure those in\napplication config via:\n\n```erlang\n{erlcloud, [\n    {services_vpc_endpoints, [\n        {\u003c\u003c\"sqs\"\u003e\u003e, [\u003c\u003c\"myAZ1.sqs-dns.amazonaws.com\"\u003e\u003e, \u003c\u003c\"myAZ2.sqs-dns.amazonaws.com\"\u003e\u003e]},\n        {\u003c\u003c\"kinesis\"\u003e\u003e, {env, \"KINESIS_VPC_ENDPOINTS\"}}\n    ]}\n]}\n```\n\nTwo options are supported:\n\n- explicit list of Route53 AZ endpoints\n- OS environment variable (handy for ECS deployments). The value of the\n  variable should be of comma-separated string like\n  `\"myAZ1.sqs-dns.amazonaws.com,myAZ2.sqs-dns.amazonaws.com\"`\n\nUpon config generation, `erlcloud` will check the AZ of the deployment and\nmatch it to one of the pre-configured DNS records. First match is used and if\nnot match found default is used.\n\n## Basic use\n\nThen you can start making API calls, like:\n\n```erlang\nerlcloud_ec2:describe_images().\n% list buckets of Account stored in config in process dict\n% of of the account you are running in.\nerlcloud_s3:list_buckets().\nerlcloud_s3:list_buckets(erlcloud_aws:default_cfg()).\n% List buckets on 3d Account from Conf\nerlcloud_s3:list_buckets(Conf).\n```\n\nCreating an EC2 instance may look like this:\n\n```erlang\nstart_instance(Ami, KeyPair, UserData, Type, Zone) -\u003e\n    Config = #aws_config{\n            access_key_id = application:get_env(aws_key),\n            secret_access_key = application:get_env(aws_secret)\n           },\n    InstanceSpec = #ec2_instance_spec{image_id = Ami,\n                                      key_name = KeyPair,\n                                      instance_type = Type,\n                                      availability_zone = Zone,\n                                      user_data = UserData},\n    erlcloud_ec2:run_instances(InstanceSpec, Config).\n```\n\nFor usage information, consult the source code and\n[GitHub repo](https://hexdocs.pm/erlcloud). For detailed API description refer\nto the AWS references at:\n\n- [AmazonEC2](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/Welcome.html)\n- [Amazon S3](http://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html)\n- and [other services](https://aws.amazon.com/documentation/)\n\n## Notes\n\nIndentation in contributions should follow indentation style of surrounding\ntext.  In general it follows default indentation rules of official erlang-mode\nas provided by OTP team.\n\n## Best Practices\n\n- All interfaces should provide a method for working with non-default config.\n- Public interfaces with paging logic should prefer `{ok, Results, Marker}`\n  style to the `{{paged, Marker}, Results}` found in some modules.\n  In case of records output, tokens should be part of the record.\n- Passing next page `NextToken`, `NextMarker` is preferred with `Opts` rather\n  than a fun parameter like found in many modules.\n- Public interfaces should normally expose proplists over records. All new\n  modules are preferred to have both.\n- Exposed records are to be used only for complex outputs. Examples to follow:\n  ddb2, ecs.\n- Library should not expose any long running or stateful processes - no\n  gen_servers, no caches and etc.\n\n\n## Publishing to hex.pm\n\nerlcloud is available as a [Hex](https://hex.pm) 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.\n\nGithub Actions will eventually be used to automatically publish new versions.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferlcloud%2Ferlcloud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferlcloud%2Ferlcloud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferlcloud%2Ferlcloud/lists"}