ctlptl

ctlptl 是一個用於聲明性地設置本地 Kubernetes 集羣的 CLI。通過x-cmd一鍵安裝，即刻體驗高效工作流程。

Language	Go
Homepage	https://github.com/tilt-dev/ctlptl

x install ctlptl

/asdf

x asdf use ctlptl

ctlptl - 聲明式管理本地 Kubernetes 集羣

本地開發和測試 Kubernetes 應用時，搭建集羣環境往往是第一道門檻。KIND、Minikube、k3d、Docker Desktop... 選擇很多，但每個工具都有自己的一套命令和配置方式，切換起來相當麻煩。更頭疼的是，當你需要在團隊中共享一套標準化的本地環境配置時，口頭傳達或文檔説明總是容易出錯。

ctlptl（發音 "cattle patrol"）就是為了解決這個問題而生的。它由 Tilt 團隊開發，借鑑了 kubectl 和 Cluster API 的 clusterctl 的設計理念，讓你用聲明式 YAML 配置來統一管理本地 Kubernetes 集羣——不管是哪種底層實現。

核心能力：一把鑰匙開多把鎖

ctlptl 的定位很清晰：不替代任何本地集羣工具，而是統一它們的操作接口。它支持目前主流的本地 K8s 方案：

支持的平台	特點
Docker Desktop	Mac/Windows 原生支持，集成度高
KIND	在 Docker 中運行 K8s，輕量快速
Minikube	功能最全面，驅動支持豐富
k3d	k3s 的容器化版本，資源佔用極低

使用 ctlptl，你可以用同一套命令和配置語法來管理這些不同的集羣，無需記憶每個工具特有的參數。

聲明式配置：像管理 Pod 一樣管理集羣

ctlptl 的核心是聲明式理念。你定義"想要什麼"，ctlptl 負責"讓現實符合期望"。

最小配置示例：

apiVersion: ctlptl.dev/v1alpha1
kind: Cluster
product: kind

這條配置表示：確保一個 KIND 集羣存在。如果已經存在，什麼都不做；如果不存在，創建一個。

帶鏡像倉庫的完整配置：

apiVersion: ctlptl.dev/v1alpha1
kind: Registry
name: ctlptl-registry
port: 5005
---
apiVersion: ctlptl.dev/v1alpha1
kind: Cluster
product: kind
registry: ctlptl-registry

這個配置會先創建一個本地鏡像倉庫，然後創建 KIND 集羣並自動配置好倉庫集成——這在本地開發中非常實用，可以直接把鏡像推送到本地倉庫，無需處理複雜的認證和地址問題。

四大核心命令

ctlptl 的命令設計非常精簡，只有四個主要操作：

命令	功能
ctlptl get	查看所有運行中的本地集羣
ctlptl create cluster <product>	創建集羣並設為當前 kubectl 上下文
ctlptl apply -f cluster.yaml	根據 YAML 聲明確保集羣狀態
ctlptl delete -f cluster.yaml	刪除集羣及其狀態

查看現有集羣：

ctlptl get clusters

快速創建集羣：

# Docker Desktop，指定 4 CPU
ctlptl create cluster docker-desktop --min-cpus=4

# KIND，帶內置倉庫（隨機端口）
ctlptl create cluster kind --registry=ctlptl-registry

# Minikube，指定 K8s 版本
ctlptl create cluster minikube --kubernetes-version=v1.28.0

聲明式創建（推薦用於團隊協作）：

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

鏡像倉庫集成：本地開發的痛點解決者

本地 K8s 開發最大的麻煩之一就是鏡像管理。你需要：

1. 搭建本地倉庫
2. 配置集羣使用這個倉庫
3. 讓 kubelet 能夠拉取鏡像

ctlptl 把這個過程自動化了。以 KIND 為例：

# 一步創建帶倉庫的集羣
ctlptl create cluster kind --registry=ctlptl-registry

# 獲取倉庫地址用於推送鏡像
ctlptl get cluster kind-kind -o template --template '{{.status.localRegistryHosting.host}}'

輸出類似 localhost:12345 的地址，直接用這個地址給鏡像打標籤並推送即可。集羣內的 Pod 可以無感知地拉取這些鏡像。

如果你需要固定端口（比如 CI 環境）：

# 先創建指定端口的倉庫
ctlptl create registry ctlptl-registry --port=5005

# 再創建關聯的集羣
ctlptl create cluster kind --registry=ctlptl-registry

