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

บทที่ 2.8

การติดตั้งบนเครื่องเดียว

ติดตั้ง Nexus บนเซิร์ฟเวอร์ Linux เครื่องเดียวด้วย nexusctl หรือประเมินผลการใช้งานบนแล็ปท็อปด้วย k3d และเข้าถึงคอนโซลผ่าน HTTPS เพื่อให้การลงชื่อเข้าใช้และพาสคีย์ทำงานได้

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

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

ก่อนที่ Harrow Port Authority จะนำ Nexus ขึ้นสู่คลัสเตอร์ใช้งานจริง Tomás Reilly ต้องการการติดตั้งขนาดเล็กสองชุดก่อน ชุดแรกคือระบบนำร่องบนเซิร์ฟเวอร์ Linux สำรองในอาคารปฏิบัติการ สำหรับผู้ใช้งาน 12 คนแรกที่จะได้ทดลองใช้ ส่วนอีกชุดรันอยู่บนแล็ปท็อปของเขาเอง เพื่อที่เขาจะได้ทดลองปรับแก้จนระบบพังได้โดยไม่มีใครสังเกตเห็น บทนี้ครอบคลุมทั้งสองแบบ ทั้งคู่ใช้ชาร์ตเดียวกัน อิมเมจเดียวกัน และการรันครั้งแรกแบบเดียวกันกับการติดตั้งบน Kubernetes เต็มรูปแบบ ดังนั้นสิ่งที่คุณเรียนรู้จากเครื่องหนึ่งจะนำไปใช้ต่อได้ทันที

แนวทางสำหรับเซิร์ฟเวอร์ใช้เพียงคำสั่งเดียว: nexusctl install --single-node จะสร้างคลัสเตอร์ k3s บนเครื่อง ติดตั้ง cert-manager แล้วจึงติดตั้ง Nexus ส่วนแนวทางสำหรับแล็ปท็อปต้องลงมือทำเองมากกว่า คุณต้องสร้างคลัสเตอร์ k3d ด้วยตนเอง ติดตั้ง cert-manager และชาร์ตด้วย Helm จากนั้นทำงานเพิ่มอีกหนึ่งอย่างที่เกือบทุกคนมักติดปัญหา นั่นคือการวางคอนโซลไว้หลัง HTTPS บนเครื่องของคุณเอง เพราะการทำ port-forward แบบธรรมดาจะไม่สามารถใช้ลงชื่อเข้าใช้ได้เลย

ขนาดของเครื่องที่ต้องใช้

Nexus ขอใช้ CPU (หน่วยประมวลผลกลาง) ประมาณ 2.05 คอร์ และหน่วยความจำ 6.7 GiB ในส่วนของ requests ตามค่าเริ่มต้นของชาร์ต และมีขนาดโวลุ่มรวมกัน 142 GiB ยอดรวมนี้แบ่งเป็น PostgreSQL 50, Valkey 5, Neo4j 20, Qdrant 10, ระบบจัดเก็บอ็อบเจกต์ 50, ที่เก็บข้อมูล OpenBao สองส่วนที่ 1 และ 5 และโวลุ่มใบรับรองการทำรายการ (receipts) อีก 1 ค่า requests คือสิ่งที่ตัวจัดตารางงาน (scheduler) จองไว้ และการใช้งานจริงจะสูงขึ้นเมื่อมีผู้เริ่มทำงาน

เครื่อง CPU หน่วยความจำ (RAM, หน่วยความจำเข้าถึงโดยสุ่ม) ดิสก์
โหนดเดี่ยวที่แนะนำ 8 vCPU 32 GiB 250 GB SSD (โซลิดสเตตไดรฟ์)
ขั้นต่ำสำหรับการประเมินผล 4 vCPU 16 GiB 200 GB

แล็ปท็อปที่ผ่านเกณฑ์ขั้นต่ำสำหรับการประเมินผลจะสามารถรัน Nexus ได้ แต่จะนับตามขีดจำกัดหน่วยความจำของ Docker เอง ไม่ใช่ของแล็ปท็อป โปรดกำหนดหน่วยความจำให้ Docker อย่างน้อย 16 GiB ก่อนเริ่มต้น

ทั้งสองแนวทางต้องการ Kubernetes 1.33 ขึ้นไป แนวทางแบบโหนดเดี่ยวจะมาพร้อมกับ Kubernetes ของตัวเองคือ k3s v1.33.6+k3s1 ซึ่งเป็นดิสทริบิวชันที่ใช้ทดสอบในทุกรีลีส

ส่วนที่หนึ่ง: เซิร์ฟเวอร์ Linux เครื่องเดียวด้วย nexusctl

เซิร์ฟเวอร์นำร่องของ Tomás เป็นเครื่องแบบ 8 คอร์ มีหน่วยความจำ 32 GiB และ SSD ขนาด 500 GB ที่รัน Linux รุ่นปัจจุบันโดยไม่มีสิ่งอื่นติดตั้งอยู่ การติดตั้งจำเป็นต้องใช้สิทธิ์ root เนื่องจากต้องติดตั้ง k3s เป็นบริการของระบบ

