mcpField
N
Newt Blueprint Generator

Newt Blueprint Generator

github.com/rknallクラウド・DevOps86291 回インストール53 週間前に更新
リポジトリ

Newt Blueprint Generator について

Pangolin Newtのブループリント設定を作成、検証、管理するスキルです。プロキシリソースの設定向けに、単独のYAMLとDocker Labelsに対応し、クライアントリソースや認証、プロトコル別の検証も扱います。

主な機能

  1. 01YAMLブループリントの生成
  2. 02Docker Labelsの設定
  3. 03プロキシとクライアントリソースの定義
  4. 04HTTPリソースの認証設定
  5. 05プロトコルとリソース制約の検証

活用シーン

  1. 01HTTP、TCP、UDPプロキシの作成
  2. 02Olmクライアントリソースの設定
  3. 03ブループリント形式の変換
  4. 04ブループリント検証エラーの調査

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/rknall/claude-skills --skill newt-blueprint-generator

インストール後、Claude Code で/newt-blueprint-generatorを入力して読み込まれたか確認します。

同梱ファイルREADME.mdvalidation-reference.md

詳細

Newt ブループリントジェネレーター

Pangolin Newt ブループリントの設定の作成、検証、管理を支援します。

このスキルを使用する場面

次の場合に、このスキルを使用してください：

  • Pangolin ブループリントの設定を作成するとき
  • Newt 用の YAML 設定ファイルを生成するとき
  • Pangolin ラベルを含む Docker Compose ファイルを作成するとき
  • プロキシリソース（HTTP、TCP、UDP）を設定するとき
  • Olm 用のクライアントリソースを設定するとき
  • 認証（SSO、ベーシック認証、PIN コード、パスワード）を設定するとき
  • ブループリントの設定を検証するとき
  • ブループリントの検証エラーをトラブルシューティングするとき
  • YAML と Docker ラベルの形式を相互に変換するとき

概要

Pangolin ブループリントは、リソースとその設定を構造化形式で定義できる宣言的な設定です。次の 2 つの形式に対応しています。

  1. YAML 設定ファイル：単独の設定ファイル
  2. Docker ラベル：Docker Compose ファイルに埋め込む設定

ブループリントの形式

YAML 設定形式

YAML 設定は、次の方法で適用できます：

  • Newt CLI：--blueprint-file /path/to/blueprint.yaml を指定します
  • API：base64 エンコードされた JSON ボディを /org/{orgId}/blueprint に POST します

Newt の使用例：

newt --blueprint-file /path/to/blueprint.yaml <other-args>
Docker ラベル形式

コンテナ化されたアプリケーションでは、pangolin. プレフィックスを付けた Docker ラベルを使ってブループリントを定義できます。

Docker ソケットへのアクセスを有効にします：

newt --docker-socket /var/run/docker.sock <other-args>

または、環境変数を使用します：

DOCKER_SOCKET=/var/run/docker.sock

リソースの種類

プロキシリソース

プロキシリソースを使用すると、Pangolin 経由で HTTP、TCP、UDP サービスを公開できます。

HTTP プロキシリソースの例
proxy-resources:
  resource-nice-id-uno:
    name: this is a http resource
    protocol: http
    full-domain: uno.example.com
    host-header: example.com
    tls-server-name: example.com
    headers:
      - name: X-Example-Header
        value: example-value
      - name: X-Another-Header
        value: another-value
    rules:
      - action: allow
        match: ip
        value: 1.1.1.1
      - action: deny
        match: cidr
        value: 2.2.2.2/32
      - action: pass
        match: path
        value: /admin
    targets:
      - site: lively-yosemite-toad
        hostname: localhost
        method: http
        port: 8000
      - site: slim-alpine-chipmunk
        hostname: localhost
        path: /admin
        path-match: exact
        method: https
        port: 8001
TCP／UDP プロキシリソースの例
proxy-resources:
  resource-nice-id-dos:
    name: this is a raw resource
    protocol: tcp
    proxy-port: 3000
    targets:
      - site: lively-yosemite-toad
        hostname: localhost
        port: 3000
ターゲットのみのリソース

ターゲット設定のみを含む簡易リソースです：

proxy-resources:
  additional-targets:
    targets:
      - site: another-site
        hostname: backend-server
        method: https
        port: 8443
      - site: another-site
        hostname: backup-server
        method: http
        port: 8080

