企业官网建设流程全解析

AgentOps Jockey 深度实战：Kaniko 集群内构建、ECR 推送与 Redis 队列 Worker 全解

【免费下载链接】agentopsPython SDK for AI agent monitoring, LLM cost tracking, benchmarking, and more. Integrates with most LLMs and agent frameworks including CrewAI, Agno, OpenAI Agents SDK, Langchain, Autogen, AG2, and CamelAI项目地址: https://gitcode.com/GitHub_Trending/ag/agentops

Jockey 是 AgentOps 仓库app/deploy目录下的 Python 部署工具，负责把容器镜像在 Kubernetes（EKS）集群内用 Kaniko 无守护进程方式构建出来、推送到 AWS ECR，并部署到按项目隔离的命名空间中。读完本文，你可以掌握 Jockey 的完整配置体系、setup-kubeconfig/setup-builder/test-build/deploy-test等全部 CLI 命令、多命名空间与 Secret 隔离架构，以及如何运行基于 Redis 队列的异步部署 Worker。

一、Jockey 是什么、解决什么问题

根据 Jockey README 的描述，Jockey 是一个“用于构建容器镜像并将其部署到 Kubernetes 集群的 Python 工具”（building container images and deploying them to Kubernetes clusters），核心特性有两条：

• 使用Kaniko做安全、无 root 权限的镜像构建——构建过程本身就是集群里运行的 Kubernetes Job，不需要在任何节点安装 Docker daemon；
• 使用AWS ECR作为容器镜像仓库，构建 Job 通过 builder 命名空间内的 AWS 凭证 Secret 完成推送。

在整个 AgentOps 项目中，Jockey 承担的是“把用户项目（如 FastAPI 服务、CrewAI Agent）真正跑起来”这一环：API 层把部署请求写入 Redis 队列，Worker 从队列取任务，调用 执行层 完成“拉代码 → Kaniko 构建 → 推 ECR → 创建 Deployment/Ingress”的完整链路。

二、前置条件与环境变量

2.1 前置条件

README 列出的运行前提：

• 已激活 Python 虚拟环境（source ../api/.venv/bin/activate）；
• Kubeconfig 文件位于./config/kubeconfig；
• AWS 凭证 Secret 已部署到 Kubernetes；
• ECR 仓库可用。

2.2 完整环境变量清单（结合源码默认值）

README 给出了基础配置示例：

# Kubernetes Configuration KUBECONFIG=./config/kubeconfig KUBERNETES_NAMESPACE=default # Container Registry IMAGE_REGISTRY=315680545607.dkr.ecr.us-west-1.amazonaws.com AWS_DEFAULT_REGION=us-west-1 # AWS Credentials (for kubectl secret) AWS_ACCESS_KEY_ID=your_access_key AWS_SECRET_ACCESS_KEY=your_secret_key

更完整的配置项与默认值可以从 环境配置模块 中确认，该模块还支持在LOCAL_DEV=1时自动加载jockey/.env文件。关键变量及其默认值如下：

三、初始化命令：setup-kubeconfig 与 setup-builder

3.1 生成 EKS kubeconfig

# From the jockey directory export KUBECONFIG=./config/kubeconfig python -m jockey setup-kubeconfig

从 CLI 入口 可以看到该命令的实现细节：它校验EKS_CLUSTER_NAME与AWS_REGION两个环境变量必须存在，确保config/目录存在，然后子进程调用：

aws eks update-kubeconfig --region <AWS_REGION> --name <EKS_CLUSTER_NAME> --kubeconfig <KUBECONFIG_PATH> [--profile <AWS_PROFILE>]

即直接用 AWS CLI 从 EKS 集群信息生成 kubeconfig，省去手工粘贴；若本机没有awscli会明确报awscli not found。

3.2 初始化 builder 命名空间与 AWS 凭证

python -m jockey setup-builder

该命令完成三件事（实现见 setup_builder）：

1. kubectl create namespace builder——创建专用的builder命名空间，若已存在则幂等跳过；
2. 通过aws configure get aws_access_key_id/aws configure get aws_secret_access_key从本地 AWS CLI 配置中提取凭证（支持AWS_PROFILE指定 profile），并校验非空；
3. 删除旧的aws-credentialsSecret 后，用kubectl create secret generic aws-credentials --from-literal=access-key=... --from-literal=secret-key=... -n builder重建。

