# Amazon ECS 任务定义示例：将日志路由到 FireLens
<a name="firelens-taskdef"></a>

要将自定义日志路由与 FireLens 结合使用，您必须在任务定义中指定以下内容：
+ 包含 FireLens 配置的日志路由器容器。我们建议将容器标记为 `essential`。
+ 一个或多个包含指定 `awsfirelens` 日志驱动程序的日志配置的应用程序容器。
+ 一个任务 IAM 角色 Amazon 资源名称（ARN），其中包含任务路由日志所需的权限。

使用 AWS 管理控制台创建新的任务定义时，通过 Firelens 集成部分可以轻松添加日志路由器容器。有关更多信息，请参阅 [使用控制台创建 Amazon ECS 任务定义](create-task-definition.md)。

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

**重要**  
FireLens 在端口 `24224` 上侦听。因此，为了确保从任务外部无法访问 FireLens 日志路由器，不得允许任务使用的安全组中端口 `24224` 上的入口流量。对于使用 `awsvpc` 网络模式的任务，这是与任务关联的安全组。对于使用 `host` 网络模式的任务，它是与托管任务的 Amazon EC2 实例关联的安全组。对于使用 `bridge` 网络模式的任务，请勿创建任何使用端口 `24224` 的端口映射。

默认情况下，Amazon ECS 会在日志条目中添加其他字段来帮助标识日志源。
+ `ecs_cluster`：任务所属的集群的名称。
+ `ecs_task_arn` – 容器所属的任务的完整 Amazon 资源名称（ARN）。
+ `ecs_task_definition`：任务正在使用的任务定义名称和修订。
+ `ec2_instance_id` – 容器托管于的 Amazon EC2 实例 ID。此字段仅对使用 EC2 启动类型的任务有效。

如果您不想要元数据，可以将 `enable-ecs-log-metadata` 设置为 `false`。

下面的任务定义示例定义了一个日志路由器容器，它使用 Fluent Bit 将日志路由到 CloudWatch Logs。该示例还定义了一个应用程序容器，它使用日志配置将日志路由到 Amazon Data Firehose 并将用于缓冲事件的内存设置为 2MiB。

**注意**  
有关更多示例任务定义，请参阅 GitHub 上的 [Amazon ECS FireLens 示例](https://github.com/aws-samples/amazon-ecs-firelens-examples)。

```
{
  "family": "firelens-example-firehose",
  "taskRoleArn": "arn:aws:iam::123456789012:role/ecs_task_iam_role",
  "containerDefinitions": [
    {
            "name": "log_router",
            "image": "public.ecr.aws/aws-observability/aws-for-fluent-bit:3",
            "cpu": 0,
            "memoryReservation": 51,
            "portMappings": [],
            "essential": true,
            "environment": [],
            "mountPoints": [],
            "volumesFrom": [],
            "logConfiguration": {
                "logDriver": "awslogs",
                "options": {
                    "awslogs-group": "/ecs/ecs-aws-firelens-sidecar-container",
                    "mode": "non-blocking",
                    "awslogs-create-group": "true",
                    "max-buffer-size": "25m",
                    "awslogs-region": "us-east-1",
                    "awslogs-stream-prefix": "firelens"
                },
                "secretOptions": []
            },
            "systemControls": [],
            "firelensConfiguration": {
                "type": "fluentbit"
            }
        },
    {
      "essential": true,
      "image": "public.ecr.aws/docker/library/httpd:latest",
      "name": "app",
      "logConfiguration": {
        "logDriver": "awsfirelens",
        "options": {
          "Name": "firehose",
          "region": "us-west-2",
          "delivery_stream": "my-stream",
          "log-driver-buffer-limit": "1048576"
        }
      },
      "memoryReservation": 100
    }
  ]
}
```

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

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

**注意**  
FirelLens 可管理 `match` 配置。您没有在任务定义中指定 `match` 配置。

## 使用自定义配置文件
<a name="firelens-taskdef-customconfig"></a>

您可以指定自定义配置文件。配置文件格式是您所使用的日志路由器的本机格式。有关更多信息，请参阅 [Fluentd Config 文件语法](https://docs.fluentd.org/configuration/config-file)和 [YAML 配置](https://docs.fluentbit.io/manual/administration/configuring-fluent-bit/yaml)。

在您的自定义配置文件中，对于使用 `bridge` 或 `awsvpc` 网络模式的任务，请勿通过 TCP 设置 Fluentd 或 Fluent Bit 转发输入，因为 FireLens 会将它添加到输入配置中。

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

`config-file-type`  
自定义配置文件的源位置。可用选项为 `s3` 或 `file`。  
托管在 AWS Fargate 上的任务仅支持 `file` 配置文件类型。但是，您可以使用适用于 Fluent Bit 的 AWS 初始化容器在 AWS Fargate 上使用 Amazon S3 中托管的配置文件。有关更多信息，请参阅 GitHub 上的 [ECS 上的 Fluent Bit 的初始化进程，多配置支持](https://github.com/aws/aws-for-fluent-bit/blob/mainline/use_cases/init-process-for-fluent-bit/README.md)。

`config-file-value`  
自定义配置文件的源。如果使用 `s3` 配置文件类型，则配置文件值是 Amazon S3 存储桶和文件的完整 ARN。如果使用 `file` 配置文件类型，则配置文件值是容器映像中或挂载到容器中的卷上存在的配置文件的完整路径。  
在使用自定义配置文件时，必须指定一个与 FireLens 所用路径不同的路径。Amazon ECS 保留对于 Fluent Bit 和 `/fluentd/etc/fluent.conf` 对于 Fluentd 的文件路径 `/fluent-bit/etc/fluent-bit.conf`。

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

**重要**  
要指定托管于 Amazon S3 中的自定义配置文件，请确保已创建具有适当权限的任务执行 IAM 角色。

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

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

**注意**  
托管在 AWS Fargate 上的任务仅支持 `file` 配置文件类型。但是，您可以使用适用于 Fluent Bit 的 AWS 初始化容器在 AWS Fargate 上使用 Amazon S3 中托管的配置文件。有关更多信息，请参阅 GitHub 上的 [ECS 上的 Fluent Bit 的初始化进程，多配置支持](https://github.com/aws/aws-for-fluent-bit/blob/mainline/use_cases/init-process-for-fluent-bit/README.md)。