okteto-agent 镜像文档

一、镜像概述

镜像名称：okteto-agent
主要用途：运行在 Okteto 虚拟机（VM）中的代理程序，负责与 Okteto 平台进行通信，协调开发环境资源管理、状态同步及任务执行，是 Okteto 开发环境自动化运维的核心组件。

二、核心功能与特性

1. 平台通信桥接

• 建立与 Okteto 平台的加密连接，实时上报虚拟机状态（如运行状态、资源使用率）。
• 接收并执行 Okteto 平台下发的指令（如环境启动/停止、配置更新）。

2. 环境生命周期管理

• 自动化管理 Okteto 开发环境的生命周期，包括环境初始化、启动、暂停、恢复及销毁。
• 支持多环境并行管理，区分开发、测试、预览等环境类型。

3. 资源监控与上报

• 实时采集虚拟机 CPU、内存、磁盘、网络等资源使用数据，周期性上报至 Okteto 平台。
• 触发资源阈值告警（如内存使用率过高），并同步至平台告警系统。

4. 配置动态同步

• 支持从 Okteto 平台拉取最新环境配置（如环境变量、挂载卷规则），并动态应用至本地虚拟机。
• 确保本地开发环境配置与平台定义一致，避免手动配置偏差。

三、使用场景

1. Okteto 开发环境自动化运维

• 适用于开发团队通过 Okteto 平台管理远程开发环境，实现环境一键部署、状态监控及故障自愈。

2. 本地-云端环境协同

• 作为本地开发机与 Okteto 云端资源的中间层，同步代码变更、依赖安装等操作，确保本地开发体验与云端一致。

3. CI/CD 流程集成

• 在 CI/CD 流水线中作为环境代理，触发 Okteto 环境的构建、测试或预览环境部署，简化开发至交付的流程。

4. 多租户环境隔离

• 支持为不同用户或项目分配独立代理实例，实现资源隔离与权限控制，保障多租户环境安全性。

四、使用方法与配置说明

1. 前提条件

• 已安装 Docker Engine（20.10+ 版本）。
• 已注册 Okteto 账户，并获取平台 API 密钥（通过 Okteto 控制台「个人设置」>「API 访问」生成）。
• 目标虚拟机需具备访问 Okteto 平台的网络权限（默认端口 443）。

2. 快速启动（docker run）

通过 docker run 命令直接启动容器，需指定 Okteto 平台连接参数：

docker run -d \
  --name okteto-agent \
  --restart always \
  -e OKTETO_API_KEY="your_okteto_api_key" \
  -e OKTETO_ENVIRONMENT="dev-env-01" \  # 目标 Okteto 环境名称
  -e OKTETO_PLATFORM_URL="[***]" \  # Okteto 平台地址（默认官方云地址）
  -e LOG_LEVEL="info" \  # 日志级别：debug/info/warn/error
  --network host \  # 推荐使用 host 网络确保通信稳定性
  okteto-agent:latest

3. Docker Compose 配置示例

创建 docker-compose.yml 文件，定义 agent 服务及依赖（如必要的网络或存储配置）：

version: "3.8"
services:
  okteto-agent:
    image: okteto-agent:latest
    container_name: okteto-agent
    restart: always
    environment:
      - OKTETO_API_KEY=your_okteto_api_key
      - OKTETO_ENVIRONMENT=dev-env-01
      - OKTETO_PLATFORM_URL=[***]
      - LOG_LEVEL=info
      - REPORT_INTERVAL=30s  # 资源上报间隔（默认 30s）
    network_mode: host  # 需与 Okteto 平台通信，建议使用 host 网络
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock  # 如需管理本地容器，挂载 Docker 套接字

启动命令：

docker-compose up -d

4. 环境变量配置说明

5. 注意事项

• 网络权限：容器需允许出站连接至 Okteto 平台端口 443，确保 TLS 握手正常。
• 持久化存储：如需保留 agent 运行日志或配置，可挂载本地目录（如 -v ./agent-logs:/var/log/okteto-agent）。
• 权限要求：运行容器的用户需具备访问 Docker 套接字的权限（如需管理本地容器），或通过 --user root 临时提升权限（生产环境慎用）。

五、参考信息

由于原始描述信息有限，本文档核心功能与配置基于 Okteto 平台代理程序的通用特性推断。实际使用时，请以 Okteto 官方文档 及镜像内置 README 为准。