ההתנהגות הנושכת כאן מצוינת, לא מקרית: ה מפרט YAML 1.2 מגדיר כיצד סקלר לא מצוטט נפתר לסוג.
פעם שלחתי פריסה שהצמידה שירות לגרסה 1.1 כאשר קובץ התצורה אמר בבירור 1.10. לא שגיאת הקלדה. לא רע למצוא ולהחליף. קובץ YAML, שקראתי ארבע פעמים, אמר את זה:
image_tag: 1.10
והמנתח מסר לסקריפט הפריסה שלי את המספר 1.1. כי 1.10 isn't מחרוזת גרסה ל-YAML - it's a לצוף מילולית, וצפים don't לשמור על אפסים נגררים עשר הופך להיות אחד-נקודה-אחד הקובץ היה 100% תקף YAML הלינטר היה שמח.CI היה ירוק המיכל הלא נכון יצא.
זה ' זה הדבר שאף אחד לא אומר לך על אימות YAML: "valid" אינו זהה ל-"correct." בודק תחביר שעונה רק כן/לא עונה על השאלה הקלה השאלה הקשה - זו שבאמת שוברת פריסות - היא למה הפך ה-YAML שלי? מכיוון ש-YAML אינו פורמט תצורה, הוא ' הוא מנוע הסקת סוג שלובש פורמט תצורה 's בגדים, והוא מקבל החלטות לגבי הנתונים שלך שמעולם לא ביקשת ממנו לקבל.
ה מאמת יאמל על Toolz.dev עונה על שתי השאלות זה אומר לך אם המסמך מנתח, ואז זה מראה לך את התוצאה המנותחת כ-JSON - מבנה הנתונים בפועל שהכלים שלך יקבלו המחצית השנייה הזו היא מה שהיה מציל אותי. "image_tag": 1.1 בחלונית הפלט אי אפשר לקרוא לא נכון.
TL;DR: הדבק את YAML שלך לתוך מאמת יאמל ולקרוא את פלט JSON, לא רק סימן הביקורת הירוק. That's שבו כפיית סוג מראה את עצמה:
1.10→1.1,0123→123, ערכים לא מצוטטים הופכים בשקט למספרים, בוליאנים או null. זה פועל על js-yaml (YAML 1.2) כולו בדפדפן שלך, כך שסודות Kubernetes ואישורי מסד נתונים לעולם לא עוזבים את המחשב שלך. ציטוט כל דבר שחייב להישאר מחרוזת. אם אתה צריך להשוות את התוצאה מול תצורת JSON, ה פורמט JSON ו JSON Diff תרימי משם.
מה בעצם בודק מאמת YAML?
שני דברים שונים, וזה 's שווה להפריד ביניהם כי הם נכשלים אחרת.
אימות תחביר שואל: האם ניתן לנתח את הטקסט הזה בכלל? כרטיסיות שבהן רווחים שייכים, רווח חסר אחרי נקודתיים, סקלר בלוק שגופו הוא 't indented, ציטוט לא סגור. אלה הם בקול רם כשלים המנתח שלך זורק, הצינור שלך נהיה אדום, אתה מתקן את זה בשתי דקות מעצבן, לא מסוכן.
בדיקה סמנטית שואל: מה זה ניתח לתוך? כאן חיים הכשלים השקטים המסמך תקף הצינור ירוק הערך פשוט לא מה שחשבת שכתבת אף אחד לא מגלה עד שההפקה מתנהגת בצורה מוזרה, ועד אז אף אחד's מסתכל על קובץ התצורה, כי קובץ התצורה הוא "fine."
רוב הדמקה YAML באינטרנט רק לעשות את הראשון. Toolz.dev validator עושה את הראשון ולאחר מכן מוסר לך את השני - המסמך מנותח, מעובד כמו JSON, ממש ליד הקלט שלך קבל את הרגל לקרוא כי pane.It & #39;s ההבדל בין " הקובץ הוא מעוצב היטב" ו " הקובץ אומר למה התכוונתי."
אילו שגיאות YAML בעצם Break Builds?
Here's מה באמת מופיע, מדורג לפי כמה מחיי כל אחד עלה לי. כל התנהגות למטה אימתתי נגדה js-yaml 4, שהוא המנתח שמפעיל המאמת Toolz.dev ואשר מיישם את ימל 1.2 מפרט.
1. כרטיסיות. תמיד כרטיסיות.
YAML אוסר על תווי כרטיסיות להזחה. לא "discourages" - אוסר. המפרט מפורש, והודעת השגיאה ישירה בצורה מרעננת:
tab characters must not be used in indentation
הסיבה שזה ממשיך לקרות היא שהכרטיסיות אינן נראות העורך שלך מראה לך קובץ מיושר יפה; המנתח רואה תו בקרה תקן אותו במקור: הגדר את העורך שלך להכנסת רווחים, והפעל את " תקן רווח לבן" עבור קבצי YAML. שני רווחים לכל רמה, שהיא המוסכמה שכל מערכת אקולוגית גדולה של YAML התיישבה בה.
2. שכפול מפתחות
database:
host: localhost
port: 5432
host: production-db.example.com
host מופיע פעמיים מה קורה? ״ זה תלוי לחלוטין במנתח שלך, שזה משפט מחריד לכתוב על פורמט config.
js-yaml זורק: duplicated mapping key. טוֹב. זה 's ההתנהגות שאתה רוצה, וזה 's מה Toolz.dev validator יראה לך. אבל PyYAML - שזה מה Ansible, והרבה כלי Python, יושב על - לוקח בשקט את אחרון ערך וממשיך הלאה אין אזהרה מארח מסד הנתונים שלך הוא עכשיו מה שהכפיל האחרון אמר, אשר בקובץ ארוך התמזגת רע עשוי להיות במרחק שלוש מאות שורות מהמקום שבו אתה & #39;מחפשים.
זהו הארגומנט היחיד הטוב ביותר להפעלת configs דרך מאמת קפדני גם כאשר כלי הייצור שלך מקבל אותם. מאמת ש-'s מחמיר מאשר זמן הריצה שלך הוא מאמת שמוצא באגים.
3. כפייה מסוג - זו שהשיגה אותי
YAML מסיק סוגים מסקלרים לא מצוטטים. זה מאוד בטוח ולעתים קרובות זה שגוי לגבי הכוונה שלך:
| אתה כתבת | התכוונת | YAML 1.2 נותן לך |
|---|---|---|
version: 1.10 |
המחרוזת "1.10" | המצוף 1.1 |
pin: 0123 |
המחרוזת "0123" | המספר השלם 123 |
port: "8080" |
המספר 8080 | המחרוזת "8080" |
enabled: true |
בוליאנית | בוליאנית true - נכון |
value: |
מחרוזת ריקה, אולי? | null |
value: ~ |
טילדה | null |
שֶׁז 0123 שורה היא זה I'd קעקוע על אנשים. Zip קודים, PINs, מספרי חשבון, אפס-מזהים מרופדים - כל אפס מוביל שכתבת מסיבה מסוימת מקבל אכול ציטוט אותם.
הכלל שמעולם לא אכזב אותי: אם הערך הוא מזהה, גרסה, קוד או כל דבר שאתה ' לעולם לא תעשה עליו חשבון, שים אותו במרכאות. יציאות וספירת העתקים יכולים להישאר חשופים. כל מה שרק נראה מספרי צריך להיות "quoted".
4. הבוליאנים התלויים בגרסה (aka בעיית נורבגיה)
זה באמת ידוע לשמצה, והפרטים חשובים יותר מהמם.
ב ימל 1.1, הסוג הבוליאני מקבל yes, no, on, off, y, n, וההיוון שלהם, בנוסף true ו false. כך country: NO - נורווגיה's קוד מדינה ISO - מנתח כבוליאני שקר. ב ימל 1.2, שניקה את זה, רק true ו false הם בוליאנים; NO הוא רק המחרוזת "NO".
מה שאומר שאותו קובץ פירושו דברים שונים בכלים שונים:
country: NO
feature_flag: on
- js-yaml 4 (YAML 1.2, ובמה משתמש המאמת הזה):
{"country": "NO", "feature_flag": "on"}- מחרוזות. - PYYAML (YAML 1.1):
{"country": False, "feature_flag": True}- בוליאנים.
אותם בתים נתונים שונים אם ה-CI שלך מריץ לינטר Python על תצורה ששירות Node צורך, יש לך שני מנתחים שאינם מסכימים לגבי הקובץ שלך ואף אחד מהם אינו טועה.
זהו גם המקור של GitHub Actions' המוזר ביותר: ה on: המפתח שכל זרימת עבודה מתחילה בו הוא א בוליאנית למנתח YAML 1.1, כך שסקריפטים המוך קבצי זרימת עבודה ב-Python מוצאים מפתח שנקרא True במקום on. מצטט ("on":) הוא חוקי ומתקן אותו.
המהלך ההגנתי זהה לבעבר: ציטוט זה. country: "NO" אמצעים "NO" בכל מנתח שהיה קיים אי פעם.
5. הזחה סקלרית בלוק
description: |
This is not indented
ה | (מילולית) ו > סקלרי בלוק (מקופלים) זקוקים לתוכן שלהם מחורץ ביחס למפתח. תוכן לא מוזנח מסיים את הבלוק מיד והמנתח מתחיל לקרוא את הפרוזה שלך כמפתחות YAML, מה שמייצר הודעות שגיאה שנראה שאין להן שום קשר לטעות בפועל.
שווה לדעת את האינדיקטורים המשתוללים בזמן שאתה ' כאן: | שומר על קו חדש נגרר אחד, |- מפשיט את זה, |+ שומר את כולם.If you're הטמעת מפתח פרטי או סקריפט ומשהו במורד הזרם מתלונן על קו חדש נגרר, זה הכפתור שלך.
6. תווים מיוחדים לא מצוטטים
רווח נקודתיים בתוך ערך לא מצוטט מסיים את הערך ומתחיל מפתח חדש. זה נושך בהודעות שגיאה וכתובות URL:
message: Error: file not found # parse error
regex: [a-z]+ # parsed as a LIST, not a string
time: "22:22" # quote it — in YAML 1.1 this was base-60!
[, {, #, &, *, !, |, >, %, @ בתחילת סקלר הכל אומר משהו. ציטוט קודם, שאל שאלות אחר כך.
כיצד אוכל לאמת את YAML ב-Toolz.dev?
- פתח את מאמת יאמל. אין חשבון, אין העלאה.
- הדבק את המסמך שלך. קובץ ערכי Helm, חיבור דוקר, זרימת עבודה - whatever's מתנהג בצורה לא נכונה.
- פגע ב-Validate. שגיאות חוזרות עם המדויק שורה ועמודה מהמנתח, בתוספת המנתח' מחרוזת סיבה משלו (
bad indentation of a mapping entry,duplicated mapping key, וכן הלאה). - קרא את חלונית הפלט של JSON. זה הצעד שאנשים מדלגים עליו והוא ' הוא זה שחשוב. סרוק את זה עבור הערכים שאכפת לך מהם. Is
image_tagמחרוזת או מספר? האם היציאה הזו מצוטטת? האם ערך ריק הפךnull? - תקן, אמת מחדש. שגיאות יכולות להסוות זו את זו - המנתח עוצר בראשון שהוא יכול ' לא להתאושש ממנו, אז תיקון אחד לפעמים מגלה שניים נוספים. זה ' זה נורמלי, לא סימן שהמצב מחמיר.
מגבלה ידועה אחת, נאמר בפשטות
המאמת מנתח כעת א מסמך YAML יחיד. אם אתה מדביק קובץ מרובה מסמכים - מספר מניפסטים של Kubernetes מופרדים על ידי --- בקובץ אחד, שהוא דפוס נפוץ ביותר - הוא ידווח:
expected a single document in the stream, but found more
That's המנתח תקין, לא הקובץ נשבר. הפתרון כיום הוא לאמת כל מסמך בנפרד: הדבק את כל מה שמעל ---, בדוק את זה, ואז הדבק את הנתח הבא. תמיכה בריבוי מסמכים נמצאת ברשימה שלי בדיוק בגלל שמשתמשי Kubernetes פגעו בזה מיד, ו-I' מעדיף לספר לך על הפער מאשר לתת לך לגלות אותו באמצע המקרה.
YAML נגד JSON: מתי עלי להשתמש באיזה?
YAML 1.2 הוא ערכת-על קפדנית של JSON - כל מסמך JSON חוקי הוא YAML חוקי, וזו הסיבה שהמאמת יכול למסור לך פלט JSON בכלל. אבל לפורמטים יש אישיות הפוכה.
| ימל | JSON | |
|---|---|---|
| מבנה מוגדר על ידי | הזחה (משמעותית למרחב הלבן) | פלטה וסוגריים (מפורש) |
| תגובות | כן (#) |
לא |
| הסקת סוג | אגרסיבי - מסיק מספרים, בוליאנים, אפס, תאריכים | None - ציטוטים פירושם מחרוזת, תמיד |
| ריבוי מסמכים | כן (--- מפריד) |
לא |
| שימוש חוזר | עוגנים (&), כינויים (*), מפתחות מיזוג (<<) |
אף אחד |
| מצב כשל | פרשנות שגויה שקטה | שגיאת ניתוח חזק |
| הכי טוב ב | קבצים שבני אדם כותבים ועורכים | החלפת מכונות נתונים |
המסחר הוא אמיתי וזה הולך לשני הכיוונים. YAML' קריאות והערות הן בדיוק הסיבה לכך שתצורת תשתית חיה שם - אף אחד לא רוצה לשמור על מניפסט Kubernetes בן 400 שורות ב-JSON ללא הערות. JSON' חוסר פיקחות מוחלט הוא בדיוק הסיבה שממשקי API משתמשים בו: "1.10" הוא "1.10" ואין על מה לדון.
הכלל שלי: YAML עבור קבצים שאנשים עורכים, JSON עבור מכונות נתונים עוברים. וכאשר קובץ YAML נוצר על ידי תוכנית במקום מוקלד על ידי אדם, זה ' הוא ריח - תצורה שנוצרה על ידי מכונה לא מקבלת אף אחד מהיתרונות של YAML's וכל הסיכונים שלו.
אם אתה' עוברים בין השניים, ה ממיר JSON ל-YAML מטפל בטרנספורמציה, וה פורמט JSON יסדר את הצד השני.
מהם עוגנים וכינויים, והאם עלי להשתמש בהם?
YAML מאפשר לך להגדיר בלוק פעם אחת ולעשות בו שימוש חוזר. עוגן עם &, התייחסות עם *, התמזג למפה עם <<:
defaults: &defaults
adapter: postgres
host: localhost
port: 5432
development:
<<: *defaults
database: myapp_dev
test:
<<: *defaults
database: myapp_test
שניהם development ו test צא עם המתאם, המארח והיציאה שהתמזגו ב. It's שימושי באמת, ו-js-yaml מטפל בזה - אימתתי שהמיזוג נפתר כהלכה.
שתי אזהרות, אבל.
ראשון, מפתחות מיזוג הם סיומת YAML 1.1, לא חלק מליבת YAML 1.2. התמיכה נפוצה אך לא אוניברסלית, וזו שתופסת אנשים - GitHub Actions לא תומך בהם. עוגנים בקובץ זרימת עבודה לא יעשו מה שאתה רוצה בדוק את הצרכן שלך לפני שאתה נשען על זה.
שנית, עוגנים מקשים על הקריאה של קובץ עבור האדם הבא, ובתצורה האדם הבא הוא בדרך כלל אתה ב-2 לפנות בוקר. אני משתמש בהם עבור בלוקים שחוזרים על עצמם באמת ולעולם לא עבור פיקחות.
בעוד אנחנו' נמצאים בצד המסוכן של YAML: הפורמט תומך בתגיות מותאמות אישית שחלק מהמנתחים משתמשים בהן כדי לבנות אובייקטים שרירותיים. Python's yaml.load() היה מפורסם לניצול בדרך זו, וזו הסיבה yaml.safe_load() קיים ומדוע כדאי להשתמש בו - תמיד - בכל YAML שהגיע מחוץ לצוות שלך. js-yaml's load() ב-v4 בטוח כברירת מחדל (הוא זכה 't לבנות סוגים שרירותיים), וזה דבר אחד פחות לדאוג כאן.
איך אני מפסיק לכתוב YAML שבור מלכתחילה?
מניעה מנצחת אימות, ורובו הוא תצורת עורך:
- שני רווחים, אף פעם לא כרטיסיות. הגדר אותו לפי סוג קובץ כך שתוכל 't לשכוח.
- הפעל עיבוד רווח לבן עבור
.yml/.yaml. אם אתה יכול לראות את הכרטיסייה, זכית ב-'t commit the tab. - התקן שרת שפות YAML. אימות סכימה בזמן אמת נגד Kubernetes, GitHub Actions וסכימות חיבור דוקר תופס סוג שלם של שגיאות שאימות תחביר יכול't: YAML חוקי עם מפתח שגוי באיות.
- ציטוט כברירת מחדל כאשר יש ספק. העלות של הצעת מחיר מיותרת היא אפס העלות של חסר היא פריסה.
- אמת לפני שאתה דוחף, לא אחרי ש-CI נכשל. הדבקה בכרטיסיית דפדפן אורכת שמונה שניות; צינור כושל לוקח שמונה דקות.
- עבור Kubernetes, שכב את הצ'קים. מבנה תופס אימות תחביר;
kubectl apply --dry-run=clientסכימת תופס הם מוצאים באגים שונים ואתה רוצה את שניהם.
וההרגל שבעצם שינה לי דברים: כשפריסה מונעת תצורה עושה משהו בלתי מוסבר, תסתכל על הפלט המנותח לפני שאתה מסתכל על כל דבר אחר. לא הקובץ הפלט המנותח הקובץ הוא סיפור על מה שהתכוונת הפלט המנותח הוא מה שקרה בפועל.
זה ' הוא אותו אינסטינקט ששולט בכל דבר שלי זרימת עבודה של ניפוי באגים ב-API - קרא את הנתונים, לא את הקוד - והוא חל באותה מידה על configs כמו על תגובות.If you want the wider tour of what else lives in that toolbox, the מדריך כלי קידוד מכסה אותו.
שאלות נפוצות
מדוע YAML שלי מאמת אך עדיין שובר את הפריסה שלי?
כי תוקף תחביר ונכונות סמנטית הם דברים שונים. YAML מסיק סוגים מערכים לא מצוטטים, אז 1.10 הופך לצוף 1.1, 0123 הופך למספר השלם 123, וערך ריק הופך null - הכל במסמך חוקי לחלוטין קרא את פלט JSON המנותח, לא רק את תוצאת המעבר/נכשל, וציטט כל ערך שחייב להישאר מחרוזת.
למה YAML הופך את מספר הגרסה שלי למספר אחר?
1.10 הוא צף מילולי ל-YAML, ומצופים אינם משמרים אפסים נגררים, ולכן הוא מחליט לעשות זאת 1.1. יש לצטט כל גרסה, מספר בנייה או מזהה מרופד אפס: version: "1.10". זוהי אחת הטעויות היקרות ביותר של YAML מכיוון שהקובץ נראה נכון והניתוח מצליח.
מהי בעיית נורבגיה ב-YAML?
ב-YAML 1.1, הערכים no, NO, off, ו yes האם בוליאנים, אז נורווגיה's קוד מדינה NO מנתח כמו false. YAML 1.2 תיקן את זה - בלבד true ו false הם בוליאנים - אבל כלים רבים (בעיקר PyYAML, שבו Ansible משתמש) עדיין מיישמים 1.1. לכן אותו קובץ יכול להיות אומר דברים שונים בכלים שונים. ציטוט הערך (country: "NO") הופך אותו למחרוזת בכל מקום.
האם אוכל להשתמש בכרטיסיות להזחה ב-YAML?
מס 'מפרט YAML אוסר על תווי כרטיסיות בהזחה, ומנתחים דוחים אותם עם שגיאה כמו " אין להשתמש בתווי כרטיסייה בהזחה." הגדר את העורך שלך להכנסת רווחים עבור קבצי YAML - שני רווחים לכל רמה הם המוסכמה הסטנדרטית.
האם Toolz.dev YAML Validator תומך בקבצי ריבוי מסמכים?
לא כרגע. זה מאמת מסמך בודד, כך שקובץ המכיל כמה מניפסטים של Kubernetes מופרדים על ידי --- מחזירה "צפוי מסמך בודד בזרם." אמת כל מסמך בנפרד כפתרון עוקף. מתוכננת תמיכה בריבוי מסמכים.
האם מותר להשתמש במפתחות כפולים ב-YAML?
המפרט אומר שמפתחות המיפוי חייבים להיות ייחודיים, אבל המנתחים לא מסכימים בפועל. js-yaml - שבו משתמש המאמת הזה - זורק " מפתח מיפוי משוכפל" שְׁגִיאָה. PyYAML שומר בשקט על הערך האחרון, מה שאומר שכפיל יכול לעקוף בשקט את התצורה שלך ללא אזהרה כלל. הפעלת התצורה שלך דרך מאמת קפדני תופסת זאת לפני שזמן הריצה שלך מקבל זאת בשקט.
האם זה בטוח לאמת סודות ואישורים של Kubernetes באינטרנט?
עם מאמת Toolz.dev, כן - הניתוח מתרחש כולו בדפדפן שלך באמצעות JavaScript ושום דבר לא מועבר לשרת כלשהו. אתה יכול לאשר זאת בעצמך על ידי פתיחת הדפדפן שלך's כרטיסיית רשת בזמן שאתה מאמת ומתבונן שלא הוגשה בקשה. החל את אותה בדיקה על כל כלי מקוון לפני הדבקת תצורת תשתית לתוכו.
מה ההבדל בין .yml ו.yaml?
שום דבר לא פונקציונלי - שתי ההרחבות מוכרות על ידי כל מנתח YAML. ההמלצה הרשמית היא .yaml; .yml שורד מעידן ההרחבות של שלוש תווים ונשאר נפוץ ביותר (Docker Compose ו-GitHub Actions שניהם ברירת מחדל). בחר אחד והישאר עקבי בתוך פרויקט.
כיצד אוכל להמיר את YAML ל-JSON?
הדבק את ה-YAML לתוך המאמת וקרא את חלונית הפלט - הוא מציג את המסמך המנותח כ-JSON, שהוא ההמרה. מכיוון ש-YAML 1.2 הוא ערכת-על של JSON, לכל מסמך YAML חוקי יש מקבילה ל-JSON, אך תחילה מוחל הסקת סוג, כך שלא מצוטט 1.10 מגיע כמו 1.1 ו 0123 כ 123. ציין תחילה את הערכים האלה אם אתה צריך שהם יישמרו כמחרוזות.
כיצד אוכל לאמת את YAML מול סכימה?
מאמת זה בודק תחביר ומציג את התוצאה המנותחת, אך הוא אינו מאמת מול סכימה - כלומר בדיקה נפרדת המאשרת את המפתחות וסוגי הערכים שלך תואמים למה שכלי כמו Kubernetes או GitHub Actions מצפה. לאימות סכימה, השתמש בשרת שפת YAML בעורך שלך, או ב-CLI מודע לסכימה כגון kubeconform לקוברנטס או kubectl apply --dry-run=client. אימות תחביר וסכימה תופסים באגים שונים, אז הפעל את שניהם.
