Kustomize 設計理念與使用說明

农夫运维發表於2024-11-29

Kustomize 設計理念與使用說明

一、設計理念

Kustomize 的設計理念是基於"基礎配置 + 補丁"的模式，這裡解釋一下為什麼需要在 base 目錄下建立基礎配置：

  1. 基礎配置的重要性：

    • base 目錄下的配置是所有環境共享的基礎配置
    • 包含了服務最基本的定義和配置
    • 確保了不同環境的配置一致性

  2. 環境差異管理：

    • overlays 目錄只存放與基礎配置的差異部分
    • 每個環境只需要關注自己特有的配置
    • 避免了配置重複和維護困難

  3. 配置複用：

    • 基礎配置可以被多個環境複用
    • 減少了重複配置的維護成本
    • 確保了配置的一致性

  4. 如果只在 overlays 下建立配置的問題：

    • 每個環境都需要維護完整的配置
    • 配置變更需要在多個環境中同步修改
    • 容易造成環境間的配置不一致
    • 難以追蹤配置的變化

    base 中放置：

    • 容器埠
    • 資源限制
    • 健康檢查
    • 基礎標籤

    overlays 中放置：

    • 環境變數
    • 映象版本
    • 副本數量
    • 特定註解

二、工作流

kustomization工作流方式

Kustomize 不是一個新工具，它自 2017 年以來一直在建設中，並在 1.14 版本中作為原生 kubectl 子命令引入。Kustomize 由 Google 和 Kubernetes 社群構建，符合 Kubernetes 使用 Kubernetes 物件定義配置檔案和以宣告方式管理這些配置的原則。Kustomize 配置物件稱為 Kustomization，用於描述如何生成或轉換其他 Kubernetes 物件。Kustomization 在名為 kustomization.yaml 的檔案中以宣告方式定義，此檔案可由 Kustomize 本身生成和修改。

在 kustomize 中，可以定義常見、可重複使用的 kustomization（稱為基礎）並使用多個其他 kustomization（稱為覆蓋層）對其進行修補，這些 kustomization 可以選擇性地覆蓋基礎中定義的設定以生成變體。然後，Kustomize 根據 kustomization 基礎和覆蓋層中定義的配置轉換和生成資源，此過程稱為融合或渲染。接下來，這些渲染資源會寫入標準輸出或檔案，並保持原始 YAML 檔案不變，以便許多不同的疊加層重複使用基礎。

這種無模板方法在 Kustomization 庫的易用性和可重用性方面非常強大。使用它你能夠以幾乎任何想要的方式自定義 Kubernetes 配置，而無需為每個單獨的用例提供大量值。

二、Kustomize 支援眾多的功能特性

欄位 型別 解釋
namespace string 為所有資源新增名字空間
namePrefix string 此欄位的值將被新增到所有資源名稱前面
nameSuffix string 此欄位的值將被新增到所有資源名稱後面
labels map[string]string 要新增到所有資源和選擇算符的標籤
commonAnnotations map[string]string 要新增到所有資源的註解
resources []string 列表中的每個條目都必須能夠解析為現有的資源配置檔案
configMapGenerator []configmapargs 列表中的每個條目都會生成一個 ConfigMap
secretGenerator []secretargs 列表中的每個條目都會生成一個 Secret
generatorOptions GeneratorOptions 更改所有 ConfigMap 和 Secret 生成器的行為
bases []string 列表中每個條目都應能解析為一個包含 kustomization.yaml 檔案的目錄
patchesStrategicMerge []string 列表中每個條目都能解析為某 Kubernetes 物件的策略性合併補丁
patchesJson6902 []patch 列表中每個條目都能解析為一個 Kubernetes 物件和一個 JSON 補丁
vars []var 每個條目用來從某資源的欄位來析取文字
images []image 每個條目都用來更改映象的名稱、標記與/或摘要，不必生成補丁
configurations []string 列表中每個條目都應能解析為一個包含 Kustomize 轉換器配置 的檔案
crds []string 列表中每個條目都應能夠解析為 Kubernetes 類別的 OpenAPI 定義檔案

二、目錄結構說明

Kustomize-dc/
├── base/                    # 基礎配置目錄
│   ├── backend/            # 後端服務基礎配置
│   │   └── accounting-service/
│   ├── frontend/           # 前端服務基礎配置
│   │   └── ybf-www-h5/
│   └── kustomization.yaml  # 基礎配置的kustomization檔案
└── overlays/               # 環境特定配置目錄
    ├── prod/               # 生產環境配置
    │   ├── backend/
    │   ├── frontend/
    │   └── kustomization.yaml
    ├── test/               # 測試環境配置
    └── dev/                # 開發環境配置

三、常用命令示例

  1. 檢視生成的配置：
kubectl kustomize overlays/prod
  1. 應用配置到叢集：
kubectl apply -k overlays/prod
  1. 刪除已部署的資源：
kubectl delete -k overlays/prod

