0

Ghép lại: Azure Pipelines build image, đẩy lên registry, Portainer tự cập nhật stack

Chín bài trước mỗi bài một mảnh: Dockerfile, compose cho prod, Portainer, pipeline, version theo tag, phê duyệt, secret. Cách nhiều team ghép chúng lại lúc đầu là: pipeline build xong image, rồi một người mở Portainer, vào stack, bấm "Pull and redeploy". Chạy được, nhưng có ba vấn đề. Phải có người ngồi bấm. Không ai trả lời được "trên server đang chạy bản nào" mà không mở Portainer ra xem. Và muốn quay về bản cũ thì không có nút nào cả.

Bài này là luồng mình đề xuất để nối các mảnh đó: pipeline build image gắn đúng số phiên bản, đẩy lên registry, ghi số phiên bản vào file compose trong Git, rồi Portainer tự kéo về và cập nhật. Quay về bản cũ là revert một commit. YAML trong bài là mẫu dựng từ các bài trước, đổi tên cho hợp project của bạn.

Toàn bộ luồng

 push tag api-prod-1.8.3
          │
          ▼
 ┌─ Stage Build (Azure Pipelines) ─────────────────────┐
 │  lấy version từ tag (bài 7)                          │
 │  docker build, test                                  │
 │  docker push  myregistry.azurecr.io/api:1.8.3        │
 └──────────────────────────────────────────────────────┘
          │
          ▼  chờ người duyệt (Environment "Production")
 ┌─ Stage Deploy ───────────────────────────────────────┐
 │  sửa repo deploy: image: ...api:1.8.2 → ...api:1.8.3 │
 │  commit + push                                        │
 │  gọi webhook GitOps của Portainer                     │
 │  chờ /health trả version 1.8.3                        │
 └──────────────────────────────────────────────────────┘
          │
          ▼
 Portainer kéo file compose mới từ Git, pull image 1.8.3, tạo lại container

Điểm mấu chốt: Git là nơi ghi bản nào đang chạy. File compose trong repo deploy luôn chứa đúng tag đang chạy trên server. Muốn biết, đọc file. Muốn đổi, commit. Muốn quay lại, revert. Người ta gọi kiểu này là GitOps.

Vì sao không dùng tag latest

Cách đơn giản hơn là pipeline đẩy image tag latest, Portainer bật "Re-pull image" và tự kéo latest mỗi lần cập nhật. Mình không chọn vì:

Tag latest Tag theo version, ghi trong Git
Biết server đang chạy bản nào Phải xem digest của image rồi tra ngược Đọc file compose
Quay về bản cũ Không có cách nào gọn, latest cũ đã bị đè Revert commit
Hai server pull ở hai thời điểm Có thể chạy hai bản khác nhau Cùng một tag, cùng một image
Ai đổi bản, lúc nào Không có dấu vết Lịch sử commit

Stage Build: build và push image

Pipeline cần một service connection tới registry (Project settings → Service connections → Docker Registry). Ví dụ dùng Azure Container Registry, Docker Hub cũng làm y vậy:

stages:
  - stage: Build
    jobs:
      - job: GetVersion
        steps:
          - checkout: self
            fetchDepth: 0
            fetchTags: true
          - bash: |
              tag=$(git describe --tags --match "api-prod-*" --abbrev=0) || { echo "Không có tag release"; exit 1; }
              v=${tag#api-prod-}
              echo "##vso[task.setvariable variable=Version;isoutput=true]$v"
              echo "##vso[build.updatebuildnumber]$v"
            name: Ver

      - job: Image
        dependsOn: GetVersion
        variables:
          Version: $[ dependencies.GetVersion.outputs['Ver.Version'] ]
        steps:
          - task: Docker@2
            displayName: 'Build và push image'
            inputs:
              command: buildAndPush
              containerRegistry: 'acr-connection'   # tên service connection, không phải mật khẩu
              repository: 'api'
              Dockerfile: 'Dockerfile'
              tags: |
                $(Version)

Mật khẩu registry nằm trong service connection, YAML chỉ ghi tên của nó. Đây là cùng nguyên tắc với variable group ở bài 8.

Nếu muốn test chạy trên chính image vừa build (thay vì trên code), tách buildAndPush thành hai bước build rồi push, chèn bước test ở giữa: image hỏng thì không bao giờ lên registry.

Phía Portainer: stack từ Git, cập nhật bằng webhook

Repo deploy (có thể là một thư mục trong cùng repo, nhưng tách repo thì quyền rõ ràng hơn) chứa file compose của prod, kiểu như ở bài 4:

# deploy/api/docker-compose.yml
services:
  api:
    image: myregistry.azurecr.io/api:1.8.2   # pipeline sửa dòng này
    environment:
      - ConnectionStrings__Default=${DB_CONNECTION}   # giá trị khai báo trong Portainer
    # ... healthcheck, limits, logging như bài 4

Trên Portainer:

  1. Registries → Add registry, thêm registry với một tài khoản chỉ có quyền pull. Với ACR, tạo một token gắn scope map có sẵn _repositories_pull. Server chỉ cần kéo image về, không có lý do gì cầm quyền đẩy image lên.
  2. Stacks → Add stack → Repository, trỏ tới repo deploy, đường dẫn tới file compose.
  3. Bật GitOps updates, chọn cơ chế Webhook. Portainer hiện một URL, copy lại.
  4. Khai báo biến môi trường của stack (DB_CONNECTION...) trong Portainer, không đưa vào Git.

Về phiên bản: theo tài liệu của Portainer, cập nhật GitOps bằng polling hoặc webhook dùng được cho stack tạo từ Git. Còn webhook cho stack tạo bằng web editor (kiểu "gọi URL này để redeploy, kèm biến đổi tag") là tính năng của bản Business. Nếu bạn dùng bản CE, luồng Git trong bài này là đường đi được.

URL webhook là một bí mật: ai có nó là kích được việc deploy lại. Đưa nó vào variable group, đánh dấu secret.

Stage Deploy: sửa tag trong Git, gọi Portainer, chờ bản mới sống

  - stage: Deploy
    dependsOn: Build
    variables:
      - group: portainer-prod            # chứa PortainerWebhookUrl (secret)
    jobs:
      - deployment: Production
        environment: Production          # nút phê duyệt nằm ở đây (bài 7)
        variables:
          Version: $[ stageDependencies.Build.GetVersion.outputs['Ver.Version'] ]
        strategy:
          runOnce:
            deploy:
              steps:
                - checkout: git://Platform/deploy-config@main
                  persistCredentials: true   # cho phép git push bằng danh tính của pipeline
                - bash: |
                    set -euo pipefail
                    file=api/docker-compose.yml
                    sed -i -E "s#(image: myregistry\.azurecr\.io/api:).*#\1$(Version)#" "$file"
                    grep -q "api:$(Version)" "$file" || { echo "Không sửa được tag"; exit 1; }
                    git config user.email "pipeline@example.com"
                    git config user.name "Release pipeline"
                    git commit -am "deploy(api): $(Version)"
                    git push origin HEAD:main
                  displayName: 'Ghi version vào repo deploy'

                - bash: |
                    set -euo pipefail
                    curl -fsS -X POST "$WEBHOOK"
                  env:
                    WEBHOOK: $(PortainerWebhookUrl)   # biến secret phải map rõ qua env
                  displayName: 'Báo Portainer cập nhật'

                - bash: |
                    for i in $(seq 1 30); do
                      v=$(curl -fsS https://api.example.com/health/version || true)
                      [ "$v" = "$(Version)" ] && { echo "Đã chạy bản $v"; exit 0; }
                      sleep 10
                    done
                    echo "Sau 5 phút vẫn chưa thấy bản $(Version)"; exit 1
                  displayName: 'Chờ bản mới chạy'

Mấy chi tiết dễ vấp:

  • Cú pháp lấy output từ stage khác là stageDependencies.<stage>.<job>.outputs[...], khác với dependencies.<job>... khi cùng stage ở bài 7.
  • Pipeline cần quyền push vào repo deploy. Vào Project settings → Repositories → repo deploy → Security, cấp quyền Contribute cho tài khoản <tên project> Build Service. Không có quyền thì bước git push lỗi 403. Đừng giải quyết bằng cách dán token cá nhân vào pipeline.
  • Webhook trả về trước khi Portainer deploy xong. Tài liệu Portainer ghi rõ điều này. Nên bước cuối phải tự kiểm: app có một endpoint trả về version của chính nó (đọc từ biến môi trường hay assembly), pipeline gọi tới khi thấy đúng số phiên bản. Không có bước này, pipeline xanh chỉ có nghĩa là "đã gửi yêu cầu".
  • Commit vào repo deploy không được kích lại pipeline build, không thì thành vòng lặp. Repo deploy tách riêng giải quyết luôn chuyện này.

Quay về bản cũ

Bản 1.8.3 có lỗi, cần về 1.8.2 ngay:

git -C deploy-config revert --no-edit HEAD     # commit "deploy(api): 1.8.3" bị đảo ngược
git -C deploy-config push origin main
curl -fsS -X POST "$PORTAINER_WEBHOOK_URL"

Image 1.8.2 vẫn còn nguyên trên registry vì không có tag nào ghi đè lên nó. Lịch sử Git ghi lại cả lần deploy lẫn lần quay về, kèm người làm. Nếu không muốn ai gõ lệnh tay lúc có sự cố, làm một pipeline "rollback" nhận tham số version và chạy đúng stage Deploy ở trên với version đó.

Một lưu ý: quay về bản cũ của code thì dễ, quay về bản cũ của database thì không. Nếu bản 1.8.3 có migration đổi schema, revert compose không đảo ngược migration. Viết migration sao cho bản cũ vẫn chạy được trên schema mới (thêm cột thì được, xoá hay đổi tên cột thì để sang bản sau), thì nút quay về mới thật sự dùng được.

Checklist toàn luồng

[ ] Image tag theo version, không dùng latest
[ ] Mật khẩu registry nằm trong service connection
[ ] Server dùng tài khoản registry chỉ có quyền pull
[ ] File compose prod nằm trong Git, ghi đúng tag đang chạy
[ ] Secret của stack khai báo trong Portainer, không trong Git
[ ] URL webhook là biến secret
[ ] Có bước phê duyệt trước stage Deploy
[ ] Pipeline chờ app báo đúng version mới coi là xong
[ ] Đã thử quay về bản cũ ít nhất một lần, lúc không có sự cố
[ ] Migration của bản mới không phá bản cũ

Thử ngay: dòng gần cuối checklist là dòng hay bị bỏ qua nhất. Chọn một buổi chiều yên ổn, quay server test về bản trước đó theo đúng quy trình bạn định dùng lúc có sự cố, và bấm giờ.

Mười bài đầu của series đi từ một Dockerfile năm dòng tới một luồng deploy có phê duyệt và có đường quay về. Bài sau trong series: dựng server từ VPS Ubuntu trắng tới app chạy HTTPS, nơi luồng ở bài này chạy, với Docker, Portainer và Nginx Proxy Manager hoặc Caddy. Bạn muốn series sau đi sâu vào phần nào: Kubernetes, giám sát và cảnh báo, hay agent tự host trên Windows? Comment cho mình biết với.

P.S. Luồng trong bài này mình phác trước với skill cloud-devops-deployer trong PrimeKit, bộ skill mình tự làm. Skill nắm Docker, CI/CD, GitOps và phần soát bảo mật khi deploy, hợp để hỏi "luồng này hở chỗ nào" trước khi dựng thật. Cài bằng npx @lovehlmmm/primekit init, rồi gõ /pk:cloud-devops-deployer kèm mô tả hạ tầng của bạn. Diễn tập quay về bản cũ thì không skill nào làm thay được.

Tài liệu để đọc thêm


Series khác của mình


All rights reserved

Viblo
Hãy đăng ký một tài khoản Viblo để nhận được nhiều bài viết thú vị hơn.
Đăng kí