ดาวน์โหลดและตรวจสอบ nexusctl

  1. ดาวน์โหลด nexusctl สำหรับสถาปัตยกรรมเครื่องของคุณจาก https://downloads.adverant.ai/nexus/1.0.0-alpha.1/ พร้อมกับคีย์สาธารณะของรีลีส บันทึกคีย์เป็นชื่อ release.pub บทที่ 2.4 การรับและตรวจสอบรีลีส จะอธิบายวิธีตรวจสอบลายนิ้วมือ (fingerprint) ของคีย์เทียบกับที่ Adverant เผยแพร่
  2. ตรวจสอบไบนารีและรีลีสด้วยคีย์:
nexusctl version --json
nexusctl verify

nexusctl verify จะตรวจสอบไฟล์ที่ดาวน์โหลดเทียบกับคีย์รีลีสของ Adverant และปฏิเสธทุกอย่างที่ไม่สามารถยืนยันความถูกต้องได้ หากล้มเหลว ให้หยุดและดาวน์โหลดใหม่ อย่ารันการติดตั้งจากไฟล์ที่ไม่ผ่านการยืนยันเด็ดขาด

สร้างคีย์ผู้ดูแลเก็บรักษา (custodian key)

ที่เก็บคีย์ของการติดตั้งจะปิดผนึก (seal) คีย์กู้คืนไว้กับผู้ดูแลเก็บรักษา (custodian) อย่างน้อยหนึ่งคน ผู้ดูแลเก็บรักษาคือบุคคลที่ถือไฟล์ข้อมูลประจำตัว age ไว้แบบออฟไลน์ และชาร์ตจะปฏิเสธการติดตั้งหากไม่มีผู้ดูแลอย่างน้อยหนึ่งคน บนเครื่องของผู้ดูแลเก็บรักษาเอง ให้รัน:

age-keygen -o custodian.key

ไฟล์จะขึ้นต้นด้วยบรรทัด # public key: age1... ส่วนที่เป็นคีย์สาธารณะนั้นคือสิ่งที่จะนำไปใส่ในไฟล์ values ตัวไฟล์ข้อมูลประจำตัวจะไม่ออกไปจากเครื่องของผู้ดูแลเก็บรักษาเลย บนเครื่อง Mac ที่มี Secure Enclave คำสั่ง age-plugin-se keygen --access-control=any-biometry -o custodian.key จะสร้างคีย์ที่ต้องใช้ Touch ID ในการใช้งาน และส่วนที่เป็นคีย์สาธารณะจะขึ้นต้นด้วย age1se1

เขียนไฟล์ values

# harrow-pilot-values.yaml (Helm values)
global:
  imageRegistry: registry.adverant.ai
  domain: harrow.example
hosts:
  console: console.harrow.example
  api: api.harrow.example
  auth: auth.harrow.example
edition: community
enterprise:
  enabled: false
tls:
  mode: existing
  existingSecret: harrow-public-tls
keys:
  installationName: harrow-pilot
  custody:
    recipients:
      - "<custodian-age-recipient>"

<custodian-age-recipient> คือบรรทัด age1... จาก custodian.key ให้เพิ่มหนึ่งรายการต่อผู้ดูแลเก็บรักษาหนึ่งคน

keys.installationName เป็นค่าถาวร การเริ่มต้นครั้งแรกของที่เก็บคีย์จะสร้างข้อมูลประจำตัวของการติดตั้งภายใต้ชื่อนั้น และไม่มีสิ่งใดเปลี่ยนชื่อนี้ได้ในภายหลัง ชื่อจะต้องตรงตามรูปแบบ ^[a-z][a-z0-9-]{0,62}$: เป็นตัวพิมพ์เล็ก ขึ้นต้นด้วยตัวอักษร และยาวไม่เกิน 63 อักขระ อย่าคัดลอก nexus-example หรือผู้รับตัวอย่างจากไฟล์ตัวอย่างของชาร์ตเอง ชาร์ตจะปฏิเสธทั้งสองอย่างตามชื่อที่ระบุ และขั้นตอนตรวจสอบล่วงหน้า (preflight) ก็จะรายงานรหัสข้อผิดพลาดเดียวกันนี้ก่อนด้วย

โฮสต์ทั้งสามคือข้อมูลประจำตัวของการติดตั้ง ทุกบริการจะปฏิเสธการเริ่มต้นทำงานหากไม่มีโฮสต์เหล่านี้ และทุกการลงชื่อเข้าใช้ คุกกี้ และพาสคีย์ (passkey) จะถูกผูกไว้กับ hosts.console โปรดเลือกชื่อที่คุณจะยังต้องการใช้อยู่ในอีกห้าปีข้างหน้า

ชี้ชื่อทั้งสามไปยังเซิร์ฟเวอร์

