AWS

macro service(module_name::Symbol)

Include a high-level service wrapper based off of the module_name parameter.

When calling the macro you cannot match the predefined constant for the lowl level API. The low level API constants are named in all lowercase, and spaces replaced with underscores.

Examples:

using AWS.AWSServices: secrets_manager
using AWS: @service

# This matches the constant and will error!
@service secrets_manager
> ERROR: cannot assign a value to variable AWSServices.secrets_manager from module Main

# This does NOT match the filename structure and will error!
@service secretsmanager
> ERROR: could not open file /.julia/dev/AWS.jl/src/services/secretsmanager.jl

# All of the examples below are valid!
@service Secrets_Manager
@service SECRETS_MANAGER
@service sECRETS_MANAGER

Arguments

• module_name::Symbol: Name of the service to include high-level API wrappers in your namespace

Return

• Expression: Base.include() call to introduce the high-level service API wrapper functions in your namespace

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 a series of possible locations and stops as soon as it finds credentials. The order of precedence for this search is as follows:

1. Passing credentials directly to the AWSCredentials constructor
2. Environment variables
3. Shared credential file (~/.aws/credentials)
4. AWS config file (~/.aws/config)
5. Assume Role provider via the aws config file
6. Instance metadata service on an Amazon EC2 instance that has an IAM role configured

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::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::AbstractAWSConfig: AWSConfig containing credentials and other information for fulfilling the request, default value is the global configuration

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::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::AbstractAWSConfig: AWSConfig containing credentials and other information for fulfilling the request, default value is the global configuration

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::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::AbstractAWSConfig: AWSConfig containing credentials and other information for fulfilling the request, default value is the global configuration

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::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::AbstractAWSConfig: AWSConfig containing credentials and other information for fulfilling the request, default value is the global configuration

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

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_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. Environmental variable: as specified by the AWS_DEFAULT_REGION environmental variable.
2. AWS configuration file: region as specified by the profile in the configuration file, typically "~/.aws/config".
3. 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_get_role_details(profile::AbstractString, ini::Inifile) -> Tuple

Return a tuple of profile details and the role arn.

Arguments

• profile::AbstractString: Specific profile to get role details about
• ini::Inifile: Inifile to look into to find the role details

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{AWSCredential, Nothing}

Retrieve AWSCredentials for the default or specified profile from the ~/.aws/config file. If this fails try to retrieve credentials from _aws_get_role(), otherwise return nothing

Arguments

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

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

Retrieve AWSCredentials from the ~/.aws/credentials file

Arguments

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

ec2_instance_credentials() -> AWSCredentials

Parse the EC2 metadata to retrieve AWSCredentials.

ec2_instance_metadata(path::AbstractString) -> Union{String, Nothing}

Retrieve the AWS EC2 instance metadata as a string using the provided path. If no instance metadata is available (typically due to not running within an EC2 instance) then nothing will be returned. See the AWS documentation for details on what metadata is available: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html

Arguments

• path: The URI path to used to specify that metadata to return

ec2_instance_region() -> Union{String, Nothing}

Determine the AWS region of the machine executing this code if running inside of an EC2 instance, otherwise nothing is returned.

ecs_instance_credentials() -> Union{AWSCredential, Nothing}

Retrieve credentials from the local endpoint. Return nothing if not running on an ECS instance.

More information can be found at: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.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() -> Union{AWSCredential, Nothing}

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

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