README 专门解释了为什么要这样隔离：构建 Pod 需要 AWS 凭证才能向 ECR 推镜像，而业务 Pod 只需要拉取镜像，不需要任何 AWS 凭证。把 builder 操作隔离在独立命名空间中，就实现了凭证的最小暴露面。

四、构建与部署：test-build 和 deploy-test

4.1 只构建并推送镜像：test-build

# Test image building and pushing to ECR python -m jockey test-build # 支持 --name / --namespace / --template 参数，默认使用配置值（hosting/agent-images）

test_build 命令 创建一个Image对象（tag 固定为test），消费其build()事件流并按EventStatus打印：STARTED→ 开始构建；PROGRESS→ 过滤掉 Kaniko 的---噪音行后打印步骤；COMPLETED→ 打印完整镜像 URL；ERROR→ 中止。

4.2 完整构建 + 部署：deploy-test

# Build image, push to ECR, and deploy to Kubernetes (uses default namespace) python -m jockey deploy-test # Deploy with custom namespace (must exist first!) python -m jockey deploy-test --namespace test-namespace # Deploy with custom template python -m jockey deploy-test --template simple-api

deploy_test 命令 内部构造DeploymentConfig（端口固定为8080），然后消费 execute_serve 生成器，按event_type分三段打印：build（构建）、push（推送，仅保留digest:/Pushed关键行）、deployment（部署进度）。部署完成后会打印最终的 Deployment 名称、镜像 URL 与命名空间。

4.3 Kaniko 构建的底层实现（源码级）

构建的核心在 Image 模型，流程可以拆解为：

1. 确保 ECR 仓库存在：ensure_ecr_repository 从IMAGE_REGISTRY域名中解析出 region（例如从...dkr.ecr.us-west-1.amazonaws.com提取us-west-1），先用 boto3describe_repositories探测；不存在则create_repository，且imageTagMutability='MUTABLE'、关闭 push 扫描；

2. 生成 Dockerfile 并写入 ConfigMap：generate_dockerfile()用 Jinja2 渲染templates/docker/{模板}.j2（默认模板变量含base_image: python:3.12-slim-bookworm、port: 6969、run_command: /app/.venv/bin/agentstack run），再创建名为dockerfile-{job_name}的 ConfigMap 挂载到/workspace；若同名 ConfigMap 已存在（HTTP 409）则删除重建；

3. 可选的 build_files 注入：DeploymentConfig.build_files中的文件（如instance/包下的 Python 源码）会被打成tar.gz、Base64 编码后存入instance-{tar哈希前8位}ConfigMap，挂载到/mnt/build_files——用内容哈希命名避免脏 ConfigMap 被复用；

4. 创建 Kaniko Job：容器镜像为gcr.io/kaniko-project/executor:latest，核心参数为--dockerfile=/workspace/Dockerfile、--context=/workspace、--destination=<完整 ECR URL>、--build-arg=JOB_ID=...，并追加 S3 层缓存参数：

   --cache=true --cache-repo=s3://<S3_BUCKET_NAME>/build-cache/<sha256(仓库名)[:16]> --cache-ttl=24h

   缓存 key 按仓库名做 SHA256 截断，因此每个项目有独立的层缓存命名空间。容器环境变量从aws-credentialsSecret 注入AWS_ACCESS_KEY_ID（key:access-key）与AWS_SECRET_ACCESS_KEY（key:secret-key），DOCKER_CONFIG指向/kaniko/.docker；

5. Job 规格与清理：restart_policy=Never、backoff_limit=1、ttl_seconds_after_finished=300（完成后 5 分钟由 K8s 自动回收）。Job 名由builder-{job_id}生成，并把:、/替换为-、统一小写——这正是 README 中“Kubernetes 名字不能包含/或:，会被自动净化”的由来；

6. Watch 等待结果：通过 Kubernetes Watch API 以field_selector=metadata.name=<job名>监听 Job 状态（timeout_seconds=600），succeeded>0时 yieldCOMPLETED事件并返回镜像 URL，failed>0时 yieldERROR并抛出异常；finally中删除 Job 与 Dockerfile ConfigMap，忽略清理错误。

