# 用 Docker 架設 VMware Tanzu Community Edition 的安裝筆記

這幾天我在嘗試 [VMware Tanzu Community Edition](https://tanzu.vmware.com/tanzu/community)，畢竟 VMWare 也是個大廠，現在正在全力衝刺 Kubernetes 市場，我覺得整體上安裝體驗還可以，管理架構也很乾淨，算是非常好上手，文件也寫的不錯。這篇文章是我在實作的過程中的安裝筆記，詳實記錄了一些重要觀念與注意事項。

### 基礎架構

[VMware Tanzu Community Edition](https://tanzu.vmware.com/tanzu/community) (TCE) 是一套由 VMWare 公司推出的 Kubernetes 叢集散佈版本 (Distribution)，除了[開源](https://github.com/vmware-tanzu/community-edition)免費、功能完整、便於管理外，也非常適合拿來當作學習與開發環境。

TCE 本身包含了四個主要的構成要素：

1.  Tanzu CLI
    
    這個 `tanzu` 是 TCE 的命令列管理工具 (CLI)，他有許多**子命令**可以用來管理叢集、應用程式、外掛套件等等。每個**子命令**其實都連結到不同的執行檔，並位於 `${XDG_DATA_HOME}/tanzu-cli` 目錄下，也因此 `tanzu` CLI 從架構上來說，是非常容易的進行擴充的，你可以透過 plugins 進行新增、移除或更新。
    
    > Linux 作業系統環境預設的 `${XDG_DATA_HOME}` 位於 `~/.local/share` 目錄。
    
    ![Tanzu CLI 將子命令分派給 tanzu-cli 目錄下的外掛執行檔](https://stwillblogassets.blob.core.windows.net/files/images/2026/10/external-image-repairs/tanzu-cli-architecture.jpg)
    
    大多數 plugins 都位於 [Tanzu Framework](https://github.com/vmware-tanzu/tanzu-framework/) Repo 下，並共用於多個不同 Tanzu Editions 版本之間。部分 plugins 則位於 [Tanzu Community Edition](https://github.com/vmware-tanzu/community-edition) Repo 下，待社群培育成熟之後，可能會移入 [Tanzu Framework](https://github.com/vmware-tanzu/tanzu-framework/) Repo 底下。不過，即便某些 Plugins 會遷移到 [Tanzu Framework](https://github.com/vmware-tanzu/tanzu-framework/) Repo，基本上是不影響現有 TCE 用戶的！
    
2.  Managed Clusters
    
    你可以使用 `tanzu cluster` 命令建立兩種不同類型的叢集，其中一種叫做 Managed Clusters (受控叢集)，你必須透過 `tanzu management-cluster create` 命令先建立好一個 **Management Cluster** (管理叢集)，才能在這個叢集底下建立**受控叢集**，又稱**工作負載叢集**(Workload Cluster)，事實上這就是實際執行應用程式的叢集環境。基本上 VMWare 官方建議用這種方式來管理叢集，建議在**生產環境**(Production)使用。
    
3.  Unmanaged Clusters
    
    你可以使用 `tanzu cluster` 命令建立兩種不同類型的叢集，另一種就叫做 Unmanaged Clusters (非受控叢集)，你必須透過 `tanzu unmanaged-cluster create` 命令直接建立一個叢集，這種叢集只能部署在**單一節點**，主要拿來當作開發測試環境之用。TCE 支援在同一台主機上建立多組**非受控叢集**，管理上十分便利。
    
4.  Package Management
    
    你可以用 `tanzu` CLI 進行**套件管理**(package management)，方便你可以發現、安裝、升級、刪除想要執行在 Tanzu 叢集的軟體。所有的套件皆由 [carvel](https://carvel.dev/) 工具建立，你只要遵循[套件封裝流程](https://github.com/vmware-tanzu/community-edition/blob/main/docs/site/content/docs/edge/designs/package-process.md)(packaging process)即可。套件可以被封裝進一個所謂 package repository，並且可以推送到 [OCI](https://ithelp.ithome.com.tw/articles/10216215) (Open Container Iinitiative) 相容的儲存庫中。
    
    在 Tanzu 叢集中，[kapp-controller](https://carvel.dev/kapp-controller) 會不斷監視 package repositories 的變更 (透過 PackageRepository 這個 [CRD](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) 來宣告)，當叢集被告知有新的版本 (透過 `tanzu package repository` 命令)，這個 [kapp-controller](https://carvel.dev/kapp-controller) 就會拉取這個 package repository 回來，讓這些套件可以使用在叢集內。
    
    ![kapp-controller 監看 PackageRepository，從 OCI repository bundle 建立 Package 資源](https://stwillblogassets.blob.core.windows.net/files/images/2026/10/external-image-repairs/tanzu-package-repository.jpg)
    
    你可以透過 `tanzu package install` 命令建立一個 `PackageInstall` (CRD) 資源，[kapp-controller](https://carvel.dev/kapp-controller) 就會幫你下載並安裝到叢集中。
    
    ![tanzu package install 建立 PackageInstall，由 kapp-controller 下載套件並建立 Kubernetes 資源](https://stwillblogassets.blob.core.windows.net/files/images/2026/10/external-image-repairs/tanzu-package-install.png)
    
    > 注意：若你安裝 Tanzu Community Edition (TCE) 的 **Unmanaged Clusters** 的話，預設會幫你安裝好 `tkg-core-repository` 這個 package repository (官網文件是寫 `tce-repo` 這個名稱，應該是文件沒有更新到)。若你安裝的是 **Managed Clusters** 的話，就要額外安裝 package repository 才行！
    

### 安裝 Unmanaged Clusters 非受控叢集

這裡我以 Windows 作業系統平台為例進行示範，安裝步驟如下：

1.  先安裝 [Docker Desktop for Windows](https://www.docker.com/get-started)
    
2.  透過 Chocolatey 安裝 `tanzu` CLI 工具
    
    ```bash
    choco install tanzu-community-edition -y
    ```
    
3.  建立一個名為 `beepboop` 的非受控叢集 (Unmanaged Clusters)
    
    TCE 可以在同一台電腦建立多個叢集，用以區分不同的開發環境，相當便利。建立一個叢集的命令也非常簡單，一個命令就可以完成：
    
    ```bash
    tanzu unmanaged-cluster create beepboop --cni=calico
    ```
    
    > 注意：**Docker for Windows** 需要特別加上 `--cni=calico` 才能順利建立完整的叢集，否則網路部分會出問題！
    
    你也可以用 `uc` 當成 `unmanaged-cluster` 的縮寫：
    
    ```bash
    tanzu uc create beepboop --cni=calico
    ```
    
    > 注意: 整個叢集都會安裝在 Docker 環境下，不會污染 Windows 目前環境。
    
    若要在日後切換不同的 Unmanaged Clusters 叢集，只要用 `kubectl config use-context kind-<CLUSTER-NAME>` 即可：
    
    ```bash
    kubectl config use-context kind-beepboop
    ```
    
4.  安裝 [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) 工具
    
    ```bash
    choco install kubernetes-cli -y
    ```
    
    你可以用以下命令查詢已安裝版本：
    
    ```bash
    kubectl version --short
    ```
    
5.  管理套件
    
    Tanzu Community Edition (TCE) 的 Unmanaged Clusters 在安裝好之後，預設就會先安裝好名為 `tkg-core-repository` 的 package repository，你可以用以下命令列出現有的 package repository 清單：
    
    ```bash
    tanzu package repository list --all-namespaces
    ```
    
    將內建的 `tkg-core-repository` 套件儲存庫更新到最新版 (**重要**)
    
    ```bash
    tanzu package repository update tkg-core-repository --url projects.registry.vmware.com/tce/main -n tanzu-package-repo-global
    ```
    
    列出所有可安裝的套件：
    
    ```bash
    tanzu package available list
    ```
    
    列出 `cert-manager.community.tanzu.vmware.com` 套件版本：
    
    ```bash
    tanzu package available list cert-manager.community.tanzu.vmware.com
    ```
    
    安裝 `1.6.1` 版的 `cert-manager` 套件：
    
    ```bash
    tanzu package install cert-manager --package-name cert-manager.community.tanzu.vmware.com --version 1.6.1
    ```
    
    確認已安裝的套件清單：
    
    ```bash
    tanzu package installed list
    ```
    
    刪除 `cert-manager` 套件：
    
    ```bash
    tanzu package installed delete cert-manager
    ```
    
6.  刪除叢集
    
    列出 Unmanaged Cluster 非受控叢集清單
    
    ```bash
    tanzu unmanaged-cluster list
    ```
    
    刪除叢集
    
    ```bash
    tanzu unmanaged-cluster delete beepboop
    ```
    

> 更完整的命令請參考 [Unmanaged Clusters Reference](https://github.com/vmware-tanzu/community-edition/blob/main/docs/site/content/docs/edge/ref-unmanaged-cluster.md) 官網文件。

### 安裝 Managed Clusters 受控叢集

受控叢集的安裝步驟就複雜的多，完整流程請參考 [Getting Started with Managed Clusters](https://github.com/vmware-tanzu/community-edition/blob/main/docs/site/content/docs/edge/getting-started.md) 官網文件。

這裡最重要的觀念，就是你要先建立 `1` 個 **Management Clusters** (管理叢集)，然後再透過這個 **Management Clusters** 安裝 `N` 個**工作負載叢集**(Workload Clusters)，所有應用程式都應該安裝到**工作負載叢集**之中。

你要先在本機安裝一個「啟動叢集」(bootstrap cluster)，基本上該叢集是一套以 Kind 為基礎的 Kubernetes 叢集，而且完全跑在 Docker 容器中，你可以透過該叢集來安裝一個「管理叢集」到你指定的目標提供者，目前有支援 Docker, VMware vSphere, Amazon Web Services 與 Microsoft Azure 等等。當「管理叢集」安裝完成後，「啟動叢集」就可以刪除了！

這裡我以 Linux 作業系統平台為例進行示範，搭配 [Multipass](https://multipass.run) 快速建立 Ubuntu 虛擬機器，安裝步驟如下：

1.  使用 [Multipass](https://multipass.run/) 建立名為 `tanzu` 虛擬機器 (VM)
    
    建立 [VMware Tanzu](https://github.com/vmware-tanzu/community-edition) 最好要有 **4 CPUs** 與 **6GB RAM** 以上，我這邊加上 `--bridged` 參數是為了讓我可以直接從我的區域網路直接連上這台虛擬機器。
    
    ```powershell
    multipass launch --name 'tanzu' --bridged --disk 50G --cpus 4 --mem 6G
    ```
    
    虛擬機器建立完成後就可以直接連進去 Shell 環境進行安裝：
    
    ```bash
    multipass shell 'tanzu'
    ```
    
2.  下載 `tanzu` CLI 工具
    
    ```bash
    wget https://github.com/vmware-tanzu/community-edition/releases/download/v0.10.0/tce-linux-amd64-v0.10.0.tar.gz
    tar zxvf tce-linux-amd64-v0.10.0.tar.gz
    cd tce-linux-amd64-v0.10.0/
    ./install.sh
    tanzu version
    ```
    
    這是我本次安裝的 `tanzu` CLI 版本資訊：
    
    ```
    version: v0.10.1
    buildDate: 2022-02-14
    sha: 401d55b
    ```
    
3.  安裝 Kubectl 工具
    
    因為我知道 `tanzu` CLI 會建立 `v1.21.5` 的 Kubernetes 叢集，所以我才預先安裝好 `v1.21.5` 版本的 `kubectl` 工具。
    
    ```bash
    curl -LO https://dl.k8s.io/release/v1.21.5/bin/linux/amd64/kubectl
    sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
    kubectl version --short --client
    rm -f kubectl
    ```
    
4.  安裝 [Docker Engine](https://www.docker.com/get-started)
    
    ```bash
    sudo apt update && sudo apt install docker.io -y && sudo usermod -a -G docker ubuntu
    ```
    
    這裡的 `sudo usermod -a -G docker ubuntu` 命令，是為了讓 `non-root` 身份也可以順利執行 `docker` 命令，但設定完之後記得**要登出再重新登入**，所以需要執行 `exit` 先退出 Shell 環境。
    
5.  這次重新登入 `tanzu` 虛擬機器要用 SSH 並啟用 Port Forwarding 功能 (Port `8080`)
    
    假設我們 VM 的 IP 地址為 `192.168.1.13`（預設 Multipass 建立的 VM 預設登入帳號為 `ubuntu`）
    
    ```bash
    ssh -i C:\Windows\System32\config\systemprofile\AppData\Roaming\multipassd\ssh-keys\id_rsa -L 8080:localhost:8080 -L 17777:localhost:7777 ubuntu@192.168.1.13
    ```
    
    > Port `8080` 是給 TCE 安裝介面用的，而 Port `17777` 則是給 [octant](https://github.com/vmware-tanzu/octant) 儀表版用的。
    
6.  安裝管理叢集 (Management Cluster)
    
    啟動一個 Tanzu Community Edition 安裝介面 (Web UI)，並監聽 `8080` Port：
    
    ```bash
    tanzu management-cluster create --ui -b 0.0.0.0:8080
    ```
    
    啟動之後，就可以在本機電腦開啟 [http://localhost:8080/](http://localhost:8080/) 網頁，這是一個 Web 介面的 Tanzu Community Edition (TCE) 的安裝程式。由於我打算在本機安裝 VMware Tanzu，因此請選擇 Docker 來部署：
    
    ![image](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/bf54d107d69078f7383d-156009918-8d0a23cd-475e-4596-9113-dc04ef5dc1be.png)
    
    這裡只需要設定管理叢集名稱 `tanzumgmt` 與 Kubernetes 的網路相關設定：
    
    ![image](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/995b116b2b3101567e04-158031863-75f4e40c-a22b-4364-b6ea-2c573ae97190.png)
    
    確認設定後就可以按下 **DEPLOY MANAGEMENT CLUSTER** 進行全自動安裝，必要時你可以按 **EXPORT CONFIGURATION** 匯出設定檔，日後可以用 CLI 自動安裝出完全相同的管理叢集。
    
    ![image](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/9e9f18beff978539cae0-158031898-d6118631-4a78-4eef-8517-749f8eae5d17.png)
    
    ![image](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/c2aad212b30897a27d70-158032200-dd3ca9fd-34ff-4ef2-9140-a22d450ea5a3.png)
    
    除了透過 Web UI 進行安裝外，你也可以使用 CLI 進行更簡便快速的安裝：
    
    ```bash
    tanzu management-cluster create -i docker --name 'tanzumgmt' -v 10 --plan dev --ceip-participation=false
    ```
    
    安裝完成之後，可以在 Shell 底下執行以下命令，確認管理叢集已經順利啟動：
    
    ```bash
    tanzu management-cluster get
    ```
    
    ![image](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/bcbe0ccfc22cff0cebf9-158032287-8cdc0c4d-c34c-48e3-82df-b1b8c9dafe77.png)
    
    由於 Management Cluster 也是一個 Kubernetes 叢集，因此你可以用以下命令取得該叢集的 `KUBECONFIG` 憑證：
    
    ```bash
    tanzu management-cluster kubeconfig get tanzumgmt --admin
    ```
    
    切換 KUBECONFIG 到管理叢集：
    
    ```bash
    kubectl config get-contexts
    kubectl config use-context tanzumgmt-admin@tanzumgmt
    kubectl get nodes
    ```
    
    ![image](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/81654800cd3abb5bcc0e-158032264-fc5f87a0-4f01-4512-b9a8-b1d8e658a12b.png)
    
    確認已經有 Nodes 成功運行：
    
    ```bash
    kubectl get nodes
    ```
    

接著我們就要來安裝**工作負載叢集**(Workload Cluster)了！

1.  建立一個**工作負載叢集**，假設名稱為 `dev1`
    
    ```bash
    tanzu cluster create 'dev1' --plan dev
    ```
    
2.  確認**工作負載叢集**已安裝完畢，並取得**工作負載叢集**的 `KUBECONFIG` 憑證
    
    ```bash
    tanzu cluster list
    ```
    
    ![image](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/241ff81c3857cdd9dd6d-158032500-fdd101a3-ead6-4d9a-bd3b-1446271d10ba.png)
    
    取得**工作負載叢集**的 `KUBECONFIG` 憑證
    
    ```bash
    tanzu cluster kubeconfig get 'dev1' --admin
    ```
    
    切換到工作負載叢集：
    
    ```bash
    kubectl config use-context 'dev1-admin@dev1'
    ```
    
3.  查看叢集內所有的 Pods
    
    ```bash
    kubectl get pods -A
    ```
    
    ![image](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/f89d8422108e85ea2f8d-158032530-894f0b75-6bd1-4500-aa22-6042cb8fa401.png)
    
4.  查看 Docker Engine 運行的容器
    
    此時應該會有 `1` 個管理叢集與 `1` 個工作負載叢集，且各有 `1` 個 control plane node 與 `1` 個 worker node。而且兩座叢集各有一個 `haproxy` 容器，可以讓日後 control plane 加入 HA (高可用) 的設定！
    
    ```bash
    docker ps -a --format="table {{.ID}}\t{{.Names}}\t{{.Image}}\t{{.Status}}"
    ```
    
    ![image](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/feff16f12a2b90f9b3d4-158032683-086cc624-e49e-4ac1-8019-0d952b3dd656.png)
    
    你可以直接進入 control plane node 試看看 kubectl 命令 (Continer ID 為 `dea`)：
    
    ```bash
    docker exec -it 'dea' /bin/bash
    ```
    
    或是用 Container 的 **Label** 直接選到 control plane 節點：
    
    ```bash
    docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Labels}}\t{{.Status}}"
    docker exec -it $(docker ps --filter 'label=io.x-k8s.kind.cluster=dev1' --filter 'label=io.x-k8s.kind.role=control-plane' --format "{{.ID}}") /bin/bash
    ```
    
    ```bash
    kubectl --kubeconfig=/etc/kubernetes/admin.conf get nodes
    ```
    
    ![image](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/e0a63224a0ef5eb746ee-158032827-23180c8e-d943-46ff-998b-b2964d909a2f.png)
    
    > 截至今日為止，TCE 安裝好之後，若 Docker 所在的主機重開，叢集會需要重建！這個議題已有 [#832](https://github.com/vmware-tanzu/community-edition/issues/832) 進行追蹤。
    
5.  管理套件
    
    切換到工作負載叢集：
    
    ```bash
    kubectl config use-context 'dev1-admin@dev1'
    ```
    
    安裝 Tanzu Community Edition 官方提供的 `tce-repo` package repository 到 `tanzu-package-repo-global` namespace
    
    ```bash
    tanzu package repository add tce-repo --url projects.registry.vmware.com/tce/main:0.10.0 --namespace tanzu-package-repo-global
    ```
    
    > 注意: 安裝到 `tanzu-package-repo-global` namespace 的 package repository 預設會套用到整座 Kubernetes 叢集。但你也可以在個別的 namespace 安裝不同的 package repository！
    
    將內建的 `tkg-core-repository` 套件儲存庫更新到最新版 (**重要**)
    
    ```bash
    tanzu package repository update tkg-core-repository --url projects.registry.vmware.com/tce/main -n tanzu-package-repo-global
    ```
    
    列出已安裝的 package repository
    
    ```bash
    tanzu package repository list --namespace tanzu-package-repo-global
    ```
    
    列出所有可安裝的套件：
    
    ```bash
    tanzu package available list
    ```
    
    列出 `cert-manager.community.tanzu.vmware.com` 套件版本：
    
    ```bash
    tanzu package available list cert-manager.community.tanzu.vmware.com
    ```
    
    安裝 `1.6.1` 版的 `cert-manager` 套件到 `cert-manager` namespace：
    
    ```bash
    tanzu package install cert-manager --package-name cert-manager.community.tanzu.vmware.com --version 1.6.1
    ```
    
    確認已安裝的套件清單：
    
    ```bash
    tanzu package installed list
    ```
    
    刪除 `cert-manager` 套件：
    
    ```bash
    tanzu package installed delete cert-manager
    ```
    
6.  安裝精美的 [octant](https://github.com/vmware-tanzu/octant) 儀表版 (Dashboard)
    
    從 [https://github.com/vmware-tanzu/octant/releases](https://github.com/vmware-tanzu/octant/releases) 找到最新版 (`octant_0.25.1_Linux-64bit.tar.gz`) 進行安裝：
    
    ```bash
    curl -LO https://github.com/vmware-tanzu/octant/releases/download/v0.25.1/octant_0.25.1_Linux-64bit.tar.gz
    tar -xzvf octant_0.25.1_Linux-64bit.tar.gz
    ./octant_0.25.1_Linux-64bit/octant
    ```
    
    在本機連結 [http://localhost:17777/](http://localhost:17777/) 即可進入管理介面！
    
    ![image](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/27fdbc93829efea2ae5d-158033442-3b31edc2-6759-40dd-83ee-9079ca064c66.png)
    
7.  刪除叢集
    
    刪除工作負載叢集
    
    ```bash
    tanzu cluster delete 'dev1'
    ```
    
    刪除管理叢集
    
    ```bash
    tanzu management-cluster get
    tanzu management-cluster delete 'tanzumgmt'
    ```
    
8.  刪除 Multipass 建立的虛擬機器
    
    ```powershell
    multipass delete 'tanzu' ; multipass purge
    ```
    

### 相關連結

-   [Kubernetes Platform Documentation | Tanzu Community Edition](https://github.com/vmware-tanzu/community-edition/tree/main/docs/site/content/docs/edge)
    -   [Planning Your Installation](https://github.com/vmware-tanzu/community-edition/blob/main/docs/site/content/docs/edge/installation-planning.md)
    -   [Install Tanzu Community Edition](https://github.com/vmware-tanzu/community-edition/blob/main/docs/site/content/docs/edge/cli-installation.md)
    -   [Docker](https://github.com/vmware-tanzu/community-edition/blob/main/docs/site/content/docs/edge/docker-intro.md)
    -   [Deploy a Management Cluster to Docker](https://github.com/vmware-tanzu/community-edition/blob/main/docs/site/content/docs/edge/docker-install-mgmt.md)
    -   [Examine the Management Cluster Deployment](https://github.com/vmware-tanzu/community-edition/blob/main/docs/site/content/docs/edge/verify-deployment.md)
    -   [Work with Packages](https://github.com/vmware-tanzu/community-edition/blob/main/docs/site/content/docs/edge/package-management.md)
-   [Docker Desktop for Windows does not work with TCE #3527](https://github.com/vmware-tanzu/community-edition/issues/3527)