k3d 集群整体架构文档

AI摘要

本文档系统介绍了k3d（k3s in Docker）集群的架构。k3d是轻量级Kubernetes发行版k3s的Docker封装，用于在容器中快速搭建K8s集群。其核心架构包括控制平面节点（集成API Server、etcd等）、可选工作节点、负责外部访问的LoadBalancer，以及默认集成的Traefik Ingress、CoreDNS等系统组件。所有组件运行于独立的Docker网络与存储卷中，适合开发、测试与学习，但不适用于生产环境。

k3d 集群整体架构文档

本文档详细说明 k3d（k3s in Docker）集群的整体架构，包括各个组件、网络、存储和数据流向。

概述

k3d 是 k3s 的 Docker 包装器，用于在 Docker 容器中运行轻量级的 Kubernetes 集群。k3s 是一个轻量级的 Kubernetes 发行版，专为边缘计算和资源受限环境设计。

k3d 的特点

轻量级：相比完整 Kubernetes 更小，启动更快
单二进制：k3s 打包为单个二进制文件
内置组件：默认包含 Traefik Ingress Controller
Docker 原生：所有组件运行在 Docker 容器中
易于管理：通过 k3d CLI 工具管理集群

整体架构图

完整架构视图


graph TB

    subgraph "Docker Host (宿主机)"

        subgraph "k3d-mycluster Network (Docker Network)"

            subgraph "Control Plane Node"

                SERVER[k3d-mycluster-server-0<br/>k3s Server Container<br/>┌─────────────────────┐<br/>│ API Server          │<br/>│ etcd                │<br/>│ Controller Manager  │<br/>│ Scheduler           │<br/>│ Kubelet             │<br/>│ Kube-proxy          │<br/>└─────────────────────┘]

            end

            subgraph "LoadBalancer"

                LB[k3d-mycluster-lb<br/>LoadBalancer Container<br/>Port Mapping<br/>8000:80<br/>8443:443]

            end

            subgraph "Worker Nodes (Optional)"

                AGENT1[k3d-mycluster-agent-0<br/>Worker Node<br/>Kubelet<br/>Kube-proxy]

                AGENT2[k3d-mycluster-agent-1<br/>Worker Node<br/>Kubelet<br/>Kube-proxy]

            end

            subgraph "System Pods (kube-system)"

                TRAEFIK[Traefik<br/>Ingress Controller<br/>Default in k3d]

                COREDNS[CoreDNS<br/>DNS Server]

                METRICS[Metrics Server<br/>Resource Metrics]

                LOCAL[local-path-provisioner<br/>Storage Provisioner]

            end

            subgraph "Application Pods"

                APP1[Application Pod 1]

                APP2[Application Pod 2]

                APP3[Application Pod 3]

            end

        end

        subgraph "Docker Volumes"

            VOL1[k3d-mycluster-images<br/>Container Images]

            VOL2[k3d-mycluster-data<br/>etcd Data<br/>kubeconfig]

        end

    end

    EXTERNAL[External Access<br/>localhost:8000] --> LB

    LB --> TRAEFIK

    TRAEFIK --> APP1

    TRAEFIK --> APP2

    TRAEFIK --> APP3

    SERVER --> APP1

    SERVER --> APP2

    SERVER --> APP3

    AGENT1 --> APP1

    AGENT2 --> APP2

    SERVER -.->|存储| VOL1

    SERVER -.->|存储| VOL2

    style SERVER fill:#ffcccc

    style LB fill:#ccffcc

    style AGENT1 fill:#ccccff

    style AGENT2 fill:#ccccff

    style TRAEFIK fill:#ffffcc

    style COREDNS fill:#ffccff

    style APP1 fill:#e1f5e1

    style APP2 fill:#e1f5e1

    style APP3 fill:#e1f5e1

简化架构视图


graph LR

    subgraph "Docker Host"

        subgraph "k3d-mycluster"

            SERVER[Server Node<br/>Control Plane]

            LB[LoadBalancer]

            AGENT[Agent Nodes<br/>Workers]

            PODS[Application Pods]

        end

    end

    USER[User] -->|localhost:8000| LB

    LB --> PODS

    SERVER --> PODS

    AGENT --> PODS

    style SERVER fill:#ffcccc

    style LB fill:#ccffcc

    style AGENT fill:#ccccff

    style PODS fill:#e1f5e1

