Documenting Services (การทำเอกสาร Service)
ด้วย การแบ่งระบบของเราออกเป็นไมโครเซอร์วิสที่ละเอียดขึ้น เราหวังว่าจะเปิดเผยรอยต่อมากมายในรูปแบบของ API ที่คนสามารถใช้เพื่อทำสิ่งที่ หวังว่าจะยอดเยี่ยมได้มากมาย ถ้าคุณทำ discovery ของเราถูกต้อง เราก็รู้ว่าสิ่งต่างๆ อยู่ที่ไหน แต่เราจะรู้ได้อย่างไรว่าสิ่งเหล่านั้น ทำอะไรหรือใช้อย่างไร ตัวเลือกหนึ่งที่ชัดเจนคือการมีเอกสารเกี่ยวกับ API แน่นอนว่าเอกสารมักจะล้าสมัยได้บ่อยๆ ในอุดมคติ เรา อยากมั่นใจว่าเอกสารของเราทันสมัยอยู่เสมอกับ microservice API และทำให้ง่ายที่จะเห็นเอกสารนี้เมื่อเรารู้ว่า service endpoint อยู่ที่ไหน
Explicit Schemas (Schema ที่ชัดเจน)
การมี schema ที่ชัดเจนช่วยได้มากในการทำให้เข้าใจง่ายขึ้นว่า endpoint หนึ่งๆ เปิดเผยอะไร แต่ด้วยตัวมันเองมักไม่เพียงพอ อย่างที่เราคุยกันไป schema ช่วยแสดงโครงสร้าง แต่มันไม่ได้ช่วยมากนักในการสื่อสารพฤติกรรมของ endpoint ดังนั้นเอกสารที่ดีก็ยังคงจำเป็นเพื่อช่วยให้ ผู้เรียกใช้เข้าใจวิธีใช้ endpoint แน่นอนว่าควรสังเกตว่าถ้าคุณตัดสินใจไม่ใช้ schema ที่ชัดเจน เอกสารของคุณก็จะจบลงด้วยการต้องทำงาน มากขึ้น คุณจะต้องอธิบายว่า endpoint ทำอะไรและยังต้องบันทึกโครงสร้างและรายละเอียดของ interface ด้วย ยิ่งไปกว่านั้น หากไม่มี schema ที่ชัดเจน การตรวจจับว่าเอกสารของคุณทันสมัยกับ endpoint จริงหรือไม่ก็ยากขึ้น เอกสารที่ล้าสมัยเป็นปัญหาต่อเนื่อง แต่อย่างน้อย schema ที่ชัดเจนก็ให้โอกาสมากขึ้นที่มันจะทันสมัยอยู่
ผม ได้แนะนำ OpenAPI ในฐานะ schema format ไปแล้ว แต่มันก็มีประสิทธิภาพมากในการให้เอกสารด้วยเช่นกัน และตอนนี้มีเครื่องมือ open source และเชิงพาณิชย์มากมายที่รองรับการใช้ OpenAPI descriptor เพื่อช่วยสร้าง portal ที่มีประโยชน์ให้นักพัฒนาอ่านเอกสารได้ ควรสังเกตว่า open source portal สำหรับดู OpenAPI ดูเหมือนจะค่อนข้างพื้นฐาน—ผมดิ้นรนที่จะหาตัวที่รองรับ search functionality ตัวอย่างเช่น สำหรับผู้ที่อยู่บน Kubernetes developer portal ของ Ambassador น่าสนใจเป็นพิเศษ Ambassador เป็นตัวเลือกยอดนิยมอยู่แล้วในฐานะ API gateway สำหรับ Kubernetes และ Developer Portal ของมันมีความสามารถในการ autodiscover OpenAPI endpoint ที่มีอยู่ แนวคิดของการ deploy ไมโครเซอร์วิสใหม่แล้วให้เอกสาร ของมันพร้อมใช้โดยอัตโนมัติดึงดูดผมมาก
ในอดีตเราขาดการรองรับที่ดีสำหรับการทำเอกสาร event-based interface ตอนนี้อย่างน้อยเราก็มีตัวเลือก AsyncAPI format เริ่มต้น จากการดัดแปลงมาจาก OpenAPI และตอนนี้เราก็มี CloudEvents ด้วยเช่นกัน ซึ่งเป็นโปรเจกต์ของ CNCF ผมยังไม่ได้ใช้ทั้งสองอย่างจริงจัง (นั่นคือ ในสถานการณ์จริง) แต่ผมค่อนข้างเอนเอียงไปทาง CloudEvents เพียงเพราะมันดูเหมือนจะมีการ integrate และการรองรับที่มากมาย ส่วนใหญ่เป็นเพราะความเกี่ยวข้องกับ CNCF อย่างน้อยในอดีต CloudEvents ดูเหมือนจะจำกัดกว่าในแง่ของ event format เมื่อเทียบกับ AsyncAPI โดยมีแค่ JSON ที่ได้รับการรองรับอย่างถูกต้อง จนกระทั่งการรองรับ protocol buffer ถูกนำกลับมาใช้ใหม่เมื่อไม่นานมานี้ หลังจากที่เคยถูกลบออกไปก่อนหน้านี้ ดังนั้นนั่นอาจเป็นข้อพิจารณาหนึ่ง
The Self-Describing System (ระบบที่อธิบายตัวเองได้)
ระหว่าง วิวัฒนาการช่วงแรกๆ ของ SOA มาตรฐานอย่าง Universal Description, Discovery, and Integration (UDDI) ผุดขึ้นมาเพื่อช่วยให้เราเข้าใจ ว่า service อะไรกำลังรันอยู่ แนวทางเหล่านี้ค่อนข้างหนักหน่วง ซึ่งนำไปสู่เทคนิคทางเลือกในการพยายามทำความเข้าใจระบบของเรา Martin Fowler ได้คุยถึงแนวคิดของ humane registry ซึ่งเป็นแนวทางที่เบากว่ามากที่มนุษย์สามารถบันทึกข้อมูลเกี่ยวกับ service ในองค์กรลงในสิ่งที่พื้นฐานอย่าง wiki ได้
การได้ภาพของระบบของเราและวิธีที่มันทำงานเป็นสิ่งสำคัญ โดยเฉพาะเมื่อเราอยู่ในระดับ scale เราได้ครอบคลุมเทคนิคที่แตกต่างกัน จำนวนหนึ่งที่จะช่วยให้เราได้ความเข้าใจโดยตรงจากระบบของเรา ด้วยการติดตามสุขภาพของ downstream service ของเราร่วมกับ correlation ID เพื่อช่วยให้เราเห็น call chain เราสามารถได้ข้อมูลจริงในแง่ของวิธีที่ service ของเราเกี่ยวข้องกัน การใช้ระบบ service discovery อย่าง Consul เราสามารถเห็นได้ว่าไมโครเซอร์วิสของเรารันอยู่ที่ไหน กลไกอย่าง OpenAPI และ CloudEvents สามารถช่วยเราเห็นว่ามี capability อะไรบ้างที่ถูก host อยู่บน endpoint หนึ่งๆ ในขณะที่หน้า health check และระบบ monitoring ของเราให้เรารู้สุขภาพของ ทั้งระบบโดยรวมและ service แต่ละตัว
ข้อมูลทั้งหมดนี้พร้อมใช้แบบ programmatic ข้อมูลทั้งหมดนี้ทำให้เราสามารถทำให้ humane registry ของเรามีพลังมากกว่าแค่หน้า wiki ธรรมดาที่ไม่ต้องสงสัยเลยว่าจะล้าสมัย แทนที่จะเป็นแบบนั้น เราควรใช้มันเพื่อควบคุมและแสดงข้อมูลทั้งหมดที่ระบบของเราจะปล่อยออกมา ด้วยการสร้าง dashboard แบบกำหนดเอง เราสามารถรวบรวมข้อมูลมากมายที่มีอยู่เพื่อช่วยให้เราเข้าใจ ecosystem ของเรา
เชิญเริ่มต้นด้วยอะไรง่ายๆ อย่างหน้าเว็บแบบ static หรือ wiki ที่บางทีอาจดึงข้อมูลเล็กน้อยจากระบบจริงมา แต่ให้มองหาที่จะดึงข้อมูล เพิ่มขึ้นเรื่อยๆ เมื่อเวลาผ่านไป การทำให้ข้อมูลนี้พร้อมใช้ง่ายเป็นเครื่องมือสำคัญในการจัดการความซับซ้อนที่กำลังเกิดขึ้นซึ่งจะมาจาก การรันระบบเหล่านี้ในระดับ scale
ผมเคยคุยกับหลายบริษัทที่เคยมีปัญหาเหล่านี้และจบลงด้วยการสร้าง registry ภายในแบบง่ายๆ เพื่อช่วยรวบรวม metadata เกี่ยวกับ service บาง registry เหล่านี้แค่ crawl source code repository เพื่อหาไฟล์ metadata ในการสร้างรายการ service ที่มีอยู่ ข้อมูลนี้สามารถ ถูกรวมเข้ากับข้อมูลจริงที่มาจากระบบ service discovery อย่าง Consul หรือ etcd เพื่อสร้างภาพที่สมบูรณ์ยิ่งขึ้นว่ามีอะไรกำลังรัน อยู่และคุณสามารถคุยกับใครได้บ้างเกี่ยวกับมัน
Financial Times สร้าง Biz Ops เพื่อช่วยแก้ปัญหานี้ บริษัทมี service หลายร้อยตัวที่พัฒนาโดยทีมทั่วโลก เครื่องมือ Biz Ops ( Figure 5-8 ) ให้บริษัทมีที่เดียวที่คุณสามารถหาข้อมูลที่มีประโยชน์มากมายเกี่ยวกับไมโครเซอร์วิสของมันได้ นอกเหนือจากข้อมูลเกี่ยวกับ IT infrastructure service อื่นๆ เช่น network และ file server สร้างขึ้นบน graph database Biz Ops มีความยืดหยุ่นมากเกี่ยวกับ ข้อมูลที่มันรวบรวมและวิธีที่ข้อมูลสามารถถูก model ได้
Figure 5-8. The Financial Times Biz Ops tool, which collates information about its microservices (เครื่องมือ Biz Ops ของ Financial Times ซึ่งรวบรวมข้อมูลเกี่ยวกับไมโครเซอร์วิสของมัน)
อย่างไรก็ตาม เครื่องมือ Biz Ops ไปไกลกว่าเครื่องมือคล้ายๆ กันส่วนใหญ่ที่ผมเคยเห็น เครื่องมือนี้คำนวณสิ่งที่มันเรียกว่า System Operability Score ดังแสดงใน Figure 5-9 แนวคิดคือมีบางสิ่งที่ service และทีมของพวกมันควรทำเพื่อให้แน่ใจว่า service สามารถถูกดำเนินการได้ง่าย ซึ่งอาจครอบคลุมตั้งแต่ การทำให้แน่ใจว่าทีมได้ให้ข้อมูลที่ถูกต้องใน registry ไปจนถึงการทำให้แน่ใจว่า service มี health check ที่เหมาะสม System Operability Score เมื่อคำนวณแล้ว จะทำให้ทีมสามารถเห็นได้ในแวบเดียวว่ามีอะไรที่ต้องแก้ไข
นี่ เป็นพื้นที่ที่กำลังเติบโต ในโลก open source เครื่องมือ Backstage ของ Spotify เสนอกลไกสำหรับสร้าง service catalog แบบ Biz Ops พร้อมกับโมเดล plug-in ที่ให้เพิ่มเติมได้อย่างซับซ้อน เช่น ความสามารถในการ trigger การสร้างไมโครเซอร์วิสใหม่ หรือดึงข้อมูลสดจาก Kubernetes cluster Service Catalog ของ Ambassador เอง มุ่งเน้นแคบกว่าไปที่การมองเห็น service ใน Kubernetes ซึ่งหมายความว่ามันอาจไม่มีความน่าสนใจโดยทั่วไปมากเท่า กับอะไรอย่าง Biz Ops ของ FT แต่ก็ยังดีที่ได้เห็นแนวคิดใหม่ๆ ในเรื่องนี้ที่พร้อมใช้งานโดยทั่วไปมากขึ้น
