fly-io

Fly.io のデプロイと管理

基本概念

• Fly App：1 つの組織に属する、Machine（VM）、設定、ネットワーク、シークレットの名前付きグループです
• Fly Machine：高速起動する VM（1 秒未満で起動）です。一時的なルートファイルシステムを備えています。ライフサイクル：作成 -> 起動 -> 停止 -> 破棄
• Fly Volume：NVMe ベースの永続ストレージです。Machine と 1:1 で対応し、リージョンに固定され、デフォルトで保存時に暗号化されます
• Fly Proxy：TLS 終端、ロードバランシング、自動停止／自動起動、HTTP ルーティングを処理するエッジプロキシです
• flyctl (fly)：Fly.io のすべての操作に使用する CLI です。インストール方法：brew install flyctl または curl -L https://fly.io/install.sh | sh
• fly.toml：アプリ設定ファイルです。完全なリファレンスについては、references/fly-toml-config.md を参照してください

クイックスタートのワークフロー

# 1. Create app + fly.toml
fly launch

# 2. Set secrets
fly secrets set DATABASE_URL=postgres://... SECRET_KEY=...

# 3. Deploy
fly deploy

# 4. Check status
fly status
fly logs

fly.toml の基本

最小限の Web アプリ設定：

app = 'my-app'
primary_region = 'ord'

[build]
  dockerfile = "Dockerfile"