注：ターゲットのみのリソースを使用する場合、name フィールドと protocol フィールドは不要です。

クライアントリソース

クライアントリソースでは、Olm クライアント（SSH、RDP）からアクセスできるプロキシ対象のリソースを定義します：

client-resources:
  client-resource-nice-id-uno:
    name: this is my resource
    protocol: tcp
    proxy-port: 3001
    hostname: localhost
    internal-port: 3000
    site: lively-yosemite-toad

認証設定

認証はデフォルトで無効です。有効にするには、auth セクションにフィールドを追加します。

注：認証を設定できるのは HTTP リソースのみです。TCP／UDP では設定できません。

proxy-resources:
  secure-resource:
    name: Secured Resource
    protocol: http
    full-domain: secure.example.com
    auth:
      pincode: 123456
      password: your-secure-password
      basic-auth:
        user: asdfa
        password: sadf
      sso-enabled: true
      sso-roles:
        - Member
        - Admin
      sso-users:
        - [email protected]
      whitelist-users:
        - [email protected]

Docker ラベル形式

Docker Compose の完全な例
services:
  newt:
    image: fosrl/newt
    container_name: newt
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - PANGOLIN_ENDPOINT=https://app.pangolin.net
      - NEWT_ID=h1rbsgku89wf9z3
      - NEWT_SECRET=z7g54mbcwkglpx1aau9gb8mzcccoof2fdbs97keoakg2pp5z
      - DOCKER_SOCKET=/var/run/docker.sock

  nginx1:
    image: nginxdemos/hello
    container_name: nginx1
    labels:
      # Proxy Resource Configuration
      - pangolin.proxy-resources.nginx.name=nginx
      - pangolin.proxy-resources.nginx.full-domain=nginx.fosrl.io
      - pangolin.proxy-resources.nginx.protocol=http
      - pangolin.proxy-resources.nginx.headers[0].name=X-Example-Header
      - pangolin.proxy-resources.nginx.headers[0].value=example-value
      # Target Configuration - port and hostname auto-detected
      - pangolin.proxy-resources.nginx.targets[0].method=http
      - pangolin.proxy-resources.nginx.targets[0].path=/path
      - pangolin.proxy-resources.nginx.targets[0].path-match=prefix

  nginx2:
    image: nginxdemos/hello
    container_name: nginx2
    labels:
      # Additional target with explicit hostname and port
      - pangolin.proxy-resources.nginx.targets[1].method=http
      - pangolin.proxy-resources.nginx.targets[1].hostname=nginx2
      - pangolin.proxy-resources.nginx.targets[1].port=80

networks:
  default:
    name: pangolin_default
Docker ラベルに関する考慮事項
  • 自動検出：ホスト名と内部ポートが定義されていない場合、Pangolin はコンテナ設定から自動検出します
  • サイトの割り当て：サイトが指定されていない場合、リソースは検出を行った Newt サイトに割り当てられます
  • 設定のマージ：コンテナ間の設定がマージされ、完全なリソース定義が作成されます

設定プロパティのリファレンス

プロキシリソースのプロパティ
プロパティ型必須説明制約
namestring条件付き人間が読みやすい名前ターゲットのみの場合を除き必須
protocolstring条件付きプロトコルの種類（http、tcp、udp）ターゲットのみの場合を除き必須
full-domainstringHTTP のみ完全修飾ドメイン名HTTP では必須。一意である必要があります
proxy-portnumberTCP／UDP のみTCP／UDP 用のポートTCP／UDP では必須。1～65535 の範囲で、一意である必要があります
sslbooleanいいえSSL／TLS を有効にするかどうか-
enabledbooleanいいえリソースを有効にするかどうかデフォルトは true
host-headerstringいいえカスタム Host ヘッダー-
tls-server-namestringいいえTLS 用の SNI 名-
headersarrayいいえカスタムヘッダー各項目に name と value が必要（1 文字以上）
rulesarrayいいえアクセス制御ルール「ルール」セクションを参照
authobjectHTTP のみ認証設定「認証」セクションを参照
targetsarrayはいターゲットエンドポイント「ターゲット」セクションを参照
ターゲット設定プロパティ
プロパティ型必須説明制約
sitestringいいえサイト識別子-
hostnamestringはいターゲットのホスト名または IP-
portnumberはいターゲットのポート1-65535
methodstringHTTP のみプロトコルメソッド（http、https、h2c）HTTP では必須
enabledbooleanいいえターゲットを有効にするかどうかデフォルトは true
internal-portnumberいいえ内部ポートのマッピング1-65535
pathstringHTTP のみパスのプレフィックス、完全一致、または正規表現-
path-matchstringHTTP のみパスの照合タイプ（prefix、exact、regex）-
認証プロパティ

