[float]
=== AWS Credentials Configuration
To configure AWS credentials, either put the credentials into the {beatname_uc} configuration, or use a shared credentials file, as shown in the following examples.

[float]
==== Configuration parameters
* *access_key_id*: first part of access key.
* *secret_access_key*: second part of access key.
* *session_token*: required when using temporary security credentials.
* *credential_profile_name*: profile name in shared credentials file.
* *shared_credential_file*: directory of the shared credentials file.
* *role_arn*: AWS IAM Role to assume.
* *endpoint*: URL of the entry point for an AWS web service.
Most AWS services offer a regional endpoint that can be used to make requests.
The general syntax of a regional endpoint is `protocol://service-code.region-code.endpoint-code`.
Some services, such as IAM, do not support regions. The endpoints for these
services do not include a region. In `aws` module, `endpoint` config is to set
the `endpoint-code` part, such as `amazonaws.com`, `amazonaws.com.cn`, `c2s.ic.gov`,
`sc2s.sgov.gov`.
* *proxy_url*: URL of the proxy to use to connect to AWS web services. The syntax is `http(s)://<IP/Hostname>:<port>`

[float]
==== Supported Formats

NOTE: The examples in this section refer to Metricbeat,
but the credential options for authentication with AWS are the same no matter which Beat is being used.

* Use `access_key_id`, `secret_access_key`, and/or `session_token`

Users can either put the credentials into the Metricbeat module configuration or use
environment variable `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and/or
`AWS_SESSION_TOKEN` instead.

If running on Docker, these environment variables should be added as a part of
the docker command. For example, with Metricbeat:

[source,terminal]
----
$ docker run -e AWS_ACCESS_KEY_ID=abcd -e AWS_SECRET_ACCESS_KEY=abcd -d --name=metricbeat --user=root --volume="$(pwd)/metricbeat.aws.yml:/usr/share/metricbeat/metricbeat.yml:ro" docker.elastic.co/beats/metricbeat:7.11.1 metricbeat -e -E cloud.auth=elastic:1234 -E cloud.id=test-aws:1234
----

Sample `metricbeat.aws.yml` looks like:

[source,yaml]
----
metricbeat.modules:
- module: aws
  period: 5m
  access_key_id: ${AWS_ACCESS_KEY_ID}
  secret_access_key: ${AWS_SECRET_ACCESS_KEY}
  session_token: ${AWS_SESSION_TOKEN}
  metricsets:
    - ec2
----

Environment variables can also be added through a file. For example:

[source,terminal]
----
$ cat env.list
AWS_ACCESS_KEY_ID=abcd
AWS_SECRET_ACCESS_KEY=abcd

$ docker run --env-file env.list -d --name=metricbeat --user=root --volume="$(pwd)/metricbeat.aws.yml:/usr/share/metricbeat/metricbeat.yml:ro" docker.elastic.co/beats/metricbeat:7.11.1 metricbeat -e -E cloud.auth=elastic:1234 -E cloud.id=test-aws:1234
----

* Use `credential_profile_name` and/or `shared_credential_file`

If `access_key_id`, `secret_access_key` and `role_arn` are all not given, then
{beatname_lc} will check for `credential_profile_name`. If you use different credentials for
different tools or applications, you can use profiles to configure multiple
access keys in the same configuration file. If there is no `credential_profile_name`
given, the default profile will be used.

`shared_credential_file` is optional to specify the directory of your shared
credentials file. If it's empty, the default directory will be used.
In Windows, shared credentials file is at `C:\Users\<yourUserName>\.aws\credentials`.
For Linux, macOS or Unix, the file is located at `~/.aws/credentials`. When running as a service,
the home path depends on the user that manages the service, so the `shared_credential_file` parameter can be used to avoid ambiguity. Please see
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/create-shared-credentials-file.html[Create Shared Credentials File]
for more details.

* Use `role_arn`

`role_arn` is used to specify which AWS IAM role to assume for generating
temporary credentials. If `role_arn` is given, {beatname_lc} will check if
access keys are given. If not, {beatname_lc} will check for credential profile
name. If neither is given, default credential profile will be used. Please make
sure credentials are given under either a credential profile or access keys.

If running on Docker, the credential file needs to be provided via a volume
mount. For example, with Metricbeat:

[source,terminal]
----
docker run -d --name=metricbeat --user=root --volume="$(pwd)/metricbeat.aws.yml:/usr/share/metricbeat/metricbeat.yml:ro" --volume="/Users/foo/.aws/credentials:/usr/share/metricbeat/credentials:ro" docker.elastic.co/beats/metricbeat:7.11.1 metricbeat -e -E cloud.auth=elastic:1234 -E cloud.id=test-aws:1234
----

Sample `metricbeat.aws.yml` looks like:
[source,yaml]
----
metricbeat.modules:
- module: aws
  period: 5m
  credential_profile_name: elastic-beats
  shared_credential_file: /usr/share/metricbeat/credentials
  metricsets:
    - ec2
----

ifeval::["{beatname_lc}"=="filebeat"]
include::../../../filebeat/docs/aws-credentials-examples.asciidoc[]
endif::[]

ifeval::["{beatname_lc}"=="heartbeat"]
include::../../../heartbeat/docs/aws-credentials-examples.asciidoc[]
endif::[]

ifeval::["{beatname_lc}"=="metricbeat"]
include::../../../metricbeat/docs/aws-credentials-examples.asciidoc[]
endif::[]

ifeval::["{beatname_lc}"=="functionbeat"]
include::../../../filebeat/docs/aws-credentials-examples.asciidoc[]
endif::[]

[float]
==== AWS Credentials Types
There are two different types of AWS credentials can be used:
access keys and temporary security credentials.

* Access keys

`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are the two parts of access keys.
They are long-term credentials for an IAM user or the AWS account root user.
Please see
https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys[AWS Access Keys
 and Secret Access Keys]
