rancher/agent 镜像文档

1. 镜像概述和主要用途

rancher/agent 是 Rancher 容器管理平台的核心代理组件镜像，用于在主机与 Rancher Server 之间建立通信通道，执行 Rancher Server 下发的容器部署、服务管理、资源调度等指令，是 Rancher 环境中连接主机与管理平台的关键组件。

根据 2017 年 7 月 17 日的版本更新，rancher/agent:v1.2.5 版本被正式标记为 rancher/agent:latest，即 latest 标签从此指向 v1.2.5 版本。

2. 核心功能和特性

2.1 版本标签变更

自 2017 年 7 月 17 日起，rancher/agent:latest 标签与 rancher/agent:v1.2.5 版本完全等价，用户可通过 latest 标签直接使用 v1.2.5 版本的功能。

2.2 标准代理功能（基于 v1.2.5 版本）

• 与 Rancher Server 建立安全通信，接收并执行管理指令（如容器部署、服务扩缩容等）。
• 管理主机上的容器生命周期（启动、停止、重启、删除等）。
• 同步主机资源信息（CPU、内存、磁盘等）至 Rancher Server。

3. 使用场景和适用范围

适用于 Rancher 容器管理平台环境，需通过代理组件将主机接入 Rancher 管理的场景，具体包括：

• Rancher 环境中新增主机的注册与管理。
• 依赖 rancher/agent:v1.2.5 版本的现有部署，可迁移至 latest 标签以简化版本引用。
• 需要通过 latest 标签保持使用稳定版本（v1.2.5）的 Rancher 集群。

4. 使用方法和配置说明

4.1 基本使用流程

通过 Rancher Server 生成主机注册命令，在目标主机上执行该命令以启动 rancher/agent:latest 容器，完成主机接入 Rancher 管理平台。

4.2 Docker Run 部署示例

Rancher Server 会提供包含注册密钥和服务器地址的完整命令（需从 Rancher Server 控制台获取），典型格式如下：

bash
docker run -d --privileged --restart=unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/rancher:/var/lib/rancher \
  rancher/agent:latest \
  http://<rancher-server-ip>:8080/v3/import/<registration-key>.yaml

参数说明：

• --privileged：需特权模式以管理主机 Docker 服务和网络。
• --restart=unless-stopped：确保 Agent 容器异常退出后自动重启（手动停止除外）。
• 挂载卷：
  • /var/run/docker.sock：与 Docker 守护进程通信，管理容器。
  • /var/lib/rancher：存储 Agent 运行时数据。
• 最后的 URL：Rancher Server 生成的注册地址，包含服务器地址和注册密钥（需替换为实际值）。

5. 配置参数与环境变量

Rancher Agent 的核心配置通过启动命令中的注册 URL 传递，无需额外环境变量。若需自定义配置，可通过 Rancher Server 控制台调整主机注册参数（如标签、资源限制等）。

6. 注意事项

• 版本兼容性：确保 rancher/agent:v1.2.5（即 latest 标签）与 Rancher Server 版本兼容（建议使用 Rancher Server v1.6.x 及以上版本）。
• 标签依赖风险：latest 标签未来可能指向更新版本，若需固定使用 v1.2.5，建议显式指定 rancher/agent:v1.2.5 而非依赖 latest。
• 权限要求：必须以 --privileged 模式运行，否则 Agent 无法正常管理主机 Docker 服务。