เข้าสู่ระบบนัดหมายรับฟังข้อมูลสรุป (or นัดหมายพูดคุยกับทีมงาน)

บทที่ 2.5

การตรวจสอบความพร้อม (Preflight) ด้วย nexusctl

ทุกการตรวจสอบที่ `nexusctl preflight` ทำ สิ่งที่แต่ละรายการอ่านและสาเหตุที่ทำให้ล้มเหลว รายงานที่พิมพ์และบันทึก วิธีที่รายงานนั้นไปถึงหน้าการตรวจสอบความพร้อมของคอนโซล และทุกแฟล็ก

หน้านี้แปลโดย AI จากต้นฉบับภาษาอังกฤษ หากมีส่วนใดไม่ชัดเจน โปรดอ้างอิงจากหน้าภาษาอังกฤษ อ่านหน้านี้เป็นภาษาอังกฤษ

ใช้เวลาอ่าน 16 นาที

การรัน preflight ครั้งแรกของเราที่ Harrow Port Authority ไม่ผ่านการตรวจสอบ 4 รายการ และ 2 รายการในนั้นคงทำให้เราเสียเวลามากกว่าแค่ช่วงบ่ายหนึ่งแน่ๆ เราเริ่มต้นสร้างไฟล์ values โดยคัดลอกมาจากตัวอย่างของ chart และ preflight ก็ปฏิเสธทั้งชื่อการติดตั้งตัวอย่างและผู้ดูแลกุญแจ (custodian) ตัวอย่าง ไม่มีใครถือไพรเวตคีย์ของผู้ดูแลกุญแจคนนั้น การติดตั้งที่ถูกปิดผนึก (seal) ด้วยคีย์นั้นจะไม่สามารถเปิดผนึก (unseal) ได้อีกเลยหลังจากรีสตาร์ทโหนด Preflight ตรวจพบเรื่องนี้ในเวลาไม่กี่วินาที ก่อนที่จะมีสิ่งใดถูกสร้างขึ้นจนเกิดความเสียหาย

nexusctl preflight จะอ่านคลัสเตอร์และไฟล์ values ของคุณ พิมพ์สิ่งที่พบ บันทึกรายงาน และไม่เปลี่ยนแปลงสิ่งใดบนคลัสเตอร์ ให้รันคำสั่งนี้ก่อนการติดตั้งและการอัปเกรดทุกครั้ง บทนี้ครอบคลุมการตรวจสอบทุกรายการ รูปแบบรายงาน ตำแหน่งที่เก็บรายงาน และแฟล็กต่างๆ

การดูแลระบบให้ทำงาน

Preflight ต้องการสองสิ่ง ได้แก่ kube context ของคลัสเตอร์ที่คุณจะติดตั้ง และไฟล์ values ที่การติดตั้งจะใช้ ให้เขียนไฟล์ values ก่อน โดยในบทที่ 2.6 การติดตั้ง Community บน Kubernetes จะอธิบายทีละคีย์อย่างละเอียด จากนั้น:

nexusctl preflight --context harrow-prod --values harrow-values.yaml

เครื่องมือนี้จะอ่านข้อมูลคลัสเตอร์ผ่าน client-go ด้วยการเรียกใช้ get และ list เท่านั้น หาก tls.mode ของคุณเป็น existing ให้สร้างเนมสเปซ nexus และ Secret สำหรับ Transport Layer Security (TLS) ก่อนที่จะรันคำสั่ง (บทที่ 2.6 การติดตั้ง Community บน Kubernetes ขั้นตอนที่ 3) มิฉะนั้นการตรวจสอบใบรับรองจะรายงานว่าไม่พบ Secret

แฟล็ก สิ่งที่ทำ ค่าเริ่มต้น
--context <name> kube context ที่ต้องการตรวจสอบ (จำเป็น) ไม่มี
--values <file> ไฟล์ values ที่การติดตั้งจะใช้ (จำเป็น) ไม่มี
--namespace <name> ตำแหน่งที่ติดตั้ง Nexus nexus
--release <version> รีลีสที่กำลังตรวจสอบ เวอร์ชันของ chart ที่รวมมาด้วย
--report-dir <dir> ตำแหน่งที่บันทึกไฟล์รายงานทั้งสองไฟล์ โฟลเดอร์ปัจจุบัน
--record <mode> auto, always หรือ never: กำหนดว่าจะส่งมอบรายงานไปยังบริการจัดการคีย์ของการติดตั้งนี้หรือไม่ เพื่อให้หน้าตัวติดตั้งแสดงรายงานดังกล่าว auto
--kubeconfig <file> ไฟล์ kubeconfig ที่จะอ่าน KUBECONFIG จากนั้น ~/.kube/config
--ca-bundle <file> ใบรับรองของผู้ออกใบรับรอง (CA) ของคุณเอง สำหรับเชนที่การตรวจสอบควรเชื่อถือ ไม่มี
--single-node ตรวจสอบเครื่องเดียวสำหรับการติดตั้งแบบเครื่องเดียว (บทที่ 2.8 การติดตั้งแบบเครื่องเดียว) ปิด