ผู้ใช้จะเข้าถึงคอนโซล, API (ส่วนต่อประสานโปรแกรมประยุกต์) และบริการลงชื่อเข้าใช้ผ่านตัวควบคุม ingress ในตัวของ k3s ซึ่งก็คือ Traefik บนพอร์ต 80 และ 443 ของเซิร์ฟเวอร์ ให้เพิ่มระเบียน DNS (ระบบชื่อโดเมน) สามรายการสำหรับ console.harrow.example, api.harrow.example และ auth.harrow.example โดยแต่ละรายการชี้ไปยังที่อยู่ของเซิร์ฟเวอร์ การตรวจสอบล่วงหน้า (preflight) จะตรวจสอบแต่ละชื่อและแจ้งให้คุณทราบว่าชื่อใดยังไม่มีระเบียน

นโยบายเครือข่ายของชาร์ตจะอนุญาตให้เพียงเนมสเปซเดียวเข้าถึงบริการสาธารณะทั้งสามได้ ค่าเริ่มต้นคือ kube-system ซึ่งเป็นที่ที่ k3s รัน Traefik ดังนั้นบนโหนดเดี่ยว คุณจึงไม่ต้องแก้ไข networkPolicy.ingressNamespace

รันการตรวจสอบล่วงหน้า แล้วจึงติดตั้ง

  1. รันการตรวจสอบล่วงหน้า (preflight) พร้อมแฟล็กสำหรับโหนดเดี่ยว คำสั่งนี้จะอ่านข้อมูลเครื่องและไฟล์ values ของคุณโดยไม่เปลี่ยนแปลงสิ่งใด
sudo nexusctl preflight --single-node --values harrow-pilot-values.yaml
  1. อ่านบรรทัดสรุปในตอนท้าย คำเตือนจะไม่ขัดขวางการติดตั้ง แต่ความล้มเหลวจะบล็อกการติดตั้ง และทุกแถวที่ล้มเหลวจะมีบรรทัด fix กำกับไว้
 ────────────────────────────────────────────────────────────
 9 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
  1. ดำเนินการติดตั้ง แฟล็ก --edition ต้องตรงกับ edition ในไฟล์ values
sudo nexusctl install --single-node --values harrow-pilot-values.yaml --edition community
  1. รอดูการทำงาน ระบบจะรันการตรวจสอบล่วงหน้าอีกครั้ง ติดตั้ง k3s v1.33.6+k3s1 ติดตั้ง cert-manager v1.21.3 ติดตั้ง Nexus และรอให้ทุกบริการตอบกลับการตรวจสอบสถานะ (health check) บนเซิร์ฟเวอร์ของ Tomás ขั้นตอนนี้ใช้เวลาเกือบสิบนาที
 done   Preflight again        9 passed · 1 warning
 done   k3s v1.33.6+k3s1       node Ready
 done   cert-manager v1.21.3   ready
 done   Database and search    ready
 done   Engines                started
 done   Console                https://console.harrow.example
 Installed. Nobody can sign in yet.
 Open https://console.harrow.example/claim
 Code <code>  works once, for 30 minutes
 Fingerprint of this installation, to compare in the browser:
 3F9A C21B 77E0 5D4C 9B12 A6F3 0E88 41D7

เก็บลายนิ้วมือ (fingerprint) นั้นไว้บนหน้าจอ คุณจะต้องใช้เปรียบเทียบในเบราว์เซอร์เมื่อคุณอ้างสิทธิ์การติดตั้งด้วยรหัส หากรหัสหมดอายุก่อนที่คุณจะใช้งาน คำสั่ง nexusctl claim-code --administrator <email> จะสร้างรหัสใหม่ให้ บทที่ 2.12 การรันครั้งแรก จะอธิบายขั้นตอนต่อจากนี้

ติดตั้งรุ่น Community
ติดตั้งรุ่น Community
การติดตั้งรุ่น Community บนเซิร์ฟเวอร์เดียวประกอบด้วยการดาวน์โหลด ตรวจสอบ รันการตรวจสอบล่วงหน้า และติดตั้ง จากนั้นจึงตั้งค่าผู้ดูแลระบบคนแรก โดยไม่มีขั้นตอนเกี่ยวกับใบอนุญาตใช้งาน

นำใบรับรองไปวางในตำแหน่งที่กำหนด

เมื่อใช้ tls.mode: existing เส้นทาง ingress ทั้งสามจะให้บริการใบรับรองที่อยู่ใน Secret ซึ่งระบุชื่อโดย tls.existingSecret ใบรับรองนี้ต้องครอบคลุมทั้งสามโฮสต์ การตรวจสอบล่วงหน้าจะอ่าน Secret นั้นหากมีอยู่แล้ว และจะแจ้งเตือนหากใบรับรองจะหมดอายุภายใน 30 วัน เมื่อยังไม่มี Secret แถวข้อมูลจะแจ้งให้คุณสร้างขึ้น และถือเป็นคำเตือน ไม่ใช่ความล้มเหลว

บนโหนดเดี่ยว คลัสเตอร์จะยังไม่มีอยู่จนกว่าการติดตั้งจะสร้างมันขึ้นมา ดังนั้นให้สร้าง Secret ทันทีหลังจากการติดตั้งเสร็จสิ้น เขียนไฟล์ kubeconfig ของคลัสเตอร์ออกมาก่อน (ส่วนสุดท้ายของบทนี้จะอธิบายวิธีทำ) จากนั้นจึงสร้าง Secret ด้วยไฟล์ดังกล่าว:

