Tài liệu ZStack Xây dựng và thực hành nền tảng DevOps

I. Giới thiệu

Tài liệu là một thành phần quan trọng của sản phẩm phần mềm. Tài liệu sản phẩm, chẳng hạn như ghi chú phát hành, hướng dẫn sử dụng, tài liệu tham khảo API, hướng dẫn cài đặt và hướng dẫn dựa trên kịch bản, giúp người dùng nhanh chóng hiểu và áp dụng sản phẩm. Sự tích hợp chặt chẽ giữa phần mềm và tài liệu đặt ra một thách thức cho các công ty: làm thế nào để duy trì quy trình làm việc tài liệu nhanh chóng và hiệu quả trong bối cảnh kinh doanh thay đổi nhanh chóng và cập nhật phần mềm thường xuyên.

Bài viết này khám phá cách ZStack xây dựng thành công nền tảng Documentation DevOps của mình để tối ưu hóa quy trình làm việc về tài liệu. Nó trình bày chi tiết về phương pháp viết có cấu trúc của ZStack, chiến lược kiểm soát phiên bản, kiến ​​trúc nền tảng DevOps cũng như các thách thức và giải pháp trong quá trình xây dựng nền tảng.

II. Nền tảng của tài liệu DevOps: Viết có cấu trúc

Trong phát triển phần mềm, “Docs as Code” là một phương pháp được chấp nhận rộng rãi. Nguyên tắc cốt lõi của nó là coi tài liệu dưới dạng mã và tích hợp nó vào vòng đời phát triển phần mềm. Các phương pháp viết truyền thống, thiếu mô-đun hóa và tiêu chuẩn hóa, thường không đáp ứng được yêu cầu về tính hiệu quả của “Docs as Code”. Do đó, văn bản có cấu trúc đã nổi lên như một giải pháp hiệu quả để cải thiện hiệu quả phát triển và phát hành tài liệu.

Viết có cấu trúc nhấn mạnh vào kiến trúc thông tin. DITA (Kiến trúc gõ thông tin Darwin), ban đầu được IBM phát triển và được OASIS áp dụng làm tiêu chuẩn mở vào năm 2005, là một tiêu chuẩn quốc tế được sử dụng rộng rãi cho văn bản có cấu trúc. Là một khung dựa trên XML, DITA cung cấp các khả năng quan trọng, bao gồm tách rời định dạng nội dung, tái sử dụng nội dung, lọc và tùy chỉnh, nâng cao đáng kể tính linh hoạt và tiêu chuẩn hóa của việc phát triển tài liệu.      

Hình 1: Đặc điểm của DITA

1. Tách định dạng nội dung

Trong tài liệu có định dạng DITA, thông tin được tổ chức thành các thành phần mô-đun. DITA xác định nhiều loại mô-đun để cấu trúc thông tin theo cấp bậc. Sau đây là các loại mô-đun thường được sử dụng:

• DITAMAP: DITAMAP, thường được sử dụng ở cấp cao nhất, đóng vai trò là khung của tài liệu. Nó xác định những chủ đề nào được bao gồm và cách chúng được tổ chức trong tài liệu.
• CHỦ ĐỀ: CHỦ ĐỀ có chức năng như một chương trong tài liệu. Để phù hợp với các kịch bản viết khác nhau, DITA sử dụng cơ chế DTD để phân loại chủ đề thành nhiều loại khác nhau, chẳng hạn như Khái niệm, Nhiệm vụ, Khắc phục sự cố và Tham chiếu, đồng thời xác định cấu trúc cơ bản của từng loại chủ đề (cụ thể là các nhãn phải hoặc không thể chứa trong một loại chủ đề). Điều này đảm bảo tính tiêu chuẩn hóa và tính nhất quán giữa các chủ đề phục vụ các tình huống tương tự.
• NHÃN: NHÃN đại diện cho bất kỳ thành phần nội dung nào trong CHỦ ĐỀ - bao gồm các đoạn văn, câu, cụm từ, danh sách, bảng và hình ảnh. Nhiều NHÃN kết hợp để tạo thành một CHỦ ĐỀ hoàn chỉnh.

