temporal-cloud

Temporal Cloud スキル

tcld と temporal CLI を使用して、Temporal Cloud の接続、認証、設定に関する問題をユーザーが診断し、解決できるよう支援します。

基本方針

Cloud の問題は、設定、ネットワーク、認証、Temporal 固有のコードが交差する領域で発生するため、厄介です。ほとんどの問題は、予測可能なパターンに当てはまります。このスキルでは、根本原因をすばやく特定して修正方法を提示できるよう、体系的な診断を行います。

参考資料：

• CLI コマンドの全リファレンスとエラーコードについては、references/cloud-troubleshooting-reference.md を参照してください
• セットアップ手順の詳細については、references/common-scenarios.md を参照してください
• 環境設定のドキュメント - Cloud に接続するための SDK 設定
• HA 名前空間の接続 - マルチリージョンのエンドポイントと DNS の設定
• Dev Success のトラブルシューティングガイド - 接続に関する補足のトラブルシューティングガイド

対象外： ワーカーのパフォーマンス調整、スケーリング、メトリクスの解釈、SDK 固有の設定、デプロイパターン。これらのトピックは、ワーカーに特化した別のスキルで扱います。

問題の分類

カテゴリ	主な症状	最初に確認する項目
tcld ログイン	ログイン失敗、トークンの更新失敗、アカウントの誤り	tcld account get
接続／認証	接続できない、アクセス拒否、ハンドシェイクの失敗	エンドポイントの形式 + DNS + ポートの接続性
原因が特定しにくいランタイムエラー	context deadline exceeded、workflow is busy	まず操作とレイヤーを特定する
mTLS／証明書	x509 エラー、不明な認証局、期限切れ	openssl x509 -enddate
名前空間	名前空間が見つからない、SNI の不一致	名前空間名の形式
HA／フェイルオーバー	フェイルオーバーが機能しない、リージョンが違う、DNS が古い	DNS CNAME の解決
ワーカー	タスクが取得されない、接続が古い	temporal task-queue describe
プライベート接続	PrivateLink／PSC のエラー	VPC エンドポイントのステータス
レート制限	RESOURCE_EXHAUSTED	APS の制限

手順

ステップ 1：カテゴリを特定する

ユーザーに次のことを尋ねます：

• 正確なエラーメッセージは何ですか？（可能であればコピーして貼り付けてください）
• 何をしようとしていますか？（tcld コマンドの実行、ワーカーの起動、ワークフローの実行など）
• 最近、何が変わりましたか？（新しい証明書、新しい名前空間、新しいリージョンなど）

ステップ 2：状況を把握する

SDK／クライアントのコードスニペットを確認する場合：

• 使用している認証方式は API キーと mTLS のどちらですか？
• 使用している SDK とバージョンは何ですか？
• 使用している正確な HostPort ／アドレスは何ですか？
• 使用している正確な Namespace は何ですか？
• これは SDK のコード、temporal CLI、tcld のどれですか？

tcld の問題の場合：

• tcld account get を実行できますか？
• Temporal アカウントを複数お持ちですか？

接続の問題の場合：

• 正確なアドレス／HostPort は何ですか？
• mTLS と API キーのどちらを使用していますか？
• 使用している SDK とバージョンは何ですか？
• お客様と Cloud の間にファイアウォールやプロキシはありますか？

原因が特定しにくいランタイムエラーの場合：

• エラーは具体的にどこで発生していますか？ワークフローの開始時、シグナル／更新時、ポーリング時、クエリ時、ログ内のどこですか？
• これは処理の開始前、ポーリング中、またはワークフローコードの実行中に発生していますか？
• 該当するタスクキューにポーラーはいますか？
• トラフィックの急増、デプロイ、設定変更の後に発生し始めましたか？

証明書の問題の場合：

• 証明書はいつ生成されましたか？
• どの CA を使用しましたか？
• CA は名前空間にアップロードされていますか？

ワーカーの問題の場合：

• ワーカーは実行中ですか？何台ありますか？
• temporal task-queue describe には何が表示されますか？
• ワーカーのログにエラーはありますか？

ステップ 3：判断ツリーを適用する

カテゴリに応じた判断ツリーを使用します（以下を参照）。

Step 4: 修正方法を提示する

問題を解決するための具体的なコマンドと、確認手順を示します。