sudo nexusctl kubeconfig > harrow-pilot.kubeconfig
chmod 600 harrow-pilot.kubeconfig
export KUBECONFIG=$PWD/harrow-pilot.kubeconfig
kubectl -n nexus create secret tls harrow-public-tls --cert=harrow-public.crt --key=harrow-public.key

harrow-public.crt เก็บใบรับรองตามด้วยใบรับรองตัวกลาง (intermediate certificates) ใดๆ และ harrow-public.key เก็บคีย์ส่วนตัวของใบรับรองนั้น หากใบรับรองของคุณมาจาก CA (องค์กรออกใบรับรอง) ส่วนตัว คำสั่ง nexusctl preflight และ nexusctl install จะรับค่า --ca-bundle <file> เพื่อให้สามารถตรวจสอบห่วงโซ่ใบรับรอง (chain) ได้ วิธีอื่นๆ ในการจัดการ TLS (Transport Layer Security) อยู่ใน บทที่ 2.11 รูปแบบอื่นๆ: ที่เก็บข้อมูลภายนอก, TLS และ ingress

หากขั้นตอนนี้ล้มเหลว

สิ่งที่คุณเห็น ความหมาย สิ่งที่ต้องทำ
PREFLIGHT_FAILED (409) การตรวจสอบล่วงหน้าพบความล้มเหลว ดังนั้นการติดตั้งจึงไม่เริ่มต้น และยังไม่มีสิ่งใดถูกติดตั้ง แก้ไขแต่ละแถวที่ล้มเหลวโดยดูจากบรรทัด fix แล้วรันการติดตั้งอีกครั้ง
INSTALLATION_NAME_MISSING keys.installationName ว่างเปล่า ตั้งชื่อถาวรของการติดตั้งเอง
INSTALLATION_NAME_EXAMPLE ชื่อนี้เป็นชื่อที่มาจากค่าตัวอย่างของชาร์ต เลือกชื่อของคุณเอง
KEYS_CUSTODIAN_MISSING keys.custody.recipients ว่างเปล่า เพิ่มผู้รับ age1... สาธารณะของผู้ดูแลเก็บรักษาแต่ละคน
KEYS_CUSTODIAN_EXAMPLE ผู้รับเป็นเพียงผู้ดูแลเก็บรักษาตัวอย่างของชาร์ต ซึ่งไม่มีใครถือข้อมูลประจำตัวอยู่จริง แทนที่ด้วยผู้รับของผู้ดูแลเก็บรักษาของคุณเอง

nexusctl จะคืนค่ารหัสออก (exit code) เป็น 0 เมื่อสามารถดำเนินการต่อได้, 1 เมื่อการตรวจสอบบล็อกการทำงานไว้ และ 2 เมื่อไม่สามารถรันได้เลย (เช่น ไฟล์ values อ่านไม่ได้ หรือใช้แฟล็กผิด) สคริปต์สามารถแยกการทำงานตามรหัสทั้งสามนี้ได้

ส่วนที่สอง: การประเมินผลบนแล็ปท็อปด้วย k3d

k3d รัน k3s ภายในคอนเทนเนอร์ Docker ดังนั้นคลัสเตอร์ทั้งหมดจึงอยู่บนแล็ปท็อปและลบออกได้ด้วยคำสั่งเดียว เครื่องมือจัดการรีลีสที่ใช้ทดสอบทุกรีลีสของ Nexus ก็สร้างคลัสเตอร์ด้วยวิธีนี้เช่นกัน และการคัดลอกการตั้งค่าของเครื่องมือเหล่านั้นจะช่วยให้คุณไม่ต้องไปเจอปัญหาเดิมๆ ที่เคยพบมาแล้ว

คุณต้องมี Docker, k3d 5.8.3, kubectl, Helm v4 และ Chrome ส่วน Tomás ใช้เครื่อง Mac ของเขา

สร้างคลัสเตอร์

k3d cluster create harrow-eval --agents 0 --wait --timeout 300s \
  --image rancher/k3s:v1.33.6-k3s1 \
  --k3s-arg "--disable=traefik@server:0"
k3d kubeconfig get harrow-eval > harrow-eval.kubeconfig
chmod 600 harrow-eval.kubeconfig
export KUBECONFIG=$PWD/harrow-eval.kubeconfig

แต่ละแฟล็กมีเหตุผลในการใช้งานดังนี้

  • --agents 0 ให้โหนดเซิร์ฟเวอร์หนึ่งโหนดและไม่มีโหนด worker เนื่องจาก Nexus รันได้สบายบนโหนดเดียว และการมีโหนดที่สองมีแต่จะเปลืองหน่วยความจำ
  • --image rancher/k3s:v1.33.6-k3s1 ล็อกรุ่นของ k3s ให้ตรงกับรุ่นที่ใช้ทดสอบในทุกรีลีส หากไม่ระบุ คุณจะได้รุ่นใดก็ตามที่เป็นค่าเริ่มต้นของ k3d
  • --disable=traefik@server:0 จะไม่ติดตั้ง Traefik เนื่องจากแล็ปท็อปไม่มีที่อยู่สาธารณะที่จะให้บริการ และคุณจะเข้าถึงคอนโซลผ่านด่านหน้า HTTPS ของคุณเองแทน (ดูด้านล่าง)
  • --wait --timeout 300s จะคืนค่ากลับมาเมื่อคลัสเตอร์ตอบสนองแล้วเท่านั้น หรือล้มเหลวหลังจากผ่านไปห้านาที

