Ark 平台源码安装指南：使用 ark-cli 从零部署到本地 Kubernetes 集群

Ark Setup by mckinsey/agents-at-scale-ark

362 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/mckinsey/agents-at-scale-ark --skill 'Ark Setup'

自动化开发运维命令行工具

🇨🇳中文介绍

Ark 设置

此技能帮助您使用 ark-cli 从源码设置和安装 Ark 平台。

何时使用此技能

在以下情况下使用此技能：

用户想要安装或设置 Ark
用户需要将 Ark 部署到其本地集群
用户询问如何让 Ark 运行起来
用户需要排查 Ark 安装问题

先决条件

Docker-in-Docker (DinD) - Kind 在此容器内创建集群所必需
kubectl - Kubernetes CLI
Helm - 用于安装 Ark 组件
Node.js - 用于构建 ark-cli 工具

步骤 0：验证 Docker-in-Docker 是否可用

关键：在尝试创建 Kind 集群之前，您必须验证 Docker 是否可访问。

docker info

如果此命令失败，请立即停止。 不要尝试创建 Kind 集群。向用户报告：

"无法继续：Docker 不可用。Kind 需要 Docker-in-Docker (DinD) 才能在此容器内创建集群。容器必须使用 ark 配置文件（devspace dev -p ark）启动，该配置文件会添加 DinD sidecar。"

如果 Docker 可用，请继续下一步。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 1：克隆 Ark 仓库

首先，确保您已克隆 Ark 仓库。如果用户提供了组织/仓库，请使用它。否则，使用默认值：

git clone git@github.com:mckinsey/agents-at-scale-ark.git
cd agents-at-scale-ark

如果处理拉取请求，请检出 PR 分支：

git fetch origin pull/<PR_NUMBER>/head:pr-<PR_NUMBER>
git checkout pr-<PR_NUMBER>

步骤 2：设置 Kubernetes 集群

步骤 2a：清理现有集群

关键：始终先删除现有的 Kind 集群，以避免冲突和资源耗尽。

# 删除任何现有的 ark-cluster
kind delete cluster --name ark-cluster 2>/dev/null || true

# 验证不存在 ark-cluster
kind get clusters

步骤 2b：创建集群并配置 kubeconfig

# 创建 Kind 集群
kind create cluster --name ark-cluster