核心组件

1. 控制平面节点 (Control Plane Node)

容器名称: k3d-mycluster-server-0

功能:

运行 k3s server（轻量级 Kubernetes 控制平面）
包含所有 Kubernetes 控制平面组件

组件说明:

| 组件 | 功能 | 说明 |

|——|——|——|

| API Server | Kubernetes API 入口 | 处理所有 API 请求 |

| etcd | 分布式键值存储 | 存储集群状态和配置 |

| Controller Manager | 控制器管理器 | 运行各种控制器（Deployment、Service 等） |

| Scheduler | 调度器 | 将 Pod 调度到合适的节点 |

| Kubelet | 节点代理 | 管理 Pod 生命周期 |

| Kube-proxy | 网络代理 | 实现 Service 的网络转发 |

特点:

默认情况下，server 节点也作为 worker 节点运行 Pod
单节点模式：只有一个 server 节点，同时承担控制平面和工作节点角色

2. 工作节点 (Worker Nodes)

容器名称: k3d-mycluster-agent-0, k3d-mycluster-agent-1, …

功能:

运行应用 Pod
执行 kubelet 和 kube-proxy

创建方式:


# 创建带 2 个 worker 节点的集群

k3d  cluster  create  mycluster  --agents  2

组件:

Kubelet: 与 API Server 通信，管理 Pod
Kube-proxy: 实现 Service 的网络规则

3. LoadBalancer (负载均衡器)

容器名称: k3d-mycluster-lb

功能:

将 Kubernetes LoadBalancer 类型的 Service 映射到宿主机端口
实现外部访问集群内服务

端口映射:


# 创建集群时指定端口映射

k3d  cluster  create  mycluster  --port  "8000:80@loadbalancer"

工作原理:

k3d LoadBalancer 监听宿主机端口（如 8000）
将流量转发到集群内 LoadBalancer 类型的 Service
支持多个端口映射

4. Ingress Controller (Traefik)

默认安装: k3d 默认安装 Traefik 作为 Ingress Controller

命名空间: kube-system

功能:

提供 HTTP/HTTPS 路由
基于域名和路径的路由规则
SSL/TLS 终止

访问方式:

通过 LoadBalancer 暴露（如果配置了端口映射）
或通过 NodePort 访问

5. CoreDNS

命名空间: kube-system

功能:

集群内部 DNS 解析
Service 名称解析
Pod 之间的服务发现

示例:


# 在 Pod 中访问 Service

mysql.default.svc.cluster.local

6. Metrics Server

命名空间: kube-system

功能:

收集节点和 Pod 的资源使用情况
支持 kubectl top 命令
为 HPA（水平 Pod 自动扩缩容）提供数据

注意: k3d 默认可能不包含 metrics-server，需要手动安装

7. Local Path Provisioner

命名空间: kube-system

功能:

提供本地存储卷（Local PersistentVolume）
自动创建和管理 PVC（PersistentVolumeClaim）
适合开发和测试环境

网络架构

Docker 网络

k3d 为每个集群创建一个独立的 Docker 网络：

网络名称: k3d-mycluster

网络类型: Bridge

IP 段: 通常是 172.x.x.x/16

网络组件关系


graph TB

    subgraph "Docker Host Network"

        HOST[宿主机网络<br/>localhost:8000]

    end

    subgraph "k3d-mycluster Network (Bridge)"

        LB[LoadBalancer<br/>172.21.0.2]

        SERVER[Server Node<br/>172.21.0.3]

        AGENT1[Agent Node 1<br/>172.21.0.4]

        AGENT2[Agent Node 2<br/>172.21.0.5]

        subgraph "Pod Network (CNI)"

            POD1[Pod 1<br/>10.42.0.x]

            POD2[Pod 2<br/>10.42.1.x]

            POD3[Pod 3<br/>10.42.2.x]

        end

    end

    HOST -->|端口映射| LB

    LB -->|转发| SERVER

    SERVER -->|调度| POD1

    SERVER -->|调度| POD2

    AGENT1 -->|运行| POD1

    AGENT2 -->|运行| POD2

    SERVER -->|运行| POD3

    style HOST fill:#e1e5f5

    style LB fill:#ccffcc

    style SERVER fill:#ffcccc

    style AGENT1 fill:#ccccff

    style AGENT2 fill:#ccccff

    style POD1 fill:#e1f5e1

    style POD2 fill:#e1f5e1

    style POD3 fill:#e1f5e1