4.4 部署阶段的执行链路

exec.py 定义了三种任务类型（对应 TaskType 枚举）：

• execute_build：只构建不部署。它先确保builder命名空间存在，再创建Repository（代码 checkout 实际发生在 builder 镜像内部，支持github_access_token拼装认证 URL），最终用hosting/{project_id}作为仓库名、latest作为 tag 构建；
• execute_serve：构建 + 部署。关键步骤包括：确保目标命名空间存在；把AGENTOPS_API_KEY通过 delete-then-create 同步进项目命名空间（因为 API key 可能在两次部署之间变化）；创建Deployment（名称为project_id）并deploy_or_upgrade（支持force_recreate）；若create_ingress为真，则调用IngressService.create_for_deployment创建 Service + Ingress——注意 Ingress 创建失败不会让部署失败，只记日志；
• execute_run：一次性任务。复用最新镜像创建 Kubernetes Job，入口命令为python /app/instance/job_runner.py，通过INPUT_DATA（JSON 字符串）、JOB_ID、CALLBACK_URL环境变量传参，ttl_seconds_after_finished=1800（30 分钟后自动清理）。

Deployment 模型（deployment.py）从环境变量读取资源限制与探针路径，DeploymentEvent携带available_replicas/ready_replicas/desired_replicas字段以生成“Scaling deployment: x/y replicas available”这类进度文案；DeployManager用两个 watcher 线程分别监听 Deployment 与 Pod 事件并合并成统一事件流，默认超时为 900 秒。

五、运行时管理命令

# List running instances in a specific project namespace python -m jockey list-instances --namespace PROJECT_ID # List builder pods python -m jockey list-instances --namespace builder # Stop a deployment (note: deployment name comes BEFORE --namespace) python -m jockey stop-deployment DEPLOYMENT_NAME --namespace PROJECT_ID # Stop a specific pod python -m jockey stop-pod pod-name-12345 --namespace PROJECT_ID # View builder logs across all namespaces python -m jockey logs-builder -f

结合main.py 的源码，这些命令的行为如下：

• list-instances：通过Pod.filter(namespace=...)列出 Pod，用●/○标记 ready 状态，并打印 Phase、Node、Restarts、Pod IP；
• stop-deployment：先Deployment.get校验存在性，再delete_by_name删除；源码中deployment_name是@click.argument（位置参数），--namespace是@click.option，这就是“名称必须在--namespace之前”这一参数顺序要求的直接原因；
• stop-pod：Pod.delete_by_name直接删 Pod，失败时提示“可能不存在或无权限”；
• logs-builder：在 builder 命名空间中过滤name以builder-开头、且带job-name标签的 Pod，按创建时间取最新一个，然后直接subprocess.Popen执行kubectl logs <pod> -n <ns> [--follow]流式打印，Ctrl+C终止。

此外 CLI 还提供了 README 未重点展开的 ALB 工具命令：list-alb-ingresses（列出使用共享 ALB 分组alb-deployments的 Ingress）、alb-status（汇总共享 ALB 的就绪状态与端点）、validate-alb-routing（校验某 hostname 的 Ingress 注解：group.name、scheme 应为internet-facing、target-type 应为ip等），可用于排查共享 ALB 的路由配置问题。

六、CLI 使用惯例与错误恢复

6.1 命令发现

python -m jockey --help # 查看全部命令 python -m jockey deploy-test --help # 查看单条命令参数

6.2 参数顺序（位置参数在前）

# ✅ Correct python -m jockey stop-deployment hosting-agent-images --namespace default # ❌ Wrong python -m jockey stop-deployment --namespace default hosting-agent-images

如第五节所述，这是 Click 中argument与option的解析规则决定的，并非笔误。

6.3 命名空间必须预先存在

kubectl create namespace test-namespace # 先建 python -m jockey deploy-test --namespace test-namespace

注意：deploy-test路径下execute_serve会自动ensure_namespace_exists，而 README 中针对deploy-test --namespace的说明是“必须已存在”，实操中建议显式创建以避免权限问题。

6.4 部署冲突与错误恢复

# 已存在同名部署时先停掉 python -m jockey stop-deployment hosting-agent-images --namespace default python -m jockey deploy-test

