routeros-app-yaml

RouterOS /app YAML 形式（7.21以降）

RouterOS 7.21で/appパス（組み込みアプリの一覧表示と管理）が導入されました。YAMLによるアプリ作成機能（/app/add）が追加されたのは7.22です（7.22beta5で初めて確認されました）。MikroTik独自の考え方を取り入れたdocker-composeの代替と考えてください。ただし、これはdocker-composeではなく、重要な違いがあります。

/appとは

/appサブシステムでは、YAMLで1つ以上のコンテナを単一の「アプリケーション」として定義できます。RouterOSがYAMLを解析し、コンテナ、ボリューム、ネットワーク、設定ファイルを作成して、ライフサイクルを管理します。

主な概念：

• 各/appは、サービス、設定、ボリューム、ネットワークを含むYAMLドキュメントで定義します
• YAMLはCLI（/app/add yaml-url=...）またはREST APIを介してRouterOSに読み込みます
• 組み込みアプリはRouterOSに同梱されています（GET /rest/appで確認できます）
• カスタムアプリはURLまたはインラインYAMLから追加できます
• アプリストア（app-store-urls=）では、厳選されたコレクションを提供します

docker-composeとの主な違い

機能	docker-compose	RouterOS /app
ポート形式	host:container[/protocol]	2種類の形式（下記参照）
環境変数	KEY=valueまたはリスト	同じですが、プレースホルダーが展開されます
ボリューム	名前付きまたはバインドマウント	一部のみ対応 — バインドマウントのオプションはありません
ネットワーク	完全なDockerネットワークモデル	簡易版 — 名前と外部ネットワーク
ビルド	Dockerfileを完全にサポート	最小限（contextとdockerfile）
設定	Docker configs API	インラインのcontentのみ
デプロイ／リソース	あり	なし — サポートされていません
トップレベルのversion:	非推奨（以前は必須）	使用しません
ファイル拡張子	.yml／.yaml	.tikapp.yaml（慣例）

トップレベルのプロパティ

プロパティ	型	必須	説明
name	string	いいえ	/appの一意の識別子
descr	string	いいえ	アプリUIに表示される、人が読める説明
page	string (URI)	いいえ	プロジェクトのホームページURL
category	string (enum)	いいえ	アプリストアの分類
icon	string (URI)	いいえ	アイコンURL（show-in-webfig=yesの場合にWebFigで表示）
default-credentials	string or null	いいえ	UIに表示されるusername:password
url-path	string	いいえ	ブラウザーアクセス用のURLパス接尾辞（例：/admin）
credentials	string	いいえ	認証情報のヒント（default-credentialsの代替）
option	boolean	いいえ	アプリがオプションかどうか
auto-update	boolean	いいえ	起動のたびにコンテナをプルして再起動するかどうか
services	object	はい	コンテナサービスの定義（1つ以上必須）
volumes	object	いいえ	名前付きボリュームの宣言
networks	object	いいえ	ネットワークの宣言
configs	object	いいえ	インラインコンテンツを含む設定ファイルの宣言

カテゴリ値（全項目）

productivity, storage, networking, development, communication,
file-management, search, video, media, media-management,
home-automation, monitoring, database, automation, ai,
messaging, radio, security, business

MikroTikが組み込みアプリを追加すると、新しいカテゴリが登場します。CIスキーマ検証でこれらを検出します。

サービスのプロパティ

services: 配下の各キーは、1つのコンテナを定義します。必須プロパティは image です。

プロパティ	型	説明
image	string	コンテナイメージ（レジストリを省略すると、/container/config の registry-url が使用されます）
container_name	string	明示的な名前。/container 配下のファイルパスのベースとして使用されます
hostname	string	コンテナのホスト名
entrypoint	string or string[]	デフォルトのエントリーポイントを上書きします
command	string or string[]	デフォルトのコマンドを上書きします
ports	array	ポートマッピング（形式のセクションを参照）
environment	object or array or null	環境変数（KEY=value のリスト、または {KEY: value} のマップ）
volumes	array of strings	ボリュームのマウント（例：my-vol:/data）
configs	array of objects	設定ファイルの配置（{source, target, mode}）
restart	enum	no、always、on-failure、unless-stopped
depends_on	array or object	サービスの依存関係の順序
devices	array of strings	コンテナに渡すデバイスマッピング
user	string	コンテナを実行するユーザー
security_opt	array of strings	セキュリティオプション
shm_size	string	共有メモリのサイズ
stop_grace_period	string or int	SIGKILL を送信するまでの時間
ulimits	object	リソース制限（例：nofile: {soft: 65536, hard: 65536}）
build	object or string	ビルド設定（コンテキスト、Dockerfile、引数）
healthcheck	object	ヘルスチェック（test、interval、timeout、retries、start_period）
stdin_open	boolean	標準入力を開いたままにします
expose	array	内部ポート（ホストには公開されません）
secrets	array of strings	公開するシークレット
attach	boolean	標準入出力に接続します

ポート形式 — 2つのスタイル

RouterOS では、2種類のポートマッピング文字列形式がサポートされています。どちらも有効ですが、7.23beta2 以降の新しいアプリではコロン形式が推奨されます。

旧 OCI 形式（7.23 より前）

[ip:]host_port:container_port[/tcp|/udp][:label]

例：