เวอร์ชันขั้นต่ำของ Kubernetes สำหรับรีลีสนั้นไม่ได้ถูกระบุตายตัวไว้ใน nexusctl แต่จะอ่านค่าขั้นต่ำของ kubeVersion ของ chart เองจาก chart ที่พกมาด้วย ดังนั้นการตรวจสอบและ helm install จึงไม่มีทางขัดแย้งกัน

สิ่งที่การรันพิมพ์ออกมา

นี่คือการรันครั้งแรกของ Harrow ตามที่พิมพ์ออกมา:

Adverant Nexus 1.0.0-alpha.1 · preflight · Tue 10 Nov 2026 08:40 · read-only

Failed first
  FAIL  Address (api)             api.harrow.example → no record    people reach Nexus by this name
        fix  add a DNS record for api.harrow.example that points at the ingress, then run preflight again
  FAIL  Address (auth)            auth.harrow.example → no record   people reach Nexus by this name
        fix  add a DNS record for auth.harrow.example that points at the ingress, then run preflight again
  FAIL  Key custodians            the example custodian of the chart's values-community.yaml and values-enterprise.yaml (age1u63etg5v…)   the key store seals its recovery keys to them; no one holds the example custodian's key
        fix  replace it in keys.custody.recipients in harrow-values.yaml with your custodians' own recipients: each custodian makes a key on their own machine with `age-keygen -o custodian.key` (the `# public key: age1...` line is the recipient), or `age-plugin-se keygen --access-control=any-biometry -o custodian.key` for a Secure Enclave key, keeps the identity file offline, and gives you only the recipient
  FAIL  Installation name         nexus-example, the example name of the chart's values-community.yaml and values-enterprise.yaml   the first key-store bootstrap mints the installation identity under it, permanently
        fix  set keys.installationName in harrow-values.yaml to this installation's own name

Warnings
  warn  Graphics nodes            none                   the assistant will need a hosted model
        fix  add a node with a graphics card and its device plugin, or have the assistant use a hosted model
  warn  Certificate               secret harrow-public-tls not found in nexus   the public address needs it before people sign in
        fix  create the TLS secret harrow-public-tls in nexus before installing, or change tls.existingSecret in harrow-values.yaml

Passed
  pass  Kubernetes version        1.33.6+k3s1            needs 1.33 or later
  pass  Nodes ready               3 of 3
  pass  Storage class             local-path (default)
  pass  Resources                 24 cores, 93.9 GiB     needs 2.1 cores, 6.7 GiB
  pass  Ingress class             traefik (default)
  pass  Ingress ports             traefik (LoadBalancer) on 80 and 443
  pass  Address (console)         console.harrow.example → 10.20.4.10
────────────────────────────────────────────────────────────────────────────
7 passed · 2 warnings · 4 failed   Install cannot continue until the failures pass.
Nothing was changed. Report saved to preflight-2026-11-10-0840.txt

เมื่อมีรายการใดไม่ผ่าน รายการที่ล้มเหลวจะแสดงขึ้นก่อน ตามด้วยคำเตือน และรายการที่ผ่าน แต่ละแถวจะแสดงผลลัพธ์ ชื่อของการตรวจสอบ สิ่งที่พบ และสิ่งที่ต้องการ โดยทุกแถวที่ไม่ผ่านจะมีบรรทัด fix อยู่ด้านล่าง สองบรรทัดสุดท้ายคือข้อมูลสรุปและไฟล์รายงาน

เราได้แก้ไขค่าต่างๆ เพิ่มระเบียน Domain Name System (DNS) สองรายการ สร้าง Secret แล้วรันคำสั่งอีกครั้ง:

Adverant Nexus 1.0.0-alpha.1 · preflight · Thu 12 Nov 2026 09:02 · read-only

Cluster
  pass  Kubernetes version        1.33.6+k3s1            needs 1.33 or later
  pass  Nodes ready               3 of 3
  pass  Storage class             local-path (default)
  pass  Resources                 24 cores, 93.9 GiB     needs 2.1 cores, 6.7 GiB
  warn  Graphics nodes            none                   the assistant will need a hosted model
        fix  add a node with a graphics card and its device plugin, or have the assistant use a hosted model