提案する診断または修正方法には、必ず信頼度スコアを含めてください。

• Confidence: 9-10/10 症状、操作、確認できるシグナルが明確に一致する場合
• Confidence: 6-8/10 根拠は十分だが、妥当な別の可能性が残る場合
• Confidence: 1-5/10 問題がまだ曖昧で、「修正方法」が実際には次の切り分け確認にあたる場合

問題が曖昧な場合は、そのことを明示し、推測した根本原因を確定事項として示すのではなく、次の確認に絞って提案してください。

決定木

tcld のログイン問題

Symptom: tcld login not working
│
├─ Can `tcld account get` run?
│  ├─ Yes → Login is valid; continue with account verification
│  └─ No → Run `tcld login`
│
├─ Token refresh failed?
│  └─ tcld logout && tcld login
│
├─ Wrong organization/account?
│  ├─ tcld account get
│  └─ Verify the expected namespace appears in `tcld namespace list`
│
└─ "unauthorized" or auth errors?
   └─ tcld logout && tcld login

接続の失敗

ドキュメント： 環境設定 - SDK の接続オプション

ネットワークのデバッグ前にエンドポイントを確認してください：

用途	推奨エンドポイント	備考
ワーカーとクライアント（すべての認証方式）	<namespace>.<account>.tmprl.cloud:7233	Namespace Endpoint - mTLS と API キー認証の両方に対応します。すべての namespace で推奨されます。
マルチリージョン HA（上級者向け）	<region>.<cloud_provider>.api.temporal.io:7233	リージョナルエンドポイント - 高度な HA ルーティングでのみ必要です。namespace アクセスのドキュメントを参照してください。
tcld / Cloud Ops API	saas-api.tmprl.cloud	コントロールプレーン

例外： Flexible Auth（プレリリース）を使用する namespace では、まだ Namespace Endpoints を使用できません。

Symptom: Can't connect to Temporal Cloud
│
├─ Check: Using Namespace Endpoint?
│  ├─ Using regional endpoint (`*.api.temporal.io`) without HA need?
│  │  └─ Switch to Namespace Endpoint (`<ns>.<acct>.tmprl.cloud:7233`)
│  ├─ Using old/stale endpoint format?
│  │  └─ Switch to Namespace Endpoint
│  └─ Endpoint looks correct → Continue
│
├─ Check: DNS resolution
│  └─ nslookup <host-from-address>
│     ├─ Fails → DNS issue (check network, VPN)
│     └─ Succeeds → Continue
│
├─ Check: Port connectivity
│  └─ nc -zv <host-from-address> 7233
│     ├─ Fails → Firewall blocking port 7233
│     └─ Succeeds → Continue
│
├─ Check: TLS handshake
│  └─ openssl s_client -connect <address>
│     ├─ Fails → Certificate issue (see mTLS tree)
│     └─ Succeeds → Continue
│
└─ Check: Temporal CLI test
   └─ temporal workflow list --limit 1 --address ...
      ├─ PERMISSION_DENIED → Check namespace name format
      ├─ UNAUTHENTICATED → Certificate not accepted
      └─ Works → Connection OK, issue elsewhere

曖昧なランタイムエラー

これらを単なる接続の失敗だと決めつけないでください。まず操作の種類に基づいて分類してください。

エラーテキスト	よくある解釈	最初の切り分け
context deadline exceeded	エンドポイントの誤り、ネットワークタイムアウト、ペイロードが大きすぎる、実行パスのブロック、クライアント側のタイムアウト	フローのどの段階で発生しますか？
workflow is busy / RESOURCE_EXHAUSTED: Workflow is busy	操作レベルの競合、ワークロードの逼迫、ユーザー向けエラーの意味の誤解	どの操作で返されましたか？
no pollers	接続中のワーカーがいない、ワーカーは存在するが設定が誤っている、古い、または誤解を招くメトリクス	temporal task-queue describe にポーラーが表示されますか？

次の手順で判断してください。