# 必需：获取控制平面容器的 IP 地址
CONTROL_PLANE_IP=$(docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' ark-cluster-control-plane)

# 导出 kubeconfig 并将主机名替换为 IP
mkdir -p ~/.kube
kind get kubeconfig --name ark-cluster --internal | sed "s/ark-cluster-control-plane/$CONTROL_PLANE_IP/g" > ~/.kube/config

# 验证连接是否正常
kubectl cluster-info

为什么需要 IP 地址： 此代理在 Docker 内部运行。默认的 127.0.0.1 无法跨容器工作，并且 --internal 主机名可能无法解析。使用实际的容器 IP 可确保连接性。

步骤 3：从源码构建 ark-cli

从克隆的仓库构建 CLI。这确保您使用与正在测试的代码匹配的版本：

cd agents-at-scale-ark
npm install
cd tools/ark-cli
npm install
npm run build

步骤 4：使用 ark-cli 安装 Ark

使用构建的 CLI 安装 Ark。为了可靠性，使用直接的 node 执行：

# 从 tools/ark-cli 目录
node dist/index.js install --yes --wait-for-ready 5m

或者，如果您在仓库根目录：

node tools/ark-cli/dist/index.js install --yes --wait-for-ready 5m

--yes 标志自动确认提示，--wait-for-ready 等待服务准备就绪。

步骤 5：验证安装

检查安装状态：

node tools/ark-cli/dist/index.js status

或者使用 kubectl：

kubectl get pods -n ark
kubectl get pods -n ark-system
kubectl get services -n ark

等待所有 Pod 显示为 Running 且服务准备就绪。

Docker 不可用 / Kind 创建集群失败

如果 docker info 失败或 kind create cluster 因 Docker 错误而失败：

停止。 此容器未配置 Docker-in-Docker (DinD)。向用户报告：

"无法创建 Kind 集群：Docker 不可用。容器必须使用 ark 配置文件（devspace dev -p ark）启动。"

kubectl get pods -A -o wide | grep -E '(ark|cert-manager)'
kubectl describe pod -n ark <pod-name>

kubectl logs -n ark deployment/ark-api
kubectl logs -n ark-system deployment/ark-controller

Kind 的 Kubeconfig 问题

如果 kubectl/helm 无法访问集群 API 服务器（连接被拒绝或找不到主机名）：

# 获取控制平面 IP 并重新配置 kubeconfig
CONTROL_PLANE_IP=$(docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' ark-cluster-control-plane)
kind get kubeconfig --name ark-cluster --internal | sed "s/ark-cluster-control-plane/$CONTROL_PLANE_IP/g" > ~/.kube/config

# 验证服务器地址是 IP，而不是 127.0.0.1 或主机名
kubectl config view --minify | grep server
# 应显示：server: https://172.x.x.x:6443

一旦 Ark 运行：

kubectl apply -f samples/agents/my-agent.yaml

kubectl get agents
kubectl get queries
kubectl get teams

kubectl describe agent <agent-name>

安装 Phoenix 以进行 OpenTelemetry 追踪：

node tools/ark-cli/dist/index.js install marketplace/services/phoenix

kubectl port-forward -n phoenix svc/phoenix-svc 6006:6006
# 打开 http://localhost:6006

请勿使用 scripts/quickstart.sh - 它已弃用。始终按照上述描述使用 ark-cli。

请勿使用 npm install -g @agents-at-scale/ark - 始终从源码构建 ark-cli 以匹配正在测试的 PR 代码。

🇺🇸English

Ark Setup

This skill helps you set up and install the Ark platform from source using the ark-cli.

When to use this skill

Use this skill when:

User wants to install or set up Ark
User needs to deploy Ark to their local cluster
User asks about getting Ark running
User needs to troubleshoot Ark installation issues

Prerequisites

Docker-in-Docker (DinD) - Required for Kind to create clusters inside this container
kubectl - Kubernetes CLI
Helm - For installing Ark components
Node.js - For building the ark-cli tool

Step 0: Verify Docker-in-Docker is available

CRITICAL: You MUST verify Docker is accessible before attempting to create a Kind cluster.

docker info

If this command fails, STOP IMMEDIATELY. Do not attempt to create a Kind cluster. Report to the user:

"Cannot proceed: Docker is not available. Kind requires Docker-in-Docker (DinD) to create clusters inside this container. The container must be started with the ark profile (devspace dev -p ark) which adds the DinD sidecar."

If Docker is available, proceed to the next step.

Step 1: Clone the Ark repository

First, ensure you have cloned the Ark repository. If the user provided an org/repo, use that. Otherwise, use the default:

git clone git@github.com:mckinsey/agents-at-scale-ark.git
cd agents-at-scale-ark

If working on a pull request, checkout the PR branch:

git fetch origin pull/<PR_NUMBER>/head:pr-<PR_NUMBER>
git checkout pr-<PR_NUMBER>

Step 2: Set up Kubernetes cluster

Step 2a: Clean up existing clusters

CRITICAL: Always delete existing Kind clusters first to avoid conflicts and resource exhaustion.

# Delete any existing ark-cluster
kind delete cluster --name ark-cluster 2>/dev/null || true

# Verify no ark-cluster exists
kind get clusters

Step 2b: Create cluster and configure kubeconfig

# Create Kind cluster
kind create cluster --name ark-cluster

# REQUIRED: Get the control plane container's IP address
CONTROL_PLANE_IP=$(docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' ark-cluster-control-plane)

# Export kubeconfig and replace hostname with IP
mkdir -p ~/.kube
kind get kubeconfig --name ark-cluster --internal | sed "s/ark-cluster-control-plane/$CONTROL_PLANE_IP/g" > ~/.kube/config

# Verify connection works
kubectl cluster-info

Why IP address is required: This agent runs inside Docker. The default 127.0.0.1 doesn't work across containers, and the --internal hostname may not be resolvable. Using the actual container IP ensures connectivity.

Step 3: Build the ark-cli from source

Build the CLI from the cloned repository. This ensures you use the version matching the code being tested:

cd agents-at-scale-ark
npm install
cd tools/ark-cli
npm install
npm run build

Step 4: Install Ark using ark-cli

Use the built CLI to install Ark. Use direct node execution for reliability:

# From the tools/ark-cli directory
node dist/index.js install --yes --wait-for-ready 5m

Or if you're in the repo root:

node tools/ark-cli/dist/index.js install --yes --wait-for-ready 5m

The --yes flag auto-confirms prompts, and --wait-for-ready waits for services to be ready.

Step 5: Verify installation

Check installation status:

node tools/ark-cli/dist/index.js status

Or use kubectl:

kubectl get pods -n ark
kubectl get pods -n ark-system
kubectl get services -n ark

Wait until all pods show as Running and services are ready.

Troubleshooting

Docker not available / Kind fails to create cluster

If docker info fails or kind create cluster fails with Docker errors:

STOP. This container does not have Docker-in-Docker (DinD) configured. Report to the user:

"Cannot create Kind cluster: Docker is not available. The container must be started with the ark profile (devspace dev -p ark)."

Check pod status

kubectl get pods -A -o wide | grep -E '(ark|cert-manager)'
kubectl describe pod -n ark <pod-name>

View logs

kubectl logs -n ark deployment/ark-api
kubectl logs -n ark-system deployment/ark-controller

Kubeconfig issues with Kind

If kubectl/helm can't reach the cluster API server (connection refused or hostname not found):

# Get the control plane IP and reconfigure kubeconfig
CONTROL_PLANE_IP=$(docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' ark-cluster-control-plane)
kind get kubeconfig --name ark-cluster --internal | sed "s/ark-cluster-control-plane/$CONTROL_PLANE_IP/g" > ~/.kube/config

# Verify the server address is an IP, not 127.0.0.1 or a hostname
kubectl config view --minify | grep server
# Should show: server: https://172.x.x.x:6443

Working with Ark

Once Ark is running:

kubectl apply -f samples/agents/my-agent.yaml

kubectl get agents
kubectl get queries
kubectl get teams

kubectl describe agent <agent-name>

Phoenix Telemetry

Install Phoenix for OpenTelemetry tracing:

node tools/ark-cli/dist/index.js install marketplace/services/phoenix

Access dashboard:

kubectl port-forward -n phoenix svc/phoenix-svc 6006:6006
# Open http://localhost:6006

Important

DO NOT usescripts/quickstart.sh - it is deprecated. Always use ark-cli as described above.

DO NOT usenpm install -g @agents-at-scale/ark - always build ark-cli from source to match the PR code being tested.

Weekly Installs

–

Repository

mckinsey/agents…cale-ark

GitHub Stars

360

First Seen

–

Security Audits

Gen Agent Trust HubFail SocketPass SnykWarn