OS Login のトラブルシューティング


このドキュメントでは、メタデータ サーバーを使用して OS Login のトラブルシューティングを行う方法について説明します。OS Login の設定や手順の詳細については、OS Login を設定するをご覧ください。

仮想マシン(VM)インスタンスの内部からメタデータ サーバーに対してクエリを行うことができます。詳細については、インスタンス メタデータの格納と取得をご覧ください。

準備

  • まだ設定していない場合は、認証を設定します。認証とは、Google Cloud サービスと API にアクセスするために ID を確認するプロセスです。ローカル開発環境からコードまたはサンプルを実行するには、次のように Compute Engine に対する認証を行います。

    このページのサンプルをどのように使うかに応じて、タブを選択してください。

    コンソール

    Google Cloud コンソールを使用して Google Cloud サービスと API にアクセスする場合、認証を設定する必要はありません。

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command:

      gcloud init
    2. デフォルトのリージョンとゾーンを設定します

    REST

    このページの REST API サンプルをローカル開発環境で使用するには、gcloud CLI に指定した認証情報を使用します。

      Install the Google Cloud CLI, then initialize it by running the following command:

      gcloud init

一般的なエラー メッセージ

OS Login の使用時に発生する可能性のある一般的なエラーの例を次に示します。

グループの名前が見つからない

OS Login を使用するときは、接続が確立された後に次のエラー メッセージが返されることがあります。

/usr/bin/id: cannot find name for group ID 123456789

このエラー メッセージは無視してください。このエラーはインスタンスには影響しません。

グループの取得に失敗した

VM を作成する際に、次のようなログが表示されることがあります。

Dec 10 22:31:05 instance-1 google_oslogin_nss_cache[381]: oslogin_cache_refresh[381]: Refreshing group entry cache
Dec 10 22:31:05 instance-1 google_oslogin_nss_cache[381]: oslogin_cache_refresh[381]: Failure getting groups, quitting

これらのログは、組織で OS Login の Linux グループが構成されていないことを示します。このようなメッセージは無視してください。

前提条件でのエラー

SSH を使用して VM に接続すると、次のようなエラーが表示されることがあります。

ERROR: (gcloud.compute.ssh) FAILED_PRECONDITION: The specified username or UID is not unique within given system ID.

このエラーは、OS Login が組織内にすでに存在するユーザー名を生成しようとした場合に発生します。これは、ユーザー アカウントが削除され、その直後に同じメールアドレスを持つ新しいユーザーが作成された場合によく発生します。ユーザー アカウントの削除後、ユーザーの POSIX 情報が削除されるまでに最長で 48 時間かかります。

この問題を解決するには、以下のいずれかを行います。

無効な引数

SSH を使用して VM に接続するか、SCP を使用してファイルを転送すると、次のようなエラーが表示されることがあります。

ERROR: (gcloud.compute.ssh) INVALID_ARGUMENT: Login profile size exceeds 32 KiB. Delete profile values to make additional space.
ERROR: (gcloud.compute.scp) INVALID_ARGUMENT: Login profile size exceeds 32 KiB. Delete profile values to make additional space.

このエラーを解決するには、次の操作を行います。

  1. gcloud compute os-login describe-profile コマンドを実行して、OS Login プロファイルを表示します。

    gcloud compute os-login describe-profile
    

    出力は次のようになります。

    name: '00000000000000'
    posixAccounts:
    ...
    sshPublicKeys:
     ...:
       fingerprint: ...
       key: |
         ssh-rsa AAAAB3NzaC1yc2...
       name: ...
     ...
    
  2. 出力を確認して、未使用の SSH 認証鍵を特定します。

  3. gcloud compute os-login ssh-keys remove コマンドを使用して、未使用の鍵を出力から削除します。

    gcloud compute os-login ssh-keys remove --key=KEY
    

    KEY は、鍵のフィンガープリントまたは鍵文字列に置き換えます。

この問題の再発を防ぐには、SSH 認証鍵の有効期限を追加します。期限切れの鍵は、期限が切れてから 48 時間後、または新しい鍵をプロファイルに追加したときに、ログイン プロファイルから自動的に削除されます。

HTTP レスポンス コード: 503

SSH を使用して VM に接続しようとすると、次のエラーが表示されることがあります。

Failed to validate organization user USERNAME has login permission, got HTTP response code: 503