或使用 YAML 聲明：

apiVersion: ctlptl.dev/v1alpha1
kind: Registry
name: ctlptl-registry
port: 5005
---
apiVersion: ctlptl.dev/v1alpha1
kind: Cluster
product: kind
registry: ctlptl-registry

Docker Desktop 的特殊控制

ctlptl 對 Docker Desktop 提供了額外的精細控制，這是其他本地集羣工具沒有的：

# 啓用 Kubernetes 並設置資源
ctlptl docker-desktop open
ctlptl create cluster docker-desktop --min-cpus=4

# 調整 VM 資源（無需重啓 Docker Desktop）
ctlptl docker-desktop set vm.resources.cpus 4
ctlptl docker-desktop set vm.resources.memory 8192

# 關閉 Kubernetes 節省資源
ctlptl docker-desktop set kubernetes.enabled false

# 完全關閉 Docker Desktop
ctlptl docker-desktop quit

這在 Mac 上特別有用——你可以用命令列精確控制 Docker Desktop 的 K8s 功能和資源分配，而不需要手動點開 GUI 設置。

遠程 Docker 主機支持

ctlptl 還支持在遠程 Docker 主機上創建集羣，這在 CI 環境（如 CircleCI）中很實用：

apiVersion: ctlptl.dev/v1alpha1
kind: Cluster
product: kind
registry: ctlptl-registry
---
apiVersion: ctlptl.dev/v1alpha1
kind: Registry
name: ctlptl-registry

配合 DOCKER_HOST 環境變量，你可以在遠程機器上創建本地開發集羣。

配置參數參考

Cluster 資源支持的完整配置：

字段	説明	示例
product	集羣類型（必填）	kind, minikube, k3d, docker-desktop
name	集羣名稱	my-cluster
registry	關聯的鏡像倉庫名稱	ctlptl-registry
minCPUs	最小 CPU 數	4
kubernetesVersion	K8s 版本	v1.28.0

Registry 資源支持的配置：

字段	説明	示例
name	倉庫名稱（必填）	my-registry
port	監聽端口	5005

典型工作流示例

開發團隊標準化環境：

將以下文件保存為 dev-cluster.yaml，放入版本控制：

apiVersion: ctlptl.dev/v1alpha1
kind: Registry
name: dev-registry
port: 5005
---
apiVersion: ctlptl.dev/v1alpha1
kind: Cluster
product: kind
name: dev-cluster
registry: dev-registry

新成員入職時只需執行：

ctlptl apply -f dev-cluster.yaml

就能獲得和其他人完全一致的本地環境。

CI/CD 流水線：

# 創建測試集羣
ctlptl apply -f test-cluster.yaml

# 運行測試...

# 清理
ctlptl delete -f test-cluster.yaml

日常開發切換：

# 查看當前有哪些集羣
ctlptl get clusters

# 切到另一個項目的環境
ctlptl delete -f project-a.yaml
ctlptl apply -f project-b.yaml

隱私説明

ctlptl 默認會發送匿名的使用統計信息用於改進工具。如果你不希望共享這些數據：

ctlptl analytics opt out

與同類工具的關係

工具	定位	與 ctlptl 的關係
kind/minikube/k3d	本地 K8s 集羣實現	ctlptl 調用這些工具，不替代它們
clusterctl	聲明式管理生產集羣	ctlptl 受其啓發，但專注本地環境
Tilt	本地 K8s 開發工作流	ctlptl 是 Tilt 團隊出品，兩者配合良好

ctlptl 的價值在於抽象和統一——它不做任何集羣實現的細節工作，而是把這些工具的優勢整合到一套聲明式接口中。

適合誰用？

• 需要在多種本地集羣方案間切換的開發者：統一的操作體驗，降低心智負擔
• 需要標準化本地開發環境的團隊：用 YAML 定義環境，版本控制，消除"我這能跑"問題
• 頻繁創建/銷燬集羣的 CI/CD 場景：聲明式配置確保環境一致性
• Tilt 用户：同源團隊開發，生態整合良好

如果你厭倦了為每種本地 K8s 工具記憶不同的命令，或者受夠了團隊裏每個人本地環境配置都不一樣，ctlptl 值得一試。它讓本地 Kubernetes 集羣的管理像寫 YAML 一樣簡單——而這正是 Kubernetes 用户最熟悉的方式。

來源：

https://github.com/tilt-dev/ctlptl