README 给出的三条错误速查表（均来自实际报错文案）：

6.5 直接 Kubectl 排查

kubectl get deployments --namespace default kubectl get pods --namespace default -l app=hosting-agent-images kubectl logs pod-name --namespace default kubectl describe pod pod-name --namespace default kubectl delete deployment hosting-agent-images --namespace default

七、架构解析：命名空间策略与 Secret 管理

7.1 三类命名空间

README 的架构章节描述的多命名空间策略，在源码中均有对应：

1. builder 命名空间（持久、setup 时创建）
   • 容纳所有 Kaniko 构建 Job、aws-credentialsSecret 与构建用 ConfigMap；
   • 只有 builder Pod 能拿到 AWS 凭证用于推送 ECR；
   • 对应 environment.py 中的BUILDER_NAMESPACE（默认builder），且execute_build明确把Image的namespace固定为BUILDER_NAMESPACE。
2. 项目命名空间（project-id）
   • 隔离单个项目的 Deployment、项目级 Secret（如AGENTOPS_API_KEY）与 Ingress；
   • 不需要 AWS 凭证——拉取 ECR 镜像走集群级权限；
   • execute_serve部署前自动创建。
3. default 命名空间
   • 遗留操作与集群级资源共享，当前架构中用途有限。

7.2 跨命名空间 Secret 限制与应对策略

Kubernetes Secret 是命名空间作用域资源，不能跨命名空间引用——README 明确把这视为“维持命名空间隔离的安全特性”。据此 Jockey 的 Secret 策略是：

1. AWS 凭证只存在于 builder 命名空间；业务 Pod 拉 ECR 依赖集群级配置，不注入任何 AWS 凭证；
2. 项目 Secret 存各自命名空间：AGENTOPS_API_KEY在每次部署时由 ensure_agentops_api_key_exists 同步（先删后建，因为 key 可能变化）；
3. 共享资源需要逐命名空间复制：设计上不做跨命名空间共享，必要时可用kubernetes-reflector一类工具自动复制 Secret。

删除项目时，delete_deployment_resources 会按app=<deployment_name>/deployment=<deployment_id>标签清理 Deployment、Service、Ingress 与 Secret 四类资源，404 视为已删除而忽略。

7.3 安全要点汇总

• AWS 凭证隔离在 builder 命名空间，业务面零凭证；
• 项目 Secret 按命名空间隔离；
• 无 Docker daemon（Kaniko in-cluster 构建）；
• 基于命名空间的访问控制与资源隔离。

README 的 Development Notes 同时坦承了当前限制与待办：部署命令尚不报告 CrashLoopBackOff（只会静默超时）；镜像拉取安全可考虑 imagePullSecrets 或 IRSA；S3 层缓存已实现（见 4.3 节），持续优化方向仍是构建加速。

八、Dockerfile 模板与部署包（Deployment Packs）

8.1 模板文件

README 说明模板位于./templates/docker/，其中test是一个简单的 Alpine + netcat HTTP 服务器，python-agent是带 AgentStack 的 Python 应用（标注为 incomplete）。仓库中实际存在 5 个 Jinja2 模板：

• test.j2：最小测试服务；
• python-agent.j2：Python + AgentStack 应用；
• fastapi-agent.j2：直接 serve 仓库中已有的 FastAPI 应用；
• crewai-agent.j2：在watch_path下寻找 CrewAI Agent 的kickoff方法并暴露为 API 端点（端口 8080）；
• crewai-job.j2：通过job_runner.py一次性执行 Agent，不暴露端口。

8.2 DeploymentPack 预设

config.py 把模板、端口与 build_files 打包成预设，供 API 侧通过DeploymentConfig.from_pack()一键生成配置：

CREWAI/CREWAI_JOB的 build_files 由 _get_instance_build_files 生成——即把 Jockey 自带的instance包（含job_runner.py等运行时代码）作为构建文件随源码一起打进镜像，对应 4.3 节第 3 步的 tar.gz + ConfigMap 注入机制。

DeploymentConfig 的其余关键字段：repository_url/branch/github_access_token（Git 源码）、entrypoint/watch_path（入口与工作子目录）、replicas、ports、secret_names、agentops_api_key、callback_url、create_ingress（默认 True）、force_recreate；__post_init__会自动派生tag=project_id、hostname={project_id}.{DEPLOYMENT_DOMAIN}。它提供serialize()/from_serialized()用于在 Redis 中持久化任务快照。