for more details.

* IAM role ARN

An IAM role is an IAM identity that you can create in your account that has
specific permissions that determine what the identity can and cannot do in AWS.
A role does not have standard long-term credentials such as a password or access keys associated with it.
Instead, when you assume a role, it provides you with temporary security credentials for your role session.
IAM role Amazon Resource Name (ARN) can be used to specify which AWS IAM role to assume to generate temporary credentials.
Please see https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html[AssumeRole API documentation] for more details.

Here are the steps to set up IAM role using AWS CLI for Metricbeat. Please replace
`123456789012` with your own account ID.

Step 1. Create `example-policy.json` file to include all permissions:
[source,yaml]
----
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "sqs:ReceiveMessage"
            ],
            "Resource": "*"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": "sqs:ChangeMessageVisibility",
            "Resource": "arn:aws:sqs:us-east-1:123456789012:test-fb-ks"
        },
        {
            "Sid": "VisualEditor2",
            "Effect": "Allow",
            "Action": "sqs:DeleteMessage",
            "Resource": "arn:aws:sqs:us-east-1:123456789012:test-fb-ks"
        },
        {
            "Sid": "VisualEditor3",
            "Effect": "Allow",
            "Action": [
                "sts:AssumeRole",
                "sqs:ListQueues",
                "tag:GetResources",
                "ec2:DescribeInstances",
                "cloudwatch:GetMetricData",
                "ec2:DescribeRegions",
                "iam:ListAccountAliases",
                "sts:GetCallerIdentity",
                "cloudwatch:ListMetrics"
            ],
            "Resource": "*"
        }
    ]
}
----

Step 2. Create IAM policy using the `aws iam create-policy` command:
[source,terminal]
----
$ aws iam create-policy --policy-name example-policy --policy-document file://example-policy.json
----

Step 3. Create the JSON file `example-role-trust-policy.json` that defines the trust relationship of the IAM role
[source,yaml]
----
{
    "Version": "2012-10-17",
    "Statement": {
        "Effect": "Allow",
        "Principal": { "AWS": "arn:aws:iam::123456789012:root" },
        "Action": "sts:AssumeRole"
    }
}
----

Step 4. Create the IAM role and attach the policy:
[source,terminal]
----
$ aws iam create-role --role-name example-role --assume-role-policy-document file://example-role-trust-policy.json
$ aws iam attach-role-policy --role-name example-role --policy-arn "arn:aws:iam::123456789012:policy/example-policy"
----

After these steps are done, IAM role ARN can be used for authentication in Metricbeat
`aws` module.

* Temporary security credentials

Temporary security credentials has a limited lifetime and consists of an
access key ID, a secret access key, and a security token which typically returned
from `GetSessionToken`. MFA-enabled IAM users would need to submit an MFA code
while calling `GetSessionToken`. `default_region` identifies the AWS Region
whose servers you want to send your first API request to by default. This is
typically the Region closest to you, but it can be any Region. Please see
https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html[Temporary Security Credentials]
for more details.
`sts get-session-token` AWS CLI can be used to generate temporary credentials. For example. with MFA-enabled:

[source,terminal]
----
aws> sts get-session-token --serial-number arn:aws:iam::1234:mfa/your-email@example.com --token-code 456789 --duration-seconds 129600
----

Because temporary security credentials are short term, after they expire, the user needs to generate new ones and modify
the aws.yml config file with the new credentials. Unless https://www.elastic.co/guide/en/beats/metricbeat/current/_live_reloading.html[live reloading]
feature is enabled for Metricbeat, the user needs to manually restart Metricbeat after updating the config file in order
to continue collecting Cloudwatch metrics. This will cause data loss if the config file is not updated with new
credentials before the old ones expire. For Metricbeat, we recommend users to use access keys in config file to enable
aws module making AWS api calls without have to generate new temporary credentials and update the config frequently.

IAM policy is an entity that defines permissions to an object within your AWS environment. Specific permissions needs
to be added into the IAM user's policy to authorize Metricbeat to collect AWS monitoring metrics. Please see documentation
under each metricset for required permissions.
