Amazon ECS
AWS Fargate 用户指南 (API 版本 2014-11-13)
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

自定义日志路由

利用 FireLens for Amazon ECS,您可以使用任务定义参数将日志路由到 AWS 服务或 AWS 合作伙伴网络 (APN) 目标来进行日志存储和分析。FireLens 与 FluentdFluent Bit 配合使用。我们提供 AWS for Fluent Bit 映像,您也可以使用自己的 Fluentd 或 Fluent Bit 映像。

支持通过 AWS 开发工具包、AWS CLI 和 AWS 管理控制台使用 FireLens 配置创建 Amazon ECS 任务定义。使用 AWS 管理控制台注册新的任务定义时,必须使用 Configure via JSON (通过 JSON 配置) 选项。

提供了几个示例任务定义

注意事项

使用 FireLens for Amazon ECS 时应注意以下事项:

  • 使用 Fargate 和 EC2 启动类型的任务支持 FireLens for Amazon ECS。

  • 对于使用 bridge 网络模式的任务,具有 FirelLens 配置的容器必须在依赖它的任何应用程序容器启动之前启动。要控制容器的启动顺序,请在任务定义中使用依赖条件。有关更多信息,请参阅容器依赖项

    注意

    如果您将容器定义中的依赖条件参数与 FirelLens 配置结合使用,请确保每个容器均具有 STARTHEALTHY 条件要求。

所需的 IAM 权限

要使用此功能,您必须为您的任务创建一个 IAM 角色,该角色提供使用任务需要的任何 AWS 服务所需的权限。例如,如果容器将日志路由到 Kinesis Data Firehose,则任务需要调用 firehose:PutRecordBatch API 的权限。有关更多信息,请参阅 IAM 用户指南 中的添加和删除 IAM 身份权限

以下示例 IAM 策略添加了将日志路由到 Kinesis Data Firehose 所需的权限。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "firehose:PutRecordBatch" ], "Resource": [ "*" ] } ] }

在以下条件下,您的任务也可能需要 Amazon ECS 任务执行角色。有关更多信息,请参阅Amazon ECS 任务执行 IAM 角色

  • 如果您的任务使用 Fargate 启动类型,并且您正在从 Amazon ECR 中拉出容器映像或在日志配置中引用 AWS Secrets Manager 中的敏感数据,则必须包含任务执行 IAM 角色。

  • 如果您指定托管于 Amazon S3 中的自定义配置文件,则您的任务执行 IAM 角色必须包括对配置文件的 s3:GetObject 权限以及对该文件所在的 Amazon S3 存储桶的 s3:GetBucketLocation 权限。有关更多信息,请参阅 Amazon Simple Storage Service 控制台用户指南 中的在策略中指定权限

    以下示例 IAM 策略添加了从 Amazon S3 中检索文件所需的权限。指定 Amazon S3 存储桶的名称和配置文件名称。

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::examplebucket/folder_name/config_file_name" ] }, { "Effect": "Allow", "Action": [ "s3:GetBucketLocation" ], "Resource": [ "arn:aws:s3:::examplebucket" ] } ] }

将 AWS 用于 Fluent Bit 映像

AWS 提供了 Fluent Bit 映像以及用于 CloudWatch Logs 和 Kinesis Data Firehose 的插件。我们建议使用 Fluent Bit 作为日志路由器,因为其资源利用率低于 Fluentd。有关更多信息,请参阅 CloudWatch Logs for Fluent BitAmazon Kinesis Firehose for Fluent Bit

Docker Hub 提供了 AWS for Fluent Bit 映像。但是,我们建议您在 Amazon ECR 中使用以下映像,因为它们提供了更高的可用性。

区域名称 区域 映像 URI

美国东部 (俄亥俄)

us-east-2

906394416424.dkr.ecr.us-east-2.amazonaws.com/aws-for-fluent-bit:latest

美国东部 (弗吉尼亚北部)

us-east-1

906394416424.dkr.ecr.us-east-1.amazonaws.com/aws-for-fluent-bit:latest

美国西部 (加利福尼亚北部)

us-west-1

906394416424.dkr.ecr.us-west-1.amazonaws.com/aws-for-fluent-bit:latest

