tiltdev/ctlptl

ctlptl 镜像文档

镜像概述和主要用途

ctlptl（发音为"coddle poodle"）是一个用于声明式设置本地Kubernetes集群的命令行工具。该工具受kubectl和https://github.com/kubernetes-sigs/cluster-api%E7%9A%84%60clusterctl%60%E5%90%AF%E5%8F%91%EF%BC%8C%E5%85%81%E8%AE%B8%E7%94%A8%E6%88%B7%E9%80%9A%E8%BF%87YAML%E5%A3%B0%E6%98%8E%E6%9C%AC%E5%9C%B0%E9%9B%86%E7%BE%A4%E9%85%8D%E7%BD%AE%EF%BC%8C%E5%B9%B6%E4%BD%BF%E7%94%A8%60ctlptl%60%E5%91%BD%E4%BB%A4%E8%BF%9B%E8%A1%8C%E9%9B%86%E7%BE%A4%E7%AE%A1%E7%90%86%E3%80%82

此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 ctlptl/ctlptl get

在CI管道中创建KIND集群

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

使用docker-compose配置

yaml
version: '3'
services:
  ctlptl:
    image: 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