Trong quá trình phát triển tài liệu, người viết kỹ thuật thiết lập kiến trúc tài liệu ở cấp độ DITAMAP và CHỦ ĐỀ, đồng thời viết nội dung ở cấp độ LABEL. Điều này đảm bảo chúng hoạt động trong một khuôn khổ tiêu chuẩn hóa và tạo ra các tài liệu được tổ chức tốt với hệ thống phân cấp rõ ràng.

Hình 2: CHỦ ĐỀ DTD

2. Tái sử dụng nội dung

DITA hỗ trợ tái sử dụng nội dung ở các cấp độ mô-đun khác nhau, bao gồm DITAMAP, TOPIC và LABEL.

• Tái sử dụng DITAMAP: Một DITAMAP (ví dụ: DITAMAP A) có thể được lồng vào một DITAMAP khác  (ví dụ: DITAMAP B). Do đó, DITAMAP B sử dụng lại tất cả nội dung từ DITAMAP A và giữ nguyên cấu trúc được xác định trong DITAMAP A.
• CHỦ ĐỀTái sử dụng: Một CHỦ ĐỀ có thể được đưa vào nhiều DITAMAP. Do đó, tất cả các DITAMAP này đều có chung CHỦ ĐỀ.
• NHÃN: Một NHÃN có thể được tham chiếu trên nhiều CHỦ ĐỀ. Do đó, tất cả các chủ đề này đều có chung một câu, bảng, hình ảnh hoặc các thành phần khác.

Trong quá trình cập nhật tài liệu, cơ chế tái sử dụng giúp giảm nỗ lực dư thừa và đảm bảo tính nhất quán của thông tin. Khi nội dung nguồn được sửa đổi, tất cả các tài liệu tham khảo sẽ tự động được đồng bộ hóa.

Trong tài liệu của ZStack, các thành phần chính như tên sản phẩm, phiên bản và thuật ngữ được quản lý tập trung trong tệp nguồn sử dụng lại. Khi cần cập nhật, người viết kỹ thuật chỉ cần sửa đổi nguồn tái sử dụng.

Hình 3: Tái sử dụng CHỦ ĐỀ

3. Lọc và tùy chỉnh

Trong quá trình phát hành tài liệu, các tệp cấu hình (DITAVAL và DITA-OT) kiểm soát nội dung và cách trình bày các sản phẩm bàn giao. Bằng cách chỉnh sửa các tệp này,  người viết kỹ thuật có thể tạo tài liệu với nhiều định dạng, ấn bản, kiểu và nội dung khác nhau từ cùng một DITAMAP, cho phép tùy chỉnh linh hoạt cho nhiều kênh xuất bản và yêu cầu kinh doanh khác nhau.

• DITAVAL:Cho phép tùy chỉnh nội dung thông qua lọc có điều kiện. Người viết kỹ thuật có thể gắn thẻ CHỦ ĐỀ hoặc NHÃN và xác định các quy tắc bao gồm/loại trừ trong DITAVAL để xác định nội dung được gắn thẻ nào sẽ xuất hiện trong các sản phẩm phân phối cuối cùng.
• DITA-OT: Xác định cách trình bày trực quan của các sản phẩm phân phối, bao gồm định dạng tài liệu, bìa, loại phông chữ, cỡ chữ, màu sắc, đầu trang và chân trang.

Theo tiêu chuẩn DITA, ZStack đã phát triển một hệ thống tài liệu có cấu trúc quy mô lớn chứa hàng chục triệu ký tự. Việc mô-đun hóa và tiêu chuẩn hóa hệ thống đặt nền tảng vững chắc cho việc xây dựng nền tảng DevOps.

Hình 4: Hệ thống tài liệu có cấu trúc

III. Chiến lược kiểm soát phiên bản tài liệu

ZStack tận dụng kho lưu trữ Git để kiểm soát phiên bản tài liệu.