九、Worker：基于 Redis 队列的异步部署

9.1 Worker 是什么

Jockey 支持以 Docker 容器方式运行一个后台 Worker，从 Redis 队列消费部署任务。核心实现在 worker/ 目录：

• queue.py：队列与事件存储层。任务元数据存在 Hashdeployment:metadata（field 为{namespace}:{project_id}:{task_id}复合键），任务 ID 依次rpush进 Listdeployment:queue；Worker 侧用lpop原子出队——源码注释指出多 Worker 并发调用时 Redis 单命令串行执行保证不会重复领取；每个任务的进度事件写入 Sorted Setdeployment:events:{task_id}，score 为 Unix 时间戳，因此get_task_status（取最新事件）与get_task_events（按起始时间过滤，zrevrangebyscore降序）都是 Redis 原生操作，无需客户端排序；
• worker.py：Worker主循环每WORKER_POLL_INTERVAL（默认 5 秒）轮询一次，领到任务后在独立守护线程中执行（同一job_id已有存活线程则跳过），按TaskType分派到execute_serve/execute_build/execute_run，期间每个BaseEvent都经queue.store_event落 Redis；SIGINT/SIGTERM触发优雅停机（等待活跃任务最多 30 秒）；
• worker/main.py：三个子命令——
  • python -m jockey.worker start：启动部署 Worker；
  • python -m jockey.worker status：检查 Redis 连通性、待处理任务数（llen deployment:queue）与“处理中”任务数，输出 Active/Idle 状态；
  • python -m jockey.worker health：Redisping健康检查，exit 0 = 健康、exit 1 = 不健康（供容器 HEALTHCHECK 使用）。

9.2 构建与运行 Worker 镜像

Worker 的 Dockerfile 基于python:3.12-slim-bookworm，安装build-essential、git、awscli，从官方镜像引入uv后pip install -e jockey，创建非 root 用户worker并设置 HEALTHCHECK（30s 间隔、10s 超时、5s 启动宽限、3 次重试）。容器默认命令为：

python -m jockey setup-kubeconfig && python -m jockey.worker start

即容器启动时先在容器内执行setup-kubeconfig生成 EKS kubeconfig（依赖容器内的 AWS 凭证），再进入 Worker 轮询循环。

# Build from the jockey directory docker build -f worker/Dockerfile -t jockey-worker .

# Check worker and queue status docker run --rm jockey-worker python -m jockey.worker status # Start the worker (requires Redis connection) docker run --rm \ -e DEPLOY_REDIS_HOST=redis.example.com \ -e DEPLOY_REDIS_PORT=6379 \ -e DEPLOY_REDIS_DB=0 \ jockey-worker # Run with Redis linked container docker run --rm \ --link redis:redis \ -e DEPLOY_REDIS_HOST=redis \ jockey-worker # Health check command (used by Docker HEALTHCHECK) docker run --rm jockey-worker python -m jockey.worker health

9.3 Worker 环境变量与 Compose 示例

Worker 运行所需变量（Redis 三项与 K8s/AWS 配置为必需）：

# Redis Configuration (required) DEPLOY_REDIS_HOST=localhost # Redis server hostname DEPLOY_REDIS_PORT=6379 # Redis server port DEPLOY_REDIS_DB=0 # Redis database number # Worker Configuration (optional) WORKER_POLL_INTERVAL=5 # Seconds between queue polls # Kubernetes Configuration (required for deployments) KUBECONFIG=/path/to/kubeconfig KUBERNETES_NAMESPACE=default # AWS Configuration (required for ECR) AWS_ACCESS_KEY_ID=your_key AWS_SECRET_ACCESS_KEY=your_secret AWS_DEFAULT_REGION=us-west-1

补充：源码中还存在DEPLOY_REDIS_USER（默认default）与DEPLOY_REDIS_PASSWORD（默认空）两个认证变量，queue.py 建客户端时一并传入。

Docker Compose 最小编排（Redis + Worker，kubeconfig 只读挂载到容器内 Jockey 默认路径）：

