Deploy to Kubernetes

部署容器化應用於 Kubernetes，具健康檢查、資源管理、自動化推出等生產級配置。

適用時機

• 部署新應用於 Kubernetes 集群（EKS、GKE、AKS、自託管）
• 自 Docker Compose 或傳統 VM 遷至容器編排
• 行零停機滾動更新與回滾
• 於 Kubernetes 管應用配置與秘鑰
• 設多環境部署（dev、staging、production）
• 建可重用之 Helm chart 以供應用分發

輸入

• 必需：Kubernetes 集群存取（kubectl cluster-info）
• 必需：已推至登錄之容器映像（Docker Hub、ECR、GCR、Harbor）
• 必需：應用需求（埠、環境變數、卷宗）
• 可選：HTTPS ingress 之 TLS 憑證
• 可選：持久儲存需求（StatefulSets、PVCs）
• 可選：基於 chart 部署用之 Helm CLI

步驟

完整配置檔案與模板，見 Extended Examples。

步驟一：建命名空間與資源配額

將應用分入命名空間，具資源限與 RBAC。

# Create namespace
kubectl create namespace myapp-prod

# Apply resource quota
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ResourceQuota
metadata:
  name: compute-quota
  namespace: myapp-prod
spec:
  hard:
    requests.cpu: "10"
    requests.memory: "20Gi"
    limits.cpu: "20"
    limits.memory: "40Gi"
    persistentvolumeclaims: "5"
    services.loadbalancers: "2"
---
apiVersion: v1
kind: LimitRange
metadata:
  name: default-limits
  namespace: myapp-prod
spec:
  limits:
  - default:
      cpu: "500m"
      memory: "512Mi"
    defaultRequest:
      cpu: "100m"
      memory: "128Mi"
    type: Container
EOF

# Create service account
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ServiceAccount
metadata:
  name: myapp
  namespace: myapp-prod
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: myapp-role
  namespace: myapp-prod
