AWS

@service service_id feature=val...
@service service_id as module_name feature=val...

Include the high-level service wrapper for service_id in a module. The module name will match the service_id or can be specified using the as syntax.

An optional list of features can be specified for this service include. See FeatureSet for a list of available features.

The module name cannot match the binding name used for the low-level API. The low-level API binding name is equivalent to the lowercase service_id where spaces are replace with underscores (e.g. the service ID Secrets_Manager can be used but secrets_manager cannot).

Extended Help

Arguments

• service_id::Symbol: The high-level API wrappers service ID to include in the current module. Note the service ID is case insensitive.
• module_name::Symbol: The name of the module containing the high-level API wrappers. Useful to avoiding name conflicts. Defaults to using service_id.
• features=val...: A list of features to enable/disable for this high-level API include. See FeatureSet for a list of available features.

Returns

• Module: The module containging the high-level service API wrapper functions.

Examples

julia> using AWS: @service

julia> @service STS
STS

julia> STS.get_caller_identity()
OrderedCollections.LittleDict{Union{String, Symbol}, Any, Vector{Union{String, Symbol}}, Vector{Any}} with 2 entries:
  "GetCallerIdentityResult" => LittleDict{Union{String, Symbol}, Any, Vector{Un…
  "ResponseMetadata"        => LittleDict{Union{String, Symbol}, Any, Vector{Un…

Specify the module name and use a feature:

julia> @service STS as SecurityTokenService use_response_type = true
SecurityTokenService

julia> SecurityTokenService.get_caller_identity()
AWS.Response: application/xml interpreted as:
OrderedCollections.LittleDict{Union{String, Symbol}, Any, Vector{Union{String, Symbol}}, Vector{Any}} with 2 entries:
  "GetCallerIdentityResult" => LittleDict{Union{String, Symbol}, Any, Vector{Un…
  "ResponseMetadata"        => LittleDict{Union{String, Symbol}, Any, Vector{Un…

Service IDs are case insensitive:

julia> @service Secrets_Manager
Secrets_Manager

julia> @service SECRETS_MANAGER
SECRETS_MANAGER

julia> @service sECRETS_MANAGER
sECRETS_MANAGER

Using an all lowercase service ID does not work as it conflicts with the low-level API binding name:

julia> @service sts
WARNING: import of AWSServices.sts into sts conflicts with an existing identifier; ignored.
sts

julia> sts.get_caller_identity()
ERROR: MethodError: objects of type Module are not callable
[...]

AWSCredentials

When you interact with AWS, you specify your AWS Security Credentials to verify who you are and whether you have permission to access the resources that you are requesting. AWS uses the security credentials to authenticate and authorize your requests. The fields access_key_id and secret_key hold the access keys used to authenticate API requests (see Creating, Modifying, and Viewing Access Keys). Temporary Security Credentials require the extra session token field. The user_arn and account_number fields are used to cache the result of the aws_user_arn and aws_account_number functions.

AWS.jl searches for credentials in multiple locations and stops once any credentials are found. The credential preference order mostly mirrors the AWS CLI and is as follows:

1. Credentials or a profile passed directly to the AWSCredentials
2. Environment variables
3. Web Identity
4. AWS Single Sign-On (SSO) provided via the AWS configuration file
5. AWS credentials file (e.g. "~/.aws/credentials")
6. External process set via credential_process in the AWS configuration file
7. AWS configuration file set via aws_access_key_id in the AWS configuration file
8. Amazon ECS container credentials
9. Amazon EC2 instance metadata

Once the credentials are found, the method by which they were accessed is stored in the renew field and the DateTime at which they will expire is stored in the expiry field. This allows the credentials to be refreshed as needed using check_credentials. If renew is set to nothing, no attempt will be made to refresh the credentials. Any renewal function is expected to return nothing on failure or a populated AWSCredentials object on success. The renew field of the returned AWSCredentials will be discarded and does not need to be set.

To specify the profile to use from ~/.aws/credentials, do, for example, AWSCredentials(profile="profile-name").

AWSCredentials(; profile=nothing) -> Union{AWSCredentials, Nothing}

Create an AWSCredentials object, given a provided profile (if not provided "default" will be used).

Checks credential locations in the order: 1. Environment Variables 2. ~/.aws/credentials 3. ~/.aws/config 4. EC2 or ECS metadata

Keywords

• profile::AbstractString: Specific profile used to search for AWSCredentials

Throws

• error("Can't find AWS Credentials"): AWSCredentials could not be found

(service::JSONService)(
    operation::String, args::AbstractDict{String, <:Any}=Dict{String, Any}();
    aws_config::AbstractAWSConfig=aws_config
)

Perform a JSON request to AWS.

Arguments

• operation::String: Name of the operation to perform
• args::AbstractDict{String, <:Any}: Additional arguments to be included in the request

Keywords

• aws_config::AbstractAWSConfig: AWSConfig containing credentials and other information for fulfilling the request, default value is the global configuration
• feature_set::FeatureSet: Specifies opt-in functionality for this specific API call.

Returns

• Tuple or Dict: If return_headers is passed in through args a Tuple containing the headers and response will be returned, otherwise just a Dict

(service::QueryService)(
    operation::String, args::AbstractDict{String, <:Any}=Dict{String, Any}();
    aws_config::AbstractAWSConfig=aws_config
)

Perform a Query request to AWS.

Arguments

• operation::String:
• args::AbstractDict{String, <:Any}: Additional arguments to be included in the request

Keywords

• aws_config::AbstractAWSConfig: AWSConfig containing credentials and other information for fulfilling the request, default value is the global configuration
• feature_set::FeatureSet: Specifies opt-in functionality for this specific API call.

Returns

• Tuple or Dict: If return_headers is passed in through args a Tuple containing the headers and response will be returned, otherwise just a Dict

(service::RestJSONService)(
    request_method::String, request_uri::String, args::AbstractDict{String, <:Any}=Dict{String, String}();
    aws_config::AbstractAWSConfig=aws_config
)

Perform a RestJSON request to AWS.

Arguments

• request_method::String: RESTful request type, e.g.: GET, HEAD, PUT, etc.
• request_uri::String: AWS URI for the endpoint
• args::AbstractDict{String, <:Any}: Additional arguments to be included in the request

Keywords

• aws_config::AbstractAWSConfig: AWSConfig containing credentials and other information for fulfilling the request, default value is the global configuration
• feature_set::FeatureSet: Specifies opt-in functionality for this specific API call.

Returns

• Tuple or Dict: If return_headers is passed in through args a Tuple containing the headers and response will be returned, otherwise just a Dict

(service::RestXMLService)(
    request_method::String, request_uri::String, args::AbstractDict{String, <:Any}=Dict{String, String}();
    aws_config::AbstractAWSConfig=aws_config
)

Perform a RestXML request to AWS.

Arguments

• request_method::String: RESTful request type, e.g.: GET, HEAD, PUT, etc.
• request_uri::String: AWS URI for the endpoint
• args::AbstractDict{String, <:Any}: Additional arguments to be included in the request

Keywords

• aws_config::AbstractAWSConfig: AWSConfig containing credentials and other information for fulfilling the request, default value is the global configuration
• feature_set::FeatureSet: Specifies opt-in functionality for this specific API call.

Returns

• Tuple or Dict: If return_headers is passed in through args a Tuple containing the headers and response will be returned, otherwise just a Dict

assume_role(principal::AbstractAWSConfig, role; kwargs...) -> AbstractAWSConfig

Assumes the IAM role via temporary credentials via the principal entity. The principal entity must be included in the trust policy of the role.

Role chaining must be manually specified by multiple assume_role calls (e.g. "role-a" has permissions to assume "role-b": assume_role(assume_role(AWSConfig(), "role-a"), "role-b")).

Arguments

• principal::AbstractAWSConfig: The AWS configuration and credentials of the principal entity (user or role) performing the sts:AssumeRole action.
• role::AbstractString: The AWS IAM role to assume. Either a full role ARN or just the role name. If only the role name is specified the role will be assumed to reside in the same account used in the principal argument.

Keywords

• duration::Integer (optional): Role session duration in seconds.
• mfa_serial::AbstractString (optional): The identification number of the MFA device that is associated with the user making the AssumeRole API call. Either a serial number for a hardware device ("GAHT12345678") or an ARN for a virtual device ("arn:aws:iam::123456789012:mfa/user"). When specified a MFA token must be provided via token or an interactive prompt.
• token::AbstractString (optional): The value provided by the MFA device. Only can be specified when mfa_serial is set.
• session_name::AbstractString (optional): The unique role session name associated with this API request.

assume_role(role; kwargs...) -> Function

Create a function that assumes the IAM role via a deferred principal entity, i.e. a function equivalent to principal -> assume_role(principal, role; kwargs...). Useful for role chaining.

Examples

Assume "role-a" which in turn assumes "role-b":

AWSConfig() |> assume_role("role-a") |> assume_role("role-b")

aws_account_number(aws::AWSConfig) -> String

Retrieve the AWS account number from the AWSConfig, if not present query STS to update the AWS account number.

Arguments

• aws::AWSConfig: AWSConfig used to retrieve the AWS account number

aws_get_profile_settings(profile::AbstractString, ini::Inifile) -> Dict

Return a Dict containing all of the settings for the specified profile.

Arguments

• profile::AbstractString: Profile to retrieve settings from
• ini::Inifile: Configuration file read the settings from

aws_get_region(; profile=nothing, config=nothing, default="us-east-1")

Determine the current AWS region that should be used for AWS requests. The order of precedence mirrors what is used by the AWS CLI:

1. Environment variable: AWS_REGION.
2. Environment variable: AWS_DEFAULT_REGION
3. AWS configuration file: region as specified by the profile in the configuration file, typically "~/.aws/config".
4. Instance metadata service on an Amazon EC2 instance that has an IAM role configured.
5. Default region: use the specified default, typically "us-east-1".

Keywords

• profile: Name of the AWS configuration profile, if any. Defaults to nothing which falls back to using AWS._aws_get_profile()
• config: AWS configuration loaded as an Inifile or a path to a configuration file. Defaults to nothing which falls back to using dot_aws_config_file()
• default: The region to return if no high-precedence was found. Can be useful to set this to nothing if you want to know that no current AWS region was defined.

aws_user_arn(aws::AWSConfig) -> String

Retrieve the User ARN from the AWSConfig, if not present query STS to update the user_arn.

Arguments

• aws::AWSConfig: AWSConfig used to retrieve the user arn

check_credentials(
    aws_creds::AWSCredentials, force_refresh::Bool=false
) -> AWSCredentials

Checks current AWSCredentials, refreshing them if they are soon to expire. If force_refresh is true the credentials will be renewed immediately

Arguments

• aws_creds::AWSCredentials: AWSCredentials to be checked / refreshed

Keywords

• force_refresh::Bool=false: true to refresh the credentials

Throws

• error("Can't find AWS credentials!"): If no credentials can be found

credentials_from_webtoken()

Assume role via web identity. https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-oidc

dot_aws_config(profile=nothing) -> Union{AWSCredentials, Nothing}

Retrieve AWSCredentials from the AWS CLI configuration file. The configuration file defaults to "~/.aws/config" but can be specified using the env variable AWS_CONFIG_FILE. When no credentials are found for the given profile then the associated source_profile will be used to recursively look up credentials of source profiles. If still no credentials can be found then nothing will be returned.

Arguments

• profile: Specific profile used to get AWSCredentials, default is nothing

dot_aws_credentials(profile=nothing) -> Union{AWSCredentials, Nothing}

Retrieve AWSCredentials from the AWS CLI credentials file. The credential file defaults to "~/.aws/credentials" but can be specified using the env variable AWS_SHARED_CREDENTIALS_FILE.

Arguments

• profile: Specific profile used to get AWSCredentials, default is nothing

ec2_instance_credentials(profile::AbstractString) -> AWSCredentials

Parse the EC2 metadata to retrieve AWSCredentials.

ecs_instance_credentials() -> Union{AWSCredentials, Nothing}

Retrieve credentials from the ECS credential endpoint. If the ECS credential endpoint is unavailable then nothing will be returned.

More information can be found at:

• https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html
• https://docs.aws.amazon.com/sdkref/latest/guide/feature-container-credentials.html

Returns

• AWSCredentials: AWSCredentials from ECS credentials URI, nothing if the Env Var is not set (not running on an ECS container instance)

Throws

• StatusError: If the response status is >= 300
• ParsingError: Invalid HTTP request target

env_var_credentials(explicit_profile::Bool=false) -> Union{AWSCredentials, Nothing}

Use AWS environmental variables (e.g. AWSACCESSKEYID, AWSSECRETACCESSKEY, etc.) to create AWSCredentials.

external_process_credentials(cmd::Base.AbstractCmd) -> AWSCredentials

Sources AWS credentials from an external process as defined in the AWS CLI config file. See https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sourcing-external.html for details.

global_aws_config(config::AbstractAWSConfig)

Set the global AWSConfig.

Arguments

• config::AWSConfig: The AWSConfig to set in the global state

Returns

• AWSConfig: Global AWSConfig

global_aws_config()

Retrieve the global AWS configuration. If one is not set, create one with default configuration options.

Keywords

• kwargs...: AWSConfig kwargs to be passed along if the global configuration is not already set

Returns

• AWSConfig: The global AWS configuration

localhost_is_ec2() -> Bool

Determine if the machine executing this code is running on an EC2 instance.

set_user_agent(new_user_agent::String)

Set the global user agent when making HTTP requests.

Arguments

• new_user_agent::String: User agent to set when making HTTP requests

Return

• String: The global user agent

sso_credentials(profile=nothing) -> Union{AWSCredentials, Nothing}

Retrieve credentials via AWS single sign-on (SSO) settings defined in the profile within the AWS configuration file. If no SSO settings are found for the profile nothing is returned.

Arguments

• profile: Specific profile used to get AWSCredentials, default is nothing

FeatureSet

Allows end users to opt-in to new breaking behaviors prior before a major/breaking package release. Each field of this struct contains a default which specifies uses the original non-breaking behavior.

Features

• use_response_type::Bool=false: When enabled, service calls will return an AWS.Response which provides streaming/raw/parsed access to the response. When disabled, the service call response typically be parsed but will vary depending on the following parameters: "returnheaders", "returnstream", "returnraw", "responsedict_type".