Network
  pass  Ingress class             traefik (default)
  pass  Ingress ports             traefik (LoadBalancer) on 80 and 443
  pass  Address (console)         console.harrow.example → 10.20.4.10
  pass  Address (api)             api.harrow.example → 10.20.4.10
  pass  Address (auth)            auth.harrow.example → 10.20.4.10
  pass  Certificate               ends 3 Nov 2027

Time and keys
  pass  Key custodians            3 custodians
  pass  Installation name         harrow-port-authority
────────────────────────────────────────────────────────────────────────────
12 passed · 1 warning · 0 failed   You can install. Warnings do not block; fix them when you can.
Report saved to preflight-2026-11-12-0902.txt · nothing was changed on the cluster

การรันที่ไม่มีรายการล้มเหลวจะแสดงรายการตรวจสอบภายใต้สามหัวข้อ ได้แก่ Cluster, Network และ Time and keys คำเตือนจะไม่บล็อกการทำงาน เราเก็บคำเตือนเรื่องกราฟิกไว้โดยตั้งใจ เพราะบนคลัสเตอร์นำร่องที่เชื่อมต่อออนไลน์นี้ ผู้ช่วยของ Harrow ใช้โมเดลที่โฮสต์ไว้พร้อมคีย์ของท่าเรือเอง

ก่อนที่คุณจะติดตั้ง
ก่อนที่คุณจะติดตั้ง
Preflight ในเทอร์มินัลของผู้ปฏิบัติงาน พร้อมจำนวนนับอยู่ด้านข้าง สังเกตว่าทุกคำเตือนจะมีวิธีแก้ไขพิมพ์อยู่ด้านล่าง และการรันระบุไว้อย่างชัดเจนว่าไม่ได้เปลี่ยนแปลงสิ่งใดบนคลัสเตอร์

รหัสสถานะการจบการทำงาน (Exit Codes)

รหัส ความหมาย
0 สามารถดำเนินการติดตั้งต่อได้ คำเตือนจะไม่บล็อกการทำงาน
1 การติดตั้งถูกบล็อก: มีการตรวจสอบอย่างน้อยหนึ่งรายการล้มเหลว
2 ไม่สามารถรัน Preflight ได้: ไม่สามารถอ่าน kubeconfig, context, ไฟล์ values หรือส่วนต่อประสานโปรแกรมประยุกต์ (API) ของคลัสเตอร์ได้ หรือระบุแฟล็กไม่ถูกต้อง

สคริปต์ควรอ่านรหัสการออก (exit code) ไม่ใช่ข้อความ ของเราเองก็รัน preflight เป็นขั้นตอนแรกของทุกการอัปเกรด และจะหยุดทำงานทันทีหากได้ค่าอื่นที่ไม่ใช่ 0

ให้รัน nexusctl ของรีลีสที่คุณกำลังจะย้ายไป ไม่ใช่รีลีสที่คุณใช้ตอนติดตั้ง ข้อกำหนดต่างๆ มาจาก chart ที่พกมาด้วย ดังนั้นรีลีสที่ใหม่กว่าอาจปรับเกณฑ์ขั้นต่ำของ Kubernetes เพิ่มขึ้นหรือต้องการหน่วยความจำมากขึ้น ซึ่งมีเพียง nexusctl ของรีลีสนั้นเองที่ทราบ --release จะเปลี่ยนเฉพาะเวอร์ชันที่ระบุในรายงาน แต่ไม่ได้เปลี่ยนว่าจะใช้กฎของ chart ใด ที่ Harrow เราเก็บ nexusctl ของแต่ละรีลีสไว้คู่กับ chart ในบันทึกการเปลี่ยนแปลง เพื่อให้การย้อนกลับ (rollback) ได้รับการตรวจสอบด้วยเครื่องมือที่ตรงรุ่นกัน

ทุกการตรวจสอบ

มีการตรวจสอบทั้งหมดสิบเอ็ดรายการ สิบรายการแรกจะสร้างผลลัพธ์รายการละหนึ่งแถว ส่วนการตรวจสอบที่อยู่จะสร้างหนึ่งแถวต่อหนึ่งโฮสต์ ดังนั้นการรันแบบเต็มจะมีสิบสามแถว การตรวจสอบเก้ารายการต้องผ่าน และหากไม่ผ่านจะถือเป็นความล้มเหลว อีกสองรายการคือโหนดกราฟิกและใบรับรอง ควรจะผ่าน และหากไม่ผ่านจะถือเป็นคำเตือน คอลัมน์สุดท้ายคือข้อความระบุข้อกำหนดที่แต่ละแถวจะนำไปใส่ไว้ในรายงาน ซึ่งคำว่า CPU ในนั้นหมายถึงหน่วยประมวลผลกลาง (central processing unit)