หากคุณทำมิเรอร์ (mirror) เรจิสทรีของรีลีสไว้บนแล็ปท็อป ให้เพิ่ม --registry-config <registries.yaml> เพื่อส่งการดึงอิมเมจไปยังมิเรอร์ และเพิ่ม --k3s-arg "--disable-default-registry-endpoint@server:0" เพื่อไม่ให้มีสิ่งใดย้อนกลับไปดึงจากเรจิสทรีต้นทาง เครื่องมือจัดการรีลีสก็รันด้วยวิธีนี้ โดยทุกอิมเมจจะมาผ่านมิเรอร์เท่านั้น

ติดตั้ง cert-manager

ชาร์ตจะสร้าง CA ท้องถิ่นของตัวเองชื่อ nexus-local-ca ในฐานะผู้ออกใบรับรอง (issuer) ของ cert-manager และทุกบริการจะได้รับใบรับรองจาก CA นี้ หากไม่มีทรัพยากรของ cert-manager อยู่ในคลัสเตอร์ คำสั่ง helm install จะปฏิเสธชาร์ตภายในไม่กี่วินาที ให้ติดตั้ง cert-manager v1.21.3 ก่อน จากชาร์ตที่โปรเจกต์ cert-manager เผยแพร่:

helm install cert-manager cert-manager-v1.21.3.tgz -n cert-manager \
  --create-namespace --set crds.enabled=true --wait --timeout 10m

Nexus ไม่ต้องการสิ่งอื่นใดจาก cert-manager อีก และโดยเฉพาะอย่างยิ่งไม่ต้องการ trust-manager

ติดตั้ง Nexus

  1. เขียนไฟล์ values สำหรับแล็ปท็อป โดยที่ TLS จะสิ้นสุดที่ด่านหน้าของคุณเอง ดังนั้น tls.mode จึงเป็น none
# harrow-eval-values.yaml (Helm values)
global:
  imageRegistry: registry.adverant.ai
  domain: harrow.example
hosts:
  console: console.harrow.example
  api: api.harrow.example
  auth: auth.harrow.example
edition: community
tls:
  mode: none
keys:
  installationName: harrow-eval
  custody:
    recipients:
      - "<custodian-age-recipient>"
  1. ติดตั้งชาร์ตจากเรจิสทรี และไม่ต้องใส่ --wait (คำเตือนด้านล่างจะอธิบายเหตุผล)
helm install nexus oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1 \
  -n nexus --create-namespace -f harrow-eval-values.yaml --timeout 45m
  1. จากนั้นให้รอให้เวิร์กโหลดพร้อมทำงานด้วยตัวคุณเอง:
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s
for s in $(kubectl -n nexus get sts -o name); do
  want=$(kubectl -n nexus get "$s" -o jsonpath='{.spec.replicas}')
  kubectl -n nexus wait "$s" --for=jsonpath='{.status.readyReplicas}'="$want" --timeout=900s
done

ลูปของ StatefulSet มีไว้เนื่องจากบางตัวจะอัปเดตทีละหนึ่งพ็อดเมื่อมีการร้องขอ และ kubectl rollout status จะปฏิเสธการทำงานกับพ็อดเหล่านั้น การรอที่ readyReplicas จึงใช้ได้กับทุกกลยุทธ์การอัปเดต

เมื่อทั้งสองคำสั่งทำงานเสร็จสิ้น ทุก Deployment จะอยู่ในสถานะ Available และทุก StatefulSet จะมีพ็อดที่พร้อมทำงาน แต่จะยังไม่มีใครลงชื่อเข้าใช้ได้ ซึ่งถูกต้องแล้ว เพราะการติดตั้งนี้ยังไม่ได้ถูกอ้างสิทธิ์

เหตุใดการทำ Port-forward จึงไม่สามารถใช้ลงชื่อเข้าใช้ได้

ขั้นตอนถัดไปที่ดูเหมือนจะทำได้ง่ายๆ คือการใช้ kubectl port-forward svc/nexus-alpha 3000:3000 แล้วเปิดเบราว์เซอร์ไปที่ http://127.0.0.1:3000 หน้าเว็บของคอนโซลจะโหลดขึ้นมา ทำให้ดูเหมือนว่าใช้งานได้ แต่ความจริงแล้วมันใช้ไม่ได้ และไม่มีการตั้งค่าใดจะทำให้มันใช้งานได้ด้วย โดยมีสาเหตุสามประการที่ขวางอยู่ ซึ่งแต่ละข้อเป็นไปตามความตั้งใจของระบบ

