Cấu hình và secret trong container: biến môi trường đi đâu, và cái log lộ khoá
Mình viết một entrypoint cho container API rất "chu đáo": lần đầu container chạy, nó tự sinh file cấu hình và một khoá khôi phục (để admin vào trang quản trị khi đăng nhập một lần bị hỏng), lưu vào volume, rồi in khoá ra log thật to cho người cài dễ thấy:
==========================================
IMPORTANT: Save this recovery key!
Recovery Key: 7K2Q-M9XD-...
==========================================
Tiện thật. Cho tới khi nghĩ lại: ai xem được log của container? Người SSH vào server, người có quyền xem container trên Portainer, công cụ gom log đẩy mọi dòng stdout về một chỗ để cả team tìm kiếm. Khoá đáng lẽ chỉ admin biết giờ nằm trong log, và log thì sống lâu hơn bạn nghĩ.
Bài này đi qua những câu hỏi mình phải tự trả lời khi đưa cấu hình và secret vào container. Mỗi mục một câu hỏi, có câu trả lời ngắn và code.
Cấu hình của app đến từ đâu, và cái nào thắng?
Với app ASP.NET Core trong container, cấu hình thường đến từ bốn chỗ. Bảng dưới xếp từ thấp tới cao: cái ở dưới ghi đè cái ở trên.
| Nguồn | Ví dụ | Dùng cho |
|---|---|---|
appsettings.json trong image |
"PathBase": "/" |
Giá trị mặc định, giống nhau ở mọi môi trường |
appsettings.Production.json |
Log level của prod | Khác biệt theo môi trường, không phải secret |
| Biến môi trường | PathBase=/apps |
Khác biệt theo từng server |
| Tham số dòng lệnh | --urls http://+:8080 |
Hiếm khi cần trong container |
Biến môi trường dùng hai dấu gạch dưới thay cho dấu hai chấm của cấu hình lồng nhau, và số cho phần tử mảng:
environment:
- ASPNETCORE_URLS=http://+:8080
- PathBase=${PATH_BASE:-/apps}
# Tương đương "Cors": { "AllowedOrigins": [ "...", "..." ] } trong appsettings
- Cors__AllowedOrigins__0=${CORS_ORIGIN_1:-https://localhost}
- Cors__AllowedOrigins__1=${CORS_ORIGIN_2:-https://localhost:7200}
${PATH_BASE:-/apps} là cú pháp của Compose: lấy biến PATH_BASE nếu có, không thì dùng /apps. Hành vi này giống shell, nên ai quen bash đọc là hiểu.
.env, env_file và environment khác nhau thế nào?
Ba thứ này hay bị nhầm vì tên giống nhau:
| Thứ | Ai đọc | Đi vào container không? |
|---|---|---|
File .env cạnh docker-compose.yml |
Compose, để thay ${...} trong file YAML |
Không, trừ khi bạn khai báo nó trong env_file |
env_file: .env |
Compose, đọc rồi đưa từng dòng vào container | Có |
environment: |
Compose, đưa vào container | Có, và thắng env_file nếu trùng tên |
Mình từng tưởng có file .env là container tự có biến. Không phải. File .env chỉ phục vụ việc thay chữ trong file compose. Muốn container nhận biến thì phải qua env_file hoặc environment. Docker có một trang riêng về thứ tự ưu tiên, đáng đọc một lần.
Dữ liệu sinh lần đầu phải nằm ở đâu?
Trong volume. Container có thể bị xoá và tạo lại bất cứ lúc nào: cập nhật image, docker compose up sau khi sửa file, server khởi động lại. Thứ gì ghi vào filesystem của container mà không nằm trong volume sẽ mất theo.
volumes:
# Cấu hình và khoá sinh lần đầu: phải sống qua các lần tạo lại container
- ./App_Data:/app/App_Data
# File tĩnh chỉ đọc
- ./wwwroot:/app/wwwroot:ro
Entrypoint chỉ sinh khi chưa có, và để nguyên khi đã có:
#!/bin/sh
set -e
CONFIG=/app/App_Data/app-config.json
KEY_FILE=/app/App_Data/recovery-key.txt
if [ ! -f "$CONFIG" ]; then
# Lọc byte ngẫu nhiên chỉ giữ chữ hoa và số, lấy đủ 16 ký tự
KEY=$(tr -dc 'A-Z0-9' < /dev/urandom | head -c 16)
# umask 077: file mới tạo chỉ user hiện tại đọc được
umask 077
printf '{ "recoveryKey": "%s" }\n' "$KEY" > "$CONFIG"
printf 'Recovery key: %s\n' "$KEY" > "$KEY_FILE"
echo "[entrypoint] Đã tạo cấu hình lần đầu. Khoá khôi phục nằm trong $KEY_FILE trên volume."
else
echo "[entrypoint] Cấu hình đã có, giữ nguyên."
fi
# Chạy app thay cho shell hiện tại
exec "$@"
Secret có được in ra log không?
Không. Kể cả lần đầu, kể cả "để người cài dễ thấy". Log in đường dẫn tới file chứa secret, không in giá trị. So với bản đầu:
| Bản đầu | Bản sửa |
|---|---|
| In khoá ra stdout, ba lần | In đường dẫn file |
| File khoá tạo với quyền mặc định | umask 077, chỉ user chạy app đọc được |
| Hướng dẫn "xem lại khoá" bằng cách đọc log | Hướng dẫn đọc file trên volume, chỉ người có quyền vào server làm được |
Nhân tiện: biến môi trường cũng không kín như nhiều người nghĩ. docker inspect <container> hiện toàn bộ biến môi trường, và giao diện quản lý container như Portainer cũng hiện chúng trong trang chi tiết container. Ai có quyền xem container là thấy hết.
Với secret thật sự nhạy cảm (khoá ký JWT, mật khẩu database prod), Compose có secrets: secret được mount thành file trong /run/secrets/, không nằm trong biến môi trường:
services:
api:
secrets:
- jwt_signing_key
environment:
# App đọc nội dung file thay vì đọc biến
- JwtSigningKeyFile=/run/secrets/jwt_signing_key
secrets:
jwt_signing_key:
file: ./secrets/jwt_signing_key.txt
Vì sao cuối entrypoint phải là exec "$@"?
"$@" là lệnh gốc của container (ví dụ dotnet App.dll). Có exec thì app thay thế shell và trở thành process số 1 trong container. Không có exec thì shell là process số 1, app là con của nó.
Khác biệt lộ ra khi dừng container: docker stop gửi tín hiệu SIGTERM tới process số 1. Nếu đó là shell, shell thường không chuyển tín hiệu cho app, app không được tắt êm (đóng kết nối, ghi nốt log), và sau 10 giây Docker giết thẳng tay bằng SIGKILL. Container nào docker stop mất đúng 10 giây là dấu hiệu quen thuộc của lỗi này.
Healthcheck cần công cụ gì trong image?
File compose của API này có một healthcheck bị comment kèm ghi chú "cần cài curl trong Dockerfile". Đúng vậy: image mcr.microsoft.com/dotnet/aspnet không có curl. Ba lựa chọn:
| Cách | Đổi lại |
|---|---|
Cài curl trong Dockerfile |
Image to hơn một chút, thêm một công cụ cho kẻ tấn công dùng |
Dùng image base Alpine, có sẵn wget của BusyBox |
Phải kiểm app chạy ổn trên Alpine |
Để healthcheck ở tầng ngoài (reverse proxy, công cụ giám sát) gọi /health |
Container không tự biết mình healthy, depends_on không dùng được |
Nếu có service khác cần depends_on: condition: service_healthy chờ API này thì cách đầu là gọn nhất. Quan trọng hơn là đừng để healthcheck bị comment mãi: không có nó, container treo vẫn hiện "running" xanh lè.
Checklist "secret đi đâu"
[ ] Không có secret trong Dockerfile (ENV, ARG) và trong image
[ ] Không commit .env; có .env.example với giá trị giả
[ ] Secret không bao giờ in ra stdout/stderr, kể cả lúc khởi tạo
[ ] Dữ liệu sinh lần đầu nằm trong volume, file tạo với quyền hẹp
[ ] Biết ai xem được biến môi trường (docker inspect, Portainer)
[ ] Secret nhạy cảm dùng secrets (mount file) thay cho biến môi trường
[ ] Entrypoint kết thúc bằng exec "$@"
Thử ngay: chạy docker logs <container> 2>&1 | grep -iE 'key|secret|password|token' trên các container của bạn. Kết quả nên trống.
Bài sau trong series: đưa compose lên prod, healthcheck, giới hạn tài nguyên, và những cổng không nên mở ra ngoài. Team bạn đang giữ secret của container ở đâu? Comment cho mình biết với.
P.S. Lỗi in khoá ra log nằm trong một diff nhìn rất vô hại: vài dòng echo. Giờ trước khi merge thay đổi đụng tới entrypoint hay cấu hình, mình chạy skill diff-security-inspector trong PrimeKit, bộ skill mình tự làm. Skill soát đúng phần diff về độ đúng, bảo mật, nguy cơ hồi quy và chỗ thiếu kiểm tra, kèm bằng chứng trong code. Cài bằng npx @lovehlmmm/primekit init, rồi gõ /pk:diff-security-inspector kèm nhánh cần soát. Nó không biết log của bạn đi về đâu, phần đó bạn phải tự trả lời.
Tài liệu để đọc thêm
- Thứ tự ưu tiên biến môi trường, Docker Docs
- Secrets trong Compose, Docker Docs
- Configuration trong ASP.NET Core, Microsoft Learn
Series khác của mình
- SQL thực chiến: Những bài học mình ước đã biết sớm hơn: viết query dễ đọc, đọc execution plan, lỗi NULL và N+1 không báo lỗi, schema và transaction, phân trang bằng con trỏ.
- Backend .NET thực chiến: những case hay gặp trên production: async/await làm treo API, HttpClient hết socket, EF Core kéo cả bảng, idempotency, outbox, caching, bảo mật API.
- Front End thực chiến: những bài toán UI mà tutorial không dạy: ngày giờ và giờ mùa hè, tầng dữ liệu theo hợp đồng API, chart, in ấn và accessibility, Outlook Add-in, E2E với Playwright.
- Dùng AI hiệu quả trong công việc: kinh nghiệm thực chiến của dev: viết prompt đủ ngữ cảnh, bắt AI bịa API, giao việc cho agent, review code AI viết, debug, đọc codebase lạ, đóng gói quy trình thành skill.
All rights reserved