Argocd

ArgoCD MCP 服务

一个用于将 ArgoCD GitOps 持续交付工具集成到 GenAI 应用中的模型上下文协议（MCP）服务，可实现智能 Kubernetes 部署管理。

功能特性

• 全面覆盖 ArgoCD API：

  • 应用管理：创建、同步、删除和回滚应用
  • 项目管理：配置项目、角色和策略
  • 仓库管理：添加/移除 Git 仓库和 Helm chart
  • 集群管理：注册和管理 Kubernetes 集群
  • 同步操作：手动/自动同步、同步窗口和钩子
  • 健康监控：应用健康状况、同步状态和资源树
  • RBAC 管理：用户、角色、策略和 JWT 令牌
  • GitOps 工作流：从 Git 提交自动部署
  • 多租户：命名空间隔离和项目限制
  • 应用集：基于模板的多集群部署

• 身份验证方式：

  • JWT 令牌身份验证
  • API 令牌身份验证
  • OIDC/OAuth2 集成
  • 支持 LDAP 身份验证

• 企业级功能：

  • 多集群支持
  • 灾难恢复工作流
  • 渐进式交付（Canary、Blue-Green）
  • 故障时自动回滚
  • 审计日志和合规性
  • 资源优化
  • 密钥管理集成

安装

pip install argocd-mcp-server

或从源码安装：

git clone https://github.com/asklokesh/argocd-mcp-server.git
cd argocd-mcp-server
pip install -e .

配置

创建 .env 文件或设置环境变量：

# ArgoCD Connection
ARGOCD_SERVER=argocd.example.com
ARGOCD_AUTH_TOKEN=your_auth_token
ARGOCD_INSECURE=false

# Optional Settings
ARGOCD_GRPC_WEB=true
ARGOCD_TIMEOUT=30
ARGOCD_CLIENT_CERT=/path/to/cert.pem
ARGOCD_CLIENT_KEY=/path/to/key.pem

# Multi-Cluster Support
ARGOCD_PROD_SERVER=argocd-prod.example.com
ARGOCD_PROD_TOKEN=prod_token

ARGOCD_DEV_SERVER=argocd-dev.example.com
ARGOCD_DEV_TOKEN=dev_token

快速开始

基本用法

from argocd_mcp import ArgoCDMCPServer

# Initialize the server
server = ArgoCDMCPServer()

# Start the server
server.start()

Claude Desktop 配置

添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "argocd": {
      "command": "python",
      "args": ["-m", "argocd_mcp.server"],
      "env": {
        "ARGOCD_SERVER": "argocd.example.com",
        "ARGOCD_AUTH_TOKEN": "your_auth_token"
      }
    }
  }
}

可用工具

应用管理

列出应用

{
  "tool": "argocd_list_applications",
  "arguments": {
    "project": "default",
    "namespace": "argocd"
  }
}

创建应用

{
  "tool": "argocd_create_application",
  "arguments": {
    "name": "my-app",
    "project": "default",
    "source": {
      "repoURL": "https://github.com/org/repo.git",
      "path": "manifests",
      "targetRevision": "main"
    },
    "destination": {
      "server": "https://kubernetes.default.svc",
      "namespace": "production"
    },
    "syncPolicy": {
      "automated": {
        "prune": true,
        "selfHeal": true
      }
    }
  }
}

同步应用

{
  "tool": "argocd_sync_application",
  "arguments": {
    "name": "my-app",
    "prune": true,
    "force": false,
    "strategy": {
      "hook": {
        "force": true
      }
    }
  }
}

获取应用状态

{
  "tool": "argocd_get_application_status",
  "arguments": {
    "name": "my-app",
    "refresh": true
  }
}

回滚应用

{
  "tool": "argocd_rollback_application",
  "arguments": {
    "name": "my-app",
    "revision": "abc123"
  }
}

项目管理

创建项目

{
  "tool": "argocd_create_project",
  "arguments": {
    "name": "production",
    "description": "Production applications",
    "sourceRepos": ["https://github.com/org/*"],
    "destinations": [
      {
        "server": "https://kubernetes.default.svc",
        "namespace": "prod-*"
      }
    ],
    "clusterResourceWhitelist": [
      {"group": "*", "kind": "*"}
    ]
  }
}

仓库管理

添加仓库

{
  "tool": "argocd_add_repository",
  "arguments": {
    "url": "https://github.com/org/repo.git",
    "name": "my-repo",
    "type": "git",
    "username": "git-user",
    "password": "git-token",
    "insecure": false
  }
}

添加 Helm 仓库

{
  "tool": "argocd_add_helm_repository",
  "arguments": {
    "url": "https://charts.example.com",
    "name": "my-charts",
    "type": "helm",
    "username": "helm-user",
    "password": "helm-password"
  }
}

集群管理

添加集群