rules:
- apiGroups: [""]
  resources: ["configmaps", "secrets"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: myapp-rolebinding
  namespace: myapp-prod
subjects:
- kind: ServiceAccount
  name: myapp
  namespace: myapp-prod
roleRef:
  kind: Role
  name: myapp-role
  apiGroup: rbac.authorization.k8s.io
EOF

# Verify namespace setup
kubectl get resourcequota -n myapp-prod
kubectl get limitrange -n myapp-prod
kubectl get sa -n myapp-prod

預期： 命名空間建成，具限計算與儲存之資源配額。LimitRange 設預設之 CPU/記憶體請求與限。ServiceAccount 以最小權限 RBAC 配之。

失敗時： 配額錯誤時，以 kubectl describe nodes 驗集群資源是否足。RBAC 錯誤時，以 kubectl auth can-i create role --namespace myapp-prod 檢集群管理權限。於被拒資源用 kubectl describe 以見配額/限違反。

步驟二：配應用秘鑰與 ConfigMap

以 ConfigMap 與 Secret 外部化配置與敏感資料。

# Create ConfigMap from literal values
kubectl create configmap myapp-config \
  --namespace=myapp-prod \
  --from-literal=LOG_LEVEL=info \
  --from-literal=API_TIMEOUT=30s \
  --from-literal=FEATURE_FLAGS='{"newUI":true,"betaAPI":false}'

# Create ConfigMap from file
cat > app.properties <<EOF
database.pool.size=20
cache.ttl=3600
retry.attempts=3
EOF

kubectl create configmap myapp-properties \
  --namespace=myapp-prod \
  --from-file=app.properties

# Create Secret for database credentials
kubectl create secret generic myapp-db-secret \
  --namespace=myapp-prod \
  --from-literal=username=appuser \
  --from-literal=password='sup3rs3cr3t!' \
  --from-literal=connection-string='postgresql://db.example.com:5432/myapp'

# Create TLS secret for ingress
kubectl create secret tls myapp-tls \
  --namespace=myapp-prod \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key

# Verify secrets/configmaps
kubectl get configmap -n myapp-prod
kubectl get secret -n myapp-prod
kubectl describe configmap myapp-config -n myapp-prod

更複雜之配置宜用 YAML 清單：

# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: myapp-config
  namespace: myapp-prod
data:
  nginx.conf: |
    server {
      listen 8080;
      location / {
        proxy_pass http://backend:3000;
        proxy_set_header Host $host;
      }
    }
  app-config.json: |
    {
      "logLevel": "info",
      "features": {
        "authentication": true,
        "metrics": true
      }
    }
---
# secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: myapp-secret
  namespace: myapp-prod
type: Opaque
stringData:  # Automatically base64 encoded
  api-key: "sk-1234567890abcdef"
  jwt-secret: "my-jwt-signing-key"

預期： ConfigMap 存非敏感之配置，Secret 存憑證/金鑰。值透過環境變數或卷宗掛載供 Pod 存取。TLS 秘鑰合 Ingress 資源之格式。

失敗時： 編碼問題時，YAML 中以 stringData 替 data。TLS 秘鑰錯誤時，以 openssl x509 -in tls.crt -text -noout 驗憑證與金鑰格式。存取問題時，查 ServiceAccount 之 RBAC 權限。以 kubectl get secret myapp-secret -o jsonpath='{.data.api-key}' | base64 -d 觀解碼之秘鑰。

步驟三：建具健康檢查與資源限之 Deployment

部署應用，具探針與資源管理之生產級配置。

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  namespace: myapp-prod
  labels:
    app: myapp
    version: v1.0.0
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0  # Zero-downtime updates
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
        version: v1.0.0
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/port: "8080"
        prometheus.io/path: "/metrics"
    spec:
      serviceAccountName: myapp
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        fsGroup: 1000
      containers:
      - name: myapp
        image: myregistry.io/myapp:v1.0.0
        imagePullPolicy: IfNotPresent
        ports:
        - name: http
          containerPort: 8080
          protocol: TCP
        env:
        - name: LOG_LEVEL
          valueFrom:
            configMapKeyRef:
              name: myapp-config
              key: LOG_LEVEL
        - name: DB_USERNAME
          valueFrom:
            secretKeyRef:
              name: myapp-db-secret
              key: username
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: myapp-db-secret
              key: password
        - name: POD_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: POD_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        resources:
          requests:
            cpu: 250m
            memory: 256Mi
          limits:
            cpu: 500m
            memory: 512Mi
        livenessProbe:
          httpGet:
            path: /healthz
            port: http
          initialDelaySeconds: 30
          periodSeconds: 10
          timeoutSeconds: 5
          failureThreshold: 3
        readinessProbe:
          httpGet:
            path: /ready
            port: http
          initialDelaySeconds: 5
          periodSeconds: 5
          timeoutSeconds: 3
          failureThreshold: 2
        startupProbe:
          httpGet:
            path: /healthz
            port: http
          initialDelaySeconds: 0
          periodSeconds: 10
          timeoutSeconds: 3
          failureThreshold: 30  # 5 minutes for slow startup
        volumeMounts:
        - name: config
          mountPath: /etc/myapp
          readOnly: true
        - name: cache
          mountPath: /var/cache/myapp
      volumes:
      - name: config
        configMap:
          name: myapp-properties
      - name: cache
        emptyDir: {}
      imagePullSecrets:
      - name: registry-credentials

應用並監部署：

# Apply deployment
kubectl apply -f deployment.yaml

# Watch rollout status
kubectl rollout status deployment/myapp -n myapp-prod

# Check pod status
kubectl get pods -n myapp-prod -l app=myapp

# View pod logs
kubectl logs -n myapp-prod -l app=myapp --tail=50 -f

# Describe deployment for events
kubectl describe deployment myapp -n myapp-prod

# Check resource usage
kubectl top pods -n myapp-prod -l app=myapp

預期： Deployment 以滾動更新策略建 3 副本。Pod 於 readiness 探針通過後方收流量。Liveness 探針重啟不健康之 pod。資源請求/限防 OOM kill。日誌示應用成功啟動。

失敗時： ImagePullBackOff 時，以 kubectl get secret registry-credentials -o yaml 驗映像存且 imagePullSecret 有效。CrashLoopBackOff 時，以 kubectl logs pod-name --previous 查日誌。探針失敗時，以 kubectl port-forward 與 curl localhost:8080/healthz 人工測端點。Pod 被 OOMKilled 時，增記憶體限或查記憶體洩漏。

步驟四：以 Service 與負載均衡器暴露應用

建 Service 資源以於內部與外部暴露應用。

# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: myapp
  namespace: myapp-prod
# ... (see EXAMPLES.md for complete configuration)

應用並測 Service：

# Apply services
kubectl apply -f service.yaml

# Get service details
kubectl get svc -n myapp-prod

# ... (see EXAMPLES.md for complete configuration)

預期： LoadBalancer Service 配外部 LB 具公開 IP/主機名。ClusterIP Service 提供穩定之內部 DNS。Endpoints 列示健康之 Pod IP。Curl 請求以預期回應成功。

失敗時： LoadBalancer 懸而未決時，查雲提供者整合與配額。無 endpoints 時，以 kubectl get pods --show-labels 驗 Pod 標籤合 Service selector。連線被拒時，驗 targetPort 合容器埠。除錯時以 kubectl port-forward 繞過 Service 層。

步驟五：配水平 Pod 自動擴展

依 CPU/記憶體或自定指標行自動擴展。

# hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: myapp-hpa
  namespace: myapp-prod
# ... (see EXAMPLES.md for complete configuration)

若 metrics-server 不可用則裝之：

# Install metrics-server
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

# Verify metrics-server
kubectl get deployment metrics-server -n kube-system
kubectl top nodes
# ... (see EXAMPLES.md for complete configuration)

預期： HPA 監 CPU/記憶體指標。超閾值時，副本擴至 maxReplicas。負載減時，副本漸縮（穩定窗防震盪）。指標以 kubectl top 可見。

失敗時： 「unknown」指標時，驗 metrics-server 運行且 Pod 已定資源請求。無擴展時，以 kubectl top pods 查當前利用率實超目標。震盪時，增 stabilizationWindowSeconds。擴展慢時，於 scaleUp 策略中減 periodSeconds。

步驟六：以 Helm Chart 打包應用

建可重用之 Helm chart 以供多環境部署。

# Create Helm chart structure
helm create myapp-chart
cd myapp-chart

# Edit Chart.yaml
cat > Chart.yaml <<EOF
# ... (see EXAMPLES.md for complete configuration)

預期： Helm chart 以模板化值打包所有 Kubernetes 資源。乾執行示渲染之清單。裝以正確順序部署所有資源。升級行滾動更新。回滾還原至前一版本。

失敗時： 模板錯誤時，執 helm template . 以本地渲染而不安裝。依賴問題時，執 helm dependency update。值覆蓋失敗時，驗 YAML 路徑於 values.yaml 中存。以 helm get manifest myapp -n myapp-prod 觀實部署之資源。

驗證

• Pod 於 Running 狀態，所有容器就緒
• Readiness 探針於 Pod 加入 Service endpoints 前通過
• Liveness 探針自動重啟不健康容器
• 資源請求與限防 OOM kill 與節點超分
• Secret 與 ConfigMap 以預期值正確掛載
• Service 自他 Pod 透過 DNS（cluster.local）解析
• LoadBalancer/Ingress 自外部網路可達
• HPA 於負載下擴副本，於閒置時縮之
• 滾動更新以零停機完成
• 日誌透過 kubectl logs 或集中日誌收集並可達

常見陷阱

• 缺 readiness 探針：Pod 於完全啟動前收流量。恆實作驗應用依賴之 readiness 探針。

• 啟動時間不足：快速 liveness 探針殺啟動慢之應用。用 startupProbe 具寬鬆 failureThreshold 以供初始化。

• 無資源限：Pod 耗無限 CPU/記憶體致節點不穩。恆設請求與限。

• 硬編碼配置：清單中之環境特定值阻重用。用 ConfigMap、Secret、Helm values。

• 預設 service account：Pod 有不必要之集群權限。建專用之 ServiceAccount 具最小 RBAC。

• 無滾動更新策略：Deployment 同時重建所有 Pod 致停機。用 RollingUpdate 具 maxUnavailable: 0。

• 秘鑰入版本控制：敏感資料提交至 Git。用 sealed-secrets、external-secrets-operator 或 vault。

• 無 pod disruption budget：集群維護排空節點致服務中斷。建 PodDisruptionBudget 以保最小可用副本。

相關技能

• setup-docker-compose - Kubernetes 前之容器編排基礎
• containerize-mcp-server - 為部署建容器映像
• write-helm-chart - 高級 Helm chart 開發
• manage-kubernetes-secrets - SealedSecrets 與 external-secrets-operator
• configure-ingress-networking - NGINX Ingress 與 cert-manager 設定
• implement-gitops-workflow - 聲明式部署之 ArgoCD/Flux
• setup-container-registry - 映像登錄整合