Cloud Build ล้มเหลวโดยมีข้อผิดพลาด SUBSTITUTIONVARIABLENOT_DEFINED สำหรับเทมเพลต CI และสคริปต์การตรวจสอบการทดแทนที่ไปป์ไลน์แบบคงที่ทำงาน

Cloud Build ได้กลายเป็นเครื่องมือสำคัญในการผสานรวมและเวิร์กโฟลว์การทำให้ใช้งานได้อย่างต่อเนื่องของนักพัฒนาและองค์กรจำนวนมาก การผสานรวมอย่างแน่นหนากับผลิตภัณฑ์ Google Cloud Platform (GCP) อื่นๆ และเวิร์กโฟลว์แบบใช้สคริปต์ได้ทำให้เป็นที่ชื่นชอบสำหรับทีมที่ต้องการไปป์ไลน์ CI/CD ที่ปรับแต่งได้และปรับขนาดได้ อย่างไรก็ตาม เช่นเดียวกับเครื่องมือที่มีประสิทธิภาพอื่นๆ Cloud Build ก็มีคุณลักษณะพิเศษ โดยเฉพาะอย่างยิ่งในเรื่องของตัวแปรและการกำหนดพารามิเตอร์ ปัญหาที่น่าหงุดหงิดประการหนึ่งที่นักพัฒนาซอฟต์แวร์จำนวนมากพบเมื่อเร็วๆ นี้ก็คือข้อผิดพลาดSUBSTITUTION_VARIABLE_NOT_DEFINEDปัญหาที่เข้าใจยากนี้อาจทำให้ไปป์ไลน์ทั้งหมดต้องหยุดชะงัก ส่งผลต่อความเร็วของการพัฒนาและเพิ่มเวลาในการแก้ไขปัญหา

TL;ดร

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

ทำความเข้าใจกับข้อผิดพลาด SUBSTITUTION_VARIABLE_NOT_DEFINED

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

ตัวอย่างเช่น เทมเพลต Cloud Build ทั่วไปอาจมีขั้นตอนการสร้างดังต่อไปนี้

ขั้นตอน:
- ชื่อ: 'gcr.io/cloud-builders/docker'
  หาเรื่อง: ['สร้าง', '-t', '${_IMAGE_NAME}', '.']

ในที่นี้ ${_IMAGE_NAME} เป็นตัวแปรทดแทนที่ผู้ใช้กำหนด หากไม่ได้ระบุตัวแปรนี้ในขณะที่ทริกเกอร์บิวด์ อาจผ่านการกำหนดค่าทริกเกอร์หรือบรรทัดคำสั่ง Cloud Build จะล้มเหลวทันทีโดยมีข้อผิดพลาดSUBSTITUTION_VARIABLE_NOT_DEFINED

สาเหตุหลักในการใช้งานเทมเพลต CI

ปัญหานี้จะกลายเป็นปัญหาอย่างยิ่งเมื่อทีมใช้เทมเพลตที่ใช้ร่วมกัน หรือเมื่อพื้นที่เก็บข้อมูลที่แตกต่างกันใช้ตรรกะ CI เดียวกันผ่านการกำหนดค่า YAML แบบรวมศูนย์ บ่อยครั้งที่ที่เก็บหรือทริกเกอร์บิวด์แต่ละรายการอาจจำเป็นต้องกำหนดตัวแปรที่แตกต่างกัน แต่การบังคับใช้ความสอดคล้องกลายเป็นเรื่องท้าทาย หลายทีมถือว่าตัวแปรทดแทนเป็นทางเลือก หรือมีทางเลือกเริ่มต้น เพียงเพื่อจะพบข้อผิดพลาดนี้เมื่อตัวแปรหายไปในบริบทของบิลด์ที่คาดหวังไว้

สถานการณ์ที่อาจเกิดข้อผิดพลาดนี้:

• เมื่อลืมค่าเริ่มต้นในการตั้งค่าทริกเกอร์
• เมื่อมีการเพิ่มเทมเพลตใหม่แต่ไม่ได้บันทึกหรือบังคับใช้ตัวแปรที่จำเป็นทั้งหมด
• เมื่อนักพัฒนาโคลนเทมเพลตข้ามสภาพแวดล้อม (เช่น การจัดเตรียม การผลิต) แต่ละเว้นคำจำกัดความของตัวแปรเฉพาะ