{
  "tool": "argocd_add_cluster",
  "arguments": {
    "name": "production-cluster",
    "server": "https://k8s-prod.example.com",
    "config": {
      "bearerToken": "cluster-token",
      "tlsClientConfig": {
        "insecure": false,
        "caData": "base64-encoded-ca"
      }
    }
  }
}

Application Sets

创建 ApplicationSet

{
  "tool": "argocd_create_applicationset",
  "arguments": {
    "name": "multi-cluster-app",
    "generators": [
      {
        "clusters": {},
        "selector": {
          "matchLabels": {
            "environment": "production"
          }
        }
      }
    ],
    "template": {
      "metadata": {
        "name": "{{cluster}}-app"
      },
      "spec": {
        "project": "default",
        "source": {
          "repoURL": "https://github.com/org/repo.git",
          "path": "{{cluster}}"
        },
        "destination": {
          "server": "{{server}}",
          "namespace": "default"
        }
      }
    }
  }
}

健康状况与监控

获取应用健康状况

{
  "tool": "argocd_get_application_health",
  "arguments": {
    "name": "my-app"
  }
}

获取资源树

{
  "tool": "argocd_get_resource_tree",
  "arguments": {
    "name": "my-app"
  }
}

高级配置

多集群 GitOps

from argocd_mcp import ArgoCDMCPServer, ClusterConfig

# Configure multiple ArgoCD instances
clusters = {
    "production": ClusterConfig(
        server="argocd-prod.example.com",
        auth_token="prod_token",
        default_namespace="argocd"
    ),
    "staging": ClusterConfig(
        server="argocd-staging.example.com",
        auth_token="staging_token",
        default_namespace="argocd-staging"
    ),
    "development": ClusterConfig(
        server="argocd-dev.example.com",
        auth_token="dev_token",
        default_namespace="argocd-dev"
    )
}

server = ArgoCDMCPServer(clusters=clusters, default_cluster="production")

渐进式交付

# Configure progressive delivery strategies
progressive_config = {
    "canary": {
        "steps": [
            {"setWeight": 10},
            {"pause": {"duration": "5m"}},
            {"setWeight": 30},
            {"pause": {"duration": "5m"}},
            {"setWeight": 50},
            {"pause": {"duration": "5m"}},
            {"setWeight": 100}
        ]
    },
    "blueGreen": {
        "activeService": "app-active",
        "previewService": "app-preview",
        "autoPromotionEnabled": false
    }
}

server = ArgoCDMCPServer(progressive_config=progressive_config)

灾难恢复

from argocd_mcp import ArgoCDMCPServer, DisasterRecoveryConfig

dr_config = DisasterRecoveryConfig(
    backup_enabled=True,
    backup_schedule="0 2 * * *",  # Daily at 2 AM
    backup_location="s3://backups/argocd",
    restore_priority=["production", "staging", "development"]
)

server = ArgoCDMCPServer(dr_config=dr_config)

集成示例

完整的集成示例请参见 examples/ 目录：

• basic_gitops.py - 基本 GitOps 工作流
• multi_cluster_deployment.py - 多集群应用部署
• progressive_delivery.py - 金丝雀和蓝绿部署
• disaster_recovery.py - 备份与恢复工作流
• genai_gitops.py - AI 驱动的 GitOps 自动化
• security_scanning.py - 与安全工具集成

安全最佳实践

1. 使用权限最小化的服务账户
2. 通过适当的策略启用 RBAC
3. 实施网络策略以隔离集群
4. 使用 sealed secrets 或外部密钥操作器
5. 启用审计日志以满足合规要求
6. 实施准入控制器以强制执行策略
7. 定期扫描镜像和清单的安全性

错误处理

该服务会提供详细的错误信息：

try:
    result = server.execute_tool("argocd_sync_application", {
        "name": "my-app"
    })
except ArgoCDError as e:
    print(f"ArgoCD error: {e.error_code} - {e.message}")
    if e.error_code == "OutOfSync":
        print("Application is out of sync")
    elif e.error_code == "ComparisonError":
        print("Error comparing application state")

性能优化

1. 对类似应用使用 application sets
2. 在 ArgoCD 中启用资源缓存
3. 实施同步窗口以控制部署时间
4. 使用 Webhook 通知代替轮询
5. 使用 Helm/Kustomize 优化清单生成

故障排除

常见问题

1. 同步失败

   • 检查应用日志
   • 验证仓库访问权限
   • 查看资源配额

2. 身份验证错误

   • 验证令牌有效性
   • 检查 RBAC 策略
   • 查看服务连接情况

3. 性能问题

   • 检查 ArgoCD 服务资源
   • 查看应用数量
   • 优化清单大小

贡献

欢迎贡献！请阅读我们的贡献指南并提交拉取请求。

许可证

MIT 许可证 - 详情请参见 LICENSE 文件