网络层次

宿主机网络层
- 用户通过 localhost:8000 访问
Docker 网络层
- k3d 创建的 Bridge 网络
- 所有容器在此网络中
Pod 网络层（CNI）
- k3d 使用 Flannel 作为 CNI 插件
- Pod 获得独立的 IP 地址（通常是 10.42.x.x/16）
- Pod 之间可以直接通信
Service 网络层
- ClusterIP: 集群内部访问
- NodePort: 通过节点端口访问
- LoadBalancer: 通过 LoadBalancer 访问

查看网络信息


# 查看 Docker 网络

docker  network  ls  | grep  k3d

# 查看网络详情

docker  network  inspect  k3d-mycluster

# 查看容器 IP

docker  inspect  k3d-mycluster-server-0  | grep  IPAddress

# 查看 Pod IP

kubectl  get  pods  -o  wide

存储架构

Docker Volumes

k3d 使用 Docker Volumes 存储集群数据：

Volume 列表:

| Volume 名称 | 用途 | 说明 |

|————|——|——|

| k3d-mycluster-images | 容器镜像 | 存储集群使用的容器镜像 |

| k3d-mycluster-data | 集群数据 | 存储 etcd 数据、kubeconfig 等 |

持久化存储

k3d 使用 local-path-provisioner 提供本地存储：


graph TB

    subgraph "Storage Architecture"

        PVC[PersistentVolumeClaim<br/>申请存储]

        PV[PersistentVolume<br/>local-path-provisioner<br/>自动创建]

        HOST_PATH[宿主机路径<br/>/var/lib/rancher/k3s/storage]

        PVC -->|绑定| PV

        PV -->|挂载| HOST_PATH

    end

    POD[Application Pod] -->|使用| PVC

    style PVC fill:#e1f5e1

    style PV fill:#fff4e1

    style HOST_PATH fill:#ffe1e1

    style POD fill:#e1e5f5

存储类 (StorageClass)

k3d 默认提供 local-path StorageClass：


apiVersion: storage.k8s.io/v1

kind: StorageClass

metadata:

 name: local-path

provisioner: rancher.io/local-path

volumeBindingMode: WaitForFirstConsumer

查看存储信息


# 查看 Docker Volumes

docker  volume  ls  | grep  k3d

# 查看 StorageClass

kubectl  get  storageclass

# 查看 PVC

kubectl  get  pvc  -n <namespace>

# 查看 PV

kubectl  get  pv

数据流向

外部访问应用流程


sequenceDiagram

    participant User as 用户

    participant Host as 宿主机

    participant LB as LoadBalancer

    participant IC as Ingress Controller

    participant SVC as Service

    participant Pod as Application Pod

    User->>Host: http://localhost:8000

    Host->>LB: 转发到 LoadBalancer

    LB->>IC: 转发到 Traefik

    IC->>SVC: 根据 Ingress 规则路由

    SVC->>Pod: 负载均衡到 Pod

    Pod-->>SVC: 响应

    SVC-->>IC: 返回

    IC-->>LB: 返回

    LB-->>Host: 返回

    Host-->>User: 响应

Pod 间通信流程


sequenceDiagram

    participant Pod1 as Pod 1 (Web App)

    participant DNS as CoreDNS

    participant SVC as Service

    participant Pod2 as Pod 2 (Database)

    Pod1->>DNS: 解析 mysql.default.svc.cluster.local

    DNS-->>Pod1: 返回 Service IP

    Pod1->>SVC: 请求 Service IP

    SVC->>Pod2: 转发到后端 Pod

    Pod2-->>SVC: 响应

    SVC-->>Pod1: 返回

控制平面通信流程


sequenceDiagram

    participant Kubelet as Kubelet

    participant API as API Server

    participant etcd as etcd

    participant CM as Controller Manager

    participant Scheduler as Scheduler

    Kubelet->>API: 上报节点状态

    API->>etcd: 存储状态

    API->>Scheduler: 新 Pod 需要调度

    Scheduler->>API: 选择节点

    API->>etcd: 更新 Pod 绑定信息

    API->>CM: Pod 创建事件

    CM->>API: 创建 ReplicaSet

    API->>etcd: 存储 ReplicaSet

    API->>Kubelet: 创建 Pod 指令

    Kubelet->>API: Pod 运行状态