Symptom: ambiguous runtime error
│
├─ Check: Which operation returned the error?
│  ├─ start / signal / update / query request
│  ├─ poll loop / worker logs
│  └─ UI / metrics only
│
├─ Check: Is work reaching a task queue?
│  ├─ No pollers listed
│  │  └─ Treat as worker connectivity / config until proven otherwise
│  ├─ Pollers listed, backlog growing
│  │  └─ Worker capacity / tuning issue (out of scope for this skill)
│  └─ Pollers listed, no backlog issue
│     └─ Continue
│
├─ For `context deadline exceeded`
│  ├─ Happens before any work starts
│  │  └─ Check endpoint format, auth, proxy, DNS, firewall
│  ├─ Happens on workflow start with large payloads
│  │  └─ Consider payload size / client timeout path
│  └─ Happens during local execution / queries
│     └─ Consider blocked execution path, local activity, or client-side timeout
│
└─ For `workflow is busy`
   ├─ Identify exact API / operation
   ├─ Check whether user is conflating this with a generic workflow failure
   └─ Explain that the error class is operation-specific before prescribing fixes

操作とその前後のシグナルからエラーを解釈できない場合は、曖昧であると明記し、修正方法を提示する前に、さらに状況を確認してください。

回答する際は、提案する診断または次の手順に、1～10 の信頼度スコアを付けてください。曖昧なケースでは信頼度を低くし、広範な修正を断定するのではなく、次の確認を限定的に示してください。

SDK スニペットのレビュー

ユーザーが SDK の設定を貼り付けた場合は、下位レベルのネットワーク確認を提案する前に、設定自体を検証してください。

次の順で確認してください：

1. 認証方式：API キーまたは mTLS
2. アドレス / HostPort：ほとんどの場合、Namespace Endpoint（<ns>.<acct>.tmprl.cloud:7233）を指定する必要があります
3. Namespace：Cloud の完全な namespace 形式（<namespace>.<account-id>）
4. TLS 設定：API キー認証では空の tls.Config{} が一般的です。mTLS ではクライアント証明書とキーが必要です
5. 環境設定：TEMPORAL_ADDRESS、TEMPORAL_NAMESPACE、TEMPORAL_API_KEY、TEMPORAL_TLS_CLIENT_CERT_PATH、TEMPORAL_TLS_CLIENT_KEY_PATH を優先してください

よくあるスニペットの診断：

• Namespace Endpoint で接続できるのに、リージョナルエンドポイント（*.api.temporal.io）を使用している → <ns>.<acct>.tmprl.cloud:7233 に簡略化する
• Cloud の namespace / 認証を使用しているのに HostPort が空 → Cloud エンドポイントの明示が不足しています
• SDK / ランタイムで TLS が有効になっていないのに API キーを使用している → SDK 固有の Cloud ガイダンスを確認する
• 古いエンドポイント形式（古いドキュメントやサンプル）を使用している → 現行の Namespace Endpoint に更新する

スニペットに誤りがある場合は、まずそれを修正してください。エンドポイントと namespace が妥当だと確認できるまでは、DNS / TLS のデバッグから始めないでください。

証明書エラー

Symptom: x509 certificate errors
│
├─ "certificate signed by unknown authority"
│  ├─ Is CA uploaded to namespace?
│  │  └─ tcld namespace accepted-client-ca list --namespace <ns>
│  │     ├─ CA not listed → Add it:
│  │     │  tcld namespace accepted-client-ca add \
│  │     │    --namespace <ns> --ca-certificate-file ca.pem
│  │     └─ CA listed → Cert not signed by that CA
│  │        └─ Verify: openssl verify -CAfile ca.pem client.pem
│  │
│  └─ Self-signed cert without CA?
│     └─ Must use CA-signed certs for Cloud
│
├─ "certificate has expired"
│  ├─ Check expiry: openssl x509 -enddate -noout -in cert.pem
│  └─ Generate new cert:
│     tcld generate-certificates end-entity-certificate \
│       --organization <org> --validity-period 365d \
│       --ca-certificate-file ca.pem --ca-key-file ca.key \
│       --certificate-file client.pem --key-file client.key
│
├─ "private key does not match"
│  └─ Wrong key file - verify match:
│     openssl x509 -modulus -noout -in cert.pem | md5
│     openssl rsa -modulus -noout -in key.pem | md5
│
└─ "bad certificate" from server
   └─ Server rejected cert - CA not in accepted list
      └─ tcld namespace accepted-client-ca list --namespace <ns>

Namespace の問題

Symptom: namespace not found or access denied
│
├─ Check: Namespace name format
│  ├─ Format: <namespace-name>.<account-id>
│  ├─ Example: my-namespace.a1b2c3
│  └─ Wrong format → Use full namespace name
│
├─ Check: Namespace exists
│  └─ tcld namespace list
│     └─ Not listed → Wrong account, or namespace not created
│
├─ Check: Address format
│  ├─ Namespace Endpoint (recommended): <namespace>.<account>.tmprl.cloud:7233
│  ├─ Regional Endpoint (HA only): <region>.<cloud_provider>.api.temporal.io:7233
│  └─ Using wrong or stale endpoint? → switch to Namespace Endpoint
│
└─ Check: User permissions
   └─ tcld user list
      └─ Verify user has access to namespace

ワーカーの問題

このスキルでは、ワーカーのCloud 接続の問題を診断します。ワーカーのパフォーマンスチューニング、スケーリング、デプロイのパターンは対象外です。

ドキュメント： 環境設定 - SDK の接続設定

Symptom: Workers not picking up tasks
│
├─ Check: Are workers running?
│  └─ Verify worker process is up, check logs for errors
│
├─ Check: Task queue status
│  └─ temporal task-queue describe --task-queue <queue>
│     ├─ No pollers listed → Workers not connected (Cloud issue)
│     │  ├─ Check task queue name matches
│     │  ├─ Check namespace in worker config
│     │  ├─ Verify SDK connection options (see env config docs)
│     │  └─ Check for connection errors in logs
│     │
│     │  Note: if only metrics or dashboards say "no pollers", verify with CLI or another direct surface before concluding workers are absent.
│     │
│     ├─ Pollers listed but backlog growing
│     │  └─ NOT a Cloud issue (worker scaling/tuning problem)
│     │
│     └─ Pollers listed, no backlog
│        └─ Workers healthy, issue is elsewhere
│
├─ Check: DNS caching (common in K8s)
│  └─ Stale DNS can cause workers to connect to wrong endpoint
│     └─ Restart workers to refresh DNS
│
└─ Check: Rate limiting
   └─ RESOURCE_EXHAUSTED in logs?
      └─ See Rate Limiting section

対象範囲の確認：

問題の種類	対象範囲内？
tcld ログイン、証明書、名前空間、プライベート接続	はい
ワーカーのスケーリング、メトリクス、チューニング、デプロイ	いいえ
「ワーカーがタスクを受け取らない」	はい - 診断し、Cloud の問題でない場合は引き継ぎます

HA 名前空間の接続

ドキュメント： HA 名前空間の接続

HA（マルチリージョン）名前空間では、階層型の DNS 構造を使用します。

• 名前空間エンドポイント：<ns>.<acct>.tmprl.cloud（アクティブリージョンへの CNAME）
• リージョンエンドポイント：<region>.region.tmprl.cloud
• フェイルオーバー時に CNAME がリージョンを切り替えます（TTL は 15 秒、収束まで約 30 秒）

Symptom: HA namespace connectivity or failover issues
│
├─ Check: DNS resolution
│  └─ nslookup <namespace>.tmprl.cloud
│     ├─ Should return CNAME → <region>.region.tmprl.cloud
│     └─ Then resolve to IP address
│
├─ Symptom: Clients not failing over
│  ├─ Check: DNS caching
│  │  ├─ TTL is 15s - clients should converge within 30s
│  │  ├─ Some DNS resolvers cache longer
│  │  └─ Fix: Restart workers to refresh DNS
│  │
│  └─ Check: SDK connection caching
│     └─ Some SDKs cache connections - may need restart
│
├─ Symptom: PrivateLink not working after failover
│  ├─ Check: Regional DNS override configured?
│  │  └─ Need Route 53 private hosted zone for region.tmprl.cloud
│  │     mapping regional endpoints to VPC endpoint IPs
│  │
│  └─ Check: Inter-region connectivity
│     └─ Workers need Transit Gateway or VPC Peering to reach
│        VPC endpoints in both regions
│
├─ Symptom: GCP Private Service Connect not working
│  └─ NOT SUPPORTED: Private connectivity not yet offered for
│     GCP Multi-region Namespaces
│
└─ Symptom: sa-east-1 region issues
   └─ NOT SUPPORTED: sa-east-1 not available for Multi-region namespaces (because there are no other regions on the continent)

HA のワーカー配置：

• オプション A：両方のリージョンでワーカーを継続的に実行する
• オプション B：単一リージョンで実行し、フェイルオーバー時のアクセスには Transit Gateway/VPC Peering を使用する

プライベート接続の問題

Symptom: PrivateLink or Private Service Connect not working
│
├─ AWS PrivateLink
│  ├─ Check: VPC endpoint status
│  │  └─ AWS Console → VPC → Endpoints → Status = available
│  │
│  ├─ Check: Security groups
│  │  └─ Allow outbound to endpoint on port 7233
│  │
│  ├─ Check: DNS resolution
│  │  └─ Should resolve to private IP (10.x or 172.x)
│  │
│  └─ Check: Connectivity rules
│     ├─ tcld connectivity-rule list --namespace <ns>
│     └─ If needed, attach rules with:
│        tcld namespace set-connectivity-rules --namespace <ns> --connectivity-rule-ids <id>
│
├─ GCP Private Service Connect
│  ├─ Check: PSC endpoint status
│  │  └─ GCP Console → Network Services → Private Service Connect
│  │
│  ├─ Check: Firewall rules
│  │  └─ Allow egress to PSC endpoint
│  │
│  └─ Check: DNS configuration
│     └─ Cloud DNS zone for tmprl.cloud pointing to PSC
│
└─ General
   └─ Verify rule details:
      tcld connectivity-rule get --connectivity-rule-id <id>

レート制限

Symptom: RESOURCE_EXHAUSTED errors
│
├─ Check: Which operation is limited?
│  └─ Error message indicates operation type
│
├─ "namespace write ops" exceeded
│  ├─ Too many workflow starts
│  ├─ Too many signals/updates
│  └─ Fix: Add backoff, batch operations
│
├─ "namespace read ops" exceeded
│  ├─ Too many list/query operations
│  └─ Fix: Add caching, reduce polling frequency
│
└─ Poll operations rate limited
   ├─ Too many pollers across workers
   └─ Fix: Reduce MaxConcurrentPollers settings

よくあるシナリオ

手順を追った説明については、references/common-scenarios.md を参照してください。

• API キー接続の設定
• 新しい名前空間の設定（mTLS）
• 証明書のローテーション
• mTLS から API キーへの切り替え

よくある落とし穴

落とし穴	発生する理由	解決策
名前空間の形式が間違っている	name.account-id ではなく短い名前を使用している	tcld namespace list で完全な名前空間を確認して使用する
自己署名証明書	CA を使わずに自己署名証明書を使用しようとしている	まず CA を生成し、それで証明書に署名してから、CA をアップロードする
不要なリージョンエンドポイントの使用	Namespace Endpoint が使えるのに *.api.temporal.io を使用している	<namespace>.<account>.tmprl.cloud:7233 に切り替える
古いエンドポイントのドキュメント	Namespace Endpoint が共通化される前の古い例に従っている	Namespace Endpoint を使用する：<ns>.<acct>.tmprl.cloud:7233
証明書の期限切れ	有効期限を監視していない	アラートを設定し、期限が切れる前にローテーションする
tcld のアカウントが違う	別の組織にログインしている	tcld account get を実行し、tcld namespace list で名前空間を確認する
tcld のログイン状態が古い	キャッシュされた認証状態が無効になっている	tcld logout && tcld login
DNS キャッシュ	K8s ポッドが古い DNS をキャッシュしている	エンドポイントの変更後にポッドを再起動する
ポートの指定漏れ	ファイアウォールが 7233 をブロックしている	ポート 7233 への送信が許可されていることを確認する

ヒント

• 正確なエラーメッセージを必ず入手する - 言い換えず、コピーして貼り付けてください
• まず簡単なことから確認する - DNS、ポート接続、証明書の有効期限
• デフォルトでは Namespace Endpoint を使用する - <ns>.<acct>.tmprl.cloud:7233 は mTLS と API キー認証の両方で機能します
• 証明書の問題には openssl を使用する - SDK よりも明確なエラーメッセージが表示されます
• tcld account get が役立ちます - 現在のアカウントコンテキストを表示します
• 名前空間名では大文字と小文字が区別されます - 正確に一致させてください
• API キーは mTLS より簡単です - より簡単な構成にする場合は検討してください
• 環境設定のドキュメントを案内する - 環境設定で、SDK の接続オプションをすべて確認できます