TCP/UDP リソースでは使用できません。

プロパティ型必須説明制約
pincodenumberいいえ6 桁の PINちょうど 6 桁である必要があります
passwordstringいいえアクセス用のパスワード-
basic-authobjectいいえBasic 認証の設定user と password が必要です
sso-enabledbooleanいいえSSO を有効にするデフォルトは false
sso-rolesarrayいいえ許可する SSO ロール「Admin」ロールは含められません
sso-usersarrayいいえ許可する SSO ユーザーのメールアドレス有効なメールアドレスである必要があります
whitelist-usersarrayいいえホワイトリストに登録するユーザーのメールアドレス有効なメールアドレスである必要があります
ルール設定プロパティ
プロパティ型必須説明制約
actionstringはいルールのアクション（allow、deny、pass）-
matchstringはい照合タイプ（cidr、path、ip、country）-
valuestringはい照合する値形式は照合タイプによって異なります
クライアントリソースのプロパティ
プロパティ型必須説明制約
namestringはい人が読める名前2～100 文字
protocolstringはいプロトコルの種類（tcp、udp）-
proxy-portnumberはいクライアントがアクセスできるポート1-65535、一意である必要があります
hostnamestringはいターゲットのホスト名または IP1～255 文字
internal-portnumberはいターゲットシステム上のポート1-65535
sitestringいいえサイト識別子2～100 文字
enabledbooleanいいえリソースを有効にするかどうかデフォルトは true

検証ルールと制約

リソースレベルの検証
  1. ターゲットのみのリソース：リソースに targets フィールドのみを含めることができ、その場合 name と protocol は省略可能です
  2. プロトコル固有の要件：
    • HTTP プロトコル：full-domain が必要で、すべてのターゲットに method フィールドが必要です
    • TCP/UDP プロトコル：proxy-port が必要で、ターゲットに method フィールドを含めることはできません
    • TCP/UDP プロトコル：auth 設定は使用できません
  3. ポートの一意性：
    • proxy-resources 内では、proxy-port の値が一意である必要があります
    • client-resources 内では、proxy-port の値が一意である必要があります
    • プロキシリソースとクライアントリソース間の相互検証は行われません
  4. ドメインの一意性：すべてのプロキシリソースで、full-domain の値が一意である必要があります
  5. ターゲットのメソッド要件：プロトコルが http の場合、null でないすべてのターゲットに method を指定する必要があります

よくある検証エラー

「Admin role cannot be included in sso-roles」

Admin ロールは予約されているため、sso-roles 配列に含めることはできません。

解決策：sso-roles 配列から「Admin」を削除してください。

「Duplicate 'full-domain' values found」

すべてのプロキシリソースで、full-domain は一意である必要があります。

解決策：複数のリソースには異なるサブドメインまたはパスを使用してください。

「Duplicate 'proxy-port' values found」

proxy-port のポート番号は、リソースの種類ごとに一意である必要があります。

解決策：proxy-resources と client-resources で、それぞれ異なるポート番号を割り当ててください。

「プロトコルが 'http' の場合、すべてのターゲットに 'method' フィールドが必要です」

HTTP プロキシリソースのすべてのターゲットで、接続方式を指定する必要があります。

解決策：すべてのターゲットに method: http、method: https、または method: h2c を追加します。

「プロトコルが 'tcp' または 'udp' の場合、ターゲットに 'method' フィールドを指定してはいけません」

TCP および UDP のターゲットには、method フィールドを含めないでください。

解決策：TCP/UDP リソースのターゲットから method フィールドを削除します。

「プロトコルが 'tcp' または 'udp' の場合、'auth' を指定してはいけません」

認証は HTTP リソースでのみサポートされています。

解決策：TCP/UDP リソースから auth セクションを削除します。

「リソースは targets のみを指定するか、'name' と 'protocol' の両方のフィールドを含める必要があります」

リソースは、targets のみを指定するか、完全なリソース定義にする必要があります。