Là một hệ thống kiểm soát phiên bản phân tán được sử dụng rộng rãi trong ngành công nghiệp phần mềm, Git cho phép cộng tác bằng cách cho phép các nhà phát triển cam kết và đẩy công việc cục bộ đến kho lưu trữ từ xa và tìm nạp các bản cập nhật mới nhất. Khả năng phân nhánh mạnh mẽ của Git cho phép nhiều nhánh trong một kho lưu trữ duy nhất, mỗi nhánh dành riêng cho một nhiệm vụ cụ thể. Điều này cho phép các nhà phát triển làm việc song song trên nhiều tác vụ mà không bị can thiệp. Khi cần thiết, các nhánh này có thể được hợp nhất để hợp nhất mã.

Hãy lấy tài liệu của ZStack Cloud làm ví dụ để chứng minh cách hoạt động của cơ chế phân nhánh này trong việc phát triển tài liệu. Khi bắt đầu chu kỳ phiên bản, người viết kỹ thuật tạo các nhánh tính năng dựa trên nhánh chính ổn định. Mỗi nhánh tính năng ghi lại một tính năng cụ thể. Khi một nhánh tính năng ổn định, nó sẽ được hợp nhất trở lại thành nhánh chính. Sau khi tất cả các nhánh tính năng được hợp nhất và nội dung nhánh chính được xác minh là sẵn sàng phát hành, một nhánh phát hành sẽ được tạo từ nhánh chính cho bản phát hành cuối cùng.

Trong quá trình này, người viết kỹ thuật cũng có thể xử lý các nhu cầu cấp thiết một cách linh hoạt bằng cách tạo các nhánh sửa lỗi để sửa lỗi hoặc các nhánh phát hành tùy chỉnh để cung cấp tài liệu phù hợp cho các dự án quan trọng.

Hình 5: Nhánh tài liệu đám mây ZStack

Bằng cách triển khai kiểm soát phiên bản dựa trên Git, quy trình làm việc tài liệu của ZStack có thể so sánh với việc phát triển mã phần mềm về mặt tiêu chuẩn hóa và khả năng quản lý, củng cố hơn nữa nền tảng cho nền tảng DevOps.

IV. Phương pháp thiết kế của Nền tảng DevOps Tài liệu ZStack

Với việc kiểm soát phiên bản và nội dung có cấu trúc, hệ thống tài liệu của ZStack đã sẵn sàng để triển khai CI/CD và tạo nền tảng cho nền tảng Documentation DevOps.

Trong phát triển phần mềm, CI/CD là một giải pháp tự động để tích hợp, thử nghiệm và triển khai mã liên tục, cho phép phân phối phần mềm nhanh chóng và đáng tin cậy. Mở rộng khái niệm này sang tài liệu, tài liệu CI/CD tự động hóa việc xây dựng, lưu trữ và trả lại tài liệu hàng loạt, cung cấp giải pháp một cửa để phân phối tài liệu nhanh chóng, đáng tin cậy và chất lượng cao.

Nền tảng DevOps Tài liệu ZStack được xây dựng trên kiến trúc microservice. Nó tận dụng ZStack Cloud và Kubernetes（K8s để chứa dịch vụ và điều phối động, tự động hóa toàn bộ quy trình phân phối tài liệu thông qua việc lập kế hoạch phối hợp giữa các dịch vụ vi mô.

Hình 6: Kiến trúc nền tảng DevOps của tài liệu ZStack

1. Cơ chế bảo mật

• Proxy ngược mạng nội bộ/bên ngoài

Ánh xạ các cổng máy chủ proxy Flask của mạng nội bộ tới các cổng bên ngoài để cho phép truy cập bên ngoài an toàn (trong một số trường hợp, người nộp đơn cần đăng ký và nhận tài liệu thông qua nền tảng bên ngoài) trong khi vẫn duy trì sự cách ly nghiêm ngặt giữa mạng nội bộ/bên ngoài. Giải pháp này đảm bảo tính bảo mật của dịch vụ nội bộ bằng cách chỉ hiển thị các API dịch vụ và xác minh tất cả các yêu cầu bên ngoài thông qua proxy ngược.

