aws-for-fluent-bit 镜像技术文档

1. 镜像概述和主要用途

aws-for-fluent-bit 是 AWS 官方发布的 Fluent Bit 容器镜像，集成了 AWS 服务专用插件（如 CloudWatch Logs、S3、Kinesis 等），专为容器化环境的日志收集与转发设计。其核心用途是在 AWS 生态（如 ECS Fargate、EKS）中实现轻量级、高效的日志流水线，无需依赖 EFS 等持久化存储即可完成配置，特别适用于无持久存储的场景（如 Fargate）。

2. 核心功能和特性

2.1 集成 AWS 服务插件

• 原生支持 CloudWatch Logs、S3、Kinesis Data Firehose、Kinesis Data Streams 等 AWS 日志目标服务。
• 内置 AWS 身份认证（IAM 角色、Access Key 等），无需额外配置认证信息。

2.2 无 EFS 依赖配置

• 支持通过环境变量、容器启动命令或任务定义嵌入配置文件，无需挂载 EFS 存储卷。
• 配置文件可直接打包至镜像或动态注入，简化 Fargate 等无持久化场景的部署。

2.3 轻量级与高性能

• 基于 Fluent Bit 构建，资源占用低（内存 < 10MB，CPU 使用率 < 1%）。
• 支持日志缓冲、批处理和重试机制，确保高吞吐场景下的可靠性。

2.4 容器化环境适配

• 兼容 Docker、Kubernetes、ECS 等容器编排平台。
• 支持容器标准日志格式（JSON、多行日志）及自定义解析规则。

3. 使用场景和适用范围

3.1 ECS Fargate 任务日志收集

• 无需挂载 EFS，直接通过任务定义嵌入配置，收集 Fargate 任务日志并转发至 CloudWatch Logs。

3.2 EKS 集群日志转发

• 在 Kubernetes 集群中作为 DaemonSet 或 Sidecar 部署，收集 Pod 日志并发送至 S3 或 Kinesis。

3.3 无持久化存储场景

• 适用于 Serverless 容器环境（如 Fargate Spot）或临时任务，避免依赖外部存储配置。

3.4 AWS 多服务日志聚合

• 将分散在 EC2、容器、Lambda 中的日志统一转发至 CloudWatch Logs 或 S3，实现集中式日志管理。

4. 使用方法和配置说明

4.1 获取镜像

官方镜像托管于 AWS ECR Public Gallery，直接拉取即可使用：

docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:latest

版本标签可指定具体版本（如 2.31.0），推荐使用固定版本避免兼容性问题。

4.2 配置文件编写

Fluent Bit 配置文件采用 ini 格式，包含 Service（全局配置）、Input（日志输入源）、Filter（日志处理）、Output（日志目标）四个核心模块。

4.2.1 基本配置结构

[SERVICE]
    Flush               5          # 日志刷新间隔（秒）
    Log_Level           info       # 日志级别（debug/info/warn/error）
    Daemon              off        # 容器环境需设为 off（前台运行）

[INPUT]
    Name                tail       # 输入插件（tail：监控文件）
    Path                /var/log/containers/*.log  # 日志文件路径
    Parser              docker     # 解析器（docker：JSON 格式日志）
    Tag                 container.* # 日志标签（用于 Output 路由）

[OUTPUT]
    Name                cloudwatch # 输出插件（CloudWatch Logs）
    Match               *          # 匹配标签（*：所有日志）
    region              us-east-1  # AWS 区域
    log_group_name      /ecs/fargate-app # CloudWatch 日志组名称
    log_stream_name     {HOSTNAME}  # 日志流名称（可使用变量）

4.2.2 无需 EFS 的配置提供方式

在 Fargate 等无持久化场景中，配置文件可通过以下方式注入，无需挂载 EFS：

4.3 部署示例

4.3.1 Docker Run 命令示例（本地测试）

通过环境变量注入配置文件，收集本地 /var/log/app.log 日志并发送至 CloudWatch：

docker run -d \
  --name aws-fluent-bit \
  -v /var/log/app.log:/var/log/app.log \  # 挂载本地日志文件（仅本地测试用）
  -e AWS_REGION=us-east-1 \              # AWS 区域
  -e CONFIG_CONTENT="$(cat <<EOF         # 注入配置文件内容
[SERVICE]
    Flush 5
    Log_Level info
[INPUT]
    Name tail
    Path /var/log/app.log
    Tag app.log
[OUTPUT]
    Name cloudwatch
    Match *
    region \${AWS_REGION}
    log_group_name /local/test
    log_stream_name \${HOSTNAME}
EOF
)" \
  public.ecr.aws/aws-observability/aws-for-fluent-bit:latest \
  sh -c "echo \"\$CONFIG_CONTENT\" > /fluent-bit/etc/fluent-bit.conf && /fluent-bit/bin/fluent-bit -c /fluent-bit/etc/fluent-bit.conf"

4.3.2 ECS Fargate 任务定义示例

以下为 ECS Fargate 任务定义片段，通过 command 动态生成配置文件，收集容器日志并转发至 CloudWatch：

{
  "family": "fargate-fluent-bit-demo",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "256",
  "memory": "512",
  "executionRoleArn": "arn:aws:iam::123456789012:role/ecs-task-execution-role",
  "containerDefinitions": [
    {
      "name": "aws-fluent-bit",
      "image": "public.ecr.aws/aws-observability/aws-for-fluent-bit:latest",
      "essential": true,
      "environment": [
        {"name": "AWS_REGION", "value": "us-east-1"}
      ],
      "command": [
        "sh", "-c", 
        "cat > /fluent-bit/etc/fluent-bit.conf <<EOF
[SERVICE]
    Flush 5
    Log_Level info
[INPUT]
    Name tail
    Path /var/log/containers/*.log  # Fargate 容器日志路径
    Parser docker
    Tag ecs.*
[OUTPUT]
    Name cloudwatch
    Match *
    region \${AWS_REGION}
    log_group_name /ecs/fargate-demo
    log_stream_name \${HOSTNAME}
EOF
&& /fluent-bit/bin/fluent-bit -c /fluent-bit/etc/fluent-bit.conf"
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/fargate-demo-fluent-bit",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "fluent-bit"
        }
      }
    }
  ]
}

4.3.3 Docker Compose 配置示例（本地开发）

version: '3'
services:
  fluent-bit:
    image: public.ecr.aws/aws-observability/aws-for-fluent-bit:latest
    environment:
      - AWS_REGION=us-east-1
    volumes:
      - ./fluent-bit.conf:/fluent-bit/etc/fluent-bit.conf  # 本地配置文件挂载（开发用）
    command: /fluent-bit/bin/fluent-bit -c /fluent-bit/etc/fluent-bit.conf

4.4 核心配置参数说明

4.4.1 SERVICE 模块

4.4.2 INPUT 模块（以 tail 插件为例）

4.4.3 OUTPUT 模块（以 cloudwatch 插件为例）

4.5 环境变量说明

5. 注意事项

• IAM 权限配置：运行镜像的任务/ Pod 需附加 IAM 权限（如 CloudWatchLogsFullAccess），或通过环境变量配置 AWS 密钥（非推荐）。
• 配置文件格式：确保配置文件无语法错误（如括号匹配、参数拼写），错误会导致容器启动失败。
• 日志流命名：避免使用动态变化的日志流名称（如随机字符串），否则可能导致 CloudWatch Logs 存储成本上升。
• 版本兼容性：Fluent Bit 插件参数可能随版本变化，建议固定镜像版本（如 2.31.0）并参考官方文档。