この問題は、メタデータ サーバーのレート制限(仮想マシン インスタンスあたりの秒間クエリ数が 100)が原因で発生します。この上限は調整できません。この問題を解決するには、数秒待ってから、接続を再試行します。

今後、この問題を回避するには、次のことを試してください。

  • アプリケーション コードに再試行メカニズムを実装します。詳細については、次をご覧ください。
  • 既存の SSH 接続を再利用します。
  • コマンドをバッチで送信して、SSH 接続と OS Login メタデータ クエリを減らします。

OS Login のデフォルト メタデータ エントリ

Compute Engine では、OS Login の情報を提供する一連のデフォルト メタデータ エントリが定義されています。デフォルト メタデータは常にサーバーによって定義され、設定されます。デフォルトのメタデータキーは大文字と小文字が区別されます。

次の表にクエリ可能なエントリを示します。

パスの基準: http://metadata.google.internal/computeMetadata/v1/
メタデータ エントリ 説明
project/attributes/enable-oslogin 現在の Google Cloud プロジェクトで OS Login が有効であるかどうかを確認します。
instance/attributes/enable-oslogin 現在の VM で OS Login が有効であるかどうかを確認します。
oslogin/users/ OS Login ユーザーのプロファイル情報を取得します。usernameuidpagesizepagetoken などのクエリ パラメータを渡すことができます。
oslogin/authorize/

OS Login ユーザーのログインまたは管理レベルの権限設定を取得します。

権限を確認するには、policy クエリ パラメータを指定する必要があります。ポリシー パラメータの値は、login(ログイン権限を確認)または adminLogin(sudo アクセスを確認)に設定する必要があります。

OS Login が構成されているかどうかの確認

Google Cloud コンソールまたは Google Cloud CLI を使用してメタデータをクエリして、OS Login が有効かどうかを確認します。プロジェクトまたはインスタンス メタデータで enable-oslogin メタデータキーが TRUE に設定されている場合、OS Login は有効です。インスタンス メタデータとプロジェクト メタデータの両方が設定されている場合、インスタンス メタデータで設定された値が優先されます。

OS Login ユーザーの表示

複数のユーザーのプロファイル情報を表示するには、pagesize パラメータと pagetoken パラメータを指定する必要があります。pagesizepagetoken は必要な数値に置き換えます。

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?pagesize=PAGE_SIZE&
pagetoken=PAGE_TOKEN" -H "Metadata-Flavor: Google"

たとえば、pagesize1 に設定し、pagetoken0 に設定するには、次のコマンドを実行します。

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?pagesize=1&pagetoken=0" -H "Metadata-Flavor: Google"

ほとんどのディストリビューションでは、Unix コマンド getent passwd を実行して組織ユーザーのパスワード エントリを取得できます。

特定の OS Login ユーザーの表示

VM の特定のユーザーのプロフィール情報を表示するには、次のコマンドを実行します。

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=USERNAME" -H "Metadata-Flavor: Google"

USERNAME は、クエリを実行するユーザーのユーザー名に置き換えます。

たとえば、ユーザー user_example_com を参照するリクエストを行うことができます。次のコマンドと出力の表示では、読みやすくするために書式が追加されています。

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=user_example_com" -H "Metadata-Flavor: Google"

出力は次のようになります。

{
    "loginProfiles": [{
        "name": "12345678912345",
        "posixAccounts": [{
            "primary": true,
            "username": "user_example_com",
            "uid": "123451",
            "gid": "123451",
            "homeDirectory": "/home/user_example_com",
            "operatingSystemType": "LINUX"
        }],
        "sshPublicKeys": {
            "204c4b4fb...": {
                "key": "ssh-rsa AAAAB3Nz...",
                "fingerprint": "204c4b4fb..."
            }
        }
    }]
}

ほとんどのディストリビューションでは、getent passwd usernamegetent passwd uid などの Unix コマンドを実行してプロファイル情報を取得できます。

ユーザーの SSH 認証鍵を取得するには、/usr/bin/google_authorized_keys USERNAME を実行するという方法もあります。鍵が返されない場合、そのユーザーは VM へのログインに必要な権限を持っていない可能性があります。

ログイン権限の確認