解決策：targets フィールドのみを指定するか、name と protocol の両方のフィールドを含めます。

ブループリント生成のワークフロー

ユーザーが Pangolin Newt のブループリント設定を求めた場合：

  1. 要件を確認します：

    • リソースタイプ（プロキシまたはクライアント）
    • プロトコル（HTTP、TCP、UDP）
    • ドメインまたはポートの要件
    • ターゲットエンドポイント（ホスト名、ポート、サイト）
    • 認証の要件（HTTP の場合）
    • アクセス制御ルール（ある場合）
    • 希望する形式（YAML または Docker Labels）

  2. 形式を選択します：

    • スタンドアロン設定または API デプロイには YAML を使用します
    • コンテナ化されたアプリケーションには Docker Labels を使用します

  3. 設定を検証します：

    • プロトコル固有の要件が満たされていることを確認します
    • full-domain（HTTP）または proxy-port（TCP/UDP）が一意であることを確認します
    • 認証が HTTP リソースでのみ使用されていることを確認します
    • すべての HTTP ターゲットに method フィールドがあることを確認します
    • TCP/UDP ターゲットに method フィールドがないことを確認します

  4. 設定を生成します：

    • 構成の整った YAML または Docker Compose ファイルを作成します
    • 各セクションを説明する役立つコメントを含めます
    • 命名規則（リソース ID にはケバブケース）に従います

  5. 使用方法を説明します：

    • 設定の適用方法（Newt CLI または API）を説明します
    • 必要な環境変数を記載します
    • 該当する場合は検証コマンドを含めます

ベストプラクティス

  1. リソース ID：内容が分かるケバブケースの識別子を使用します（例：web-app-prod、database-backup）
  2. ターゲットの整理：関連するターゲットを同じリソース ID の下にまとめます
  3. セキュリティを最優先します：機密性の高い HTTP リソースでは認証を有効にします
  4. ポート管理：競合を避けるため、ポートの割り当てを記録します
  5. サイトの割り当て：複数サイトへのデプロイでは、site を明示的に指定します
  6. パスのマッチング：幅広いマッチングには prefix を、特定のエンドポイントには exact を使用します
  7. ヘッダー：バックエンドの要件に応じてカスタムヘッダーを追加します（例：X-Forwarded-* ヘッダー）
  8. ルール：具体性の高い順にルールを並べます
  9. 検証：デプロイ前に必ず設定を検証します
  10. ドキュメント：YAML または Docker Compose ファイルに、分かりにくい選択の理由を説明するコメントを含めます

リソース

使用例

使用例 1：シンプルなウェブアプリケーション

要件：localhost:8080 で稼働するウェブアプリを、app.example.com で HTTPS 経由で公開する

proxy-resources:
  web-app:
    name: Web Application
    protocol: http
    full-domain: app.example.com
    targets:
      - hostname: localhost
        port: 8080
        method: https
使用例 2：TCP データベースアクセス

要件：ポート 5432 の PostgreSQL データベースを公開する

proxy-resources:
  postgres-db:
    name: PostgreSQL Database
    protocol: tcp
    proxy-port: 5432
    targets:
      - hostname: localhost
        port: 5432
使用例 3：複数ターゲットの負荷分散 HTTP サービス

要件：同じドメインに複数のバックエンドサーバーを設定する

proxy-resources:
  api-service:
    name: API Service
    protocol: http
    full-domain: api.example.com
    targets:
      - site: site-01
        hostname: backend-01
        port: 8080
        method: http
      - site: site-02
        hostname: backend-02
        port: 8080
        method: http
使用例 4：SSO による保護されたリソース

要件：SSO 認証を使用するウェブアプリ

proxy-resources:
  secure-app:
    name: Secure Application
    protocol: http
    full-domain: secure.example.com
    auth:
      sso-enabled: true
      sso-roles:
        - Member
        - Developer
      sso-users:
        - [email protected]
    targets:
      - hostname: localhost
        port: 3000
        method: https

コミュニケーションスタイル

ブループリントを生成する際は：

  • 要件が不明確な場合は、確認の質問をしてください
  • 検証エラーをわかりやすく説明してください
  • 完全に動作する例を提示してください
  • 複雑な設定にはコメントを付けてください
  • セキュリティのベストプラクティスを先回りして提案してください
  • 適切な場合は、YAML 形式と Docker Labels 形式の両方を提示してください

コメント

Markdown 対応