【テクニカル・上級編】Pulumi型安全性を極める：TypeScript/Pythonの厳格なスキーマ検証とカスタムバリデーション実装術 – インフラ構成管理（IaC）活用バイブル

Pulumi型安全性を極める：TypeScript/Pythonの厳格なスキーマ検証とカスタムバリデーション実装術

インフラストラクチャ・アズ・コード（IaC）の歴史は、「文字列とYAMLの泥沼」から「汎用プログラミング言語による抽象化」への進化の歴史であった。
その究極形の一つがPulumiである。HCLやYAMLの静的な縛りから解放され、TypeScriptやPythonといった成熟したエコシステムを利用できることは、インフラエンジニアにとって福音であったはずだ。

しかし、現実はどうか？
「“aws.ec2.Instance`の`instanceType`に`t3.invalid`という存在しないインスタンスタイプを指定してしまい、30分後にAWS APIから怒られた」「環境変数から読み込んだプレフィックスが空文字で、全リソースの命名規則が崩壊した」。
こうした悲劇を、未だに「デプロイ時のエラー（Fail Fastの欠如）」として放置していないだろうか。

プログラミング言語を使っているのにもかかわらず、APIリクエストを投げるその瞬間までパラメータの不正に気づけないのだとしたら、それは道具のポテンシャルをドブに捨てているのと同義だ。

今回は、TypeScriptのZod、そしてPythonのPydanticをPulumiのエンジンと完全に同期させ、「デプロイ前の静的解析・実行時バリデーション」によって不適切なインフラパラメータの混入を物理的に根絶するための設計パターンを解説する。

—

1. なぜ「型定義」だけではインフラを守れないのか

TypeScriptのインターフェースやPythonの型ヒント（Type Hints）は、開発体験（DX）を爆発的に向上させるが、これらはコンパイル時（または静的解析時）にしか機能しない。

さらに言えば、Pulumiのコンフィグ（`pulumi.Config`）や外部API、CI/CDの環境変数から流入するデータは、すべて「型を持たない動的な文字列（`any` または `str`）」としてランタイムに侵入する。

// 悪夢のようなアンチパターン
const config = new pulumi.Config();
const minInstances = parseInt(config.require(“minInstances”)); // もし “abc” が渡されたら？
const instanceType = config.require(“instanceType”); // どんな文字列でも通ってしまう

この「境界領域（Boundary）」における型安全性の欠如こそが、インフラ障害の温床である。
境界を跨ぐ瞬間に、データを厳密にパースし、不毛な入力を即座に「死刑（例外送出）」にする要塞を築く必要がある。

—

2. TypeScript編：Zodによる厳格なインフラコンフィグ検証

TypeScriptエコシステムにおいて、ランタイムの型検証のデファクトスタンダードである Zod を用いて、Pulumiのスタック設定（Config）を完全武装する。

実装アーキテクチャ

1. `Pulumi..yaml` からの入力を受け取る。
2. Zodスキーマでバリデーションと型推論を同時に行う。
3. 検証済みの強ザイロ（Typed Object）のみをリソース定義に渡す。

コード実装：`config/schema.ts`

import as z from “zod”;
import as pulumi from “@pulumi/pulumi”;

// インフラパラメータの物理的制約をZodで定義
const NetworkConfigSchema = z.object({
// CIDRブロックの簡易正規表現検証
vpcCidr: z.string().regex(
/^([0-9]{1,3}\.){3}[0-9]{1,3}\/([0-9]|[1-2][0-9]|3[0-2])$/,
{ message: “無効なVPC CIDRフォーマットです” }
),
// 許可された環境名のみを許可
environment: z.enum([“dev”, “staging”, “production”]),
// 最小インスタンス数は1以上、100以下
maxClusterSize: z.number().int().min(1).max(100),
// オプションだが、指定された場合は特定のフォーマットを強制するドメイン名
domainName: z.string().domain().optional(),
});

// 推論された型をエクスポート（以降のコードはこの型に縛られる）
export type ValidatedConfig = z.infer;

/

• PulumiのConfigを読み込み、Zodで厳密にバリデーションして返す関数

/
export function loadAndValidateConfig(): ValidatedConfig {
const config = new pulumi.Config();

// 生の入力データを取得（環境変数やPulumi configから）
const rawConfig = {
vpcCidr: config.require(“vpcCidr”),
environment: config.require(“environment”),
// Pulumiのconfigは文字列で返るため、数値にパースを試みる
maxClusterSize: Number(config.require(“maxClusterSize”)),
domainName: config.get(“domainName”),
};

// パース & バリデーション実行
const result = NetworkConfigSchema.safeParse(rawConfig);

if (!result.success) {
// デザイナーが泣いて喜ぶ、詳細かつ構造化されたエラーメッセージを出力して即座にプロセスを殺す
const formattedErrors = JSON.stringify(result.error.format(), null, 2);
throw new pulumi.RunError(
`[FATAL] インフラストラクチャ構成パラメータのバリデーションに失敗しました:\n${formattedErrors}`
);
}

return result.data;
}

エントリポイントでの利用：`index.ts`

import { loadAndValidateConfig } from “./config/schema”;
import as aws from “@pulumi/aws”;

// デプロイの瞬間にバリデーションが走る。不正な値があればリソース構築すら開始されない。
const config = loadAndValidateConfig();

// ここから先は完全に型安全であり、不正な値が存在し得ない世界線
const vpc = new aws.ec2.Vpc(“my-vpc”, {
cidrBlock: config.vpcCidr,
tags: {
Environment: config.environment,
ManagedBy: “Pulumi”,
},
});

export const vpcId = vpc.id;

—

3. Python編：Pydantic v2による自己文書化インフラストラクチャ

PythonによるPulumi実装では、Pydantic v2を用いることで、RustやGo並みの堅牢なデータバリデーションをインフラコードに持ち込むことができる。

コード実装：`config_validator.py`

from typing import Literal, Optional
import re
from pydantic import BaseModel, Field, field_validator, model_validator
import pulumi

class InfrastructureConfig(BaseModel):
aws_region: Literal[“us-east-1”, “ap-northeast-1”, “eu-central-1″] = Field(
…, description=”許可されたAWSリージョンのみ”
)
instance_type: str = Field(…, description=”EC2インスタンスタイプ”)
node_count: int = Field(ge=1, le=50, description=”ノード数は1〜50の間”)
encryption_key_arn: Optional[str] = Field(None, description=”KMSキーARN”)

@field_validator(“instance_type”)
@classmethod
def validate_instance_type(cls, v: str) -> str:
# t3, m5, c6i 系のインスタンスファミリーのみを許可するカスタムバリデーション
allowed_families = (“t3.”, “m5.”, “c6i.”)
if not v.startswith(allowed_families):
raise ValueError(
f”コンプライアンス違反: インスタンスタイプ ‘{v}’ は許可されていません。”
f”許可されているファミリー: {allowed_families}”
)
return v

@model_validator(mode=”after”)
def validate_production_constraints(self) -> “InfrastructureConfig”:
# 本番環境固有のクロスフィールド・バリデーション
# 例: リージョンが us-east-1 の場合、暗号化キーの指定を強制する
if self.aws_region == “us-east-1” and not self.encryption_key_arn:
raise ValueError(
“セキュリティポリシー違反: us-east-1でのデプロイには ‘encryption_key_arn’ の指定が必須です。”
)
return self

def load_validated_config() -> InfrastructureConfig:
cfg = pulumi.Config()

# 生データを取得し、Pydanticモデルへ流し込む
raw_data = {
“aws_region”: cfg.require(“awsRegion”),
“instance_type”: cfg.require(“instanceType”),
# PulumiのgetInt()を活用しつつ、存在チェック
“node_count”: cfg.get_int(“nodeCount”) or 3,
“encryption_key_arn”: cfg.get(“encryptionKeyArn”),
}

try:
# ここでPydanticが型変換とバリデーションを同時に実行
return InfrastructureConfig(raw_data)
except Exception as e:
# Pulumiのエンジンに分かりやすい形でエラーを伝播
raise pulumi.RunError(f”\n[PULUMI CONFIG ERROR] 設定値の検証に失敗しました:\n{e}”)

—

4. 高度な応用：Pulumi Custom Resource / ComponentResource へのスキーマ適用

トップレベルのConfigだけでなく、自作の ComponentResource（カスタムコンポーネント） の入力プロパティ（Args）に対しても、この厳格な検証を適用すべきである。

これにより、チームメンバーや他のモジュールから自分が書いたコンポーネントが呼ばれた際、「間違った引数を渡した瞬間にIDEやプレビューでエラーを検知できる」 構造が完成する。

TypeScriptにおけるComponentResourceの型安全化

import as pulumi from “@pulumi/pulumi”;
import as aws from “@pulumi/aws”;
import as z from “zod”;

// コンポーネントへの入力スキーマを定義
const SecureBucketArgsSchema = z.object({
bucketName: z.string().min(3).max(63).regex(/^[a-z0-9-]+$/, “バケット名は小文字英数字とハイフンのみ許可されます”),
enableVersioning: z.boolean().default(true),
});

export type SecureBucketArgs = z.infer;

export class SecureBucket extends pulumi.ComponentResource {
public readonly bucket: aws.s3.Bucket;

constructor(name: string, args: SecureBucketArgs, opts?: pulumi.ComponentResourceOptions) {
super(“custom:module:SecureBucket”, name, args, opts);

// コンポーネントの初期化時にargsを再検証（ランタイムの堅牢性を担保）
const parsedArgs = SecureBucketArgsSchema.parse(args);

// バケット作成
this.bucket = new aws.s3.Bucket(`${name}-bucket`, {
bucket: parsedArgs.bucketName,
}, { parent: this });

if (parsedArgs.enableVersioning) {
new aws.s3.BucketVersioningV2(`${name}-versioning`, {
bucket: this.bucket.id,
versioningConfiguration: { status: “Enabled” },
}, { parent: this });
}

this.registerOutputs({});
}
}

このアプローチにより、誰かが `SecureBucket` を使う際に `bucketName: “INVALID_UPPERCASE”` と指定した瞬間に、Pulumiのプレビュー（`pulumi preview`）の初期段階で例外が飛ぶようになる。AWSへの無駄なAPIコールは1バイトたりとも発生しない。

—

5. エキスパートの知見：パフォーマンス最適化とCI/CDパイプライン統合

最後に、この厳格なスキーマ検証を大規模なエンタープライズ環境のCI/CDパイプラインに組み込む際のベストプラクティスを共有する。

1. プレビュー（Preview）とアップ（Up）の二重実行コストの排除

厳格なスキーマ検証を言語ランタイム（TS/Python）の初期化フェーズで行うことの最大のメリットは、「PulumiエンジンがAWSなどのプロバイダに接続するよりも圧倒的に早くエラーを検知できる」点にある。
ネットワークIOが発生する前にプロセスが終了するため、CI/CDパイプラインのフィードバックループを極限まで短縮できる。

2. 静的解析（Linter）との二段構え

Runtimeでのバリデーションに加え、TypeScriptの場合は `tsconfig.json` で `strict: true` を有効化し、Pythonの場合は `mypy –strict` をCIに組み込むこと。

• 静的解析（Compile Time）: 開発者のIDE上でのタイポや型ミスの検知
• ランタイム検証（Zod / Pydantic）: 外部から注入される不正な設定値（Config, Env）のブロック

この二段構えを完遂したインフラコードベースは、もはや「壊しようがない」領域に到達する。

—

結び：インフラストラクチャは「コード」であり「ソフトウェア」である

インフラをコードで管理するということは、単にYAMLをプログラムに置き換えることではない。ソフトウェア開発における最高峰の設計パターン（型安全性、防御的プログラミング、テスト容易性）をインフラストラクチャの領域に持ち込むことに他ならない。

「動かしてみるまで分からないインフラ」から「コードを書いた瞬間、あるいはバリデーションを通過した瞬間に正しさが証明されるインフラ」へ。
ZodやPydanticを駆使した厳格なスキーマ検証は、あなたのインフラストラクチャを、絶対に破綻しない鉄壁の要塞へと昇華させる最高の武器となるだろう。