私は昨年の午後、同僚が正しいと誓ったHelm値ファイルのデバッグに費やしました すべてのキーが正しく見えました サービスは開始を拒否しました 犯人は次の4 文字であることが判明しました: NO 国コードとして、引用符で囲まれていませんが、リージョンのリストにあります。 YAML パーサーはそれをブール値として読みます false、 レンダリングされたテンプレート false ヘッダーに, そして、要求はYAMLもノルウェーも言及していないエラーメッセージの下流で拒否されました. そのバグは名前を持っているために十分に有名です - ノルウェー問題 - そしてそれは私たちのほとんどが扱っている形式で待っている驚きの一族の一つにすぎません " JSON より良い空白で. "
tl;dr: ザ・ YAML から JSON へのコンバータ YAML ドキュメントを解析し、同等の JSON を出力し、途中でアンカー、エイリアス、マージ キー、ブロック スカラーを解決します。 json としてコンフィグを表示すると、その解釈がクラスターに到達する前に、パーサーが値の意味を決定したもの (どのタイプを推測し、どの参照を拡張したのか) が正確に表示されます。ブラウザー内で完全に実行されます。
YAMLからJSONへの変換は、形式の変更だけではありません。 これは、構成に実際に含まれているものについて利用可能な最速の監査です。 JSONにはコメントもアンカーも、構文が完全に述べている以上の暗黙的な型付けもないため、マニフェストのJSONビューはその解決された明確なバージョンです。このガイドでは、YAMLがJSONにどのようにマッピングされるか、実際のインシデントを引き起こす型と参照の動作、コンフィグのデバッグ、マニフェストに対するスクリプト作成、またはテストフィクスチャの書き込みを行う際のコンバータの使用方法について説明します。
YAMLからJSONへの変換は実際に何をしますか?
関係は偶発的ではなく定義されます YAML 1.2 仕様 は、YAML が JSON のスーパーセットであるため、すべての JSON ドキュメントはすでに有効な YAML であると述べています。 YAML と JSON は、値、順序付きシーケンス、およびスカラーへのキーのマッピングという同じ 3 つのことを記述します。変換により、YAML ドキュメントがウォークされ、各コンストラクトが JSON 相当のもので放出されます。ブロック マッピングはオブジェクトになります。ブロック シーケンスは配列になります。スカラーは、YAML コア スキーマによる解決方法に応じて、文字列、数値、ブール値、または null になります。
構造部分は機械的なので面白くない 興味深い部分は、コンバータがあなたに代わって決定を下さなければならない場所であるため、YAMLがJSONが表現できないすべてです:
| YAML 機能 | JSONが取得するもの | なぜ重要なのか |
|---|---|---|
コメント ()# ...) |
落とした | JSON にはコメント構文がありません; コンフィグのドキュメントは存続しません |
アンカーとエイリアス ()&base、 *base) |
拡張コピー | JSONには参照構文がないため、共有ブロックは複製されます |
キーをマージ ()<<: *base) |
オブジェクトに平らに | マージキーの仕様に従って、明示的なキーはマージされたキーを上書きします |
| ブロック スカラー (` | , >`) |
エスケープ付きの単一の文字列 |
複数の文書 ()---) |
文書の配列 | Kubernetes バンドルは、リソースごとに 1 つの要素を持つ JSON 配列になります |
| 暗黙的な型付け | 解決済みの型 | 引用なし 8080 が数になる、 true ブール値、 null ヌル |
その最後の行は凝視する価値のある行です.JSONは構文を通してすべての値にその型を宣言するように強制します: quotesは平均文字列, bare digitsは平均数値.YAMLはテキストの形から型を推測します.JSONに変換すると推論が見えるようになります. もしバージョン文字列を期待していてJSONが示してくれるなら, 1.1 YAMLが言ったところ 1.10、あなたがそうでなければ出荷していたであろうバグを見つけました.
なぜYAML& #39; s暗黙的な入力は、実際の停止を引き起こします
YAML 1.2 コアスキーマは、引用符で囲まれていないスカラーをパターンごとに解決します。桁は整数になります。小数点または指数を持つ桁は浮動小数点になります。 true あんど false ブール値になる. null あんど ~ null になります. それ以外は全て文字列です.
それは、あるタイプのように見え、別のタイプとして意図されている値を満たすまで、きちんと聞こえます:
- ポートと ID.
port: 08080は8080 という数字ではありません。 0 が先にあるとコアスキーマの下では無効な整数になるので、ほとんどのパーサーは文字列をハンドバックし、古いものでは8 進数として解釈するものもあります。 0 が先にある郵便番号、電話番号、アカウントIDも同じ問題を抱えています。 - バージョン.
version: 1.10は 浮き1.1.末尾のゼロがなくなり、パーサーが警告しない。これをコンテナタグと比較し、ルックアップが失敗する。 - 国および言語コード. YAML 1.1 では、PyYAML はデフォルトで引き続きこのツールに従い、多くの Ruby および古い Java ツールも追加されます
y、n、yes、no、on、そしてoffは ブール値.NO、ON、そしてNA現実世界ではまったく普通の 2 文字のコードです。 - 時間と六十進法. YAML 1.1 も解析します
12:3060 進数の 750 として。 cron のような文字列または継続時間のような文字列は、整数に消える可能性があります。
これらのそれぞれはサイレントデータ破損であり、解析エラーではありません。文書は有効で、パイプラインは緑色で、値は間違っています。 converter' s 弦を張る オプションはまさにこのクラスの調査のために存在します: スイッチをオンにすると、すべての単純なスカラーが文字列として戻ってくるため、2 つの変換を並べて比較し、パーサーがどの値を再解釈していたかを正確に確認できます。そのオプションなしで JSON が表示するものはすべて、現在実稼働パーサーが実行している可能性が最も高くなります。
ソース YAML の修正は常に同じです。意味がテキストであるものを引用します。 port: "8080"、 version: "1.10"、 region: "NO".引用符はコストをかからず、バグのカテゴリ全体を削除します。 YAML を記述するのではなく JSON から生成する場合は、 JSON から YAML へのコンバータ 曖昧な値に対してその引用を自動的に適用します。
アンカー、エイリアス、マージキーの変換方法
アンカーはYAML& #39; sの繰り返しに対する答えです。 でノードをマークします &name、そして後で参照してください *name:
defaults: &defaults
restartPolicy: Always
terminationGracePeriodSeconds: 30
web:
<<: *defaults
replicas: 3
worker:
<<: *defaults
terminationGracePeriodSeconds: 120
JSONは " (引用) を言う方法がありません 向こうと同じ値です " だからコンバータはすべての参照を完全なコピーに展開します 上の出力は3 つのオブジェクトになり それぞれが独自のものを運びます restartPolicy、そしてJSONは、それを生成したYAMLよりも長いです。 それは変換の欠陥ではありません - それはYAMLが意味するものです、書き出されます。
マージキー << 優先順位のルールは後ろ向きになりやすいため、独自の注意が必要です。子マッピングで明示的に記述されたキーは、マージによって引き込まれたキーに勝ちます。の例では、 worker マージ線が明示的なキーの上または下に表示されるかどうかに関係なく、最終的に猶予期間は 30 ではなく 120 になります。コンバーターはそのルールを実装するため、JSON は効果的なマージ後の構成を示します。これは通常、実際に検査したかったものです。
これから2 つの実用的な使い方が続きます。 まず、コンフィグが重いアンカリングを使用する場合、JSONへの変換が " に答える最も早い方法です。この環境は実際に何に解決しますか?" デプロイを実行せずに。 2 番目に、エイリアスに一致するアンカーがない場合、つまり 1 つの大きなファイルをいくつかに分割する一般的な結果である場合、コンバータは、サイレントに null を生成するのではなく、行番号のエラーとして報告します。
ブロックスカラーの変換方法
YAMLには複数行のテキストを埋め込む2 つの方法があり、それらは異なる動作をします:
- リテラル ()
|) すべての改行を記述どおりに保持します。シェルスクリプト、pem証明書、sql、および空白に敏感なあらゆるものにそれを使用します。 - 折られる ()
>) 連続した行を 1 つのスペースで結合し、空白行を段落区切りとして扱います。ソース ファイルに折り返すものの、値に結合したい散文に使用します。
どちらも末尾の改行を制御するチョンピングインジケータを受け入れます。 clipping と呼ばれるデフォルトは、ちょうど1 つの末尾の改行を保持します。 マイナス ()|-)後続の改行をすべてストリップします。 ()をプラスします|+) それらをすべて保持します.
JSON では、これらすべてが 1 つの文字列に折りたたまれます \n escapes. JSON ビューが便利なもう 1 つの理由は、それが明確であることです。 A | 最後の行が誤ってインデントされたブロック、または a > 別々に保つつもりだった 2 つのラインを折り畳んでブロックすることは、JSON では明らかですが、YAML ではほとんど見えません。コンバーターは、単純な実装をキャッチするケースも処理します - a # リテラル ブロック内の文字はコメントではなくコンテンツであり、シェルバングで始まるシェルスクリプトを埋め込んだ瞬間に重要になります。
YAML to JSON Converterの使い方
ステップ1:文書を貼り付けます
任意の YAML を入力パネルに貼り付けます: Kubernetes マニフェスト、a docker-compose.yml、 GitHub Actions ワークフロー 、 Ansible プレイブック 、 a .gitlab-ci.yml、 または アプリケーションコンフィグ マルチドキュメントファイル with --- 分離器は大丈夫です - 各ドキュメントは独立して解析されます。 をクリックします サンプルをロードします ネストされたマップ、シーケンス、空のコレクション、およびリテラル ブロック スカラーを実行する現実的な展開から始めるには。
解析しないのはタブ文字によるインデントです。 YAML はタブを完全に禁止しており、コンバータは推測ではなく問題のある行番号でそう言います。 Enter にタブを挿入するエディタは通常のソースです。 " インデントをスペースに変換して引用; ファイル全体を一度に修正するコマンドが最も多くあります。
ステップ2: 出力形状を選択します
ピック 2スペース、 4スペース、または 縮小.minified は、結果を a に貼り付けようとしているときに必要なものです curl body または環境変数。 indented 出力は、人間が読み込まなければならないときに必要なものです。
キーの並べ替え すべてのレベルでオブジェクトキーをアルファベット順に書き換えます これは、コンフィグの2 つのバージョンを比較する場合に非常に貴重です: キーの順序のみが異なる2 つのファイルは、同一のソートされたJSONを生成するため、差分は実際の変更に両方の出力を供給します json 差分 ツールを使用すると、行ごとの比較ではなく、正確な構造比較が得られます。
弦を張る 上で説明したように、スカラー強制を無効にします。すべての値の生のテキストを表示したい場合、またはダウンストリームの消費者がとにかくすべてを文字列として扱う場合に使用します。
ステップ3: エラーを変換して読み取る
クリック 変換する。ドキュメントが適切にフォーミングされている場合、JSON は行数、キー数、バイト サイズ、および - マルチドキュメント ストリームの場合 - 見つかったドキュメントの数とともに下に表示されます。
整形式でない場合、エラーは行に名前を付けます。メッセージは、実際に発生する失敗をカバーします: インデントに使用されるタブ、兄弟と一貫性なくインデントされた行、終端されていない引用文字列、アンカーのないエイリアス、マッピングではないものを指すマージ キー。行番号により、5 分間のハントが 5 秒間の修正に変わります。
ステップ4: コピー、ダウンロード、または続行し続ける
JSON をクリップボードにコピーするか、としてダウンロードします .json ファイル。そこから、一般的な次のステップは、pretty-printing と validating です JSON フォーマッタ、コンフィグローダーの型を生成します JSON から TypeScript、または CI 検証のための契約を導き出します JSON スキーマジェネレーター。
これが適合する実際のワークフロー
"looks fine" というマニフェストをデバッグしています
デプロイメントが予期せず動作し、YAML が正しく読み取ったら、変換します。 10 回中 9 回、JSON は問題をすぐに示します。ブール値になった値、迷走スペースのために意図したよりも 1 レベル浅いネストされたキー、古くなったものに拡張されたアンカー。 JSON ビューは、バグを不可視にした空白の曖昧さを削除します。
構成に対するスクリプト作成
Shell スクリプトと Node スクリプトは JSON をネイティブに処理します; YAML には依存関係が必要です。 manifest のバンドルからすべてのイメージタグを引き出す必要があるとき、最初に JSON に変換してパイピングスルーします jq は、使い捨てスクリプトに YAML ライブラリを追加するよりも高速です。 converter' s マルチドキュメント サポートはここで重要です。6 つのリソースを含む Kubernetes バンドルは、反復できる JSON 配列になります。
建物のテスト据え付け品
統合テストでは、多くの場合、configファイルではなくconfigオブジェクトが必要です real manifestをJSONに変換すると、実稼働形状に一致することが保証されたフィクスチャが得られ、メモリから入力したオブジェクトよりもはるかに優れたスタートポイントとペアリングします JSON から TypeScript そしてあなたの据え付け品はタイプと来ます.
プルリクエストで構成を確認します
アンカーへの一行の変更は、すべての消費者を静かに変更するため、強くアンカーYAMLの違いは読みにくい。 との両方のバージョンを変換します キーの並べ替え JSON を有効にして差分すると、編集された行だけでなく、変更されたすべての解決された値である真のブラスト半径が表示されます。
ツール間の移行
多くのプラットフォームはJSONを受け入れますがYAMLは受け入れません、またはその逆 通常、変換は移行全体です 逆の方向に戻る必要があるとき - JSONを手に、YAMLが必要です - the JSON から YAML へのコンバータ ループを閉じます YAML バリデータ コミットする前に結果の解析を確認します。
YAMLとJSONを比較しました
| ディメンション | ヤムル | json |
|---|---|---|
| コメント | はいって | いやー |
| 人間編集 | 字下げベースで、スキムしやすい | 句読点が多く、冗長 |
| マシン解析 | より遅く、より大きなパーサー、より多くのエッジケース | どこにでも素早く小さなパーサー |
| 型推論 | 暗黙的、スキーマ依存 | 構文から明示 |
| 参考文献 | アンカー、エイリアス、マージキー | なし |
| ファイルごとに複数のドキュメント | はい、経由 --- |
いやー |
| 代表的な家 | Config ファイル、CI パイプライン、マニフェスト | API、データ交換、ストレージ |
YAML 1.2 は形式的には JSON のスーパーセットであるため、すべての JSON ドキュメントはすでに有効な YAML です。逆は真ではないため、YAML から JSON への変換はまさに一方向での非可逆操作になります。コメントと参照構造は破棄されますが、データは保持されます。 YAML に気になるコメントがある場合は、YAML を真実のソースとして保持し、JSON を派生アーティファクトとして扱います。
プライバシー: これがブラウザで実行される理由
Config ファイルは、チームが持つ最も機密性の高い平文アーティファクトの 1 つです。内部ホスト名、クラスター名、レジストリ パス、サービス アカウント、データベース識別子、そして - 誰もがそうであったにもかかわらず ' の最善の意図 - まだ秘密マネージャーになっていない時折の資格情報が含まれています。
コンバータはクライアントサイドのJavaScriptです ドキュメントはページで解析され JSONはページで生成され リクエストはデータをどこにも運びません ツールを1 回ロードすると ネットワークとの連動がオフに続きます マニフェストを貼り付けるものには 合理的な習慣です これはサイト上のすべてのツールの背後にある同じ原理であり 推論は上のガイドに詳しく書かれています オンライン ツールのデータ プライバシー。 汎用ブラウザツールキットを組み立てる場合は、 Web 開発者ツールキット ガイドでは、その中に他に何が含まれるかを説明します。
知る価値のある制限
ブラウザ タブに収まるコンバータは YAML 仕様の隅々まで実装されておらず、エッジがないことを示唆するよりも、エッジについて具体的にする方が便利です。
複雑なマッピング キー - 明示的なキー ? key キー自体がシーケンスまたはマッピングであるフォーム - JSON オブジェクト キーは文字列である必要があるため、サポートされていません。 などのタグを入力します !!binary またはカスタム !MyType ディレクティブは解釈されません; 値はテキストとして通過します。 special float values .inf、 -.inf、そして .nan JSON にはリテラルがなく、静かに変換されるため、文字列として保存されます null 保存するよりも多くの情報を失うことになります。 などのディレクティブ %YAML 1.2 行動するのではなく無視されます.
これらはいずれも通常の Kubernetes、Compose、Actions、Ansible ファイルには表示されません。 1 つヒットすると、特定の言語用に書かれたドキュメント & #39;s YAML ライブラリを操作することになり、そのライブラリ & #39;s 独自のダンパーが適切なツールになります。
フェイク
YAML をオンラインで JSON に変換するにはどうすればよいですか?
YAML を入力パネルに貼り付け、[変換] をクリックします。 パーサーは、ドキュメントを読み取り、アンカーとブロック スカラーを解決し、コピーまたはダウンロードできるフォーマットされた JSON を印刷します。 すべてのブラウザで発生するため、ファイルはアップロードされません。
JSON は YAML のサブセットですか?
はい。 YAML 1.2 は JSON の厳密なスーパーセットとして再定義されたため、有効な JSON ドキュメントはすべて有効な YAML にもなります。 逆は正しくありません。YAML は、コメント、アンカー、ブロック スカラー、ファイルごとの複数のドキュメント、および非文字列キーを追加します。これらのキーは、どれも直接表現できません。
YAML アンカーとエイリアスはどのようにして JSON に変換されますか?
JSON には参照構文がないため、各エイリアスはアンカーが定義した値の完全なコピーに展開されます。 defaults ブロックを 3 回再利用するコンフィグは、3 つの同一の JSON オブジェクトを生成します。したがって、出力は YAML ソースよりも大きくなりますが、意味的には同一です。
ダブルアングルブラケットのようなマージキーはどうなりますか?
参照されたマッピングは、現在のオブジェクトにマージされます。 子マッピングで明示的に書かれたキーは、YAML マージキー仕様の動作と Kubernetes および Ansible Tooling と一致するマージされたキーを勝ち取ります。
タブエラーでYAMLが失敗した理由は?
YAML はインデントにタブ文字を禁止します。仕様ではスペースのみが許可されています。Enter にタブを挿入する編集者は通常の原因です。先頭のタブをスペースに変換します。これは、ほとんどの編集者がファイル全体に対して一度に実行でき、ドキュメントは解析されます。
マルチドキュメントYAMLファイルをドキュメントセパレータで変換できますか?
はい。 separator マーカー間の各ドキュメントは独立して解析され、結果はソース順序でドキュメントごとに 1 つの要素を持つ JSON 配列になります。 single-document ファイルは、1 要素の配列ではなくオブジェクト自体を返します。
ポート番号とバージョン文字列はその型を維持しますか?
プレーンスカラーは YAML コアスキーマによって解決されるため、引用符で囲まれていない 8080 は数値 8080 になり、引用符で囲まれていない 1.10 は 1.1 になります。 YAML の値を引用して文字列を保持するか、Keep strings オプションをオンにしてすべてのスカラー強制をオフにします。
リテラルと折りたたまれたブロックスカラーはどのように変換されますか?
リテラルブロックは改行をすべて保持するので、改行をエスケープした JSON 文字列になります。 折り畳まれたブロックは連続する行をスペースで結合し、空白行を段落の区切りとして扱います。 chomping インジケーターは尊重されます。 a マイナスは末尾の改行を削除し、プラスは末尾のすべての空白行を保持します。
