🆗

Google Cloud Workflowsのスキーマはローカルで検証しよう

に公開
テーマ「インフラ・セキュリティ」
Google Cloud
Workflows
zennfes2025infra
tech

はじめに

Google Cloud Workflowsを開発していて、YAMLファイルの構文ミスでデプロイが失敗した経験はありませんか？私もよくあります。実は、ajvというJSONスキーマバリデータを使うことで、デプロイ前にローカルでWorkflowsの構文チェックができるんです。

なぜローカル検証が必要なのか

Google Cloud Workflowsでは、YAMLファイルに記述ミスがあると、デプロイ時にエラーが発生します。しかし、エラーメッセージが必ずしも分かりやすいとは限らず、原因を特定するのに時間がかかることがあります。

ローカルでの検証により：

  • デプロイ前にエラーを発見できる
  • 開発サイクルが短縮される
  • CIに組み込むことで、PRの段階でエラーを防げる

ajvを使った検証方法

1. 必要なツールのインストール

ajvとajv-formatsをインストールします

$ npm install -g ajv-cli ajv-formats

または、プロジェクトごとにインストールせずにnpxで実行することも可能です。

2. Workflowsのスキーマファイルを取得

Google Cloud Workflowsの公式スキーマはhttps://json.schemastore.org/workflows.jsonから取得できます：
curl -o workflows.schema.json https://json.schemastore.org/workflows.json

3. 検証の実行

以下のコマンドでWorkflowsのYAMLファイルを検証できます：

npx ajv validate -c ajv-formats -s workflows.schema.json -d workflows/your-workflow.yaml

複数のファイルを一度に検証する場合：

npx ajv validate -c ajv-formats -s workflows.schema.json -d "workflows/**/*.yaml"

CIへの組み込み

GitHub Actionsを使ってCIに組み込む例を紹介します：

name: Validate Workflows

on:
  pull_request:
    paths:
      - "workflows/**"

jobs:
  validate-workflow-schema:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Validate workflow schema
        run: |
          npx -y \
              -p "ajv-cli@5.0.0" \
              -p "ajv-formats@2.1.1" \
              ajv validate \
                -c ajv-formats \
                -s workflows.schema.json \
                -d "workflows/**/*.yaml"

このワークフローは、workflows/ディレクトリ配下のYAMLファイルが変更されたときに自動的に実行され、構文エラーがあればPRの段階で検出できます。

実際のエラー例

例えば、以下のような不正なWorkflowsファイルがあるとします：

main:
steps:
  - hello:
      call: http.get
      args:
        # urlが必須なのに指定されていない
        method: GET  # methodはhttp.requestでのみ使用可能

ajvで検証すると、以下のようなエラーが出力されます：

workflows/invalid.yaml invalid
data/main/steps/0/hello/args must have required property 'url'

まとめ

ajvを使ったローカル検証により、Google Cloud
Workflowsの開発効率が大幅に向上します。特にCIに組み込むことで、チーム全体の開発品質を向上させることができます。

皆さんもぜひ試してみてください！

参考リンク

Discussion