四、最佳實踐建議

  1. 標籤管理：

    • 使用統一的標籤體系
    • 在base中定義基礎標籤
    • 在overlays中新增環境特定標籤

  2. 配置管理：

    • 敏感配置使用Secret
    • 環境變數使用ConfigMap
    • 避免在base中包含環境特定的配置

  3. 補丁使用：

    • 使用strategic merge patch進行配置覆蓋
    • 只在必要時使用json patch
    • 保持補丁檔案的簡潔性

五、常見問題解答

  1. Q: 如何處理不同環境的域名配置？
    A: 在overlays中使用patch-ingress.yaml進行覆蓋，如示例中的ybf-www-h5服務。

  2. Q: 如何管理不同環境的標籤？
    A: 在base中定義通用標籤，在overlays中使用labels欄位新增環境標籤。

  3. Q: 如何處理配置檔案的優先順序？
    A: Kustomize按照以下順序應用配置：

    • base配置
    • overlays中的補丁
    • overlays中的資源

  4. Q: 如何維護大型專案的配置？
    A: 建議按照服務型別（前端/後端）和業務模組進行目錄劃分，保持清晰的層次結構。

六、配置示例

1. 基礎服務配置示例

base/backend/accounting-service/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: accounting-service
spec:
  replicas: 1
  selector:
    matchLabels:
      app: accounting-service
  template:
    metadata:
      labels:
        app: accounting-service
    spec:
      containers:
        - name: accounting-service
          ports:
            - containerPort: 8080
          resources:
            limits:
              cpu: '1'
              memory: 2Gi
            requests:
              cpu: 500m
              memory: 1Gi

2. 環境特定配置示例

overlays/prod/backend/accounting-service/patch-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: accounting-service
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: accounting-service
          image: your-registry/accounting-service:prod
          env:
            - name: SPRING_PROFILES_ACTIVE
              value: prod

3. ConfigMap配置示例

base/configmap.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  application.properties: |
    server.port=8080
    spring.application.name=my-app

overlays/prod/patch-configmap.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  apollo_namespace: prod
  sw_agent_collector_backend_services: skywalking-oap.prod-ybf-mid:11800
  apollo_cluster: prod
  apollo_config_service: http://service-apollo-config-server.prod-ybf-mid:8080

4. Ingress配置示例

base/ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/ssl-redirect: 'false'
spec:
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-app
                port:
                  number: 80

5. Kustomization檔案示例

base/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml
  - service.yaml
  - ingress.yaml
  - configmap.yaml

labels:
  - pairs:
      app.kubernetes.io/component: backend
      app.kubernetes.io/name: my-app
    includeSelectors: true

overlays/prod/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

namespace: prod

patches:
  - path: patch-deployment.yaml
  - path: patch-configmap.yaml

labels:
  - pairs:
      environment: prod
    includeSelectors: true

這些示例展示了：

  1. 基礎部署配置
  2. 環境特定的補丁
  3. ConfigMap的基礎配置和環境特定配置
  4. Ingress配置
  5. Kustomization檔案的組織方式

五、使用說明

前端專案部署

  • 進入專案目錄
  • 執行 kustomize build overlays/prod/frontend/ybf-www-h5/ 生成 prod 環境服務的 yaml
  • 執行 kustomize build overlays/prod/frontend/ 生成 prod 環境所有前端服務的 yaml
  • 執行 kustomize build overlays/prod/ 生成 prod 環境所有服務的 yaml

後端專案部署

  • 進入專案目錄
  • 執行 kustomize build overlays/prod/backend/accounting-service/ 生成 prod 環境服務的 yaml
  • 執行 kustomize build overlays/prod/backend/ 生成 prod 環境所有後端服務的 yaml
  • 執行 kustomize build overlays/prod/ 生成 prod 環境所有服務的 yaml

六、除錯命令

使用 --load-restrictor 引數除錯
kustomize build --load-restrictor LoadRestrictionsNone ./Kustomize-dc/overlays/prod
驗證 yaml 語法
kustomize build ./Kustomize-dc/overlays/prod | kubectl apply --dry-run=client -f -
使用 --verbose 引數獲取詳細錯誤資訊
kustomize build --verbose ./Kustomize-dc/overlays/prod

七、新服務新增說明

後端服務新增：

  1. 複製 base/backend/accounting-service 目錄作為模板
  2. 複製 overlays/prod/backend/accounting-service 目錄作為模板
  3. 修改所有檔案中的服務名稱
  4. 更新 base/backend/kustomization.yaml 新增新服務

前端服務新增：

  1. 複製 base/frontend/ybf-www-h5 目錄作為模板
  2. 複製 overlays/prod/frontend/ybf-www-h5 目錄作為模板
  3. 修改所有檔案中的服務名稱
  4. 更新 base/frontend/kustomization.yaml 新增新服務

八、優勢

  1. 配置清晰可維護
  2. 環境差異一目瞭然
  3. 基礎配置變更容易同步到所有環境
  4. 降低配置錯誤的風險
  5. 便於版本控制和審計

相關文章