[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = "stop"
  auto_start_machines = true
  min_machines_running = 1

  [http_service.concurrency]
    type = "requests"
    soft_limit = 200
    hard_limit = 250

[[vm]]
  memory = '512mb'
  cpu_kind = 'shared'
  cpus = 1

すべてのセクションを含む fly.toml の完全なリファレンスについては、references/fly-toml-config.md を参照してください。

Machines の管理

# Scale horizontally
fly scale count 3                          # 3 Machines in primary region
fly scale count 3 --region ord,iad         # Across regions

# Scale vertically
fly scale vm performance-1x --vm-memory 2048

# Direct Machine control
fly machine run <image> --region ord
fly machine clone <machine-id> --region iad
fly machine update <machine-id> --vm-memory 512
fly machine stop <machine-id>
fly machine start <machine-id>
fly machine destroy <machine-id>

Machine のサイズ：shared-cpu-1x（デフォルトで 256MB）、shared-cpu-2x、shared-cpu-4x、shared-cpu-8x、performance-1x から performance-16x まで。GPU オプション：a10、l40s、a100-pcie-40gb、a100-sxm4-80gb。

Volumes

fly volumes create mydata --region ord --size 10   # 10GB
fly volumes list
fly volumes extend <vol-id> --size 20              # Extend to 20GB (cannot shrink)
fly volumes snapshots list <vol-id>
fly volumes fork <vol-id>                          # Copy a volume

fly.toml で設定します：

[mounts]
  source = "mydata"
  destination = "/data"
  initial_size = "10gb"
  auto_extend_size_threshold = 80
  auto_extend_size_increment = "1GB"
  auto_extend_size_limit = "50GB"

重要：Volume は Machine と 1:1 で対応し、リージョンに固定されます。自動レプリケーションはありません。冗長性を確保するため、必ず Volume を持つ Machine を 2 台以上用意してください。Volume 間のデータレプリケーションは、アプリ側で処理する必要があります。

シークレット

fly secrets set KEY=value OTHER_KEY=other_value
fly secrets set KEY=value --stage               # Stage without restarting
fly secrets deploy                               # Deploy staged secrets
fly secrets list                                 # Names only, no values
fly secrets unset KEY OTHER_KEY

シークレットは保存時に暗号化され、起動時に環境変数として注入されます。シークレットをファイルとしてマウントするには、fly.toml で [[files]] を使用します（値は Base64 エンコードする必要があります）：

[[files]]
  guest_path = "/etc/ssl/private/key.pem"
  secret_name = "TLS_PRIVATE_KEY"

ログ

fly logs                                     # Continuous tail (default, streams indefinitely)
fly logs --no-tail                           # Output recent logs once and exit
fly logs --machine <machine-id>              # Filter to a specific machine
fly logs --machine <machine-id> --no-tail    # Recent logs for one machine, then exit
fly logs --region iad                        # Filter by region
fly logs --json                              # JSON-formatted output

重要：flyctl logs は -n、--tail <count>、--lines フラグをサポートしていません。出力を制限するには、標準ツールにパイプしてください：

fly logs --no-tail | head -50                # Last 50 lines
fly logs --no-tail | tail -20                # Most recent 20 lines
fly logs --machine <id> --no-tail | grep -i error   # Search for errors

使用可能なフラグ：

フラグ	説明
--no-tail (-n)	ログを一度出力して終了します（ストリーミングしません）
--machine <id>	特定の Machine ID に絞り込みます
--region <code>	リージョンで絞り込みます（例：iad、ord）
--json (-j)	JSON 出力形式
--app <name> (-a)	アプリ名を指定します（fly.toml のあるディレクトリにいない場合）

ネットワーク

パブリックサービス、プライベートネットワーク、Flycast、カスタムドメイン、DNS など、ネットワークの詳細なパターンについては、references/networking.md を参照してください。

クイックリファレンス

fly ips list                                 # List allocated IPs
fly ips allocate-v6                          # Dedicated IPv6 (free)
fly ips allocate-v4 --shared                 # Shared IPv4 (free)
fly ips allocate-v4                          # Dedicated IPv4 (paid)
fly certs create mydomain.com                # Add custom domain + TLS cert

プライベートネットワーク：組織内のすべてのアプリが WireGuard メッシュ（6PN）を共有します。アプリ間通信には <appname>.internal DNS を使用してください。プライベート接続を受け付けるには、fly-local-6pn または [::]:port にバインドします。

ヘルスチェック

サービスレベルのチェックは Fly Proxy のルーティングに影響します。トップレベルの [checks] は監視専用です。

# In [http_service] or [[services]]
[[http_service.checks]]
  grace_period = "10s"
  interval = "30s"
  timeout = "5s"
  method = "GET"
  path = "/health"

# Top-level (monitoring, no routing impact)
[checks.my_check]
  type = "http"
  port = 8080
  path = "/health"
  interval = "30s"
  timeout = "5s"

自動スケーリング

自動停止／自動起動（Fly Proxy ベース、Web サービス向け）：

[http_service]
  auto_stop_machines = "stop"      # "off", "stop", or "suspend"
  auto_start_machines = true
  min_machines_running = 1

  [http_service.concurrency]
    type = "requests"
    soft_limit = 200               # Used for excess capacity calculation

メトリクスベースの自動スケーリング：自動スケーラーアプリを組織内にデプロイします。このアプリは Prometheus メトリクスをポーリングし、Machine を作成／破棄します。設定については Fly.io のドキュメントを参照してください。

デプロイ戦略

[deploy]
  strategy = "rolling"              # "rolling" (default), "immediate", "canary", "bluegreen"
  max_unavailable = 0.33            # For rolling: fraction or integer
  release_command = "bin/migrate"   # One-off command before deploy (e.g., DB migrations)

• rolling：1 台ずつ置き換えます（デフォルト）
• immediate：一斉に置き換え、ヘルスチェックの待機を省略します
• canary：Machine を 1 台起動してヘルスを確認してから、ローリングデプロイを行います（Volume は使用不可）
• bluegreen：新しい Machine 群を古い群と並行して起動し、ヘルスチェック後にトラフィックを移行します（ヘルスチェックが必要、Volume は使用不可）

GitHub Actions による CI/CD

デプロイトークン、レビューアプリ、複数アプリのデプロイを含む CI/CD の完全な設定については、references/cicd-github-actions.md を参照してください。

クイックセットアップ：

# .github/workflows/fly.yml
name: Fly Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    concurrency: deploy-group
    steps:
      - uses: actions/checkout@v4
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: flyctl deploy --remote-only
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

デプロイトークンを生成します：fly tokens create deploy -x 999999h

データベースとストレージ

データベースとストレージの詳細なパターンについては、references/databases-storage.md を参照してください。

• Managed Postgres：fly mpg create -- 完全マネージド型、自動バックアップ
• Tigris Object Storage：S3 互換、fly storage create
• Upstash Redis：マネージド Redis、fly redis create

本番環境のチェックリスト

1. セキュリティ：SSO を有効にし、機密データにはシークレットを使用し、プライベートアプリから不要なパブリック IP を解放し、内部サービスには Flycast を使用します
2. パフォーマンス：本番環境の Web アプリにはパフォーマンス CPU を使用し、メモリを適切なサイズに設定し、スパイクを吸収できるようにスワップ（swap_size_mb）を有効にします
3. 可用性：2 台以上の Machine を実行し（理想的には複数リージョンに分散）、自動停止／自動起動を設定し、ヘルスチェックを構成します
4. ネットワーク：カスタムドメインと TLS 証明書を設定し、必要に応じて専用 IPv4 を検討します
5. 監視：Prometheus メトリクスのエクスポートを構成し、Sentry を設定し、ログを外部サービスにエクスポートします
6. CI/CD：デプロイトークンを使って GitHub Actions 経由でデプロイし、レビューアプリのプレビューを設定します

プロセスグループ

1 つのアプリで複数のプロセスを実行します（例：Web + ワーカー）。

[processes]
  web = "bin/rails server -b 0.0.0.0 -p 8080"
  worker = "bin/sidekiq"

[http_service]
  internal_port = 8080
  processes = ["web"]

[[vm]]
  processes = ["web"]
  memory = "1gb"

[[vm]]
  processes = ["worker"]
  memory = "512mb"

便利なコマンド一覧

コマンド	説明
fly launch	アプリと fly.toml を作成します
fly deploy	ビルドしてデプロイします
fly deploy --remote-only	Fly.io ビルダーでビルドします
fly status	アプリと Machine のステータスを表示します
fly logs	ライブログを継続的に表示します
fly logs --no-tail	最近のログを一度出力して終了します
fly logs --machine <id>	特定の Machine のログに絞り込みます
fly logs --machine <id> --no-tail	1 台の Machine の最近のログを表示して終了します
fly logs --region iad	リージョンでログを絞り込みます
fly logs --json	ログを JSON 形式で出力します
fly ssh console -s	Machine に SSH 接続します（選択）
fly proxy 5432:5432	ローカルポートをアプリにプロキシします
fly dashboard	Web ダッシュボードを開きます
fly scale show	現在のスケーリング設定を表示します
fly checks list	ヘルスチェックのステータスを表示します
fly releases	リリースの一覧を表示します
fly config show	現在の fly.toml を表示します
fly apps restart	すべての Machine を再起動します