ports:
  - "8080:80/tcp"
  - "8443:443/tcp:https"
  - "192.168.1.1:53:53/udp:dns"

新しい RouterOS 形式（7.23 以降）

[ip:]host_port:container_port[:label][:tcp|:udp]

プロトコルはスラッシュではなくコロンで付加します：

ports:
  - "8080:80:web:tcp"
  - "8443:443:https:tcp"
  - "53:53:dns:udp"

ロング形式（オブジェクト）構文

ports:
  - target: 80
    published: 8080
    protocol: tcp
    name: web
    app_protocol: http

ポートでの IP アドレスとプレースホルダー

ポート文字列には、リテラルの IP アドレスやプレースホルダー式を含めることができます：

ports:
  - "[accessIP]:[accessPort]:80/tcp:web"      # Old style with placeholders
  - "[accessIP]:[accessPort]:80:web:tcp"       # New style with placeholders

プレースホルダー

RouterOS はデプロイ時に、次のプレースホルダーを展開します：

プレースホルダー	展開後の値
[accessIP]	アプリへの外部アクセスに使用する IP アドレス
[accessPort]	外部アクセス用のプライマリーホストポート
[accessPort2]	セカンダリーホストポート
[containerIP]	コンテナに割り当てられた IP アドレス
[routerIP]	ルーター自体の IP アドレス

プレースホルダーは、ポートマッピング、環境変数の値、設定内容に使用できます。

設定（インラインファイル）

トップレベルの configs: で設定内容を宣言し、サービスから参照します：

configs:
  my-config:
    content: |
      server {
        listen 80;
        server_name [accessIP];
      }

services:
  web:
    image: nginx:alpine
    configs:
      - source: my-config
        target: /etc/nginx/conf.d/default.conf
        mode: 0644

ボリュームとネットワーク

volumes:
  app-data: {}      # Named volume (null or empty object)

networks:
  app-net:
    name: my-network
    external: true   # Use existing RouterOS network

ストアスキーマ（app-store-urls）

RouterOS は、app-store-urls= で設定した URL からアプリコレクションを読み込めます。ストア形式は、/app 定義を並べた単純な YAML 配列です：

- name: app-one
  services:
    web:
      image: nginx:alpine
- name: app-two
  services:
    db:
      image: postgres:16

ストアファイルには、慣例として .tikappstore.yaml 拡張子を使用します。

/app の REST API

// List all /app entries (built-in + custom)
const apps = await fetch(`${base}/app`, auth).then(r => r.json());

// Each entry has: .id, name, yaml (raw YAML string), and metadata
// The 'yaml' field is a RouterOS string containing the full YAML document

// Add a custom /app from URL
await fetch(`${base}/app`, {
  method: "PUT",
  ...auth,
  body: JSON.stringify({ "yaml-url": "https://example.com/my-app.tikapp.yaml" }),
});

注： /app エンドポイントを使用するには、container 追加パッケージがインストールされている必要があります。

検証用 JSON Schema

各 /app ドキュメントには、2種類のスキーマがあります：

スキーマ	用途	ポートの検証	環境変数名
*.latest.json	CI／厳格な検証	正規表現パターンを適用	^[A-Z_][A-Z0-9_]*$ のみ
*.editor.json	エディター／SchemaStore の使いやすさ	正規表現なし（自動補完が可能）	大文字と小文字を区別しない

厳格なスキーマでは、ポート文字列に正規表現の pattern が設定されており、VSCode の自動補完が妨げられます。YAML 拡張機能は、パターンが設定されたフィールドの値を候補として提案しません。エディター用のバリアントでは、これらのパターンを削除しています。

VSCode との統合

YAML の自動補完を有効にするには、VSCode の設定に次を追加します：

{
  "yaml.schemas": {
    "https://tikoci.github.io/restraml/routeros-app-yaml-schema.latest.json": "*.tikapp.yaml",
    "https://tikoci.github.io/restraml/routeros-app-yaml-store-schema.latest.json": "*.tikappstore.yaml"
  }
}

厳格な検証の精度は下がりますが、自動補完を改善するには .editor.json の URL を使用してください。

バージョン履歴

• 7.22：基本的なサービスプロパティを備えた /app の初期サポート
• 7.23beta2：コロン形式のポートフォーマットを追加（:tcp／:udp サフィックス）
• 7.23+：サービスプロパティを追加（devices、expose、secrets、attach）

よくある間違い

• docker-compose との互換性を前提にする — すべてのプロパティがサポートされているわけではなく、一部は動作が異なります
• version: キーを使う — RouterOS はこれを無視するため、不要です
• 1 つのエントリでポート形式を混在させる — 各ポート文字列では、いずれか 1 つの形式のみを使用する必要があります
• 厳密な検証では環境変数名を大文字にする必要があります — 大文字と小文字が混在する場合は *.editor.json を使用してください
• コンテナパッケージを忘れる — container 追加パッケージがないと /app は 404 を返します
• deploy: や resources: を使う — RouterOS ではサポートされていません

その他のリソース

• RouterOS の基本、CLI 構文、REST API については、routeros-fundamentals スキルを参照してください
• QEMU での CHR の実行（/app のテストに必要）については、routeros-qemu-chr スキルを参照してください
• MikroTik フォーラムの参考資料：https://forum.mikrotik.com/t/amm0s-manual-for-custom-app-containers-7-22beta/268036/22