version: '3.8' services: redis: image: redis:7-alpine ports: - "6379:6379" jockey-worker: image: jockey-worker depends_on: - redis environment: - DEPLOY_REDIS_HOST=redis - DEPLOY_REDIS_PORT=6379 - DEPLOY_REDIS_DB=0 - WORKER_POLL_INTERVAL=5 volumes: - /path/to/kubeconfig:/app/config/kubeconfig:ro

队列与 Worker 的行为有对应测试：test_queue.py、test_queue_integration.py（配合 Dockerfile.redis 起真实 Redis）与 test_api_main.py，可用于回归验证队列语义与健康检查。

十、排障指南

10.1 常见问题

1. Image pull errors：检查aws-credentialsSecret 是否存在且格式正确（access-key/secret-key两个 key）；
2. Build failures：确认 ECR 仓库存在、AWS 凭证具备 push 权限；
3. CrashLoopBackOff：查看容器日志，确认应用是长驻进程（一次性进程应走execute_run/ Job 路径）；
4. Job name errors：K8s 名字不允许/与:，builder-{job_id}生成时已自动替换为-并小写化。

10.2 调试命令

# Check recent builder pods kubectl get pods --namespace builder | grep builder # Check builder logs (convenience command) python -m jockey logs-builder -f # Check AWS credentials secret in builder namespace kubectl get secret aws-credentials --namespace builder -o yaml # Check project deployment pods / secrets kubectl get pods --namespace PROJECT_ID kubectl get secrets --namespace PROJECT_ID # Verify ECR repository exists aws ecr describe-repositories --region us-west-1 --registry-id 315680545607

十一、端到端工作流示例

README 给出的完整闭环示例（含清理步骤）：

# 1. Initial setup (one-time) source ../api/.venv/bin/activate export KUBECONFIG=./config/kubeconfig python -m jockey setup-kubeconfig # 生成 EKS kubeconfig python -m jockey setup-builder # builder 命名空间 + AWS 凭证 Secret # 2. Build and deploy python -m jockey deploy-test --name hosting/agent-images --template test # 3. Verify deployment kubectl get pods -l app=hosting-agent-images # 4. Monitor build progress python -m jockey logs-builder -f # 5. Cleanup kubectl delete deployment hosting-agent-images

十二、Jockey 目录结构

README 给出了一份简化的文件结构；结合当前仓库实际内容，各模块职责如下（以仓库为准）：

jockey/ ├── __main__.py # CLI 命令组（Click） ├── config.py # DeploymentConfig / DeploymentPack / TaskType ├── exec.py # execute_build / execute_serve / execute_run 执行编排 ├── environment.py # 全部环境变量与默认值 ├── template.py # Jinja2 模板渲染 ├── secret.py # Secret 创建/删除 ├── labels.py / log.py # 标签常量与日志 ├── api/ # API 层（main.py、run.py） ├── backend/ │ ├── client.py # Kubernetes 客户端封装 │ ├── event.py # 事件模型与序列化（BaseEvent / EventStatus） │ └── models/ # image / deployment / pod / job / secret / service 等 K8s 模型 ├── templates/docker/ # 5 个 Dockerfile Jinja2 模板 ├── worker/ # Redis 队列 Worker（queue.py / worker.py / Dockerfile） └── tests/ # 队列、API、集成与模型测试

总结

Jockey 把“构建—推送—部署—观测”四件事收敛进一个以事件流为骨架的 Python 工具链：Kaniko in-cluster Job 保证构建安全无守护进程依赖，builder / project 双命名空间 + 最小化 Secret 分布保证凭证隔离，execute_serve/execute_run统一事件协议让 CLI、API 与 Redis Worker 三种入口复用同一套执行逻辑，而 Sorted Set 时间戳事件存储又让上游可以按时间范围回放任意一次部署的完整进度。理解以上机制后，你可以按本文第三至六节完成手工部署，或按第九节把 Worker 容器化接入 AgentOps 的队列式部署链路。

【免费下载链接】agentopsPython SDK for AI agent monitoring, LLM cost tracking, benchmarking, and more. Integrates with most LLMs and agent frameworks including CrewAI, Agno, OpenAI Agents SDK, Langchain, Autogen, AG2, and CamelAI项目地址: https://gitcode.com/GitHub_Trending/ag/agentops