美国西部 (俄勒冈)

us-west-2

906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest

亚太地区(香港)

ap-east-1

449074385750.dkr.ecr.ap-east-1.amazonaws.com/aws-for-fluent-bit:latest

亚太地区 (东京)

ap-northeast-1

906394416424.dkr.ecr.ap-northeast-1.amazonaws.com/aws-for-fluent-bit:latest

亚太地区 (首尔)

ap-northeast-2

906394416424.dkr.ecr.ap-northeast-2.amazonaws.com/aws-for-fluent-bit:latest

亚太地区 (孟买)

ap-south-1

906394416424.dkr.ecr.ap-south-1.amazonaws.com/aws-for-fluent-bit:latest

亚太地区 (新加坡)

ap-southeast-1

906394416424.dkr.ecr.ap-southeast-1.amazonaws.com/aws-for-fluent-bit:latest

亚太地区 (悉尼)

ap-southeast-2

906394416424.dkr.ecr.ap-southeast-2.amazonaws.com/aws-for-fluent-bit:latest

加拿大 (中部)

ca-central-1

906394416424.dkr.ecr.ca-central-1.amazonaws.com/aws-for-fluent-bit:latest

欧洲 (法兰克福)

eu-central-1

906394416424.dkr.ecr.eu-central-1.amazonaws.com/aws-for-fluent-bit:latest

欧洲(斯德哥尔摩)

eu-north-1

906394416424.dkr.ecr.eu-north-1.amazonaws.com/aws-for-fluent-bit:latest

欧洲 (爱尔兰)

eu-west-1

906394416424.dkr.ecr.eu-west-1.amazonaws.com/aws-for-fluent-bit:latest

欧洲 (伦敦)

eu-west-2

906394416424.dkr.ecr.eu-west-2.amazonaws.com/aws-for-fluent-bit:latest

欧洲 (巴黎)

eu-west-3

906394416424.dkr.ecr.eu-west-3.amazonaws.com/aws-for-fluent-bit:latest

南美洲(圣保罗)

sa-east-1

906394416424.dkr.ecr.sa-east-1.amazonaws.com/aws-for-fluent-bit:latest

AWS GovCloud(美国东部)

us-gov-east-1

161423150738.dkr.ecr.us-gov-east-1.amazonaws.com/aws-for-fluent-bit:latest

AWS GovCloud(美国西部)

us-gov-west-1

161423150738.dkr.ecr.us-gov-west-1.amazonaws.com/aws-for-fluent-bit:latest

中国(北京)

cn-north-1

128054284489.dkr.ecr.cn-north-1.amazonaws.com.cn/aws-for-fluent-bit:latest

中国 (宁夏)

cn-northwest-1

128054284489.dkr.ecr.cn-northwest-1.amazonaws.com.cn/aws-for-fluent-bit:latest

创建使用 FirelLens 配置的任务定义

要将自定义日志路由与 FirelLens 结合使用,您必须在任务定义中指定以下内容:

  • 包含 FirelLens 配置的日志路由器容器。此容器必须标记为必需。

  • 一个或多个包含指定 awsfirelens 日志驱动程序的日志配置的应用程序容器。

  • 一个任务 IAM 角色 ARN,其中包含任务路由日志所需的权限。

Amazon ECS 将转换日志配置并生成 Fluentd 或 Fluent Bit 输出配置。输出配置装载在 /fluent-bit/etc/fluent-bit.conf(对于 Fluent Bit)和 /fluentd/etc/fluent.conf(对于 Fluentd)处的日志路由容器中。

为了演示其工作原理,以下是一个示例任务定义,其中包含一个使用 Fluent Bit 将其日志路由到 CloudWatch Logs 的日志路由器容器,以及一个使用日志配置将日志路由到 Amazon Kinesis Data Firehose 的应用程序容器。