รหัสการตรวจสอบ หมวดหมู่ ต้องผ่าน ข้อกำหนดที่พิมพ์ออกมา
kubernetes-version cluster ใช่ Kubernetes 1.33 หรือใหม่กว่า
nodes-ready cluster ใช่ ทุกโหนดอยู่ในสถานะพร้อมใช้งาน
storage-class cluster ใช่ คลาสพื้นที่จัดเก็บข้อมูลสำหรับข้อมูล
resources cluster ใช่ มี CPU และหน่วยความจำเพียงพอสำหรับรีลีส
graphics-nodes cluster ไม่ใช่ โหนดกราฟิก
ingress-class network ใช่ คลาส Ingress สำหรับที่อยู่ทั้งสาม
ingress-ports network ใช่ คอนโทรลเลอร์ Ingress เปิดพอร์ต 80 และ 443
address-console, address-api, address-auth network ใช่ ที่อยู่ console, api หรือ auth สามารถแปลงชื่อใน DNS ได้
certificate network ไม่ใช่ ใบรับรองมีอายุใช้งานเหลืออีกอย่างน้อย 30 วัน
custodians time-and-keys ใช่ บุคคลผู้ถือกุญแจกู้คืนของการติดตั้งนี้
installation-name time-and-keys ใช่ ชื่อถาวรของการติดตั้งนี้

kubernetes-version

อ่านเวอร์ชันของเซิร์ฟเวอร์ API แล้วนำไปเปรียบเทียบกับเกณฑ์ขั้นต่ำของ chart เช่น พบว่าเป็น 1.33.6+k3s1 หากต่ำกว่า 1.33 จะถือว่าล้มเหลวพร้อมแสดงวิธีแก้ไข upgrade the cluster to 1.33 or later หากสตริงเวอร์ชันไม่ใช่รูปแบบที่ nexusctl อ่านได้ จะถือว่าล้มเหลวแทนที่จะคาดเดา

nodes-ready

แสดงรายการโหนดและนับจำนวนโหนดที่มีเงื่อนไข Ready เป็นจริง ในรูปแบบ 3 of 3 โหนดใดก็ตามที่ไม่พร้อมจะถูกระบุชื่อ และวิธีแก้ไขจะแนะนำให้คุณนำโหนดนั้นกลับสู่สถานะ Ready และอ่านเงื่อนไขของโหนด คลัสเตอร์ที่ไม่มีโหนดเลยจะล้มเหลวพร้อมคำใบ้ว่า context อาจชี้ไปยังคลัสเตอร์ผิดตัว

storage-class

หากไฟล์ values ของคุณตั้งค่า storage.className ไว้ การตรวจสอบจะค้นหาคลาสนั้น และจะล้มเหลวด้วยรหัส <name> does not exist เมื่อไม่พบ หากไม่ได้ตั้งค่าไว้ จะค้นหาคลาสที่ทำเครื่องหมายเป็นค่าเริ่มต้นและรายงานเป็น local-path (default) หากไม่มีค่าเริ่มต้นเลยจะล้มเหลวด้วยรหัส none marked default และคอลัมน์สิ่งที่ต้องการจะอธิบายว่าเหตุใดจึงสำคัญ: the database cannot claim a disk หากมีสองคลาสที่ทำเครื่องหมายเป็นค่าเริ่มต้น คลัสเตอร์จะให้การร้องขอ (claim) ใหม่ใช้คลาสที่ใหม่ที่สุด ดังนั้นคลาสนั้นจึงเป็นคลาสที่ถูกรายงาน

resources

คำนวณสิ่งที่รีลีสต้องการจาก chart และไฟล์ values ของคุณ จากนั้นรวมจำนวนคอร์ของหน่วยประมวลผลกลาง (CPU) และหน่วยความจำที่จัดสรรได้ของทุกโหนดที่อยู่ในสถานะ Ready ไม่ได้ถูกกั้น (cordon) และไม่มี taint NoSchedule หรือ NoExecute เนื่องจากพ็อดของ chart ไม่มี toleration โหนดที่มี taint จึงไม่สามารถรันพ็อดเหล่านั้นได้และจะไม่ถูกนับรวม คลัสเตอร์ที่มีทรัพยากรไม่พอจะล้มเหลวพร้อมระบุส่วนที่ขาดอย่างชัดเจน เช่น add nodes with 1 more core and 2.5 GiB more memory, or lower the sizes under components and dataTier in harrow-values.yaml ความต้องการจะถูกปัดเศษขึ้นและทรัพยากรที่มีจะถูกปัดเศษลง ดังนั้นการตรวจสอบนี้จะไม่ประเมินเข้าข้างคุณ