2. APILớp

• Máy chủ proxy Flask

Ban đầu xử lý các yêu cầu, phân tích các tham số yêu cầu, kích hoạt các bản dựng tài liệu và truy xuất các bản ghi bản dựng tài liệu.

• Xây dựng giao diện quản lý tác vụ

Cung cấp giao diện trực quan cho người viết kỹ thuật để quản lý cấu hình ánh xạ tài liệu (mối quan hệ ánh xạ giữa các tệp thiết yếu cần thiết cho quá trình xây dựng tài liệu, bao gồm DITAMAP, DITA-OT và DITAVAL) và để kích hoạt các tác vụ xây dựng tài liệu theo cách thủ công.

3. Lớp cơ sở hạ tầng

• Cụm DevOps

Một nền tảng để quản lý môi trường sản xuất nội bộ của công ty, tích hợp các quy trình CI/CD.

• Cụm Jenkins K8s

Thực hiện xây dựng tài liệu trong đơn vị nhiệm vụ.

• Cơ sở dữ liệu

Lưu trữ các tham số tác vụ, bản ghi thực thi và Siêu dữ liệu.

4. Lớp thực thi tác vụ

• Yêu cầu xử lý tham số
• Tiêu chuẩn hóa thông số

Xác thực các tham số yêu cầu, sửa đổi/lọc các tham số không tuân thủ và xử lý trước các tham số tuân thủ để sử dụng trong các luồng tiếp theo.

• Phân bổ không gian làm việc
• Cách ly mã tài liệu

Sử dụng nhiều không gian làm việc để đạt được sự tách biệt mã, mỗi mã quản lý không gian làm việc sẽ tìm nạp từ một nhánh tài liệu cụ thể.

• Sửa đổi tập tin cấu hình tài liệu
• Sửa đổi tham số DITA-OT/DITAVAL

Tự động điều chỉnh các tham số trong tệp DITAVAL và DITA-OT để đáp ứng các yêu cầu kinh doanh khác nhau.

• Xây dựng tài liệu
• Tạo nhật ký

Tạo nhật ký được tiêu chuẩn hóa và trực quan hóa bao gồm các tham số DITAVAL/DITA-OT và đầu ra DITA-OT. Những nhật ký này được sử dụng để xác minh xem quá trình xây dựng có thành công hay không.

• Tạo tài liệu

Tạo tài liệu theo yêu cầu và tải chúng lên bộ lưu trữ đối tượng MINIO.

V. Những thách thức và giải pháp trong quá trình xây dựng nền tảng DevOps

1. Xung đột cấu hình trong các bản dựng hàng loạt

Để đảm bảo tính hiệu quả và tiêu chuẩn hóa của việc xây dựng tài liệu, nền tảng DevOps xây dựng tài liệu theo đơn vị nhiệm vụ. Mỗi tác vụ bao gồm việc xây dựng song song nhiều tài liệu có thể chia sẻ cùng một tệp DITAVAL/DITA-OT nhưng yêu cầu các tham số DITAVAL/DITA-OT khác nhau.

Để giải quyết xung đột này, nền tảng DevOps giới thiệu cơ chế không gian làm việc, nhóm các tài liệu yêu cầu cùng tham số DITAVAL/DITA-OT vào cùng một không gian làm việc và định cấu hình DITAVAL/DITA-OT tương ứng cho từng không gian làm việc.、

2. Bảo trì động các tệp cấu hình

Các tham số trong tệp cấu hình (DITAVAL và DITA-OT) thay đổi tùy theo yêu cầu kinh doanh – chẳng hạn như các tham số được sử dụng để xác định tên sản phẩm và nhãn hiệu trong sản phẩm bàn giao. Để đáp ứng nhu cầu kinh doanh đa dạng, các thông số này phải linh hoạt và dễ bảo trì. Nền tảng DevOps sử dụng bộ tệp cấu hình chuyên dụng để quản lý tập trung các tham số này. Do đó, việc điều chỉnh tham số có thể được thực hiện trong bộ tệp này, loại bỏ nhu cầu sửa đổi thường xuyên đối với mã CI/CD.

