Posted inDevOps

Tự động hóa Terraform với Atlantis trên Docker: Hướng dẫn GitOps thực tế

DevOps tutorial - IT technology blog
DevOps tutorial - IT technology blog

Bối cảnh & Lý do: Vấn đề của việc chạy Terraform thủ công

Quản lý hạ tầng dưới dạng mã (IaC) với Terraform thường bắt đầu như một dự án cá nhân. Bạn viết mã HCL, chạy terraform plan, và nhấn apply từ terminal. Mọi thứ diễn ra suôn sẻ cho đến khi có kỹ sư thứ hai tham gia vào đội ngũ. Đột nhiên, xung đột bắt đầu xảy ra. Bạn bắt đầu nghe thấy những tiếng gọi lớn trong văn phòng: “Ai vừa cập nhật instance RDS staging thế?” hay “Tại sao file state bị khóa suốt 20 phút rồi?”

Thực thi tại máy cục bộ (local) giống như một canh bạc. Nó thiếu nhật ký kiểm tra (audit trail) tập trung và dễ dẫn đến hội chứng ‘chạy tốt trên máy tôi’. Một kỹ sư có thể đang dùng AWS provider v4.0 trong khi người khác dùng v5.0, dẫn đến tình trạng lệch state (state drift) ngay lập tức. GitOps giải quyết vấn đề này bằng cách chuyển việc thực thi ra khỏi máy tính cá nhân. Hạ tầng tiến hóa thông qua các commit Git, không phải bằng lệnh terminal thủ công.

Atlantis lấp đầy khoảng trống này. Đây là một ứng dụng chuyên dụng lắng nghe webhook từ GitHub, GitLab hoặc Bitbucket. Khi bạn mở một PR, Atlantis sẽ chạy plan và gửi phản hồi (comment) kết quả vào PR để mọi người cùng xem. Sau khi đội ngũ phê duyệt, bạn chỉ cần comment atlantis apply để kích hoạt thay đổi. Với kinh nghiệm quản lý các cluster có hơn 50 microservices của tôi, quy trình này đã loại bỏ 90% rắc rối về tình trạng môi trường bị ‘lệch pha’.

Cài đặt: Triển khai Atlantis với Docker

Docker là cách nhanh nhất để đưa Atlantis vào hoạt động mà không làm xáo trộn hệ thống máy chủ của bạn. Chúng ta sẽ sử dụng Docker Compose để điều phối container và các biến môi trường của nó.

1. Điều kiện tiên quyết

  • Một VPS Linux hoặc máy cục bộ đã cài đặt Docker và Compose.
  • Tài khoản GitHub có quyền admin đối với repository của bạn.
  • Một địa chỉ IP công khai hoặc domain. Atlantis cần nhận được webhook. Đối với việc thử nghiệm cục bộ, các công cụ như ngrok có thể giúp đưa cổng 4141 ra ngoài internet.

2. Bản thiết kế Docker Compose

Đầu tiên, hãy tạo một thư mục riêng. Bên trong đó, thêm file docker-compose.yml. Cấu hình này sẽ kéo image chính thức và ánh xạ một volume cố định để lưu trữ dữ liệu Terraform của bạn.

version: '3.8'

services:
  atlantis:
    image: runatlantis/atlantis:latest
    container_name: atlantis
    ports:
      - "4141:4141"
    volumes:
      - ./atlantis-data:/atlantis-data
    environment:
      - ATLANTIS_GH_USER=your-github-username
      - ATLANTIS_GH_TOKEN=your-github-token
      - ATLANTIS_GH_WEBHOOK_SECRET=your-webhook-secret
      - ATLANTIS_REPO_ALLOWLIST=github.com/your-org/*
      - ATLANTIS_DATA_DIR=/atlantis-data
      - ATLANTIS_ATLANTIS_URL=http://your-public-url:4141
    restart: always

Bảo mật rất quan trọng. ATLANTIS_REPO_ALLOWLIST là lá chắn chính của bạn; nó đảm bảo chỉ các repository đã được xác minh mới có thể kích hoạt bot.

Cấu hình: Cái bắt tay hai chiều

Sau khi container đã sẵn sàng, bạn cần cấp quyền kết nối giữa máy chủ và GitHub. Việc này yêu cầu một Personal Access Token (PAT) và thiết lập Webhook cụ thể.

1. Tạo GitHub PAT

Đi tới GitHub Settings > Developer Settings > Personal Access Tokens (Classic). Tạo một token với phạm vi (scope) repo. Điều này cho phép Atlantis đọc các file HCL và đăng bình luận. Hãy sao chép token này ngay lập tức—bạn sẽ không thấy lại nó đâu—và dán nó vào biến ATLANTIS_GH_TOKEN của bạn.

2. Cấu hình GitHub Webhook

Mở repository mà bạn muốn tự động hóa. Điều hướng đến Settings > Webhooks > Add webhook.

  • Payload URL: http://your-public-url:4141/events
  • Content type: application/json
  • Secret: Sử dụng chính xác chuỗi ký tự từ ATLANTIS_GH_WEBHOOK_SECRET của bạn.
  • Events: Chọn “Let me select individual events” và tích vào Issue comments, Pull requests, Pull request reviews, và Pushes.

3. Kiểm soát chi tiết với atlantis.yaml

Theo mặc định, Atlantis sẽ quét mọi thư mục để tìm các file .tf. Để kiểm soát chính xác hơn, hãy đặt file atlantis.yaml vào thư mục gốc của repository. File này định nghĩa các dự án cụ thể và quy tắc tự động hóa của chúng.

version: 3
projects:
- name: staging-app
  dir: staging/us-east-1
  autoplan:
    when_modified: ["*.tf", "../modules/**"]
    enabled: true
- name: production-app
  dir: prod/us-east-1
  autoplan:
    enabled: false # Chỉ plan thủ công cho các môi trường quan trọng

Xác minh: Pull Request tự động đầu tiên của bạn

Đã đến lúc kiểm chứng. Hãy khởi động container của bạn:

docker-compose up -d

1. Quy trình làm việc thực tế

Tạo một branch mới, thêm một tag đơn giản vào tài nguyên hiện có và mở một Pull Request. Vài giây sau, Atlantis sẽ “thức dậy”. Nó sẽ quét các thay đổi của bạn và đăng một bình luận đã được định dạng hiển thị kết quả terraform plan trực tiếp trong luồng thảo luận của PR.

Kiểm tra kỹ bản plan. Nếu các thay đổi (diff) trông có vẻ chính xác, hãy nhập một bình luận mới:

atlantis apply

Bot sẽ thực thi lệnh và báo cáo kết quả. Nếu thành công, nó sẽ đặt một khóa (lock) lên dự án để ngăn chặn tình trạng tranh chấp (race conditions) cho đến khi PR được merge.

2. Giám sát và khắc phục sự cố

Truy cập http://your-public-url:4141 để xem giao diện người dùng (UI) của Atlantis. Nó cung cấp cái nhìn rõ ràng về các state lock hiện tại. Nếu bot giữ im lặng sau khi tạo PR, hãy kiểm tra log ngay lập tức:

docker logs -f atlantis

Hãy chú ý các lỗi 403 Forbidden (thường là vấn đề về quyền của token) hoặc lỗi 400 (thường là do secret của webhook không khớp). Sử dụng phương pháp dựa trên Docker này đảm bảo pipeline CI/CD của bạn được cô lập, có khả năng tái lập và dễ dàng mở rộng khi hạ tầng của bạn phát triển.

Share:
Tags: