Chapter 12: Factor XII — Admin Processes

Chạy các tác vụ quản trị như những process dùng một lần, trong đúng môi trường của ứng dụng

  • Theo Twelve-Factor, các admin/management tasks như migration database, mở console, hoặc chạy script sửa dữ liệu phải được chạy như one-off processes trong môi trường giống hệt các process chạy lâu dài của ứng dụng. Chúng phải dùng cùng release, cùng codebase, cùng config như app chính.
  • Tài liệu gốc còn nhấn mạnh rằng admin code phải đi cùng application code. Nếu tách rời, bạn rất dễ gặp lỗi lệch version, lệch schema, lệch dependency.
  • Trong thực tế hiện đại, Heroku hiện thực hóa ý này bằng one-off dynos chạy qua heroku run, còn Kubernetes có Job cho tác vụ chạy một lần đến khi hoàn tất và CronJob cho tác vụ lặp lại theo lịch.

1) Mở bài: vì sao factor cuối này lại quan trọng đến vậy?

Đây là một cảnh rất quen trong nhiều team:

  • migration thì chạy trên laptop của một anh senior,
  • script sửa dữ liệu nằm ở một repo riêng,
  • console production mở bằng một cách “bí truyền” chỉ 2 người biết,
  • còn cron job thì chạy ở đâu đó ngoài ứng dụng, không ai chắc nó đang dùng version code nào.

Những việc đó trông có vẻ “chỉ là tác vụ phụ”, nhưng thực ra lại rất nguy hiểm. Vì các tác vụ quản trị thường đụng thẳng vào dữ liệu thật và thay đổi trạng thái hệ thống. Twelve-Factor đưa Factor XII vào cuối bộ nguyên lý để chốt lại một ý rất đẹp: những việc quản trị không phải ngoại lệ kỳ lạ; chúng cũng phải tuân theo cùng kỷ luật triển khai như app chính.

2) Định nghĩa gốc của Factor XII

Tên chính thức của factor này là:

“Admin processes — Run admin/management tasks as one-off processes.”

Tài liệu gốc nêu thẳng một số ví dụ của admin processes:

  • chạy migration database,
  • mở console để chạy code tùy ý hoặc inspect dữ liệu,
  • chạy script một lần được check vào repo để sửa dữ liệu hay xử lý sự cố hành chính.

Điểm cốt lõi nhất là:

One-off admin processes phải chạy trong môi trường giống hệt các process chạy thường xuyên của ứng dụng. Chúng chạy trên một release cụ thể, dùng cùng codebase và cùng config như các process khác của release đó.

Diễn giải thật dễ hiểu cho junior:

Migration, console, data fix script, backfill script… không phải là “mấy thứ chạy tạm ngoài lề”. Chúng là process đặc biệt nhưng vẫn thuộc về ứng dụng, nên phải chạy bằng đúng bộ code và đúng môi trường của ứng dụng đó.

3) Factor này thật sự muốn giải quyết điều gì?

Factor XII giải quyết một loại rủi ro rất âm thầm: tác vụ quản trị bị tách khỏi vòng đời thật của ứng dụng.

Khi điều đó xảy ra, bạn thường gặp các vấn đề như:

  • script dùng version code cũ,
  • migration chạy bằng dependency khác production,
  • console mở ra nhưng config không giống release đang chạy,
  • dữ liệu bị sửa bằng một script copy-paste ngoài repo.

Twelve-Factor chặn đúng điểm này bằng 2 yêu cầu:

  • chạy admin task như one-off process, và
  • admin code phải đi cùng application code để tránh synchronization issues.

Nói ngắn gọn: app chính chạy kiểu nào, tác vụ quản trị cũng phải chạy kiểu đó.

4) “One-off process” là gì?

“One-off process” là một process được khởi chạy để làm một việc quản trị cụ thể, rồi kết thúc.

Khác với:

  • web process chạy liên tục để nhận request,
  • worker process chạy liên tục để xử lý queue,

admin process thường:

  • chạy migration,
  • mở console tạm thời,
  • chạy script backfill dữ liệu,
  • hoặc thực hiện một thao tác bảo trì rồi thoát.

Heroku diễn giải rất sát tinh thần này: one-off dynos dùng để thực hiện administrative hoặc maintenance tasks, chạy song song với các dynos khác, xuất hiện dưới process type run, và không tự động restart như dynos trong formation.

5) “Cùng release, cùng code, cùng config” nghĩa là gì?

Đây là câu quan trọng nhất của bài này.

Theo Twelve-Factor, admin process phải chạy:

  • trên cùng release,
  • với cùng codebase,
  • và cùng config như app chính.

Điều đó có nghĩa là:

  • nếu app production đang chạy release A, migration của bạn cũng nên chạy trên release A,
  • nếu app dùng config production hiện tại, console production cũng phải thấy đúng config đó,
  • nếu app có dependency đã khóa version, script quản trị cũng phải dùng đúng bộ dependency ấy.

Đây là lý do Factor XII nối rất chặt với các factor trước:

  • Factor II: dependency phải rõ,
  • Factor III: config phải đúng theo deploy,
  • Factor V: release phải là thực thể rõ ràng,
  • và Factor XII: admin task phải chạy trên cùng release đó.

6) Vì sao admin code phải đi cùng application code?

Tài liệu gốc nói rất rõ: admin code should ship with application code để tránh synchronization issues.

Đây là một ý cực kỳ thực chiến.

Nếu bạn để:

  • migration trong repo A,
  • app trong repo B,
  • data fix scripts trong thư mục ai đó lưu riêng,
  • cron scripts ở máy nào đó,

thì sớm muộn bạn sẽ gặp cảnh:

  • script giả định schema cũ,
  • app đã đổi model nhưng script chưa cập nhật,
  • dependency lệch version,
  • console chạy được trên local nhưng production không hợp lệ.

Việc “ship cùng application code” giúp bạn tránh chính xác loại lệch pha đó.

7) Ví dụ cực dễ hiểu

Hãy tưởng tượng ứng dụng của bạn là một bệnh viện.

  • web process giống như quầy tiếp nhận bệnh nhân, hoạt động liên tục.
  • worker process giống như các bộ phận xử lý hồ sơ phía sau.
  • admin process giống như một ca can thiệp đặc biệt: kiểm kê kho thuốc, điều chỉnh hồ sơ bệnh án, chạy một đợt rà soát dữ liệu.

Điều vô lý là bạn lại giao việc kiểm kê cho một người dùng sổ sách cũ, quy trình cũ, và không vào đúng hệ thống hiện tại của bệnh viện.

Factor XII nói rằng các ca việc đặc biệt đó vẫn phải đi qua đúng hệ thống hiện tại của bệnh viện. Đó chính là ý “same environment, same code, same config”.

8) Ví dụ xuyên suốt với ứng dụng mẫu TaskFlow

Ta tiếp tục dùng ứng dụng mẫu TaskFlow.

TaskFlow có các tác vụ quản trị như:

  • chạy migration cho PostgreSQL,
  • mở console để kiểm tra trạng thái một tenant bị lỗi,
  • chạy script backfill trường task_priority,
  • chạy một lệnh dọn dữ liệu trùng sau sự cố import.

Cách làm đúng

Các tác vụ này:

  • được viết trong cùng codebase của TaskFlow,
  • chạy bằng đúng release đang deploy,
  • dùng đúng DATABASE_URL, REDIS_URL và config production hiện tại,
  • được kích hoạt như one-off processes.

Cách làm sai

  • migration chạy trên laptop cá nhân với .env cũ,
  • data fix script nằm ở repo khác,
  • cron job gọi vào một đoạn Python “tự viết thêm” không cùng dependency với app,
  • console production dùng image khác image đang chạy chính thức.

Những cách làm sai này đều đi ngược trực tiếp tinh thần Factor XII.

9) Case thực tế đã được xác minh: Heroku one-off dynos

Heroku là ví dụ rất đẹp cho Factor XII.

Tài liệu chính thức cho biết:

  • one-off dynos dùng để chạy administrative hoặc maintenance tasks cho app,
  • được khởi chạy bằng heroku run,
  • chạy song song với các dynos khác của app,
  • có đầy đủ lợi ích của dyno isolation,
  • và có thể dùng bất cứ thứ gì đã được deploy trong ứng dụng.

Heroku còn mô tả rõ sự khác nhau giữa formation dynos và one-off dynos:

  • formation dynos là các process type chạy thường xuyên như web, worker,
  • one-off dynos là process run cho các tác vụ quản trị,
  • one-off dynos không nhận HTTP traffic,
  • không tự động restart,
  • và không restart sau app release mới.

Đây gần như là hiện thân trực tiếp của Factor XII trên một platform thật.

10) Case thực tế đã được xác minh: Kubernetes Jobs và CronJobs

Trong Kubernetes, Job đại diện cho các tác vụ chạy một lần đến khi hoàn tất rồi dừng. Tài liệu chính thức mô tả Jobs chính xác như vậy.

Còn CronJob tạo ra Jobs theo một lịch lặp lại, phù hợp cho:

  • backups,
  • report generation,
  • hoặc các tác vụ định kỳ khác.

Điều cần nói rõ:

  • Kubernetes Job/CronJob không phải là nội dung gốc của Twelve-Factor,
  • nhưng chúng là một cách hiện đại, rất tự nhiên để hiện thực hóa ý tưởng “admin task là one-off process” hoặc “scheduled admin task là one-off process lặp lại theo lịch”.

11) Junior thường hiểu sai ở đâu?

Hiểu sai 1: “Admin process chỉ là migration”

Không. Tài liệu gốc liệt kê cả:

  • migration,
  • interactive console,
  • script một lần để chạy code tùy ý hoặc xử lý dữ liệu quản trị.

Hiểu sai 2: “Script sửa dữ liệu để ngoài repo cho tiện”

Đi ngược hẳn tinh thần Twelve-Factor. Admin code nên đi cùng application code để tránh lệch pha.

