skaffold-orbstack

OrbStack と Skaffold - ポートフォワーディング不要の開発

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

次の場合はこのスキルを使用してください…	次の場合は関連する Skaffold／コンテナーのスキルを使用してください…
OrbStack のローカル Kubernetes クラスターに Skaffold を接続する	内側の開発ループ向けにファイル同期ルールを定義する（skaffold-filesync）
ポートフォワーディングなしで *.k8s.orb.local、LoadBalancer、または Ingress 経由でサービスにアクセスする	デプロイ前の test またはデプロイ後の verify ステージを追加する（skaffold-testing）
既存のプロジェクトを kubectl port-forward から OrbStack ネットワーキングに移行する	コンテナーイメージ自体を強化または縮小する（container-development）

概要

OrbStack は、ほかのツール（minikube、kind、Docker Desktop）と比べて、優れたローカル Kubernetes ネットワーキングを提供します。ポートフォワーディングなしで、macOS から直接サービスにアクセスできます。

OrbStack の主な利点

機能	OrbStack	minikube/kind
LoadBalancer の自動プロビジョニング	✅ はい	❌ MetalLB が必要
ワイルドカード DNS（*.k8s.orb.local）	✅ はい	❌ なし
ホストからの cluster.local アクセス	✅ はい	❌ なし
Pod IP への直接アクセス	✅ はい	❌ なし
HTTPS 証明書の自動発行	✅ はい	❌ なし

サービスへのアクセス方法

方法 1：LoadBalancer サービス（最も簡単）

サービスタイプを ClusterIP から LoadBalancer に変更します。

apiVersion: v1
kind: Service
metadata:
  name: my-app
spec:
  type: LoadBalancer  # OrbStack auto-provisions external IP
  ports:
    - port: 80
      targetPort: 8080
  selector:
    app: my-app

アクセス：macOS から curl http://my-app.default.svc.cluster.local を実行します。

方法 2：ワイルドカード DNS を使用した Ingress（推奨）

初回セットアップ - Ingress コントローラーをインストールします：

# Ingress-NGINX (recommended)
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.1/deploy/static/provider/cloud/deploy.yaml

# OR Traefik
helm repo add traefik https://traefik.github.io/charts
helm install traefik traefik/traefik

サービス用の Ingress を作成します：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
spec:
  ingressClassName: nginx
  rules:
    - host: my-app.k8s.orb.local
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-app
                port:
                  number: 80

アクセス：http://my-app.k8s.orb.local（自動的に名前解決されます）

方法 3：サービス DNS への直接アクセス（cluster.local）

OrbStack はクラスター DNS を macOS に公開します。

# Access any service directly
curl http://my-app.default.svc.cluster.local:8080

# Full DNS pattern
curl http://<service>.<namespace>.svc.cluster.local:<port>

OrbStack 向け Skaffold 設定

最小限の skaffold.yaml（ポートフォワーディング不要）

apiVersion: skaffold/v4beta11
kind: Config
metadata:
  name: my-app

build:
  local:
    push: false
    useBuildkit: true
  artifacts:
    - image: my-app
      docker:
        dockerfile: Dockerfile

deploy:
  kubeContext: orbstack
  kubectl:
    manifests:
      - k8s/*.yaml
  statusCheck: true
  statusCheckDeadlineSeconds: 180

# Port-forward REMOVED - use LoadBalancer/Ingress instead

プロファイル：Ingress を使用したローカル環境

profiles:
  - name: local-ingress
    deploy:
      kubeContext: orbstack
      kubectl:
        manifests:
          - k8s/base/*.yaml
          - k8s/ingress/*.yaml  # Ingress resources

プロファイル：サービスのみ（フロントエンドのローカル開発）

profiles:
  - name: services-only
    build:
      artifacts: []  # Don't build frontend
    deploy:
      kubeContext: orbstack
      kubectl:
        manifests:
          - k8s/namespace.yaml
          - k8s/database/*.yaml
          - k8s/api/*.yaml

ローカルで npm run dev を実行しながら、http://api.k8s.orb.local でバックエンドにアクセスします。

Kubernetes マニフェストのテンプレート

LoadBalancer サービスのテンプレート

# k8s/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: {{ .name }}
  labels:
    app: {{ .name }}
spec:
  type: LoadBalancer
  ports:
    - name: http
      port: 80
      targetPort: {{ .containerPort | default 8080 }}
  selector:
    app: {{ .name }}

Ingress のテンプレート

# k8s/ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ .name }}
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
    - host: {{ .name }}.k8s.orb.local
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: {{ .name }}
                port:
                  number: 80

移行：ポートフォワーディングから LoadBalancer へ

移行前（従来の方法）

# skaffold.yaml with port-forward
portForward:
  - resourceType: service
    resourceName: api
    port: 8080
    localPort: 8080
    address: 127.0.0.1
  - resourceType: service
    resourceName: frontend
    port: 3000
    localPort: 3000
    address: 127.0.0.1

skaffold dev  # Services at localhost:8080, localhost:3000

移行後（OrbStack ネイティブ）

# k8s/services.yaml - Change service types
apiVersion: v1
kind: Service
metadata:
  name: api
spec:
  type: LoadBalancer  # Changed from ClusterIP
  ports:
    - port: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: frontend
spec:
  type: LoadBalancer  # Changed from ClusterIP
  ports:
    - port: 3000

# skaffold.yaml - Remove portForward section entirely
deploy:
  kubeContext: orbstack
  kubectl:
    manifests:
      - k8s/*.yaml
# No portForward needed!

skaffold dev  # Services at api.default.svc.cluster.local:8080
              #            frontend.default.svc.cluster.local:3000

よくあるパターン

データベースへのアクセス

# k8s/postgresql.yaml
apiVersion: v1
kind: Service
metadata:
  name: postgresql
spec:
  type: LoadBalancer  # Access from local tools (DBeaver, pgAdmin)
  ports:
    - port: 5432

接続文字列：postgres://user:[email protected]:5432/db

マルチサービスアプリケーション

# k8s/ingress.yaml - Single Ingress for all services
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-ingress
spec:
  ingressClassName: nginx
  rules:
    - host: api.k8s.orb.local
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: api
                port:
                  number: 8080
    - host: web.k8s.orb.local
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: frontend
                port:
                  number: 3000
    - host: admin.k8s.orb.local
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: admin-panel
                port:
                  number: 8000

セキュリティに関する考慮事項

デフォルト：ローカルホストのみ

OrbStack はデフォルトでサービスへのアクセスをローカルホストに制限するため、信頼できないネットワークでも安全です。

LAN に公開する（慎重に使用してください）

設定 → Kubernetes → 「サービスをローカルネットワークデバイスに公開」

次の場合に限り有効にしてください：

• 同じネットワーク上のモバイルデバイスからテストする
• ローカル環境をチームと共有する
• 信頼できるネットワークを使用している

トラブルシューティング

サービスにアクセスできない

1. サービスタイプを確認します：kubectl get svc
2. LoadBalancer に EXTERNAL-IP が割り当てられていることを確認します（<pending> ではないこと）
3. DNS をテストします：nslookup my-app.default.svc.cluster.local

Ingress が機能しない

1. Ingress コントローラーが実行中であることを確認します：

   kubectl -n ingress-nginx get pods
   

2. Ingress コントローラーに LoadBalancer IP が割り当てられていることを確認します：

   kubectl -n ingress-nginx get svc
   

3. Ingress リソースを確認します：

   kubectl describe ingress my-app
   

DNS 名前解決の問題

# Test cluster DNS from macOS
nslookup my-service.default.svc.cluster.local

# If short names fail, use full domain
# ❌ my-service.default.svc
# ✅ my-service.default.svc.cluster.local

Pod IP への直接アクセス（デバッグ）

# Get pod IP
kubectl get pods -o wide

# Connect directly (OrbStack routes pod network to macOS)
curl http://10.42.0.15:8080

エージェント向けの最適化

用途	コマンド
開発を開始する（ポートフォワーディングなし）	skaffold dev --kube-context=orbstack
サービス IP を確認する	kubectl get svc -o wide
Ingress を確認する	kubectl get ingress
DNS 名前解決をテストする	nslookup my-app.default.svc.cluster.local
Ingress コントローラーを確認する	kubectl -n ingress-nginx get pods
Pod IP を取得する	kubectl get pods -o wide
特定のプロファイルを実行する	skaffold dev -p services-only --kube-context=orbstack
Ingress の詳細を表示する	kubectl describe ingress my-app

クイックセットアップチェックリスト

1. Ingress コントローラーをインストールします（初回のみ）
2. サービスタイプを LoadBalancer に変更します
3. 見やすい URL 用の Ingress リソースを作成します
4. skaffold.yaml から portForward を削除します
5. デプロイ設定で kubeContext: orbstack を設定します
6. ローカルの .env/config を更新し、.k8s.orb.local URL を使用します

コマンドリファレンス

# Start development (no --port-forward needed)
skaffold dev --kube-context=orbstack

# Run specific profile
skaffold dev -p services-only --kube-context=orbstack

# Check service accessibility
kubectl get svc -o wide

# Verify Ingress
kubectl get ingress