ログインの権限と管理レベルの権限を表示するには、policy=login&email=LOGIN_NAME クエリ パラメータを指定する必要があります。

  1. ユーザー プロフィールにクエリを実行して、name フィールドの値を取得します。

    curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=user_example_com" -H "Metadata-Flavor: Google"
  2. 出力で、name をメモします。

  3. name の値を使用して、次の login コマンドを実行します。

    curl "http://metadata.google.internal/computeMetadata/v1/oslogin/authorize?policy=login&email=LOGIN_NAME" -H "Metadata-Flavor: Google"
    

たとえば、前のセクションで表示したユーザー user_example_com のログイン権限をクエリで取得できます。

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/authorize?policy=login&email=12345678912345" -H "Metadata-Flavor: Google"

コマンド出力では、ユーザーが VM にログインする権限を持っていることを示しています。

{"success":true}

VM にサービス アカウントがあるかどうかの確認

メタデータ サーバーに対してクエリを行い、VM に関連付けられているサービス アカウントの有無を確認できます。VM で次のコマンドを実行します。

curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/" -H "Metadata-Flavor: Google"

出力は次のようになります。

12345-sa@developer.gserviceaccount.com/
default/

サービス アカウントが見つからない場合、出力は空白になります。

gcpdiag を使用した OS Login の問題のデバッグ

gcpdiag はオープンソース ツールです。正式にサポートされている Google Cloud プロダクトではありません。gcpdiag ツールを使用すると、Google Cloud プロジェクトの問題を特定して修正できます。詳細については、GitHub の gcpdiag プロジェクトをご覧ください。

この gcpdiag ランブックでは、Google Cloud の Windows VM と Linux VM の両方で SSH アクセスの問題が発生する可能性のある原因を調査します。主な内容は次のとおりです。
  • VM の健全性: VM が実行中で、十分なリソース(CPU、メモリ、ディスク)があるかどうかを確認します。
  • 権限: SSH 認証鍵を構成するための適切な IAM 権限があることを確認します。
  • VM 設定: SSH 鍵とその他のメタデータが正しく構成されていることを確認します。
  • ネットワーク ルール: ファイアウォール ルールを確認し、SSH トラフィックが許可されていることを確認します。
  • ゲスト OS: SSH をブロックする可能性のある内部 OS の問題を探します。

Google Cloud コンソール

  1. 次のコマンドを入力してコピーします。
  2. gcpdiag runbook gce/ssh --project=PROJECT_ID \
        --parameter name=VM_NAME \
        --parameter zone=ZONE \
        --parameter principal=PRINCIPAL \
        --parameter tunnel_through_iap=IAP_ENABLED
  3. Google Cloud コンソールを開き、Cloud Shell をアクティブにします。
  4. Cloud コンソールを開く
  5. コピーしたコマンドを貼り付けます。
  6. gcpdiag コマンドを実行します。gcpdiag Docker イメージがダウンロードされ、診断チェックが実行されます。必要に応じて、出力の指示に沿って、失敗したチェックを修正します。

Docker

Docker コンテナで gcpdiag を起動するラッパーを使用して gcpdiag を実行できます。Docker または Podman がインストールされている必要があります。

  1. ローカル ワークステーションに次のコマンドをコピーして実行します。
    curl https://gcpdiag.dev/gcpdiag.sh >gcpdiag && chmod +x gcpdiag
  2. gcpdiag コマンドを実行します。
    ./gcpdiag runbook gce/ssh --project=PROJECT_ID \
        --parameter name=VM_NAME \
        --parameter zone=ZONE \
        --parameter principal=PRINCIPAL \
        --parameter tunnel_through_iap=IAP_ENABLED

このランブックで使用可能なパラメータを表示します。

次のように置き換えます。

  • PROJECT_ID: リソースを含むプロジェクトの ID。
  • VM_NAME: プロジェクト内のターゲット VM の名前。
  • ZONE: ターゲット VM が配置されているゾーン。
  • PRINCIPAL: SSH 接続を開始するユーザーまたはサービス アカウント プリンシパル。鍵ベースの認証では、Cloud Shell コマンドライン ツールで認証されたユーザー、または Google Cloud コンソールにログインしたユーザーを使用します。サービス アカウントの権限借用の場合は、サービス アカウントのメールアドレスにする必要があります。
  • IAP_ENABLED: SSH 接続の確立に Identity-Aware Proxy が使用されるかどうかを示すブール値(true または false)。デフォルト: true

有用なフラグ:

gcpdiag ツールのフラグの一覧と説明については、gcpdiag の使用手順をご覧ください。

次のステップ