graphics-nodes

ค้นหาโหนดในสถานะ Ready ที่มีหน่วยประมวลผลกราฟิก (GPU) ที่สามารถจัดสรรได้ คือ nvidia.com/gpu หากไม่มีเลยจะแจ้งเตือนว่า: the assistant will need a hosted model Preflight ถือว่าสิ่งนี้เป็นคำแนะนำและจะไม่บล็อกการทำงาน เพราะผู้ช่วยสามารถตอบคำถามผ่านโมเดลปัญญาประดิษฐ์ (AI) ที่โฮสต์ไว้แทนได้ บทที่ 2.14 ผู้ให้บริการและโมเดล AI ครอบคลุมทั้งสองแนวทาง

ingress-class

หากมีการตั้งค่า ingress.className การตรวจสอบจะค้นหาคลาสนั้น หากไม่ได้ตั้งค่า จะค้นหาคลาสที่ทำเครื่องหมายเป็นค่าเริ่มต้นเพียงคลาสเดียว หากมีสองคลาสที่ทำเครื่องหมายเป็นค่าเริ่มต้นก็จะล้มเหลวเช่นกัน เนื่องจากเซิร์ฟเวอร์ API จะปฏิเสธ Ingress ที่ไม่ระบุคลาส การตรวจสอบนี้จะถูกข้ามไปและไม่แสดงแถวข้อมูล เมื่อ ingress.enabled มีค่าเป็น false

ingress-ports

ค้นหาในเนมสเปซที่ระบุโดย networkPolicy.ingressNamespace (ค่าเริ่มต้นคือ kube-system ซึ่งเป็นที่ที่ k3s รัน Traefik) เพื่อหา Service ประเภท LoadBalancer หรือ NodePort หนึ่งรายการที่เปิดพอร์ตทั้ง 80 และ 443 นโยบายเครือข่ายของ chart อนุญาตให้เฉพาะเนมสเปซนั้นเข้าถึง Service สาธารณะทั้งสามได้ ดังนั้นคอนโทรลเลอร์ Ingress ที่อยู่ที่อื่นจะไม่สามารถให้บริการ Nexus ได้แม้ว่าจะเปิดรับการเชื่อมต่ออยู่ก็ตาม วิธีแก้ไขจะระบุทางออกไว้ทั้งสองทาง คือ เปิดพอร์ตคอนโทรลเลอร์ที่เนมสเปซนั้น หรือตั้งค่า networkPolicy.ingressNamespace ให้ชี้ไปยังที่ที่คอนโทรลเลอร์รันอยู่ การตรวจสอบนี้จะถูกข้ามไปเมื่อ ingress.enabled มีค่าเป็น false

address

ค้นหา hosts.console, hosts.api และ hosts.auth จากเวิร์กสเตชันของคุณ โดยใช้เวลารายการละห้าวินาที และพิมพ์ผลลัพธ์หนึ่งแถวต่อหนึ่งโฮสต์ โฮสต์ที่ไม่มีระเบียนจะล้มเหลวด้วยรหัส <host> → no record โฮสต์ที่ไม่ได้ตั้งค่าจะล้มเหลวด้วยรหัส hosts.<key> is not set เมื่อชื่อหนึ่งมีหลายที่อยู่ แถวข้อมูลจะแสดงที่อยู่แรกโดยให้ IPv4 มาก่อน IPv6 พร้อมระบุว่ามีที่อยู่อื่นอีกกี่รายการ

certificate

ทำงานเฉพาะเมื่อ tls.mode เป็น existing และ tls.existingSecret ระบุชื่อ Secret เท่านั้น หากใช้ cert-manager หรือ none จะไม่มีใบรับรองของคุณให้อ่าน และแถวข้อมูลนี้จะถูกเว้นไป การตรวจสอบจะอ่าน tls.crt จาก Secret ในเนมสเปซที่ติดตั้งเท่านั้นโดยไม่อ่านสิ่งอื่น ใบรับรองที่ใช้งานได้อีก 30 วันขึ้นไปจะผ่านเป็น ends 3 Nov 2027 หากหมดอายุเร็วกว่านั้นจะแจ้งเตือนเป็น ends in 9 days และหากหมดอายุไปแล้วจะแจ้งเตือนเป็น ended 4 days ago หากไม่พบ Secret หรือใน Secret ไม่มีใบรับรองอยู่ จะแจ้งเตือนพร้อมวิธีแก้ไข

custodians

