CAPI集群管理服务镜像文档

1. 镜像概述

本镜像为用于创建和管理Cluster API (CAPI)集群的服务镜像。Cluster API是Kubernetes***提供的集群生命周期管理API，允许用户通过声明式方式定义和管理Kubernetes集群的创建、升级、扩展及删除等全生命周期操作。本镜像封装了CAPI集群管理服务，提供标准化的CAPI集群管理能力。

2. 核心功能与特性

2.1 核心功能

集群创建：支持通过CAPI规范定义的资源对象（如Cluster、Machine等）创建Kubernetes集群
生命周期管理：提供集群升级（Kubernetes版本更新）、节点扩展（增加/减少节点）、集群删除等完整生命周期操作
声明式API支持：兼容Kubernetes声明式API，支持通过YAML配置文件定义集群状态，实现状态驱动的集群管理

2.2 关键特性

CAPI规范兼容：遵循最新CAPI规范（如v1beta1/v1beta2），支持主流基础设施提供商（AWS、Azure、GCP、vSphere等）的CAPI实现
自动化运维：内置集群状态监控与自愈能力，支持异常节点自动替换
多集群管理：支持同时管理多个CAPI集群，提供统一的集群视图与操作入口

3. 使用场景与适用范围

3.1 典型使用场景

Kubernetes集群标准化部署：在企业内部实现统一的Kubernetes集群部署规范
多集群环境管理：针对混合云/多云环境，通过CAPI统一管理跨平台集群
CI/CD流程集成：在应用发布流程中自动创建测试/生产集群，实现环境即服务（EaaS）
集群运维自动化：简化集群升级、节点替换等运维操作，降低人工干预成本

3.2 适用对象

云原生运维工程师
Kubernetes集群管理员
DevOps团队（需自动化集群管理能力）

4. 使用方法与配置说明

4.1 环境要求

Docker引擎版本 ≥ 20.10
网络可访问CAPI管理平面（或Kubernetes集群API服务器，若使用内嵌CAPI控制器）
具备集群管理权限的认证凭证（如kubeconfig文件、云服务商访问密钥等）

4.2 配置参数

4.2.1 环境变量

环境变量名	描述	默认值	是否必填
`CAPI_API_SERVER`	CAPI管理平面API服务器地址（格式：`https://<host>:<port>`）	无	是
`KUBECONFIG_PATH`	用于访问CAPI管理平面的kubeconfig文件路径	`/etc/capi/kubeconfig`	否
`LOG_LEVEL`	日志级别（可选值：debug/info/warn/error）	`info`	否
`CAPI_PROVIDER`	基础设施提供商类型（如`aws`/`azure`/`vsphere`，需匹配目标环境CAPI实现）	无	否
`CLUSTER_NAMESPACE`	CAPI集群资源默认命名空间	`default`	否

4.2.2 数据卷挂载

认证凭证挂载：需将包含kubeconfig文件的目录挂载至容器内KUBECONFIG_PATH指定路径（默认/etc/capi/kubeconfig）
配置文件挂载：自定义CAPI集群模板配置文件可挂载至/etc/capi/templates目录，支持通过模板快速创建集群

4.3 基础操作流程

准备认证凭证（kubeconfig文件）
配置环境变量或挂载配置文件
启动服务容器
通过服务API或命令行工具管理CAPI集群

5. 部署示例

5.1 Docker Run快速启动

bash
docker run -d \
  --name capi-manager \
  -e CAPI_API_SERVER=[***] \
  -e KUBECONFIG_PATH=/etc/capi/kubeconfig \
  -e LOG_LEVEL=info \
  -v /host/path/to/kubeconfig:/etc/capi/kubeconfig \  # 挂载本地kubeconfig文件
  -v /host/path/to/templates:/etc/capi/templates \    # 可选：挂载集群模板
  capi-service:latest

5.2 Docker Compose配置示例

yaml
version: '3.8'
services:
  capi-manager:
    image: capi-service:latest
    container_name: capi-manager
    restart: unless-stopped
    environment:
      - CAPI_API_SERVER=[***]
      - KUBECONFIG_PATH=/etc/capi/kubeconfig
      - LOG_LEVEL=debug
      - CAPI_PROVIDER=aws
      - CLUSTER_NAMESPACE=capi-clusters
    volumes:
      - ./kubeconfig:/etc/capi/kubeconfig:ro  # 只读挂载kubeconfig
      - ./templates:/etc/capi/templates:ro    # 只读挂载集群模板
    ports:
      - "8080:8080"  # 暴露服务API端口（若服务提供HTTP接口）