组件交互

完整交互图


graph TB

    subgraph "External"

        USER[用户/开发者]

        GITLAB[GitLab CI/CD]

    end

    subgraph "Docker Host"

        subgraph "k3d-mycluster"

            subgraph "Control Plane"

                API[API Server]

                ETCD[etcd]

                CM[Controller Manager]

                SCHED[Scheduler]

            end

            subgraph "System Components"

                TRAEFIK[Traefik Ingress]

                DNS[CoreDNS]

                METRICS[Metrics Server]

                STORAGE[Local Path Provisioner]

            end

            subgraph "Application Layer"

                APP[Application Pods]

                DB[Database Pod]

                CACHE[Cache Pod]

            end

            LB[LoadBalancer]

        end

    end

    USER -->|localhost:8000| LB

    LB --> TRAEFIK

    TRAEFIK --> APP

    APP --> DB

    APP --> CACHE

    GITLAB -->|部署| API

    API --> ETCD

    API --> CM

    API --> SCHED

    CM --> APP

    SCHED --> APP

    APP -->|DNS 查询| DNS

    APP -->|存储| STORAGE

    style USER fill:#e1e5f5

    style GITLAB fill:#e1e5f5

    style API fill:#ffcccc

    style ETCD fill:#ffcccc

    style TRAEFIK fill:#ffffcc

    style APP fill:#e1f5e1

    style DB fill:#ffe1e1

    style CACHE fill:#ffe1e1

组件依赖关系


graph TD

    ETCD[etcd<br/>数据存储] --> API[API Server<br/>API 入口]

    API --> CM[Controller Manager<br/>控制器]

    API --> SCHED[Scheduler<br/>调度器]

    API --> KUBELET[Kubelet<br/>节点代理]

    CM --> DEPLOY[Deployment Controller]

    CM --> SVC[Service Controller]

    SCHED --> POD[Pod 调度]

    KUBELET --> POD

    DEPLOY --> REPLICASET[ReplicaSet]

    REPLICASET --> POD

    SVC --> ENDPOINT[Endpoint]

    ENDPOINT --> POD

    TRAEFIK[Traefik] --> SVC

    DNS[CoreDNS] --> SVC

    style ETCD fill:#ffcccc

    style API fill:#ffcccc

    style POD fill:#e1f5e1

查看集群信息

查看集群组件


# 查看所有节点

kubectl  get  nodes

# 查看节点详细信息

kubectl  describe  node <node-name>

# 查看系统 Pod

kubectl  get  pods  -n  kube-system

# 查看所有命名空间的 Pod

kubectl  get  pods  --all-namespaces

查看 Docker 容器


# 查看 k3d 创建的容器

docker  ps  | grep  k3d

# 查看特定容器

docker  inspect  k3d-mycluster-server-0

# 查看容器日志

docker  logs  k3d-mycluster-server-0

查看网络信息


# 查看 Docker 网络

docker  network  ls  | grep  k3d

# 查看网络详情

docker  network  inspect  k3d-mycluster

# 查看 Service

kubectl  get  svc  --all-namespaces

# 查看 Ingress

kubectl  get  ingress  --all-namespaces

查看存储信息


# 查看 Docker Volumes

docker  volume  ls  | grep  k3d

# 查看 StorageClass

kubectl  get  storageclass

# 查看 PVC

kubectl  get  pvc  --all-namespaces

# 查看 PV

kubectl  get  pv

查看集群配置


# 查看 k3d 集群列表

k3d  cluster  list

# 查看集群详细信息

k3d  cluster  get  mycluster

# 查看 kubeconfig

kubectl  config  view

# 查看当前上下文

kubectl  config  current-context

集群生命周期

创建集群


# 基本创建

k3d  cluster  create  mycluster

# 带端口映射和多个节点

k3d  cluster  create  mycluster

  --port "8000:80@loadbalancer"

 --agents  2

停止和启动集群


# 停止集群（容器停止但保留）

k3d  cluster  stop  mycluster

# 启动集群

k3d  cluster  start  mycluster

删除集群


# 删除集群（包括所有容器和网络）

k3d  cluster  delete  mycluster

导入镜像


# 导入镜像到集群

k3d  image  import  myimage:latest  -c  mycluster

# 查看集群中的镜像

k3d  image  list  -c  mycluster

典型部署架构示例

