{"id":13778602,"url":"https://github.com/Kong/lua-resty-aws","last_synced_at":"2025-05-11T12:31:06.958Z","repository":{"id":39192911,"uuid":"330924252","full_name":"Kong/lua-resty-aws","owner":"Kong","description":"AWS SDK for OpenResty","archived":false,"fork":false,"pushed_at":"2024-10-15T08:08:01.000Z","size":430,"stargazers_count":24,"open_issues_count":8,"forks_count":25,"subscribers_count":24,"default_branch":"main","last_synced_at":"2024-10-30T13:22:55.458Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://kong.github.io/lua-resty-aws/topics/README.md.html","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2021-01-19T09:15:05.000Z","updated_at":"2024-10-10T01:49:07.000Z","dependencies_parsed_at":"2023-11-06T09:39:07.041Z","dependency_job_id":"cc931a27-3bd6-4b4c-867c-45357c27700b","html_url":"https://github.com/Kong/lua-resty-aws","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kong%2Flua-resty-aws","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kong%2Flua-resty-aws/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kong%2Flua-resty-aws/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kong%2Flua-resty-aws/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kong","download_url":"https://codeload.github.com/Kong/lua-resty-aws/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225048958,"owners_count":17412901,"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-03T18:00:55.247Z","updated_at":"2024-11-17T14:30:40.223Z","avatar_url":"https://github.com/Kong.png","language":"Lua","funding_links":[],"categories":["Libraries","Lua"],"sub_categories":[],"readme":"# lua-resty-aws\n\n\n## Overview\n\nAWS SDK for OpenResty. The SDK is generated from the [original AWS JavaScript\nrepository details](https://github.com/aws/aws-sdk-js/tree/master/apis).\n\n[The documentation](https://kong.github.io/lua-resty-aws/topics/README.md.html)\nwill mostly cover the specifics for this library, the actual\n[services invoked are documented by AWS](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/).\n\nFor a quick start on how to use this library checkout\n[the examples of the AWS class](https://kong.github.io/lua-resty-aws/classes/AWS.html).\n\n---\n\n## Status\n\nNot everything has been implemented,\nand testing is hard since it requires access to AWS resources and not just\nregular CI.\n\n---\n\n## Example\n\nSee [the example](https://kong.github.io/lua-resty-aws/classes/AWS.html) in the documentation.\n\n---\n\n## Usage IMPORTANT!!\n\n### `attempt to yield across C-call boundary` error\n\nThis typically happens when initializing from within a `require` call.\nSee [Global settings](#global-settings) below on how to initialize properly.\n\n---\n\n### TLS and certificate failures\n\nThe http client defaults to tls name verification. For this to work, the CA store must be set.\nWith OpenResty this is done through the [`lua_ssl_trusted_certificate`](https://github.com/openresty/lua-nginx-module#lua_ssl_trusted_certificate)\ndirective. However; the compatibility module used, [`lua-resty-luasocket`](https://github.com/Tieske/lua-resty-luasocket), cannot automatically\nread that setting, hence you have to set it manually, see [the docs](https://tieske.github.io/lua-resty-luasocket/modules/resty.luasocket.html#get_luasec_defaults).\n\n---\n\n### Global settings\n\nThis library depends on global settings. Especially the core services for authentication\nand metadata. Many of those can (also) be specified as environment variables.  Environment\nvariables can only be accessed during the OpenResty `init` phase.  Thus, to ensure correct\nconfiguration from environment variables, the `resty.aws.config` module must be required on\nthe top-level of the module using this library:\n\n```Lua\nlocal aws_config = require(\"resty.aws.config\")\n```\n\nThe `.global` property of the `aws_config` variable can then be used as the global\nconfiguration.  Note that when `.global` is first accessed, automatic region detection\nthrough the AWS metadata service is performed.  Thus, it is not advisable to access\nit on the module level unless to avoid startup delays in non-AWS environment, caused by\nthe requests to the metadata service timing out.\n\n---\n\n### EC2 metadata\n\nThe endpoint for EC2 metadata can block (until timeout) if the SDK is used on a non-EC2\nmachine. In that case you might want to set the `AWS_EC2_METADATA_DISABLED` to a value\ndifferent from `false` (which is the default).\n\n```\n        export AWS_EC2_METADATA_DISABLED=true\n```\n\n\n---\n\n## Installation\n\nInstallation is easiest using LuaRocks:\n\n    luarocks install lua-resty-aws\n\nTo install from the git repo:\n\n    git clone https://github.com/Kong/lua-resty-aws.git\n    cd lua-resty-aws\n    make install\n\n### Troubleshooting\n\nMacOS has a known issue that the libexpat header file 'expat_config.h' is missing. If you run into that issue, install libexpat manually (eg. `brew install expat`). And then include the libexpat location when installing;\n        luarocks install lua-resty-aws EXPAT_DIR=/path/to/expat\n\nDetails: https://github.com/lunarmodules/luaexpat/issues/32\n\n---\n\n## Development\n\nTo update the SDK version being used edit the version tag in [`update_api_files.sh`](https://github.com/Kong/lua-resty-aws/blob/main/update_api_files.sh)\nand then run:\n\n    make dev\n\nMake sure to run `make dev` to pull in the generated files. Documentation can be\ngenerated using [ldoc](https://github.com/lunarmodules/LDoc) by running:\n\n    make docs\n\nNote that distribution is a little more complex than desired. This is because the\nrepo does not contain all the json files pulled in from the JS sdk. This in turn\nmeans that `luarocks upload` cannot build a rock from the repo (because it is\nincomplete after just being pulled).\n\nTo work around this the `make pack` command actually builds a .rock file that\nis compatible with LuaRocks. The `make upload` target will upload the generated\nrock.\n\nSee the detailed release instructions at [History](#history).\n\n---\n\n## Testing\n\nTests are executed using Busted and LuaCheck:\n\n    busted\n    luacheck .\n\nor run\n\n    make test\n\n---\n\n## To do\n\n- Implement the request/response objects (more AWS like, currently Lua modules)\n- Implement additional signatures (only V4 currently)\n- Implement retries from the global config\n- Additional tests for other services\n\n---\n\n## Copyright and license\n\nCopyright: (c) 2020-2024 Kong, Inc.\n\nAuthor: Thijs Schreijer\n\nLicense: [Apache 2.0](https://github.com/Kong/lua-resty-aws/blob/main/LICENSE)\n\n---\n\n## History\n\nVersioning is strictly based on [Semantic Versioning](https://semver.org/)\n\nRelease process:\n\n1. create a release branch `VERSION=x.y.z \u0026\u0026 git checkout main \u0026\u0026 git pull \u0026\u0026 git checkout -b release/$VERSION`\n1. update the changelog below\n1. run `make clean \u0026\u0026 make dev \u0026\u0026 make test \u0026\u0026 make docs`\n1. commit as `release x.y.z`\n1. push the branch, create a PR and get it merged.\n1. tag the release commit with the version `VERSION=x.y.z \u0026\u0026 git checkout main \u0026\u0026 git pull \u0026\u0026 git tag $VERSION`\n1. push the tag\n1. run `VERSION=x.y.z make pack`\n1. test the created `.rock` file `VERSION=x.y.z \u0026\u0026 luarocks install lua-resty-aws-$VERSION-1.src.rock`\n1. upload using: `VERSION=x.y.z APIKEY=abc... make upload`\n1. test installing the rock from LuaRocks\n\n\n### 1.5.4 (23-Sep-2024)\n\n- fix: fix configure endpoint bug in getRegionPrefix\n  [129](https://github.com/Kong/lua-resty-aws/pull/129)\n\n### 1.5.3 (02-Aug-2024)\n\n- fix: build the request body based on payload field\n  [126](https://github.com/Kong/lua-resty-aws/pull/126)\n\n\n### 1.5.2 (29-Jul-2024)\n\n- fix: fix sts regional endpoint injection under several cases\n  [123](https://github.com/Kong/lua-resty-aws/pull/123)\n\n### 1.5.1 (20-Jun-2024)\n\n- fix: when a \"blob\" type has no location specified, then use it as the body, same as with other types.\n  [120](https://github.com/Kong/lua-resty-aws/pull/120)\n\n### 1.5.0 (20-May-2024)\n\n- feat: decode AWS api response json body with array metatable\n  [114](https://github.com/Kong/lua-resty-aws/pull/114)\n\n- fix: do not inject region info for sts service with VPC endpoint hostname\n  [113](https://github.com/Kong/lua-resty-aws/pull/113)\n\n### 1.4.1 (19-Apr-2024)\n\n- fix: patch expanduser function to be more friendly to OpenResty environment\n  [111](https://github.com/Kong/lua-resty-aws/pull/111)\n\n### 1.4.0 (20-Mar-2024)\n\n- fix: aws configuration cannot be loaded due to pl.path cannot resolve the path started with ~\n  [94](https://github.com/Kong/lua-resty-aws/pull/94)\n- fix: fix the bug of missing boolean type with a value of false in the generated request body\n  [100](https://github.com/Kong/lua-resty-aws/pull/100)\n- security: remove the documentation entry that contains a sample access key from AWS SDK. This\n  avoids false postive vulnerability report.\n  [102](https://github.com/Kong/lua-resty-aws/pull/102)\n- feat: container credential provider now supports using auth token defined in\n  AWS_CONTAINER_AUTHORIZATION_TOKEN and AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE.\n  [107](https://github.com/Kong/lua-resty-aws/pull/107)\n- fix: operations without inputs (eg, some S3 ones) would cause errors to be thrown\n  [108](https://github.com/Kong/lua-resty-aws/pull/108)\n\n### 1.3.6 (25-Dec-2023)\n\n- fix: validator failure for some of the field types\n  [95](https://github.com/Kong/lua-resty-aws/pull/95)\n\n### 1.3.5 (19-Sep-2023)\n\n- fix: lazily initialize structures to avoid c-boundary errors on require\n  [87](https://github.com/Kong/lua-resty-aws/pull/87)\n\n### 1.3.4 (13-Sep-2023)\n\n- fix: remove more module-level uses of config.global\n  [83](https://github.com/Kong/lua-resty-aws/pull/83)\n\n### 1.3.3 (13-Sep-2023)\n\n- fix: don't invoke region detection code on the module toplevel and advise against trying to.\n  [81](https://github.com/Kong/lua-resty-aws/pull/81)\n\n### 1.3.2 (13-Sep-2023)\n\n- fix: unsigned request should support network related config option\n  [79](https://github.com/Kong/lua-resty-aws/pull/79)\n\n### 1.3.1 (17-Aug-2023)\n\n- fix: fix v4 signing request should correctly canonicalized query table as well\n  [76](https://github.com/Kong/lua-resty-aws/pull/76)\n\n### 1.3.0 (15-Aug-2023)\n\n- fix: fix AWS_CONTAINER_CREDENTIALS_FULL_URI parsing.\n  [#65](https://github.com/Kong/lua-resty-aws/pull/65)\n- feat: support configure timeout on service request.\n  [#67](https://github.com/Kong/lua-resty-aws/pull/67)\n- feat: support configure keepalive idle time on service request connection.\n  [#67](https://github.com/Kong/lua-resty-aws/pull/67)\n- feat: support configure ssl verify on service request.\n  [#67](https://github.com/Kong/lua-resty-aws/pull/67)\n- feat: add http/https proxy support for service request\n  [#69](https://github.com/Kong/lua-resty-aws/pull/69)\n- fix: fix proxy-related global config var name to lowercase.\n  [#70](https://github.com/Kong/lua-resty-aws/pull/70)\n- feat: EC2 metadata credential provider support IMDSv2\n  [#71](https://github.com/Kong/lua-resty-aws/pull/71)\n\n### 1.2.3 (20-Jul-2023)\n\n- fix: fix assumeRole function name on STS.\n  [#59](https://github.com/Kong/lua-resty-aws/pull/59)\n- fix: fix STS regional endpoint injection in build_request\n  [#62](https://github.com/Kong/lua-resty-aws/pull/62)\n- fix: replace deprecated pl.xml with luaexpat; fix STS assume role logic.\n  [#61](https://github.com/Kong/lua-resty-aws/pull/61)\n\n### 1.2.2 (2-May-2023)\n\n- fix: add the SharedFileCredentials into rockspec so it can be packed and used correctly.\n  [#53](https://github.com/Kong/lua-resty-aws/pull/53)\n- fix: the field `idempotencyToken` should be allowed and remain unvalidated as an opaque string.\n  [#52](https://github.com/Kong/lua-resty-aws/pull/52)\n\n### 1.2.1 (24-Apr-2023)\n\n- fix: fix the rds signer cannot be used in init phase.\n  [#50](https://github.com/Kong/lua-resty-aws/pull/50)\n\n### 1.2.0 (1-Mar-2023)\n\n- **IMPORTANT-IMPORTANT-IMPORTANT** feat: enable TLS name verification. This might\n  break if your CA store is not the default system one. See [usage notes](#usage-important).\n  [#47](https://github.com/Kong/lua-resty-aws/pull/47)\n- fix: STS regional endpoints woudl re-inject the region on every authentication\n  (after a token expired), causing bad hostnames to be used\n  [#45](https://github.com/Kong/lua-resty-aws/issues/45)\n- Feat: add RDS.Signer to generate tokens for RDS DB access\n  [#44](https://github.com/Kong/lua-resty-aws/issues/44)\n\n### 1.1.2 (7-Dec-2022)\n\n- fix: auto detection scheme and default to tls [#42](https://github.com/Kong/lua-resty-aws/pull/42)\n\n### 1.1.1 (21-Nov-2022)\n\n- fix: port is repeated when port is not standard [#39](https://github.com/Kong/lua-resty-aws/pull/39)\n\n### 1.1.0 (18-Nov-2022)\n\n- fix: template handling of query string [#36](https://github.com/Kong/lua-resty-aws/pull/36)\n- fix: blob param should be in raw body [#36](https://github.com/Kong/lua-resty-aws/pull/36)\n- feat: support for credential from file [#36](https://github.com/Kong/lua-resty-aws/pull/36)\n- fix: escaping for param in uri [#36](https://github.com/Kong/lua-resty-aws/pull/36)\n- fix: handling raw body conflict with body param [#36](https://github.com/Kong/lua-resty-aws/pull/36)\n- fix: crash when no type check designated [#36](https://github.com/Kong/lua-resty-aws/pull/36)\n- fix: support for \"headers\" location in API template [#36](https://github.com/Kong/lua-resty-aws/pull/36)\n- fix: support new API format (bucket in host) for S3 [#36](https://github.com/Kong/lua-resty-aws/pull/36)\n\n### 1.0.1 (20-Oct-2022)\n\n- fix: for some method incorrect URL is generates because of incorrect handling of \"+\" in URL template\n   [#34](https://github.com/Kong/lua-resty-aws/pull/34)\n\n### 1.0.0 (13-Oct-2022)\n\n- fix: `latest` doesn't indicate the most recent service version\n   [#28](https://github.com/Kong/lua-resty-aws/pull/28)\n\n### 0.5.5 (26-Sep-2022)\n\n - fix: variable names for ECS Conatiner Metatdata were missing an '_'\n   [#26](https://github.com/Kong/lua-resty-aws/pull/26)\n\n### 0.5.4 (19-Aug-2022)\n\n - chore: remove error message when no region is found\n   during config initialization [#24](https://github.com/Kong/lua-resty-aws/pull/24)\n\n### 0.5.3 (19-Aug-2022)\n\n - feat: lazy load API modules\n   [#23](https://github.com/Kong/lua-resty-aws/pull/23)\n\n### 0.5.2 (12-Jul-2022)\n\n - fix: relax validation to not validate some generic metadata fields. Encountered\n   while trying to use Lambda [#21](https://github.com/Kong/lua-resty-aws/pull/21)\n - fix: better error handling when credential providers fail to load\n   [#22](https://github.com/Kong/lua-resty-aws/pull/22)\n\n### 0.5.1 (01-Jun-2022)\n\n - feat: socket compatibility; overriding luasocket use in phases now returns\n   the existing setting\n\n### 0.5.0 (01-Jun-2022)\n\n - feat: enable use of regional STS endpoints\n - deps: bumped the [lua-resty-http](https://github.com/ledgetech/lua-resty-http)\n   dependency to 0.16 to disable the warnings and use the better connection building logic.\n - fix: added `sock:settimeouts` to the socket compatibility layer.\n - feat: implement a config object based on AWS CLI configuration.\n   - for most use cases it will now suffice to load the `config` in the `init` phase\n     since it caches al predefined environment variables.\n   - BREAKING: getting EC2 credentials will now honor AWS_EC2_METADATA_DISABLED.\n     Behaviour might change, but is expected to be very rare.\n   - BREAKING: The TokenFileWebIdentityCredentials\n     will honor the `role_session_name` setting (file or env) as default name.\n     Behaviour might change, but is expected to be very rare.\n\n\n### 0.4.0 (06-Dec-2021)\n\n - feat: added TokenFileWebIdentityCredentials. This adds default IAM credentials\n   to be picked up on EKS. The default AWS instance creates a CredentialProviderChain\n   which includes TokenFileWebIdentity. So on EKS it will now pick up container\n   based credentials instead of falling back to the underlying (more coarse) EC2\n   credentials.\n - fix: for 'query' type calls, add target action and version, which are required\n - fix: allow for unsigned requests for services requiring that (STS)\n - fix: do not validate patterns as regexes are incompatible\n\n### 0.3 (02-Sep-2021)\n\n - feat: capability to fetch metadata for ECS tasks (EC2 \u0026 Fargate), versions 2, 3, and 4\n - feat: capability to fetch IMDS metadata (EC2 \u0026 EKS), versions 1, and 2\n - feat: automatic region detection, check the docs for details (utils module)\n - fix: EC2MetadataCredentials no longer reuses the http-client to prevent issues\n   with the underlying compatibility layer.\n\n### 0.2 (05-Aug-2021)\n\n - fix: rockspec, add Penlight dependency\n - fix: add proper json Content-Type header from meta-data\n - fix: use proper signingName for the signature\n\n### 0.1 (03-Feb-2021) Initial released version\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKong%2Flua-resty-aws","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FKong%2Flua-resty-aws","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKong%2Flua-resty-aws/lists"}