このセクションでは、Managed Service for Apache Kafka で mTLS を構成して使用する際に発生する一般的な問題のトラブルシューティング ガイダンスについて説明します。
クラスタの更新時のエラー
gcloud managed-kafka clusters update コマンドまたは gcloud managed-kafka clusters create コマンドを実行すると、次のエラーが発生することがあります。
SSL プリンシパル マッピング ルールが無効です
次のいずれかのエラー メッセージが表示されます。
INVALID_ARGUMENT: The request was invalid: invalid SSL principal mapping
rule: \"RULE:INVALID-RULE\". The rule must be of the format DEFAULT or
RULE:pattern/replacement/[LU]
INVALID_ARGUMENT: The request was invalid: invalid SSL principal mapping
rules: \"RULE:\\nRULE:,DEFAULT\" contains a newline
このエラー メッセージは、ssl-principal-mapping-rules フラグに指定された値の形式が正しくないか、無効な文字が含まれている場合に発生します。
必要な形式に一致するようにルールを修正し、ルール文字列に改行文字が含まれていないことを確認します。ssl-principal-mapping-rules フラグの詳細については、プリンシパル マッピングをご覧ください。
CA プールの構成が無効です
次のいずれかのエラー メッセージが表示されます。
INVALID_ARGUMENT: The request was invalid:
ca_pool: project/managed-kafka-test/locations/us-central1/test-ca-pool
doesn't match the expected format: projects/{project}/locations/{location}/caPools/{caPool}
INVALID_ARGUMENT: The request was invalid: maximum of 10 CA pools can be specified
INVALID_ARGUMENT: The request was invalid: duplicate CA pool:
projects/managed-kafka-test/locations/us-central1/caPools/test-ca-pool.
All CA pools must be unique
このエラー メッセージは、mtls-ca-pools フラグに指定された CA プールのリストが無効であるために発生します。CA プールのリストを確認し、次のことを確認します。
すべての CA プール名には、完全なリソース形式（
projects/PROJECT_ID/locations/LOCATION/caPools/CA_POOL_ID）が使用されます。リストに重複する CA プールはありません。
CA プールの合計数が 10 個を超えていない。
クラスタが mTLS をサポートしていない
次のようなエラー メッセージが表示されます。
FAILED_PRECONDITION: Invalid resource state for \"tls_config\": mTLS is not
supported for this cluster because it was created before the mTLS feature
was added. Please create a new cluster to use mTLS.
このエラー メッセージは、この機能が利用可能になる前に作成されたクラスタで mTLS を有効にしようとした場合に発生します。エラー メッセージが示すように、mTLS を使用するには新しいクラスタを作成する必要があります。2025 年 6 月 24 日より前に作成された既存の対象外クラスタで mTLS を有効にすることはできません。
クライアント接続エラー
クライアント アプリケーションがクラスタの mTLS エンドポイントに接続できない場合は、次の一般的な構成の問題を確認します。
ブートストラップ アドレスが正しくない: 正しいブートストラップ アドレスを使用していることを確認します。
9092ではなく9192で終わる mTLS ブートストラップ アドレスを使用する必要があります。無効または正しくないクライアント証明書: クライアント証明書が有効で、有効期限が切れておらず、クラスタで構成された CA プールのいずれかに存在する CA から発行されたことを確認します。
クライアント キーストアの構成が正しくない: クライアント アプリケーションの構成がキーストア ファイルとトラストストア ファイルを正しく指しており、パスワードが正しいことを確認します。
Kafka ACL が正しくない: 認証されたプリンシパルに必要な Kafka ACL が作成されていることを確認します。プリンシパルは、
User:が付加された証明書のサブジェクト名（またはマッピングされたエイリアス）です。たとえば、サブジェクト名がtest-userの場合、プリンシパルはUser:test-userです。
Cloud Logging のエラー
クラスタのログに次のエラーが表示されることがあります。このログは Logging で確認できます。ロギングの詳細については、ログ エクスプローラを使用してログを表示するをご覧ください。
トラストストアのサイズが上限を超えている
次のようなログエントリが表示されます。
Trust store size X bytes exceeds the maximum allowed size of 1000 KiB
and cannot be updated.
このエラー メッセージは、構成された CA プール内のすべての CA 証明書の合計サイズが 1,000 KiB の上限を超えている場合に発生します。
CA プールの証明書を確認して、合計サイズを小さくします。これには、サイズの大きな証明書や不要な証明書の削除、CA チェーンの最適化などが含まれます。
CA プールから証明書を取得できませんでした
次のようなログエントリが表示されます。
Managed Service for Apache Kafka failed to fetch certificates from
CA pool <ca-pool-name>. Error: <error>.
このエラー メッセージは、Managed Service for Apache Kafka サービス エージェントが指定された CA プールから証明書を取得できなかった場合に発生します。メッセージのエラー部分に詳細が表示されます。この失敗の一般的な原因は、IAM 権限がないことです。
Managed Service for Apache Kafka サービス エージェントに、CA プールを含むプロジェクトに対する CA プール読み取り（roles/privateca.poolReader）ロールがあることを確認します。これは、クロス プロジェクトの設定で特に重要です。mTLS の構成に必要な権限の詳細については、必要なロールと権限をご覧ください。