Hiểu sai 3: “Chạy ở đâu cũng được, miễn có quyền vào DB”

Không đúng. Factor XII yêu cầu one-off admin process chạy trong môi trường giống hệt các process thường trực của app.

Hiểu sai 4: “Cron định kỳ là chuyện của máy chủ, không liên quan app”

Trong cách nhìn hiện đại, CronJob của Kubernetes hay Scheduler dùng one-off dynos của Heroku đều cho thấy tác vụ định kỳ nên vẫn được gắn vào cùng hệ sinh thái release/code/config của ứng dụng, thay vì trở thành một “bóng ma vận hành” sống ngoài luồng.

12) Làm sai thì hậu quả gì?

  • Migration lệch version, vì chạy không cùng release với app.
  • Script sửa dữ liệu gây lỗi âm thầm, vì dependency hoặc model đã khác app hiện tại.
  • Khó truy vết, vì tác vụ quản trị không đi qua quy trình release/app environment chính thức.
  • Vận hành phụ thuộc người biết “bí kíp”, thay vì là quy trình kỹ thuật rõ ràng.

Twelve-Factor sinh ra chính để giảm kiểu “tribal knowledge” này bằng cách đưa admin tasks trở về đúng khuôn mẫu của application processes.

13) Áp dụng đúng trong team như thế nào?

Bước 1: Liệt kê tất cả admin tasks thật sự

Đừng chỉ nghĩ đến migration. Hãy liệt kê cả:

  • console production,
  • backfill data,
  • cleanup scripts,
  • repair scripts,
  • one-time reindex,
  • scheduled maintenance tasks.

Nếu nó thay đổi dữ liệu hoặc trạng thái ứng dụng ngoài luồng request thông thường, rất có thể nó thuộc nhóm admin process.

Bước 2: Đưa chúng vào cùng codebase

Tác vụ quản trị phải sống cùng repo, cùng dependency graph, cùng quy trình review và release với app chính. Đây là yêu cầu gốc của Twelve-Factor.

Bước 3: Chạy chúng như one-off processes

  • Trên Heroku: dùng one-off dynos.
  • Trên Kubernetes: dùng Job cho one-time task, CronJob cho scheduled task.

Bước 4: Bảo đảm cùng release, cùng config

Đây là phần quan trọng nhất. Dù dùng nền tảng nào, admin process vẫn phải nhìn thấy đúng code và đúng config của deploy mục tiêu.

Bước 5: Không biến admin task thành “một app bí mật thứ hai”

Nếu bạn thấy mình có một repo riêng chỉ để migration, hoặc một image riêng chỉ để sửa dữ liệu, đó là tín hiệu đỏ. Factor XII muốn những tác vụ này là one-off processes của app, không phải một hệ thống lạ đứng cạnh app.

14) Diễn giải trong bối cảnh hiện đại

Trong bối cảnh cloud-native, Factor XII càng dễ thấy giá trị hơn:

  • app được release theo artifact rõ ràng,
  • runtime environment có thể tạo process tạm thời rất nhanh,
  • platform có primitive sẵn như one-off dynos, Jobs, CronJobs.

Điều đó làm cho tư tưởng của Twelve-Factor trở nên rất tự nhiên:

  • việc quản trị không còn là “SSH vào máy chạy tay”,
  • mà là “spin up một process đúng chuẩn, làm xong rồi dừng”.

Cần phân biệt rõ:

  • Nguyên lý gốc: run admin/management tasks as one-off processes.
  • Diễn giải hiện đại: one-off dynos, Jobs, CronJobs là các cơ chế platform hiện đại hiện thực hóa nguyên lý đó.

15) Checklist tự đánh giá

Hãy tự hỏi về ứng dụng của bạn:

  • Migration của tôi có chạy bằng cùng release với app không?
  • Script sửa dữ liệu có nằm trong cùng codebase không?
  • Console production có dùng đúng config của deploy hiện tại không?
  • Scheduled tasks của tôi có đang chạy như một phần chính thức của hệ sinh thái app không, hay là “cron bí mật” trên một máy nào đó?
  • Tôi có đang phụ thuộc vào một vài cá nhân biết cách chạy các tác vụ admin, thay vì có quy trình rõ ràng không? Đây là suy luận thực hành trực tiếp từ yêu cầu đồng bộ code/config/release của Twelve-Factor.

Nếu bạn thấy 2–3 câu trên trả lời chưa chắc, Factor XII của hệ thống đó còn khá yếu.

16) Tóm tắt nhanh

  • Admin processes là các tác vụ quản trị như migration, console, data fix scripts.
  • Chúng phải chạy như one-off processes trong môi trường giống hệt app chính.
  • Chúng phải dùng cùng release, cùng codebase, cùng config.
  • Admin code phải ship cùng application code để tránh lệch pha.
  • Heroku one-off dynos và Kubernetes Jobs/CronJobs là hai ví dụ rất rõ cho cách hiện thực hóa nguyên lý này ngày nay.

17) Nguồn tham khảo