Ngoài ra, nền tảng DevOps duy trì các tệp DITA-OT tập trung trên một nhánh chuyên dụng của kho lưu trữ tài liệu. Trong quá trình xây dựng tài liệu, nền tảng sẽ thay thế các tệp DITA-OT trong mỗi không gian làm việc bằng các tệp từ nhánh chuyên dụng, giảm thiểu các thay đổi đối với nội dung trên các nhánh tài liệu chính.

3. Tối ưu hóa nhật ký

Nhiệm vụ xây dựng tài liệu có thể liên quan đến việc xây dựng nhiều tài liệu. Khi một tác vụ không thành công hoặc một số tài liệu nhất định gặp lỗi, người viết kỹ thuật sẽ khó xác định và phân tích nguyên nhân gốc rễ trong nhật ký mở rộng.

Để giải quyết thách thức này, nền tảng DevOps cải thiện khả năng đọc nhật ký. Sau khi tác vụ xây dựng hoàn tất, nền tảng sẽ tự động tạo tệp nhật ký toàn diện và trực quan tóm tắt đầu ra DITA-OT và cấu hình DITAVAL cho tất cả tài liệu trong tác vụ, cho phép người viết kỹ thuật nhanh chóng xác định và phân tích mọi vấn đề.

VI. Giá trị của Nền tảng DevOps Tài liệu ZStack

1. Cho phép quản lý trực quan và thuận tiện quá trình phát hành tài liệu

Nền tảng DevOps cung cấp giải pháp toàn diện để phát hành tài liệu – từ quản lý cấu hình ánh xạ tài liệu, kích hoạt quá trình xây dựng tài liệu, theo dõi tiến trình xây dựng cho đến chẩn đoán sự cố. Nền tảng này sử dụng giao diện người dùng hợp nhất để trực quan hóa và hợp lý hóa quy trình phát hành tài liệu, cho phép quản lý các quy trình phức tạp một cách dễ dàng.

Hình 7: Quản lý cấu hình ánh xạ tài liệu

Hình 8: Quản lý tác vụ xây dựng tài liệu

Hình 9: Nhật ký trực quan

2. Nâng cao hiệu suất và hiệu quả phát hành tài liệu

Tận dụng sức mạnh của cụm DevOps, nền tảng DevOps cung cấp khả năng tính toán mạnh mẽ và lập lịch tài nguyên linh hoạt để xây dựng tài liệu, giảm đáng kể thời gian xây dựng. Sự cải tiến này đặc biệt đáng chú ý trong các bản dựng tài liệu quy mô lớn. Ví dụ: khi phát hành hệ thống tài liệu ZStack Cloud đầy đủ, nền tảng DevOps giảm 50% thời gian xây dựng so với các phương thức phát hành truyền thống.

Ngoài ra, Nền tảng DevOps còn tích hợp với nền tảng ứng viên bên ngoài. Nhân viên kinh doanh có thể gửi ứng dụng từ nền tảng này và tự động kích hoạt việc tùy chỉnh, xây dựng và phân phối tài liệu. Trong quá trình này, người viết kỹ thuật chỉ cần xem lại kết quả xây dựng và giải quyết các tác vụ bị lỗi.

VII.  Kết luận

Tối ưu hóa quy trình làm việc là động lực quan trọng cho hiệu quả của doanh nghiệp. Nhóm Tài liệu ZStack tiếp tục khám phá và triển khai các phương pháp quản lý và phát triển tài liệu linh hoạt.

Trong thời đại công nghệ tiến bộ nhanh chóng, việc tận dụng các công nghệ mới để thúc đẩy đổi mới công cụ dựa trên yêu cầu kinh doanh và tích hợp chiến lược các công cụ này vào quy trình làm việc hàng ngày là điều cần thiết để tăng năng suất và hiệu quả. Đây là một thách thức quan trọng mà mọi chuyên gia hiện đại phải giải quyết. Hãy cùng nhau tiến về phía trước.