通用应用在 k3d 集群中的部署


graph TB

    subgraph "k3d-mycluster Network"

        subgraph "Control Plane"

            SERVER[k3d-mycluster-server-0]

        end

        LB[k3d-mycluster-lb<br/>8000:80]

        subgraph "kube-system Namespace"

            TRAEFIK[Traefik Ingress]

            DNS[CoreDNS]

        end

        subgraph "production Namespace"

            subgraph "Web Application"

                APP1[App Pod 1]

                APP2[App Pod 2]

                APP3[App Pod 3]

                APP_SVC[App Service<br/>LoadBalancer]

            end

            subgraph "Database"

                DB_POD[Database Pod]

                DB_SVC[Database Service<br/>ClusterIP:5432]

                DB_PVC[Database PVC]

            end

            subgraph "Cache"

                CACHE_POD[Cache Pod]

                CACHE_SVC[Cache Service<br/>ClusterIP:6379]

            end

            INGRESS[Ingress<br/>app.local]

        end

    end

    USER[用户] -->|localhost:8000| LB

    LB --> TRAEFIK

    TRAEFIK --> INGRESS

    INGRESS --> APP_SVC

    APP_SVC --> APP1

    APP_SVC --> APP2

    APP_SVC --> APP3

    APP1 --> DB_SVC

    APP2 --> DB_SVC

    APP3 --> DB_SVC

    DB_SVC --> DB_POD

    DB_POD --> DB_PVC

    APP1 --> CACHE_SVC

    APP2 --> CACHE_SVC

    APP3 --> CACHE_SVC

    CACHE_SVC --> CACHE_POD

    SERVER --> APP1

    SERVER --> APP2

    SERVER --> APP3

    SERVER --> DB_POD

    SERVER --> CACHE_POD

    style SERVER fill:#ffcccc

    style LB fill:#ccffcc

    style TRAEFIK fill:#ffffcc

    style APP1 fill:#e1f5e1

    style APP2 fill:#e1f5e1

    style APP3 fill:#e1f5e1

    style DB_POD fill:#ffe1e1

    style CACHE_POD fill:#ffe1e1

总结

k3d 集群核心特点

轻量级: 相比完整 Kubernetes 更小更快
Docker 原生: 所有组件运行在 Docker 容器中
内置组件: 默认包含 Traefik、CoreDNS 等
易于管理: 通过 k3d CLI 工具管理
适合开发测试: 快速创建和销毁集群

关键组件

控制平面: k3s server（API Server、etcd、Controller Manager、Scheduler）
工作节点: k3s agent（Kubelet、Kube-proxy）
LoadBalancer: 端口映射和外部访问
Ingress Controller: Traefik（默认）
DNS: CoreDNS
存储: Local Path Provisioner

适用场景

✅ 本地开发和测试
✅ CI/CD 流水线测试
✅ 学习和实验 Kubernetes
✅ 快速原型开发
❌ 不适合生产环境（资源限制、单点故障）

参考资源

k8s

本作品采用《CC 协议》，转载必须注明作者和本文链接

刻意学习

iceymoss

课程读者 729 声望

GO/PHP开发工程师，转rust开发中，好好学习，天天向上！

0 人点赞

k3d 集群整体架构文档

k3d 集群整体架构文档

目录

概述

k3d 的特点

整体架构图

完整架构视图

简化架构视图

核心组件

1. 控制平面节点 (Control Plane Node)

2. 工作节点 (Worker Nodes)

3. LoadBalancer (负载均衡器)

4. Ingress Controller (Traefik)

5. CoreDNS

6. Metrics Server

7. Local Path Provisioner

网络架构

Docker 网络

网络组件关系

网络层次

查看网络信息

存储架构

Docker Volumes

持久化存储

存储类 (StorageClass)

查看存储信息

数据流向

外部访问应用流程

Pod 间通信流程

控制平面通信流程

组件交互

完整交互图

组件依赖关系

查看集群信息

查看集群组件

查看 Docker 容器

查看网络信息

查看存储信息

查看集群配置

集群生命周期

创建集群

停止和启动集群

删除集群

导入镜像

典型部署架构示例

通用应用在 k3d 集群中的部署

总结

k3d 集群核心特点

关键组件

适用场景

参考资源

推荐文章：

社区赞助商

关于 LearnKu

资源推荐

服务提供商

其他信息

请登录