อ่านค่า keys.custody.recipients หากไม่มีเลยจะล้มเหลวด้วยรหัส KEYS_CUSTODIAN_MISSING หากผู้รับคนใดเป็นผู้ดูแลกุญแจตัวอย่างจากไฟล์ values ของ chart เอง จะล้มเหลวด้วยรหัส KEYS_CUSTODIAN_EXAMPLE เนื่องจากไม่มีใครถือคีย์นั้นและกุญแจกู้คืนของการติดตั้งจะถูกปิดผนึกโดยที่ไม่มีใครเปิดได้ หากผ่านจะพิมพ์จำนวนนับ เช่น 3 custodians

installation-name

อ่านค่า keys.installationName หากไม่ได้ตั้งค่า จะล้มเหลวด้วยรหัส INSTALLATION_NAME_MISSING หากตั้งค่าเป็นชื่อตัวอย่างจากไฟล์ values ของ chart จะล้มเหลวด้วยรหัส INSTALLATION_NAME_EXAMPLE หากผ่านจะพิมพ์ชื่อออกมา คอลัมน์สิ่งที่ต้องการจะอธิบายว่าเหตุใดรายการนี้จึงสำคัญกว่ารายการส่วนใหญ่: the first key-store bootstrap mints the installation identity under it, permanently

การตรวจสอบสองรายการสุดท้ายจะรายงานรหัสเดียวกันกับที่ตัว chart ใช้ปฏิเสธการติดตั้งทุกประการ เพียงแต่ Preflight จะบอกคุณก่อน ก่อนที่ Helm จะทันได้สร้างสิ่งใดขึ้นมา

ไฟล์รายงาน

ทุกรอบการรันจะบันทึกไฟล์สองไฟล์ไว้ใน --report-dir โดยตั้งชื่อตามเวลาที่รัน ได้แก่ preflight-2026-11-12-0902.txt ซึ่งเป็นบรรทัดข้อความตามที่พิมพ์ออกมาโดยไม่มีรหัสสี และ preflight-2026-11-12-0902.json ซึ่งเป็นการรันเดียวกันในรูปแบบคงที่ที่โปรแกรมสามารถอ่านได้ เอาต์พุตบนเทอร์มินัลและบรรทัดที่บันทึกไว้มาจากรายการเดียวกัน ดังนั้นข้อมูลจะตรงกันเสมอ

รายงาน JSON เป็นไปตามสคีมา nexus.preflight/v1:

ฟิลด์ ข้อมูลที่เก็บ
schema มีค่าเป็น nexus.preflight/v1 เท่านั้น
tool ออบเจ็กต์ที่ประกอบด้วย name (nexusctl) และ version
release รีลีสที่ตรวจสอบ
ran_at เวลาที่รัน ในรูปแบบเวลาสากลเชิงพิกัด (UTC)
context ชื่อของ kube context
values ชื่อไฟล์พื้นฐาน (base name) ของไฟล์ values เท่านั้น
read_only มีค่าเป็น true เสมอ
checks หนึ่งรายการต่อหนึ่งแถว ประกอบด้วย id, section, name, requirement, must_pass, outcome (pass, warn หรือ fail), found, needs, fix และในกรณีที่ไม่ผ่านเนื่องจากสาเหตุของเครื่อง จะมี code
counts passed, warnings และ failed
can_install true เมื่อไม่มีรายการใดล้มเหลว
report_file ชื่อของไฟล์ .txt
transcript ออบเจ็กต์ที่ประกอบด้วย title (nexusctl preflight) และ lines โดยแต่ละบรรทัดจะมี kind (prompt, ok, warn, bad, note, out หรือ blank), text และ at ของตัวเอง และบางครั้งอาจมี marks

รายงานนี้ถูกสร้างขึ้นเพื่อให้นำไปแสดงก่อนที่จะมีใครลงชื่อเข้าใช้ ดังนั้นจึงไม่มีชื่อผู้ใช้ ไม่มีชื่อโฮสต์ของเวิร์กสเตชัน ไม่มีพาธของไฟล์ ไม่มีโทเค็น และไม่มีข้อมูลใดๆ จาก kubeconfig ของคุณ values เป็นเพียงชื่อไฟล์พื้นฐาน และ context เป็นเพียงชื่อของ context หากรอบการรันใดได้รายงานที่ละเมิดกฎเหล่านี้ nexusctl จะปฏิเสธที่จะพิมพ์ บันทึก หรือส่งมอบรายงานนั้น พร้อมทั้งแจ้งให้ทราบ รายงานมีขนาดสูงสุดไม่เกิน 256 KiB มีการตรวจสอบสูงสุดไม่เกิน 64 รายการ และมีความยาวสูงสุดไม่เกิน 512 อักขระในฟิลด์ข้อความใดๆ

