メインコンテンツまでスキップ

トラブルシューティング

トラブルシューティング

DuoKey AWS XKS Proxy の一般的な問題を診断して解決する

適用対象:
AWS XKS Proxy接続の問題エラーの解決

クイック診断チェックリスト​

前提条件

  • 外部キーストアの接続ステータスが確認済み
  • XKS プロキシのヘルスエンドポイントが応答している
  • AWS からプロキシへのネットワーク接続が確認済み
  • TLS 証明書が有効で期限切れでない
  • SigV4 認証クレデンシャルが正しい
  • 外部キーがキーマネージャーに存在する
  • 外部キーマネージャーにプロキシからアクセス可能
  • 最近の CloudWatch メトリクスにアクティビティが表示されている
  • プロキシログに最近のリクエストが表示されている

一般的な問題​

1. XksProxyUriUnreachableException​

警告
エラー：XksProxyUriUnreachableException: The XKS proxy URI endpoint is unreachable

考えられる原因：

  • XKS プロキシがダウンしているか実行されていない
  • ネットワーク接続の問題
  • ファイアウォールが AWS KMS の IP 範囲をブロックしている
  • DNS 解決の失敗
  • TLS 証明書の問題
Diagnose ConnectivityBASH
# 1. Check if proxy is running
curl -k https://your-proxy-address.com/health

# 2. Check DNS resolution
nslookup your-proxy-address.com
dig your-proxy-address.com

# 3. Check TLS certificate
echo | openssl s_client -connect your-proxy-address.com:443 -servername your-proxy-address.com

# 4. Check proxy logs
tail -f /var/log/duokey-xks-proxy/proxy.log

2. XksProxyInvalidResponseException​

警告
エラー：XksProxyInvalidResponseException: The XKS proxy returned an invalid response

考えられる原因：

  • プロキシが AWS XKS プロキシ API 仕様に準拠していない
  • プロキシ応答の JSON フォーマットの問題
  • 不正な HTTP ステータスコード
  • 必須の応答フィールドの欠落

3. XksProxyIncorrectAuthenticationCredentialException​

警告
エラー：XksProxyIncorrectAuthenticationCredentialException: Authentication credential is incorrect

考えられる原因：

  • AWS とプロキシの間で SigV4 クレデンシャルが一致しない
  • クレデンシャルが期限切れまたはローテーションされた
  • AWS とプロキシの間のクロックスキュー

4. XksKeyNotFoundException​

警告
エラー：XksKeyNotFoundException: External key not found

考えられる原因：

  • キー ID の不一致（大文字と小文字を区別）
  • 外部キーマネージャーからキーが削除された
  • 誤ったキーバックエンドが構成されている
  • DuoKey Cockpit のルーティングの問題

5. 高レイテンシの問題​

症状：操作の完了に 100ms 以上かかる

考えられる原因：

  • AWS とプロキシの間のネットワークレイテンシ
  • 外部キーマネージャーのパフォーマンスの問題
  • プロキシのリソース制約
  • 地理的な距離

6. TLS 証明書の問題​

症状：TLS ハンドシェイクの失敗または証明書の警告

考えられる原因：

  • 期限切れの証明書
  • 証明書チェーンが不完全
  • ドメインに対して誤った証明書
  • AWS によって信頼されていない証明書

7. 外部キーストアの切断​

症状：外部キーストアが切断状態として表示される

高度なトラブルシューティング​

デバッグモード​

Enable Debug LoggingYAML
# config.yml
logging:
level: debug
components:
  authentication: debug
  encryption: debug
  routing: debug
  backend: debug
Review Debug LogsBASH
systemctl restart duokey-xks-proxy
tail -f /var/log/duokey-xks-proxy/proxy.log | jq .

パケットキャプチャ​

Capture Network TrafficBASH
# Capture HTTPS traffic to/from proxy
tcpdump -i any -s 0 -w /tmp/xks-traffic.pcap port 443

# Analyze with Wireshark
wireshark /tmp/xks-traffic.pcap

ヘルスチェックのデバッグ​

Detailed Health CheckBASH
# Detailed health check
curl -v https://your-proxy:443/kms/xks/v1/health \
  -H "Content-Type: application/json" \
  -d '{}' | jq .

# Expected response:
# {
# "status": "OK",
# "version": "1.0",
# "keyManagers": [
# {
# "name": "vault-primary",
# "status": "ACTIVE"
# }
# ]
# }

エラーコードリファレンス​

エラーコード説明一般的な原因
XksProxyUriUnreachableExceptionプロキシに到達できないネットワーク、ファイアウォール、プロキシダウン
XksProxyInvalidResponseException無効なプロキシ応答API 準拠、バグ
XksProxyIncorrectAuthenticationCredentialException認証エラー誤ったクレデンシャル、クロックスキュー
XksKeyNotFoundException外部キーが見つからない誤ったキー ID、キーの削除
XksKeyInvalidConfigurationExceptionキー構成が無効誤ったキータイプ、キーの無効化
XksProxyInvalidConfigurationExceptionプロキシ構成が無効誤った URL、無効な設定

ヘルプの取得​

サポートに連絡する前に​

Gather Diagnostic InformationBASH
# 1. System information
uname -a
cat /etc/os-release

# 2. Proxy version and status
/usr/local/bin/duokey-xks-proxy --version
systemctl status duokey-xks-proxy

# 3. Recent logs
tail -100 /var/log/duokey-xks-proxy/proxy.log > proxy-logs.txt

# 4. External key store status
aws kms describe-custom-key-stores \
  --custom-key-store-id cks-xxxxx > keystore-status.json

# 5. CloudWatch metrics
aws cloudwatch get-metric-statistics \
  --namespace AWS/KMS \
  --metric-name XksProxyLatency \
  --dimensions Name=CustomKeyStoreId,Value=cks-xxxxx \
  --start-time $(date -u -d '1 hour ago' '+%Y-%m-%dT%H:%M:%S') \
  --end-time $(date -u '+%Y-%m-%dT%H:%M:%S') \
  --period 300 \
  --statistics Average,Maximum > cloudwatch-metrics.json

# 6. Network test results
curl -v https://your-proxy:443/health > network-test.txt 2>&1

連絡先情報​

リソース連絡先
DuoKey サポート[email protected]
AWS サポートAWS コンソールでケースを開く
コミュニティGitHub Discussions

予防措置​

定期的なヘルスチェック​

Automated Health Check ScriptBASH
#!/bin/bash
# /usr/local/bin/xks-health-check.sh

PROXY_URL="https://your-proxy:443/health"
ALERT_EMAIL="[email protected]"

RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" $PROXY_URL)

if [ "$RESPONSE" != "200" ]; then
  echo "XKS Proxy health check failed: HTTP $RESPONSE" | \
      mail -s "XKS Proxy Alert" $ALERT_EMAIL
  exit 1
fi

exit 0
Schedule Health CheckBASH
# Add to cron
*/5 * * * * /usr/local/bin/xks-health-check.sh

定期的なメンテナンススケジュール​

頻度タスク
毎週ログとメトリクスの確認
毎月ディザスタリカバリ手順のテスト
四半期ごとクレデンシャルのローテーション
毎年TLS 証明書の更新

次のステップ​

キー管理

KMS キーを管理する

監視

包括的な監視を設定する

はじめに

セットアップガイドに戻る

関連項目