{ "family": "firelens-example-firehose", "taskRoleArn": "arn:aws:iam::123456789012:role/ecs_task_iam_role", "containerDefinitions": [ { "essential": true, "image": "906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest", "name": "log_router", "firelensConfiguration": { "type": "fluentbit" }, "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "firelens-container", "awslogs-region": "us-west-2", "awslogs-create-group": "true", "awslogs-stream-prefix": "firelens" } }, "memoryReservation": 50 }, { "essential": true, "image": "httpd", "name": "app", "logConfiguration": { "logDriver":"awsfirelens", "options": { "Name": "firehose", "region": "us-west-2", "delivery_stream": "my-stream" } }, "memoryReservation": 100 } ] }

logConfiguration 对象中指定为选项的键值对用于生成 Fluentd 或 Fluent Bit 输出配置。以下是来自 Fluent Bit 输出定义的代码示例。

[OUTPUT] Name firehose Match app-firelens* region us-west-2 delivery_stream my-stream

注意

FirelLens 可管理 match 配置。您的任务定义中未指定此配置。

使用 ECS 元数据

在任务定义中指定 FileLens 配置时,您可以选择性地切换 enable-ecs-log-metadata 的值。默认情况下,Amazon ECS 会在日志条目中添加其他字段来帮助标识日志源。可以通过将 enable-ecs-log-metadata 设置为 false 来禁用此操作。

  • ecs_cluster – 任务所属的集群的名称。

  • ecs_task_arn – 容器所属的任务的完整 ARN。

  • ecs_task_definition – 任务正在使用的任务定义名称和修订。

指定自定义配置文件

除了 FirelLens 代表您创建的自动生成的配置文件之外,您还可以指定自定义配置文件。配置文件格式是您所使用的日志路由器的本机格式。有关更多信息,请参阅 Fluentd Config 文件语法Fluent Bit 配置架构

在您的自定义配置文件中,对于使用 bridgeawsvpc 网络模式的任务,不应通过 TCP 设置 Fluentd 或 Fluent Bit 转发输入,因为 FirelLens 会将它添加到输入配置中。

您的 FirelLens 配置必须包含以下选项才能指定自定义配置文件:

config-file-type

自定义配置文件的源位置。可用选项为 s3file

config-file-value

自定义配置文件的源。如果使用 s3 配置文件类型,则配置文件值是 Amazon S3 存储桶和文件的完整 ARN。如果使用 file 配置文件类型,则配置文件值是容器映像中或装载到容器中的卷上存在的配置文件的完整路径。

重要

在使用自定义配置文件时,必须指定与 FirelLens 所用路径不同的路径。Amazon ECS 将保留文件路径 /fluent-bit/etc/fluent-bit.conf(对于 Fluent Bit)和 /fluentd/etc/fluent.conf(对于 Fluentd)。

以下示例显示了指定自定义配置时所需的语法。

重要

要指定托管于 Amazon S3 中的自定义配置文件,请确保已创建具有适当权限的任务执行 IAM 角色。有关更多信息,请参阅所需的 IAM 权限

下面显示了在指定自定义配置时所需的语法:

{ "containerDefinitions":[ { "essential":true, "image":"906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest", "name":"log_router", "firelensConfiguration":{ "type":"fluentbit", "options":{ "config-file-type":"s3 | file", "config-file-value":"arn:aws:s3:::mybucket/fluent.conf | filepath" } } } ] }

注意

对于使用 Fargate 启动类型的任务,唯一支持的 config-file-type 值为 file

使用 Fluent Logger 库

在任务定义中指定 awsfirelens 日志驱动程序时,ECS 代理会将以下环境变量注入容器中:

FLUENT_HOST

分配给 FirelLens 容器的 IP 地址。

FLUENT_PORT

Fluent Forward 协议正在侦听的端口。

FLUENT_HOSTFLUENT_PORT 环境变量可让您直接从代码登录到日志路由器,而不是通过 stdout。有关更多信息,请参阅 GitHub 上的 fluent-logger-golang

使用正则表达式筛选日志

Fluentd 和 Fluent Bit 都支持基于其内容筛选日志。FirelLens 提供了启用此筛选的简单方法。在容器定义的日志配置 options 中,您可以指定特殊键 exclude-patterninclude-pattern 来将正则表达式作为其值。exclude-pattern 键会导致与其正则表达式匹配的所有日志被删除。利用 include-pattern,仅发送与其正则表达式匹配的日志。可将这些键结合使用。

以下示例说明如何使用此筛选。

{ "containerDefinitions":[ { "logConfiguration":{ "logDriver":"awsfirelens", "options":{ "@type":"cloudwatch_logs", "log_group_name":"firelens-testing", "auto_create_stream":"true", "use_tag_as_stream":"true", "region":"us-west-2", "exclude-pattern":"^[a-z][aeiou].*$", "include-pattern":"^.*[aeiou]$" } } } ] }

示例任务定义

以下是一些演示常见日志路由选项的示例任务定义。有关更多示例,请参阅 GitHub 上的 Amazon ECS FreLens 示例

将日志转发到 CloudWatch Logs

以下任务定义示例演示如何指定用于将日志转发到 CloudWatch Logs 日志组的日志配置。有关更多信息,请参阅 Amazon CloudWatch Logs User Guide 中的什么是 Amazon CloudWatch Logs?

在日志配置选项中,指定日志组名称及其所在的区域。要让 Fluent Bit 代表您创建日志组,请指定 "auto_create_group":"true"。您还可以指定有助于筛选的日志流前缀。有关更多信息,请参阅适用于 CloudWatch Logs 的 Fluent Bit 插件

{ "family": "firelens-example-cloudwatch", "taskRoleArn": "arn:aws:iam::123456789012:role/ecs_task_iam_role", "containerDefinitions": [ { "essential": true, "image": "906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest", "name": "log_router", "firelensConfiguration": { "type": "fluentbit" }, "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "firelens-container", "awslogs-region": "us-west-2", "awslogs-create-group": "true", "awslogs-stream-prefix": "firelens" } }, "memoryReservation": 50 }, { "essential": true, "image": "nginx", "name": "app", "logConfiguration": { "logDriver":"awsfirelens", "options": { "Name": "cloudwatch", "region": "us-west-2", "log_group_name": "firelens-testing-fluent-bit", "auto_create_group": "true", "log_stream_prefix": "from-fluent-bit" } }, "memoryReservation": 100 } ] }

将日志转发到 Amazon Kinesis Data Firehose 传输流

以下任务定义示例演示如何指定用于将日志转发到 Amazon Kinesis Data Firehose 传输流的日志配置。Kinesis Data Firehose 传输流必须已存在。有关更多信息,请参阅 Amazon Kinesis Data Firehose 开发人员指南 中的创建 Amazon Kinesis Data Firehose 传输流

在日志配置选项中,指定传输流名称及其所在的区域。有关更多信息,请参阅适用于 Amazon Kinesis Firehose 的 Fluent Bit 插件

{ "family": "firelens-example-firehose", "taskRoleArn": "arn:aws:iam::123456789012:role/ecs_task_iam_role", "containerDefinitions": [ { "essential": true, "image": "906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest", "name": "log_router", "firelensConfiguration": { "type": "fluentbit" }, "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "firelens-container", "awslogs-region": "us-west-2", "awslogs-create-group": "true", "awslogs-stream-prefix": "firelens" } }, "memoryReservation": 50 }, { "essential": true, "image": "httpd", "name": "app", "logConfiguration": { "logDriver":"awsfirelens", "options": { "Name": "firehose", "region": "us-west-2", "delivery_stream": "my-stream" } }, "memoryReservation": 100 } ] }

转发到外部 Fluentd 或 Fluent Bit

以下任务定义示例演示如何指定用于将日志转发到外部 Fluentd 或 Fluent Bit 机的日志配置。为您的环境指定 hostport

{ "family": "firelens-example-forward", "taskRoleArn": "arn:aws:iam::123456789012:role/ecs_task_iam_role", "containerDefinitions": [ { "essential": true, "image": "906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest", "name": "log_router", "firelensConfiguration": { "type": "fluentbit" }, "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "firelens-container", "awslogs-region": "us-west-2", "awslogs-create-group": "true", "awslogs-stream-prefix": "firelens" } }, "memoryReservation": 50 }, { "essential": true, "image": "httpd", "name": "app", "logConfiguration": { "logDriver":"awsfirelens", "options": { "Name": "forward", "Host": "fluentdhost", "Port": "24224" } }, "memoryReservation": 100 } ] }