สิ่งที่ขวางการทำงานอยู่ เหตุผล
ต้นทาง (origin) ระบบลงชื่อเข้าใช้ของคอนโซลจะปฏิเสธคำขอที่ต้นทางไม่ใช่ https://<hosts.console> ซึ่งในที่นี้คือ https://console.harrow.example หน้าเว็บที่ให้บริการจาก http://127.0.0.1:3000 มีต้นทางที่ไม่ถูกต้อง ดังนั้นการลงชื่อเข้าใช้จึงไม่เริ่มต้นทำงาน
คุกกี้ เซสชันเป็นคุกกี้ __Host- ที่ทำเครื่องหมายเป็น Secure เบราว์เซอร์จะจัดเก็บคุกกี้ดังกล่าวผ่าน HTTPS เท่านั้น โดยไม่มีแอตทริบิวต์โดเมน และใช้เฉพาะกับโฮสต์ที่ตั้งค่าคุกกี้นั้นอย่างเจาะจง หากส่งผ่าน HTTP ธรรมดา เบราว์เซอร์จะทิ้งคุกกี้นี้ไป
พาสคีย์ (passkey) ผู้ดูแลระบบคนแรกจะลงชื่อเข้าใช้ด้วยพาสคีย์ และพาสคีย์ต้องการบริบทที่ปลอดภัย (secure context) พร้อมใบรับรองที่ถูกต้อง Chrome จะปฏิเสธการสร้างพาสคีย์หากอยู่หลังหน้าคำเตือนเรื่องใบรับรอง แม้ว่าคุณจะคลิกยอมรับเพื่อผ่านเข้ามาแล้วก็ตาม

ดังนั้น เบราว์เซอร์จึงต้องสื่อสารกับ https://console.harrow.example ด้วยใบรับรองที่เบราว์เซอร์เชื่อถือ และชื่อนั้นจะต้องชี้มายังแล็ปท็อปของคุณ

การเข้าถึงคอนโซลผ่าน HTTPS บนแล็ปท็อปของคุณ

วิธีการด้านล่างนี้ใช้ CA ของชาร์ตเองในการออกใบรับรอง ใช้การทำ port-forward เพื่อเข้าถึงคอนโซล และใช้โปรไฟล์ Chrome แยกต่างหากที่เชื่อถือเฉพาะ CA นั้นเพียงตัวเดียว พร้อมทั้งจับคู่ชื่อของคอนโซลเข้ากับแล็ปท็อปของคุณ โดยที่ที่เก็บความเชื่อถือ (trust store) ของระบบคุณและไฟล์ /etc/hosts จะยังคงเดิมไม่เปลี่ยนแปลง

แผนภาพแสดง Chrome ทางด้านซ้าย มีป้ายกำกับว่า "โปรไฟล์แยก: เชื่อถือเฉพาะ nexus-local-ca; จับคู่ console.harrow.example:443 ไปยัง 127.0.0.1:28443" มีลูกศรกำกับว่า "HTTPS" ชี้ไปยังกล่อง "ด่านหน้า HTTPS บน 127.0.0.1:28443 (ใบรับรองจาก nexus-local-ca)" มีลูกศรกำกับว่า "HTTP, คงค่า Host ไว้, X-Forwarded-Proto https" ชี้ไปยัง "kubectl port-forward 127.0.0.1:3000" และลูกศรสุดท้ายชี้เข้าไปในกล่องคลัสเตอร์ k3d ไปยัง "Service nexus-alpha, พอร์ต http (3000)" มีเส้นประจาก cert-manager ภายในคลัสเตอร์โยงไปยังกล่องด่านหน้า โดยมีป้ายกำกับว่า "ออกใบรับรอง"
วิธีที่เบราว์เซอร์บนแล็ปท็อปเข้าถึงคอนโซลในคลัสเตอร์ k3d ผ่าน HTTPS

ออกใบรับรองสำหรับชื่อของคอนโซล

  1. ขอใบรับรองสำหรับโฮสต์ของคอนโซลจาก cert-manager โดยลงนามด้วยผู้ออกใบรับรอง (issuer) ของชาร์ต:
# console-front-certificate.yaml (a cert-manager Certificate)
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: nexus-console-front
  namespace: nexus
spec:
  secretName: nexus-console-front-tls
  dnsNames: [console.harrow.example]
  duration: 24h
  usages: [server auth, digital signature, key encipherment]
  privateKey: { algorithm: ECDSA, size: 256, rotationPolicy: Always }
  issuerRef: { name: nexus-local-ca, kind: Issuer, group: cert-manager.io }
kubectl apply -f console-front-certificate.yaml
kubectl -n nexus wait --for=condition=Ready certificate/nexus-console-front --timeout=120s

cert-manager จะลงนามใบรับรองภายในคลัสเตอร์ โดยที่คุณไม่ต้องอ่านคีย์ส่วนตัวของ CA เลย

  1. คัดลอกใบรับรอง คีย์ของใบรับรอง และใบรับรอง CA ออกมาจาก Secret:
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.tls\.crt}' | base64 -d > tls.crt
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.tls\.key}' | base64 -d > tls.key
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt
chmod 600 tls.key
  1. คำนวณหาค่าพิน (pin) ของ CA เนื่องจาก Chrome จะระบุคีย์ที่เชื่อถือด้วยค่า SHA-256 แบบ base64 ของคีย์สาธารณะ:
openssl x509 -in ca.crt -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64

ให้ปักหมุด (pin) ที่คีย์ของ CA ไม่ใช่ของใบรับรอง เพราะใบรับรองมีอายุหนึ่งวันและจะได้คีย์ใหม่ทุกครั้งที่ cert-manager ต่ออายุ ในขณะที่ CA จะยังคงเหมือนเดิม

วางด่านหน้า HTTPS ไว้ข้างหน้าการทำ port-forward

  1. ส่งต่อ (forward) Service ของคอนโซล พอร์ตของบริการนี้คือพอร์ตที่ชื่อว่า http ซึ่งก็คือ 3000 ในรีลีสนี้:
kubectl -n nexus port-forward svc/nexus-alpha 3000:3000
  1. รันตัวรับการเชื่อมต่อ (listener) แบบ HTTPS บน 127.0.0.1:28443 ที่ส่งต่อไปยัง 127.0.0.1:3000 คุณสามารถใช้ reverse proxy ใดก็ได้ที่คุณเชื่อถืออยู่แล้ว ตราบใดที่มันทำสิ่งต่อไปนี้ครบสี่ข้อ:
    • ให้บริการ tls.crt ตามด้วย ca.crt เป็นห่วงโซ่ใบรับรอง (chain) ร่วมกับคีย์ tls.key;
    • คงค่าส่วนหัว (header) Host ไว้เป็น console.harrow.example;
    • ตั้งค่า X-Forwarded-Proto: https;
    • ส่งผ่านการอัปเกรด WebSocket ได้ เนื่องจากคอนโซลต้องใช้งาน

การทำ port-forward ไปยัง Service จะผูกกับพ็อดตัวเดียวที่มันเลือกไว้ตอนเริ่มต้น หลังจากที่การอัปเกรดหรือการรีสตาร์ทเปลี่ยนพ็อดของคอนโซลเป็นตัวใหม่ การส่งต่อพอร์ตจะยังคงเปิดอยู่แต่ส่งต่อไปยังความว่างเปล่า และเบราว์เซอร์จะแสดงข้อผิดพลาด bad gateway ให้รีสตาร์ทการทำ port-forward ทุกครั้งที่พ็อดของคอนโซลมีการเปลี่ยนแปลง

เปิด Chrome พร้อมค่าพินและการจับคู่ชื่อ

บนเครื่อง Mac:

open -na "Google Chrome" --args --user-data-dir="$HOME/.nexus-eval-chrome" \
  "--host-resolver-rules=MAP console.harrow.example:443 127.0.0.1:28443" \
  "--ignore-certificate-errors-spki-list=<ca-pin>" \
  https://console.harrow.example/install

<ca-pin> คือผลลัพธ์จากบรรทัดคำสั่ง openssl ส่วนบน Linux ให้เริ่มการทำงานของ Chrome ด้วยแฟล็กทั้งสามตัวเดียวกันนี้

แฟล็กทั้งสามทำงานร่วมกัน โดย --host-resolver-rules จะส่ง console.harrow.example บนพอร์ต 443 ไปยังด่านหน้าของคุณ เฉพาะภายในโปรไฟล์นี้เท่านั้น --ignore-certificate-errors-spki-list จะเชื่อถือใบรับรองที่ออกโดยคีย์ CA ตัวนั้นเพียงตัวเดียว และ Chrome จะยอมรับแฟล็กนี้ก็ต่อเมื่อใช้ร่วมกับ --user-data-dir เท่านั้น โปรไฟล์ที่แยกออกมาจะช่วยกันข้อยกเว้นนี้ให้ออกห่างจากการท่องเว็บในชีวิตประจำวันของคุณ และนี่ไม่ใช่สวิตช์แบบ "เพิกเฉยต่อข้อผิดพลาดของใบรับรองทั้งหมด" เพราะสิ่งใดก็ตามที่ไม่ได้ลงนามโดย CA ของคลัสเตอร์จะยังคงล้มเหลวเช่นเดิม

เมื่อเปิดโปรไฟล์นั้นขึ้นมา https://console.harrow.example/install จะนำไปสู่หน้าอ้างสิทธิ์ และสามารถสร้างพาสคีย์ได้ บทที่ 2.12 การรันครั้งแรก จะอธิบายขั้นตอนต่อจากนี้

เมื่อแล็ปท็อปรีสตาร์ท

ที่เก็บคีย์มีสองส่วน ได้แก่ ตัวที่เก็บคีย์เอง และตัวเปิดผนึก (unsealer) ขนาดเล็กที่ถือคีย์ปลดล็อกไว้ หลังจากมีการรีสตาร์ทโหนดไม่ว่าในกรณีใด (การรีสตาร์ท Docker, การรีบูตแล็ปท็อป, คำสั่ง k3d cluster stop และ start) ตัวเปิดผนึกจะเริ่มต้นในสถานะปิดผนึก (sealed) ที่เก็บคีย์จะเปิดผนึกตัวเองผ่านตัวเปิดผนึกนี้ ดังนั้นจนกว่าผู้ดูแลเก็บรักษาจะเปิดผนึกตัวเปิดผนึกด้วยข้อมูลประจำตัว age ของตนเอง ทุกอย่างที่ต้องใช้คีย์จะไม่สามารถทำงานได้ นี่เป็นคุณสมบัติตามการออกแบบของระบบ และทำงานแบบเดียวกันบนคลัสเตอร์ใช้งานจริง บทที่ 2.15 วันที่สอง: การดูแลระบบปฏิบัติการ Nexus จะแสดงวิธีการเปิดผนึก

