[role="xpack"]

:libbeat-xpack-dir: ../../../x-pack/libbeat

:modulename: awsfargate
:has-dashboards: false

== AWS Fargate module

beta[]

This module can be used to collect container logs from Amazon ECS on Fargate.
It uses filebeat `awscloudwatch` input to get log files from one or more log
streams in AWS CloudWatch. Logs from all containers in Fargate launch type tasks
can be sent to CloudWatch by adding the `awslogs` log driver under `logConfiguration`
section in the task definition. For example, `logConfiguration` can be added into
the task definition by adding this section into the `containerDefinitions`:

[source,json]
----
{
   "logDriver":"awslogs",
   "options":{
      "awslogs-group":"awslogs-wordpress",
      "awslogs-region":"us-west-2",
      "awslogs-stream-prefix":"awslogs-example"
   }
}
----

The `awsfargate` module requires AWS credentials configuration in order to make AWS API calls.
Users can either use `access_key_id`, `secret_access_key` and/or
`session_token`, or use `role_arn` AWS IAM role, or use shared AWS credentials file.

Please see <<awsfargate-credentials,AWS credentials options>> for more details.

[float]
=== Module configuration

Example config:

[source,yaml]
----
- module: awsfargate
  log:
    enabled: true
    var.credential_profile_name: test-filebeat
    var.log_group_arn: arn:aws:logs:us-east-1:1234567890:log-group:/ecs/test-log-group:*
----

*`var.log_group_arn`*::

ARN of the log group to collect logs from.

*`var.log_group_name`*::

Name of the log group to collect logs from. Note: region_name is required when
log_group_name is given.

*`var.region_name`*::

Region that the specified log group belongs to.

*`var.log_streams`*::

A list of strings of log streams names that Filebeat collect log events from.

*`var.log_stream_prefix`*::

A string to filter the results to include only log events from log streams
that have names starting with this prefix.

*`var.start_position`*::

`start_position` allows user to specify if this input should read log files from
the `beginning` or from the `end`.

* `beginning`: reads from the beginning of the log group (default).
* `end`: read only new messages from current time minus `scan_frequency` going forward

*`var.scan_frequency`*::

This config parameter sets how often Filebeat checks for new log events from the
specified log group. Default `scan_frequency` is 1 minute, which means Filebeat
will sleep for 1 minute before querying for new logs again.

*`var.api_timeout`*::

The maximum duration of AWS API can take. If it exceeds the timeout, AWS API
will be interrupted. The default AWS API timeout for a message is 120 seconds.
The minimum is 0 seconds.

*`var.api_sleep`*::

This is used to sleep between AWS `FilterLogEvents` API calls inside the same
collection period. `FilterLogEvents` API has a quota of 5 transactions per
second (TPS)/account/Region. By default, `api_sleep` is 200 ms. This value should
only be adjusted when there are multiple Filebeats or multiple Filebeat inputs
collecting logs from the same region and AWS account.

*`var.shared_credential_file`*::

Filename of AWS credential file.

*`var.credential_profile_name`*::

AWS credential profile name.

*`var.access_key_id`*::
First part of access key.

*`var.secret_access_key`*::
Second part of access key.

*`var.session_token`*::
Required when using temporary security credentials.

*`var.role_arn`*::
AWS IAM Role to assume.

*`var.endpoint`*::

The custom endpoint used to access AWS APIs.

[id="awsfargate-credentials"]
include::{libbeat-xpack-dir}/docs/aws-credentials-config.asciidoc[]
