tiltdev/ctlptl

ctlptl 镜像文档

镜像概述和主要用途

ctlptl（发音为"coddle poodle"）是一个用于声明式设置本地Kubernetes集群的命令行工具。该工具受kubectl和https://github.com/kubernetes-sigs/cluster-api的`clusterctl`启发，允许用户通过YAML声明本地集群配置，并使用`ctlptl`命令进行集群管理。

此Docker镜像特别适用于在CI环境中快速设置一次性使用的Kubernetes集群。

核心功能和特性

• 声明式集群管理：通过YAML配置文件定义集群状态
• 多集群支持：可同时管理多个本地Kubernetes集群
• 与kubectl集成：自动设置当前kubectl上下文
• 集群生命周期管理：创建、查询、更新和删除集群
• 注册表集成：支持与容器注册表集成，便于本地镜像测试

使用场景和适用范围

• CI/CD流水线中的自动化测试环境
• 本地Kubernetes应用开发和调试
• 多集群部署测试
• 培训和演示环境的快速搭建
• 临时开发环境的创建与清理

详细使用方法和配置说明

基本命令

ctlptl支持以下核心命令：

• ctlptl get：查看所有运行中的集群
• ctlptl create cluster [product]：创建集群并设为当前kubectl上下文
• ctlptl apply -f <cluster.yaml>：确保集群按配置存在，不存在则创建
• ctlptl delete -f <cluster.yaml>：删除集群及其状态

配置示例

KIND集群与内置注册表

直接创建集群：

bash
ctlptl create cluster kind --registry=ctlptl-registry

通过配置文件确保集群存在：

bash
cat <<EOF | ctlptl apply -f -
apiVersion: ctlptl.dev/v1alpha1
kind: Cluster
product: kind
registry: ctlptl-registry
EOF

集群配置文件格式

集群配置文件使用YAML格式，基本结构如下：

yaml
apiVersion: ctlptl.dev/v1alpha1
kind: Cluster
product: <集群产品名称，如kind>
registry: <注册表名称>

Docker部署方案示例

在CI环境中使用ctlptl镜像

基本docker run命令

bash
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock docker.xuanyuan.run/ctlptl/ctlptl get

在CI管道中创建KIND集群

bash
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  -v $HOME/.kube:/root/.kube \
  docker.xuanyuan.run/ctlptl/ctlptl create cluster kind --registry=ctlptl-registry

使用docker-compose配置

yaml
version: '3'
services:
  ctlptl:
    image: docker.xuanyuan.run/ctlptl/ctlptl
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./.kube:/root/.kube
    command: apply -f /config/cluster.yaml
    volumes:
      - ./cluster-config:/config

配置参数说明

集群配置参数

常见问题

如何验证集群是否成功创建？

创建集群后，可以使用以下命令验证：

bash
kubectl get nodes

或

bash
ctlptl get clusters

如何在CI环境中清理集群资源？

可以使用以下命令删除集群：

bash
ctlptl delete -f cluster.yaml