วิธีที่รายงานไปถึงคอนโซล

การเขียนข้อมูลเพียงอย่างเดียวของ Preflight คือการส่งมอบรายงานที่เสร็จสมบูรณ์ไปยังบริการจัดการคีย์ของการติดตั้ง นั่นคือ nexus-keys เพื่อให้ตัวติดตั้งของคอนโซลสามารถแสดงรายงานดังกล่าวบนหน้า preflight ก่อนที่จะมีใครอ้างสิทธิ์ (claim) การติดตั้ง โดย --record จะเป็นตัวกำหนดว่าจะพยายามส่งมอบหรือไม่:

--record สิ่งที่จะเกิดขึ้น
auto ส่งมอบรายงานเฉพาะเมื่อเนมสเปซมี Deployment nexus-keys อยู่เท่านั้น
always บังคับส่งมอบ โดย preflight จะออกด้วยรหัส 2 หากไม่มีปลายทางให้ส่งมอบ
never ไม่ส่งมอบรายงาน

ดังนั้น การรันก่อนการติดตั้งครั้งแรกจะไม่มีปลายทางให้ส่งมอบ และจะเก็บรายงานไว้ในเวิร์กสเตชันของคุณ ส่วนการรันหลังการติดตั้งแต่ก่อนการอ้างสิทธิ์จะบันทึกรายงานนั้นไว้

การส่งมอบจะใช้สิทธิ์การเข้าถึงคลัสเตอร์ของคุณเอง โดย nexusctl จะรัน /app/nexus-keys preflight-record ในคอนเทนเนอร์ keys ของพ็อด nexus-keys ที่พร้อมใช้งาน และส่งรายงานผ่านอินพุตมาตรฐาน (standard input) ซึ่งมีผลเหมือนกับคำสั่ง:

kubectl exec -i -n nexus -c keys deploy/nexus-keys -- /app/nexus-keys preflight-record < preflight-2026-11-12-0902.json

บริการจัดการคีย์จะตรวจสอบรายงานตามกฎเดียวกันกับที่ nexusctl ใช้ และจะเก็บเฉพาะรายงานล่าสุดไว้เท่านั้น เมื่อส่งมอบเสร็จแล้ว nexusctl จะพิมพ์ข้อความเพิ่มอีกหนึ่งบรรทัดเพื่อแจ้งให้ทราบ และไฟล์ JSON ที่บันทึกไว้จะมี note เพิ่มขึ้นมาเพื่อบันทึกการส่งมอบนั้น

ตัวติดตั้งของคอนโซลจะอ่านรายงานจากเส้นทางสาธารณะของบริการจัดการคีย์ที่ GET /v1/installation/preflight เส้นทางนั้นจะตอบกลับเฉพาะในขณะที่การติดตั้งยังไม่มีการอ้างสิทธิ์เท่านั้น โดยก่อนที่จะมีการบันทึกรายงานใดๆ จะตอบกลับเป็น 404 RECORD_NOT_FOUND และเมื่อมีคนอ้างสิทธิ์การติดตั้งแล้ว จะตอบกลับเป็น ROUTE_NOT_FOUND อย่างถาวร เช่นเดียวกับเส้นทางการอ้างสิทธิ์ทุกประการ รายงานที่ส่งมอบหลังจากการอ้างสิทธิ์จะถูกปฏิเสธด้วยรหัส INSTALLATION_CLAIMED

บนคอนโซล การรันที่มีรายการล้มเหลวจะปรากฏเป็นหน้า "Preflight cannot continue" ซึ่งแสดงจำนวนที่ล้มเหลว คำเตือน และที่ผ่าน จากนั้นจะแสดงการตรวจสอบทุกรายการโดยจัดกลุ่มภายใต้ "Must pass" และ "Should pass" โดยนำรายการที่ไม่ผ่านขึ้นก่อนพร้อมข้อความสิ่งที่พบอยู่ด้านข้างแต่ละรายการ การรันที่ไม่มีรายการล้มเหลวจะไม่แสดงหน้านี้ แต่คอนโซลจะข้ามไปยังหน้าการอ้างสิทธิ์ทันที (บทที่ 2.12 การรันครั้งแรก)