การแก้ไขเชิงปฏิบัติ: สคริปต์ตรวจสอบความถูกต้องของการทดแทน

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

สคริปต์จะสแกนสภาพแวดล้อมปัจจุบันและพยายามยืนยันการมีอยู่ (และบางครั้งอาจพิมพ์หรือรูปแบบ) ของตัวแปรที่สำคัญทั้งหมด หากมีสิ่งใดขาดหายไป ระบบจะหยุดดำเนินการก่อนกำหนดและจัดเตรียมรายการที่มนุษย์สามารถอ่านได้ซึ่งตัวแปรใดหายไป

นี่เป็นตัวอย่างง่ายๆ ของสคริปต์ที่เขียนด้วย bash:

#!/bin/bash
ชุด -e

REQUIRED_VARS=(
  "_IMAGE_NAME"
  "_SERVICE_NAME"
-

สำหรับ VAR ใน "${REQUIRED_VARS[@]}"
ทำ
  ถ้า [[ -z "${!VAR}" ]]; แล้ว
    echo "ข้อผิดพลาด: ไม่ได้กำหนดตัวแปรทดแทนที่จำเป็น ${VAR}"
    ทางออก 1
  ฟิ
เสร็จแล้ว

echo "มีตัวแปรทดแทนที่จำเป็นทั้งหมดอยู่"

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

การบูรณาการเข้ากับเวิร์กโฟลว์ Cloud Build

ในขั้นตอนการทำงานจริง เชลล์สคริปต์ตรวจสอบความถูกต้องสามารถรวมเป็นคำสั่งอินไลน์หรือนำเข้าจากไฟล์สคริปต์ที่ใช้ร่วมกันในตำแหน่งที่ปลอดภัย เช่น ที่เก็บข้อมูล GCS เวอร์ชัน โดยทั่วไปจะเป็นขั้นตอนแรกในไฟล์ cloudbuild.yaml:

ขั้นตอน:
- ชื่อ: 'gcr.io/cloud-builders/bash'
  จุดเริ่มต้น: 'ทุบตี'
  หาเรื่อง: ['-c', './validate_vars.sh']

สิ่งนี้ทำให้ทีมมีความสามารถ:

• กำหนดเวอร์ชันตรรกะการตรวจสอบ CI ของพวกเขา
• รักษาแหล่งความจริงแหล่งเดียวสำหรับตัวแปรที่คาดหวัง
• ลดรอบการแก้ไขจุดบกพร่องที่มีเสียงดังซึ่งเกี่ยวข้องกับการแก้ไขทริกเกอร์แบบลองผิดลองถูก

ประสบการณ์นักพัฒนาที่ได้รับการปรับปรุง

การแนะนำสคริปต์ตรวจสอบนี้มีผลทันที:

• ไปป์ไลน์ล้มเหลวน้อยลงเนื่องจากตัวแปรหายไปโดยไม่มีใครสังเกตเห็น
• ข้อความแสดงข้อผิดพลาดที่ชัดเจนยิ่งขึ้นซึ่งชี้ไปที่ปัญหาโดยตรงแทนที่จะเป็นบันทึกที่ไม่ชัดเจน
• เตรียมความพร้อมได้เร็วขึ้นสำหรับนักพัฒนาใหม่ที่ใช้เวิร์กโฟลว์ CI ที่มีอยู่ซ้ำโดยไม่จำเป็นต้องมีความรู้เกี่ยวกับตัวแปรที่คาดหวังจากชนเผ่าอย่างสมบูรณ์

เมื่อเวลาผ่านไป บางทีมได้ขยายเครื่องมือตรวจสอบเพื่ออนุญาตตัวแปรเสริมและตั้งค่าทางเลือกทำให้เทมเพลตที่ใช้ร่วมกันมีความยืดหยุ่นมากยิ่งขึ้น โปรแกรมอื่นๆ จับคู่กับการตรวจสอบสคีมา YAML เพื่อลบไปป์ไลน์ cloudbuild.yaml ทั้งหมด ณ รันไทม์

การป้องกันข้อผิดพลาดในโครงการใหม่

เพื่อให้โครงการในอนาคตปราศจากปัญหานี้ ขอแนะนำให้ปฏิบัติตามแนวทางปฏิบัติที่ดีที่สุดเหล่านี้:

• บันทึกตัวแปรการทดแทนที่จำเป็นทั้งหมดในคู่มือ README หรือ CI สำหรับ repo
• ใช้สคริปต์ตรวจสอบความถูกต้องในเทมเพลตใหม่ที่เพิ่มลงในเวิร์กโฟลว์ CI/CD ของคุณ
• กำหนดหลักการตั้งชื่อที่ชัดเจน(เช่น ตัวแปรที่ขึ้นต้นด้วย _ หมายถึงการแทนที่แบบกำหนดเองที่จำเป็น)
• ตั้งค่าเริ่มต้นในบิลด์ตามความเหมาะสม หรือจัดเตรียมตรรกะตัวแปรเสริมผ่านการเขียนสคริปต์

ความคิดสุดท้าย

แม้ว่าข้อผิดพลาดSUBSTITUTION_VARIABLE_NOT_DEFINEDอาจดูไม่เป็นอันตรายเมื่อมองแวบแรก แต่ก็แสดงถึงปัญหาที่กว้างขึ้นในด้านสุขอนามัย CI/CD และการจัดการการกำหนดค่า การปฏิบัติต่อการตรวจสอบตัวแปรในฐานะองค์ประกอบระดับเฟิร์สคลาสของไปป์ไลน์ของคุณจะช่วยให้มั่นใจได้ว่าแนวทางปฏิบัติอัตโนมัติที่แข็งแกร่งขึ้น บิลด์ที่เสียหายน้อยลง และนักพัฒนามีความสุขมากขึ้น ด้วยการใช้สคริปต์ตรวจสอบความถูกต้องแบบง่ายๆ หลายทีมสามารถปรับปรุงเวิร์กโฟลว์ไปป์ไลน์ของตน และลดการหยุดทำงานและความพยายามในการแก้ไขจุดบกพร่องได้อย่างมาก

คำถามที่พบบ่อย: ตัวแปรและการตรวจสอบความถูกต้องของการทดแทน Cloud Build

• ถาม: ตัวแปรทดแทนใน Cloud Build คืออะไร
  ตัวแปรทดแทนคือตัวยึดตำแหน่งในไฟล์ cloudbuild.yaml ซึ่งจะถูกแทนที่ด้วยค่าจริงเมื่อมีการทริกเกอร์บิวด์ ตัวแปรเหล่านี้ใช้เพื่อปรับแต่งบิลด์สำหรับสภาพแวดล้อมหรือการกำหนดค่าที่แตกต่างกัน
• ถาม: เหตุใดฉันจึงเห็นข้อผิดพลาด SUBSTITUTION_VARIABLE_NOT_DEFINED
  ข้อผิดพลาดนี้มักเกิดขึ้นเมื่อตัวแปรที่อ้างอิงในไฟล์ YAML ไม่ถูกส่งผ่านทริกเกอร์บิวด์หรือสภาพแวดล้อม ทำให้ไม่ได้กำหนดไว้ขณะรันไทม์
• ถาม: ฉันจะจัดเตรียมตัวแปรทดแทนเมื่อทริกเกอร์บิลด์ได้อย่างไร
  คุณสามารถส่งตัวแปรการทดแทนผ่าน Google Cloud Console เมื่อตั้งค่าทริกเกอร์ หรือผ่าน gcloud CLI โดยใช้แฟล็ก --substitutions
• ถาม: ฉันสามารถตั้งค่าเริ่มต้นสำหรับตัวแปรทดแทนได้หรือไม่
  Cloud Build ไม่รองรับค่าเริ่มต้นโดยตรงใน YAML แต่คุณใช้สคริปต์ลอจิกเพื่อจัดการตัวแปรที่ไม่ได้กำหนดและกำหนดทางเลือกสำรองทางโปรแกรมในสคริปต์ทุบตีหรือ Python
• ถาม: วิธีใดคือวิธีที่ดีที่สุดในการบังคับใช้การแสดงตนของตัวแปรในหลายโปรเจ็กต์
  ใช้สคริปต์ตรวจสอบความถูกต้องที่ใช้ร่วมกันที่จุดเริ่มต้นของเทมเพลต cloudbuild.yaml ทั้งหมดเพื่อบังคับใช้ความสอดคล้องและตรวจสอบอินพุตก่อนที่จะดำเนินการงานสร้างต่อไป