Docker 與 Kubernetes 部署(單一服務)
Deploying One Go Service with Docker and Kubernetes
以訂單服務為例,用多階段 Dockerfile 編出靜態二進位檔,放進 distroless 映像檔並以非 root 執行;再用 Deployment、Service、探針、資源限制、ConfigMap/Secret 與滾動更新,把單一服務穩穩地跑在 Kubernetes 上。
這篇的步驟
上一篇〈設定與優雅關閉〉我們讓訂單服務從環境讀設定、在收到 SIGTERM 時依序收尾,並準備好 /healthz 與 /readyz;這篇接著把這一個服務打包成映像檔,放到 Kubernetes 上執行,讓那些設計真正接上平台。
這篇要解決什麼
「在我的電腦上可以跑」是部署最常聽到的一句話。原因通常是執行環境不一致:本機的 Go 版本、系統函式庫、環境變數、檔案路徑,都和伺服器不同。容器把程式連同它需要的執行環境包成一個映像檔,在任何安裝了容器執行環境的機器上都以同樣的方式啟動;Kubernetes 再負責把這些容器放到叢集中的機器上、維持指定的數量、在失敗時重啟、在更新時逐步替換。
Go 在這件事上有天生的優勢:它可以編出不依賴任何系統函式庫的靜態二進位檔,所以映像檔裡幾乎什麼都不用放,可以做到很小、很乾淨、攻擊面很少。
這篇只處理一個服務:把 cmd/order 的訂單服務打包、推上映像檔倉庫,並在 Kubernetes 上用最基本的物件把它跑穩。目標包括:
- 映像檔小、建置快、可重現,並以非 root 身分執行。
- 映像檔的標籤可以對應回原始碼版本。
- Kubernetes 知道它什麼時候「準備好」、什麼時候「卡住了」、需要多少資源。
- 設定與密鑰從平台注入,不寫進映像檔。
- 更新版本時不中斷服務,出問題能快速回滾。
整套系統(api-gateway、order、payment、inventory 加上資料庫與訊息佇列)如何一起部署,留給下一部分「實戰部署」的兩篇處理。
第 1 步:多階段 Dockerfile 與靜態二進位檔
最直覺的 Dockerfile 是以 golang 官方映像檔為基底,把原始碼複製進去、編譯、直接執行。這樣可以動,但最後的映像檔裡包含了整套 Go 工具鏈、原始碼與模組快取,體積可能接近一 GB,裡面還有 shell、套件管理工具等一堆執行時用不到的東西,每一樣都是潛在的弱點。
多階段建置解決了這個問題:第一階段(build)用完整的 Go 映像檔編譯;第二階段(runtime)從一個極小的基底開始,只把編譯好的二進位檔複製過來。最終映像檔只包含第二階段的內容。
# syntax=docker/dockerfile:1
ARG GO_VERSION=1.27
# ---- 第一階段:編譯 ----
FROM --platform=$BUILDPLATFORM golang:${GO_VERSION} AS build
WORKDIR /src
# 先只複製 go.mod / go.sum 並下載依賴,原始碼變動時這一層仍可沿用快取
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download
COPY . .
ARG TARGETOS TARGETARCH
ARG VERSION=dev
RUN --mount=type=cache,target=/go/pkg/mod \
--mount=type=cache,target=/root/.cache/go-build \
CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH \
go build -trimpath -ldflags="-s -w -X main.version=${VERSION}" \
-o /out/order ./cmd/order
# ---- 第二階段:執行 ----
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/order /order
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/order"]逐行說明幾個關鍵選擇:
CGO_ENABLED=0:關閉 cgo,讓 Go 不連結 C 函式庫,產出完全靜態的二進位檔。標準函式庫裡的net(DNS 解析)與os/user在關閉 cgo 後會改用純 Go 實作,對一般服務沒有影響。如果專案確實依賴 cgo(例如某些 SQLite 驅動),就不能用scratch或static基底,要改用帶有 C 函式庫的映像檔。-trimpath:把建置機器上的檔案路徑從二進位檔中移除,讓建置結果與在哪台機器建置無關,也不會洩露目錄結構。-ldflags="-s -w":去掉符號表與 DWARF 除錯資訊,縮小檔案。代價是無法對這個二進位檔使用除錯器;但 panic 時的堆疊追蹤仍然完整,pprof 也照常可用,下一篇〈效能調校:pprof 與 benchmark〉會用到它。-X main.version=...:在編譯時把版本字串寫進程式的變數,啟動時印進日誌、放進指標的標籤,出問題時一眼就知道是哪一版。--platform=$BUILDPLATFORM與TARGETOS/TARGETARCH:在建置機器原生的架構上執行編譯器,再交叉編譯到目標架構。Go 的交叉編譯只要設定環境變數,比用模擬器在另一個架構上編譯快得多,一次可以產出 amd64 與 arm64 兩種映像檔。- 快取掛載:
--mount=type=cache讓模組下載與編譯快取在多次建置之間保留,原始碼小改時重新建置只需要幾秒。
同時要記得加上 .dockerignore,至少排除 .git、本機的建置產物與任何含有密鑰的檔案。建置內容(build context)會整包送進建置程序,沒排除的東西不但拖慢建置,還可能被 COPY . . 意外放進第一階段。
圖:第一階段有完整工具鏈與原始碼,第二階段只接收一個靜態二進位檔,最終映像檔只包含右邊的內容。
第 2 步:選擇基底映像檔與非 root 執行
第二階段的基底有幾種常見選擇:
| 基底 | 內容 | 優點 | 注意 |
|---|---|---|---|
scratch | 完全空白 | 最小 | 沒有 CA 憑證、時區資料、/etc/passwd,需自行複製;預設以 root 執行 |
distroless/static | CA 憑證、時區、使用者定義,沒有 shell | 小、安全,內建 nonroot 使用者 | 無法 exec 進去用 shell 除錯 |
alpine | 小型發行版與 shell | 方便除錯 | 使用 musl,cgo 程式要注意相容性;有套件管理工具 |
debian-slim 等 | 一般發行版 | 相容性最好 | 體積大,弱點掃描結果較多 |
對於 CGO_ENABLED=0 的 Go 服務,distroless/static 的 nonroot 版本通常是最平衡的選擇。訂單服務會以 HTTPS 呼叫第三方金流,需要 CA 憑證才能驗證對方;日誌或報表處理時區時需要時區資料。這兩樣 scratch 都沒有,忘了補上就會在執行時才出錯。(Go 也提供 time/tzdata 套件,可以把時區資料直接嵌進二進位檔。)
以非 root 執行是映像檔層級最重要的安全設定。容器內的 root 與主機上的 root 之間雖然有隔離,但一旦有容器逃逸的弱點,以 root 執行的程序造成的損害會大得多。distroless 的 nonroot 使用者 UID 是 65532,Dockerfile 用 USER nonroot:nonroot 指定,第 4 步的 Kubernetes 設定會再加上一層 runAsNonRoot 強制檢查。
非 root 有一個連帶影響:程式不能監聽 1024 以下的埠號。Go 服務在容器內監聽 8080,再由 Kubernetes 的 Service 對外提供 80 埠即可,不需要特權。
第 3 步:建置、標籤與推送映像檔
映像檔的標籤(tag)是部署時用來指定版本的名稱。一個常見的錯誤是只用 latest:它不是「最新版」的保證,只是一個預設名稱,而且會被覆寫,你無法從 latest 知道叢集裡實際跑的是哪一版,也無法可靠地回滾。
比較好的做法是用不可變的標籤,例如 Git commit 的短雜湊或語意化版本號,每次建置都產生新的標籤,永不覆寫。部署時甚至可以直接指定映像檔的摘要(digest,sha256:...),保證拉到的位元組完全一致。
# 以 commit 雜湊當作版本與標籤
VERSION=$(git rev-parse --short HEAD)
IMAGE=registry.example.com/shop/order
# 一次建置 amd64 與 arm64,並推送到映像檔倉庫
docker buildx build \
--platform linux/amd64,linux/arm64 \
--build-arg VERSION="$VERSION" \
-t "$IMAGE:$VERSION" \
--push .
# 本機檢查:映像檔大小、執行身分、有沒有 shell
docker build -t order:local .
docker image ls order:local
docker run --rm order:local # 以 nonroot 啟動
docker run --rm --entrypoint sh order:local # distroless 沒有 shell,這行會失敗,這是預期的
# 取得推送後的 digest,部署時可直接引用
docker buildx imagetools inspect "$IMAGE:$VERSION"一個只含靜態 Go 二進位檔的 distroless 映像檔,大小通常落在十幾到幾十 MB,主要取決於程式本身的大小;相較於以完整 Go 映像檔為基底的版本,差距常常是數十倍。(實際數字依程式而定,這裡只是說明數量級。)映像檔小,拉取就快,節點上新 Pod 啟動得也快,這在擴容與滾動更新時會直接反映在等待時間上。
建置流程上線前,建議再加上兩個檢查:用弱點掃描工具掃描映像檔,以及在持續整合中確認映像檔確實以非 root 執行。
提示:密鑰絕對不要透過
ARG或ENV傳進 Dockerfile,它們會留在映像檔的層或歷史紀錄裡。建置階段真的需要密鑰(例如拉取私有模組)時,使用 BuildKit 的--mount=type=secret,它只在那一行RUN執行期間掛載,不會寫進任何一層。
第 4 步:用 ConfigMap 與 Secret 注入設定
上一篇的設定原則在這裡對應到兩種 Kubernetes 物件:一般設定放 ConfigMap,密鑰放 Secret。兩者都可以變成容器的環境變數,或掛載成檔案。
apiVersion: v1
kind: ConfigMap
metadata:
name: order-config
data:
ORDER_ADDR: ':8080'
ORDER_INVENTORY_URL: 'http://inventory:8080'
ORDER_SHUTDOWN_TIMEOUT: '20s'
---
apiVersion: v1
kind: Secret
metadata:
name: order-secrets
type: Opaque
stringData: # 範例用;實務上不要把真正的密鑰提交進版本控制
database-url: 'postgres://order:CHANGE_ME@postgres:5432/shop?sslmode=require'在 Pod 裡使用時,ConfigMap 用 envFrom 整包轉成環境變數;Secret 則建議掛成唯讀檔案,再用上一篇提到的 ORDER_DATABASE_URL_FILE 慣例讓程式讀檔。這樣密鑰不會出現在 kubectl describe pod 的環境變數清單裡,也不會被子程序繼承。
有兩點要特別注意。第一,ConfigMap 以環境變數注入時,修改 ConfigMap 不會影響已經在跑的 Pod,必須重新啟動 Pod 才會讀到新值;以檔案掛載時,檔案內容會在一段時間後更新,但程式要自己重新讀取才有效果。一個常見做法是把設定內容的雜湊寫進 Pod 範本的註記(annotation),設定一改,Pod 範本跟著改,就會自動觸發滾動更新。第二,Secret 預設只是 base64 編碼,真正的保護來自叢集的存取權限設定與 etcd 加密,實務上的密鑰值通常由外部密鑰管理服務同步進來,而不是寫在版本控制的 YAML 裡。
第 5 步:Deployment、Service 與探針
Deployment 描述「要用哪個映像檔、跑幾份、怎麼更新」,它底下會建立 ReplicaSet,再由 ReplicaSet 維持指定數量的 Pod。Service 則提供一個穩定的名稱與虛擬 IP,把流量分散到符合標籤選擇器、而且 readiness 探針通過的 Pod 上,這也是〈服務發現與負載平衡〉提到的平台內建服務發現。
apiVersion: apps/v1
kind: Deployment
metadata:
name: order
labels: { app: order }
spec:
replicas: 3
revisionHistoryLimit: 5
selector:
matchLabels: { app: order }
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1 # 更新時最多多出 1 個 Pod
maxUnavailable: 0 # 更新時不允許可用數低於 replicas
template:
metadata:
labels: { app: order }
spec:
terminationGracePeriodSeconds: 30
securityContext:
runAsNonRoot: true
seccompProfile: { type: RuntimeDefault }
containers:
- name: order
image: registry.example.com/shop/order:3f9c2ab
ports:
- { name: http, containerPort: 8080 }
envFrom:
- configMapRef: { name: order-config }
env:
- name: ORDER_DATABASE_URL_FILE
value: /etc/order/secrets/database-url
- name: GOMEMLIMIT # 讓 Go 的 GC 知道容器記憶體上限
valueFrom:
resourceFieldRef: { resource: limits.memory }
volumeMounts:
- { name: secrets, mountPath: /etc/order/secrets, readOnly: true }
resources:
requests: { cpu: 250m, memory: 128Mi }
limits: { memory: 256Mi }
startupProbe:
httpGet: { path: /healthz, port: http }
periodSeconds: 2
failureThreshold: 30
readinessProbe:
httpGet: { path: /readyz, port: http }
periodSeconds: 5
livenessProbe:
httpGet: { path: /healthz, port: http }
periodSeconds: 10
failureThreshold: 3
lifecycle:
preStop:
sleep: { seconds: 5 }
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities: { drop: ['ALL'] }
volumes:
- name: secrets
secret: { secretName: order-secrets }
---
apiVersion: v1
kind: Service
metadata:
name: order
spec:
selector: { app: order }
ports:
- { name: http, port: 80, targetPort: http }
---
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
name: order
spec:
minAvailable: 2
selector:
matchLabels: { app: order }圖:Deployment 透過 ReplicaSet 管理 Pod,Service 只把流量送到 readiness 通過的 Pod,ConfigMap 與 Secret 在 Pod 啟動時注入。
三種探針各有分工,要對應到上一篇的兩個端點:
- startupProbe:啟動期間(例如連線資料庫、暖機)先由它負責,成功之前 liveness 與 readiness 都不會執行,避免啟動較慢時被 liveness 誤判為卡死而重啟。
- readinessProbe:失敗時 Pod 只是從 Service 的端點名單移除,不會被重啟。優雅關閉期間
/readyz回 503,正是利用這個行為讓流量提早移走。 - livenessProbe:連續失敗才重啟容器,只用來偵測「程序卡死、無法自行恢復」的情況。不要在這裡檢查資料庫等外部依賴,否則外部短暫故障會讓所有 Pod 一起被重啟。
安全設定方面,runAsNonRoot 會在映像檔若以 root 執行時直接拒絕啟動,與 Dockerfile 的 USER 形成雙重保障;readOnlyRootFilesystem 讓容器的檔案系統唯讀,程式若真的需要暫存目錄,再額外掛一個 emptyDir;capabilities: drop: ["ALL"] 拿掉所有 Linux 特權能力,一般的 Go 網路服務完全用不到它們。
PodDisruptionBudget(PDB)處理的是「自願中斷」,例如節點維護時的排空(drain)或叢集升級。上面的設定要求任何時候至少保留 2 個可用的 Pod,維護工具在驅逐 Pod 時會遵守這個限制,一次只動一個,而不是把三個 Pod 同時趕走。
第 6 步:資源請求與限制
resources 是很多人照抄卻沒有細想的區塊,它對穩定性的影響其實很大:
- requests 是排程依據:Kubernetes 只會把 Pod 放到剩餘可分配資源足夠的節點上。它也是 CPU 競爭時分配比例的依據。設太低,節點會被塞爆;設太高,叢集資源浪費。
- CPU limit 是硬性的節流:程序用超過時會被暫停到下一個週期,表現為延遲突然升高,而不是錯誤。很多團隊選擇只設 CPU requests、不設 CPU limit,讓服務可以使用節點上閒置的 CPU;是否這樣做取決於叢集的多租戶策略。
- memory limit 則是硬性的上限:超過就會被核心以 OOM 終止,Pod 重啟。記憶體不像 CPU 可以節流,所以 memory limit 通常一定要設。
Go 程式在容器裡有兩個與資源相關的執行環境設定要配合。第一是 GOMEMLIMIT:上面的 Deployment 用 resourceFieldRef 把容器的記憶體上限以位元組數傳進環境變數,Go 的垃圾回收器會在接近這個值時更積極地回收,降低被 OOM 終止的機會;實務上常會設成略低於 limit,保留一些給非堆積的記憶體。第二是 GOMAXPROCS:Go 1.25 起在 Linux 上會依照容器的 CPU limit 自動設定,較舊的版本則會看到整台節點的核心數,在 CPU limit 很低時造成大量節流。這些參數的細節與調校方法,在下一篇會進一步說明。
requests 該設多少,最可靠的依據是〈可觀測性:日誌、指標、追蹤〉裡的指標:觀察一段時間內正常與尖峰流量下的 CPU 與記憶體用量,以此為基準再留一些餘裕,而不是憑感覺填一個整數。
第 7 步:滾動更新與回滾
當你把 Deployment 的映像檔標籤改成新版本,Kubernetes 會建立新的 ReplicaSet,依照 maxSurge 與 maxUnavailable 逐步增加新 Pod、減少舊 Pod。以上面的設定(3 個副本、maxSurge: 1、maxUnavailable: 0)來說,流程是:先多開一個新 Pod,等它的 readiness 通過,再關掉一個舊 Pod,如此反覆,直到全部換成新版本。任何時候可用的 Pod 都不少於 3 個。
圖:maxSurge 為 1、maxUnavailable 為 0 時,每一輪先讓一個新 Pod 就緒,再移除一個舊 Pod,可用數量始終不低於設定值。
這個流程之所以能做到零中斷,靠的是前面每一步的配合:readiness 探針確保新 Pod 真的能服務才接流量;preStop 與上一篇的優雅關閉確保舊 Pod 被移除時不會中斷進行中的請求;terminationGracePeriodSeconds 給收尾足夠的時間。少了任何一環,滾動更新都可能在切換的那幾秒產生錯誤。
# 更新映像檔並觀察進度;新 Pod 若一直無法就緒,rollout 會停在原地,舊 Pod 繼續服務
kubectl set image deployment/order order=registry.example.com/shop/order:7d41e0c
kubectl rollout status deployment/order --timeout=5m
# 檢視歷史與回滾到上一版
kubectl rollout history deployment/order
kubectl rollout undo deployment/order
# 排查:Pod 狀態、事件、上一個容器的日誌(例如設定驗證失敗而退出)
kubectl get pods -l app=order
kubectl describe pod -l app=order
kubectl logs deploy/order --previous實務上,kubectl set image 多半由持續部署流程改寫 YAML 後 kubectl apply 取代,以確保叢集狀態與版本控制中的檔案一致。回滾同理:把 YAML 改回前一個標籤並套用,比 rollout undo 更容易追蹤。這也是第 3 步堅持使用不可變標籤的原因:只有標籤唯一對應一個版本,「回到上一版」才有明確的意義。
另外,spec.progressDeadlineSeconds(預設 600 秒)決定滾動更新多久沒有進展就被標記為失敗。搭配上一篇的「設定錯誤就立刻退出」,一個帶著錯誤設定的新版本會不斷重啟、永遠無法就緒,rollout 停住並回報失敗,而舊版本完全不受影響地繼續服務。
常見陷阱
- 使用
latest標籤。 無法得知實際版本、無法可靠回滾,搭配imagePullPolicy還可能各節點跑著不同的映像檔。使用不可變標籤或 digest。 - 映像檔以 root 執行。 用 distroless 的
nonroot或自訂 UID,並在 Pod 加上runAsNonRoot: true。 scratch缺 CA 憑證或時區資料。 呼叫 HTTPS 時出現憑證驗證錯誤、時間轉換失敗,往往是這個原因。- 把密鑰寫進映像檔。
ENV、ARG、COPY進去的密鑰都會留在映像檔中。改由 Secret 在執行時注入。 - liveness 探針太嚴格或檢查外部依賴。 啟動慢或資料庫短暫斷線時,所有 Pod 被反覆重啟。啟動交給 startupProbe,liveness 只檢查程序本身。
- 沒有 readiness 探針。 新 Pod 一啟動就接流量,程式還沒準備好就回錯誤,滾動更新期間錯誤率突然上升。
- 只設 limit 不設 request,或 memory limit 過低。 前者讓排程失去依據,後者讓 Go 程式頻繁被 OOM 終止。搭配
GOMEMLIMIT,並根據實際指標調整。 - 寬限時間不足。
terminationGracePeriodSeconds小於preStop加上程式內的關閉上限,收尾做到一半就被 SIGKILL。 - 只有一個副本卻設了 PDB
minAvailable: 1。 節點排空時永遠無法驅逐這個 Pod,維護工作會卡住。副本數與 PDB 要一起規劃。
重點整理
- 多階段 Dockerfile 以完整 Go 映像檔編譯、以極小基底執行;
CGO_ENABLED=0、-trimpath、-ldflags="-s -w"產出小而可重現的靜態二進位檔。 - 基底首選
distroless/static的nonroot版本:有 CA 憑證與時區、沒有 shell、以非 root 執行。 - 映像檔使用不可變標籤(commit 雜湊或版本號),必要時以 digest 部署;密鑰不進映像檔,建置期需要時用 BuildKit 的 secret 掛載。
- 設定用 ConfigMap、密鑰用 Secret 掛成檔案;設定變更要透過滾動更新讓 Pod 重新讀取。
- Deployment 管理副本與更新、Service 提供穩定名稱並只導流到就緒的 Pod;startup、readiness、liveness 三種探針各司其職。
- requests 決定排程、memory limit 防止失控;Go 程式搭配
GOMEMLIMIT,並留意GOMAXPROCS與 CPU limit 的關係。 maxSurge/maxUnavailable、readiness、preStop、優雅關閉與 PodDisruptionBudget 一起,才能做到零中斷的滾動更新與節點維護。- 這篇只部署了一個服務;整套系統(多個服務、資料庫、訊息佇列、對外入口、自動擴縮)的部署,會在下一部分「實戰部署」的〈用 Docker Compose 部署整套微服務〉與〈在 Kubernetes 部署整套微服務〉完成。
下一篇
服務已經穩定地跑在叢集裡,但「跑得起來」不等於「跑得夠快」:資源要給多少、哪段程式最耗 CPU、記憶體為什麼一直長,都需要量測才能回答。〈效能調校:pprof 與 benchmark〉會示範如何用 benchmark 與 pprof 找出瓶頸,並調整 GOGC、GOMEMLIMIT 等執行環境參數。