Preflight ไม่สามารถดำเนินการต่อได้
Preflight ไม่สามารถดำเนินการต่อได้
หน้าคอนโซลสำหรับการรัน preflight ที่ไม่สามารถดำเนินการต่อได้ การตรวจสอบที่ล้มเหลวจะแสดงขึ้นก่อน โดยแต่ละรายการจะระบุชื่อเป็นข้อความพร้อมสิ่งที่พบ และการติดตั้งจะถูกบล็อกไว้จนกว่าจะผ่านทั้งหมด
สามคอลัมน์ ด้านซ้าย "Operator workstation": กล่อง "nexusctl preflight --context --values" พร้อมเอาต์พุตสองรายการด้านล่างคือ "preflight-<time>.txt" และ "preflight-<time>.json" ตรงกลาง "The installation, unclaimed": กล่อง "nexus-keys" พร้อมป้ายกำกับ "preflight-record, latest report only" ลูกศรจากกล่องด้านซ้ายชี้ไปยัง nexus-keys มีป้ายกำกับว่า "pod exec with your own cluster access (--record auto or always)" ด้านขวา "Browser, before sign-in": กล่อง "Console installer, Preflight cannot continue" ลูกศรจาก nexus-keys ชี้ไปยังกล่องนี้มีป้ายกำกับว่า "GET /v1/installation/preflight" ใต้กล่องตรงกลางมีหมายเหตุขนาดเล็กระบุว่า "after the claim: ROUTE_NOT_FOUND"
เส้นทางของรายงาน preflight หนึ่งฉบับ ตั้งแต่เวิร์กสเตชันของผู้ปฏิบัติงานไปจนถึงเบราว์เซอร์

สิทธิ์การเข้าถึงที่การรันต้องการ

Preflight จะรันในนามของคุณโดยใช้ kubeconfig ของคุณ บัญชีผู้ใช้จำเป็นต้องมีสิทธิ์อ่านข้อมูลต่อไปนี้:

  • โหนด สำหรับการตรวจสอบเวอร์ชัน ความพร้อม ทรัพยากร และกราฟิก
  • คลาสพื้นที่จัดเก็บข้อมูลและคลาส Ingress
  • Service ในเนมสเปซของ Ingress
  • Secret สำหรับ TLS ในเนมสเปซที่ติดตั้ง เมื่อมีการรันการตรวจสอบใบรับรอง

เมื่อการอ่านข้อมูลถูกปฏิเสธ แถวข้อมูลจะแสดง could not read <what> (the cluster refused) และวิธีแก้ไขจะระบุว่าต้องให้สิทธิ์การอ่านใดบ้าง ข้อความจะไม่รวมที่อยู่ของเซิร์ฟเวอร์หรือข้อความแสดงข้อผิดพลาดของเซิร์ฟเวอร์เอง เนื่องจากรายงานอาจถูกนำไปแสดงก่อนการลงชื่อเข้าใช้ นอกจากนี้ การส่งมอบรายงานยังต้องการสิทธิ์ pods/exec บนพ็อด nexus-keys ด้วย หากไม่มีสิทธิ์นี้ auto จะบันทึกไฟล์และพิมพ์คำเตือน ส่วน always จะออกด้วยรหัส 2

เมื่อตัวการตรวจสอบความพร้อมเองไม่สามารถรันได้

รหัสการออก 2 หมายความว่าไม่มีการสร้างรายงาน ข้อความบนเอาต์พุตข้อผิดพลาดมาตรฐาน (standard error) จะระบุสาเหตุ:

ข้อความ สิ่งที่ต้องทำ
--context is required: the kube context to check เพิ่ม --context
--values is required: the values file the install will use เพิ่ม --values
could not read the values file harrow-values.yaml ตรวจสอบพาธและสิทธิ์ของไฟล์
preflight takes flags only ลบอาร์กิวเมนต์ที่เกินมาออก
the report breaks its contract and was not printed, saved or handed over มีฟิลด์ที่จะมีข้อมูลส่วนตัวติดไปด้วย ให้รายงานเรื่องนี้ไปยัง Adverant พร้อมแฟล็กที่ใช้รัน
--record always: there is no nexus-keys Deployment in the namespace nexus to hand the report to ติดตั้งก่อน หรือใช้ --record auto
could not hand the report to this installation ตรวจสอบสิทธิ์การเข้าถึงของคุณในการ exec เข้าไปยัง nexus-keys

คลัสเตอร์ที่ไม่สามารถติดต่อ API ได้จะออกด้วยรหัส 2 เช่นกัน ให้แก้ไข kubeconfig หรือเครือข่าย แล้วรันคำสั่งอีกครั้ง

เมื่อ preflight จบการทำงานด้วยรหัส 0 failed แล้ว ให้ไปต่อที่บทที่ 2.6 การติดตั้ง Community บน Kubernetes เพื่อติดตั้งรุ่น Community หรือบทที่ 2.7 การติดตั้ง Enterprise และการใช้งานใบอนุญาต สำหรับรุ่น Enterprise