grafana/agent-nonroot

非root用户ID Agent镜像文档

镜像概述和主要用途

本镜像为采用非root用户ID运行的Agent专用镜像，设计目的是增强容器运行时的安全性。通过使用非root用户执行Agent进程，避免传统root用户运行模式下容器内进程拥有过高系统权限的风险，适用于各类需要长期稳定运行且对安全性有严格要求的Agent程序部署场景。

核心功能和特性

• 非root用户运行：内置非特权用户账号，默认以非root用户ID（UID）和组ID（GID）执行Agent进程，从根本上降低权限滥用风险。
• 安全性增强：遵循最小权限原则，容器内进程仅拥有完成其功能所需的最低权限，有效减少因进程被劫持或漏洞利用导致的权限扩散风险。
• 兼容性良好：兼容主流容器运行时环境（如Docker、containerd）及编排平台（如Kubernetes），无需额外修改即可集成至现有部署流程。
• 灵活配置：支持自定义用户ID/组ID，可根据实际环境需求调整运行时权限，平衡安全性与功能需求。

使用场景和适用范围

典型使用场景

• 企业级监控Agent部署（如Prometheus Node Exporter、Zabbix Agent等）
• 日志收集Agent（如Fluentd、Logstash等）
• 服务注册与发现Agent（如Consul Agent、etcd Agent等）
• 安全审计与合规性监控Agent

适用范围

• 对容器运行安全性有严格要求的生产环境
• 多租户共享容器平台或云环境
• 需满足行业合规标准（如PCI DSS、HIPAA）的部署场景
• 对容器内进程权限有明确限制要求的组织或项目

使用方法和配置说明

基本使用流程

1. 拉取镜像：从指定镜像仓库拉取本镜像
2. 配置运行参数：根据需求设置用户ID/组ID及其他Agent配置
3. 启动容器：通过Docker命令或编排工具启动容器

Docker 运行示例

默认配置运行

若无需自定义用户ID/组ID，可直接使用镜像内置的非root用户运行：

bash
docker run -d \
  --name secure-agent \
  docker.xuanyuan.run/[镜像仓库地址]/agent-nonroot:latest

说明：默认使用内置非root用户（UID=1000，GID=1000，用户名为agentuser）

自定义用户ID/组ID运行

如需根据环境需求自定义运行用户的UID和GID，可通过--user参数指定：

bash
docker run -d \
  --name secure-agent \
  --user 2000:2000 \  # 指定UID=2000，GID=2000
  [镜像仓库地址]/agent-nonroot:latest

注意：需确保指定的UID/GID在宿主机或容器内无冲突，且具有必要的文件访问权限

Docker Compose 配置示例

在docker-compose.yml中配置非root运行：

yaml
version: '3'
services:
  secure-agent:
    image: docker.xuanyuan.run/[镜像仓库地址]/agent-nonroot:latest
    container_name: secure-agent
    user: "2000:2000"  # 自定义UID=2000，GID=2000
    restart: always
    # 其他Agent相关配置（如环境变量、挂载卷等）
    environment:
      - AGENT_CONFIG=xxx
    volumes:
      - ./agent-data:/data

配置参数说明

权限注意事项

1. 挂载卷权限：若需挂载宿主机目录至容器内，需确保宿主机目录对指定的UID/GID有读写权限，可通过chown或chmod调整宿主机目录权限：

   bash
   # 示例：调整宿主机挂载目录权限以允许UID=2000访问
   chown -R 2000:2000 /path/to/host/directory
   

2. 端口映射：非root用户无法绑定1024以下的特权端口，若Agent需使用低端口，需通过端口映射（如宿主机高端口映射至容器内低端口）或调整系统内核参数（不推荐）。

常见问题解决

• 权限不足错误：检查容器运行用户的UID/GID是否对所需资源（文件、端口等）有访问权限，或调整挂载目录权限。
• 容器启动失败：确认指定的UID/GID在容器内是否存在（如需使用非内置用户，可能需提前在容器内创建用户）。
• 与其他工具兼容性：若使用SELinux/AppArmor，需确保相关安全策略允许非root用户运行容器进程。