เมื่อคุณทำการประเมินผลเสร็จสิ้นแล้ว:

k3d cluster delete harrow-eval

การลบคลัสเตอร์จะเป็นการลบการติดตั้งและทุกอย่างที่อยู่ภายในนั้น

nexusctl kubeconfig

คลัสเตอร์ที่ nexusctl install --single-node สร้างขึ้นจะเป็นของ nexusctl หากต้องการเข้าถึงคลัสเตอร์ด้วย kubectl, helm หรือเครื่องมืออื่นใด ให้ขอไฟล์ kubeconfig ของคลัสเตอร์นั้น:

sudo nexusctl kubeconfig > harrow-pilot.kubeconfig
chmod 600 harrow-pilot.kubeconfig
export KUBECONFIG=$PWD/harrow-pilot.kubeconfig
kubectl -n nexus get deploy,statefulset

ไฟล์นี้ให้สิทธิ์ผู้ดูแลระบบแบบเต็มรูปแบบในการเข้าถึงคลัสเตอร์ โปรดเก็บรักษาไว้ด้วยโหมด 600 บนเครื่องของผู้ที่ดูแลการติดตั้งเท่านั้น และอย่าเก็บไว้ที่อื่น ทุกคำสั่งหลังจากนี้ในส่วนที่ 2 ที่รับค่า --context หรืออ่าน KUBECONFIG จะสามารถทำงานกับโหนดเดี่ยวผ่านไฟล์นี้ได้ และหลักการเดียวกันนี้ใช้กับการอัปเกรดด้วยเช่นกัน คำสั่ง nexusctl upgrade plan --bundle <file> และ nexusctl upgrade apply --bundle <file> บนโหนดเดี่ยวจะอัปเกรดคลัสเตอร์ k3s ที่ nexusctl เป็นเจ้าของด้วย

แผนภาพแสดงชั้นข้อมูลสี่ชั้นซ้อนกันอยู่บนกล่องที่มีป้ายกำกับว่า "เซิร์ฟเวอร์ Linux หนึ่งเครื่อง" เรียงจากด้านล่างขึ้นไป: "k3s v1.33.6+k3s1 (Traefik ใน kube-system, พอร์ต 80 และ 443)" ถัดขึ้นไปคือ "cert-manager v1.21.3 และ CA ท้องถิ่นของชาร์ต nexus-local-ca" ถัดขึ้นไปคือ "ระดับชั้นข้อมูลของ Nexus: PostgreSQL, Valkey, Neo4j, Qdrant, SeaweedFS, OpenBao" และชั้นบนสุดคือ "บริการของ Nexus: คอนโซล, บริการลงชื่อเข้าใช้, เกตเวย์ และส่วนที่เหลือ" ทางด้านขวา มีลูกศรสามเส้นจากชั้นบนสุดชี้ออกจากกล่อง โดยมีป้ายกำกับว่า console.harrow.example, api.harrow.example และ auth.harrow.example ทางด้านซ้าย มีไอคอนเทอร์มินัลที่มีป้ายกำกับว่า "nexusctl kubeconfig" ชี้เข้าไปยังชั้นของ k3s
สิ่งที่ nexusctl install --single-node ติดตั้งลงบนเซิร์ฟเวอร์ Linux หนึ่งเครื่อง

สิ่งที่นำไปใช้ต่อในคลัสเตอร์ได้

ทุกอย่างที่คุณทำบนเครื่องเดียวจะมีสิ่งที่เทียบเท่ากันบนคลัสเตอร์ ไฟล์ values เป็นไฟล์เดียวกันแต่อาจมีเรจิสทรี โหมด TLS หรือคลาสการจัดเก็บข้อมูล (storage class) ที่ต่างออกไป ดังที่แสดงใน บทที่ 2.11 รูปแบบอื่นๆ: ที่เก็บข้อมูลภายนอก, TLS และ ingress การรันครั้งแรกจะเหมือนกันทุกประการ สิ่งที่ไม่สามารถย้ายตามไปได้คือตัวการติดตั้งเอง เพราะชื่อของการติดตั้งถูกกำหนดไว้เป็นการถาวร และไม่สามารถยกการติดตั้งจากแล็ปท็อปไปไว้บนเซิร์ฟเวอร์ได้ เมื่อ Tomás ย้ายจากแล็ปท็อปไปยังเซิร์ฟเวอร์นำร่อง เขาเริ่มต้นใหม่ด้วยชื่อใหม่คือ harrow-pilot และเก็บ harrow-eval ไว้สำหรับการทดลอง