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

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

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

準備

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

Select the tab for how you plan to use the samples on this page:
Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
1. Install the Google Cloud CLI, then initialize it by running the following command:
  gcloud init
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.

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

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 時間かかります。

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

削除したアカウントを復元する。
アカウントを削除する前に、アカウントの POSIX 情報を削除する。

無効な引数

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.

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

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

gcloud compute os-login describe-profile

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

name: '00000000000000'
posixAccounts:
...
sshPublicKeys:
 ...:
   fingerprint: ...
   key: |
     ssh-rsa AAAAB3NzaC1yc2...
   name: ...
 ...

出力を確認して、未使用の SSH 認証鍵を特定します。
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 ユーザーのプロファイル情報を取得します。`username`、`uid`、`pagesize`、`pagetoken` などのクエリパラメータを渡すことができます。
`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 パラメータを指定する必要があります。pagesize と pagetoken は必要な数値に置き換えます。

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

たとえば、pagesize を 1 に設定し、pagetoken を 0 に設定するには、次のコマンドを実行します。

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 username や getent passwd uid などの Unix コマンドを実行してプロファイル情報を取得できます。

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

ログイン権限の確認

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

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

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

出力で、name をメモします。

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 コンソール

次のコマンドを入力してコピーします。

gcpdiag runbook gce/ssh --project=PROJECT_ID \
    --parameter name=VM_NAME \
    --parameter zone=ZONE \
    --parameter principal=PRINCIPAL \
    --parameter tunnel_through_iap=IAP_ENABLED

Google Cloud コンソールを開き、Cloud Shell をアクティブにします。

Cloud コンソールを開く

コピーしたコマンドを貼り付けます。
gcpdiag コマンドを実行します。gcpdiag Docker イメージがダウンロードされ、診断チェックが実行されます。必要に応じて、出力の指示に沿って、失敗したチェックを修正します。

Docker

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

ローカルワークステーションで次のコマンドをコピーして実行します。
```
curl https://gcpdiag.dev/gcpdiag.sh >gcpdiag && chmod +x gcpdiag
```

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

有用なフラグ:

--project: PROJECT_ID
--universe-domain: 該当する場合、リソースをホストする信頼できるパートナーのソブリンクラウドドメイン
--parameter または -p: ランブックパラメータ

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

次のステップ

OS Login の詳細を確認する。
Compute Engine での Linux VM への SSH 接続の仕組みを学習する。
手順については、次のいずれかをご覧ください。
- OS Login の設定。
- 2 段階認証プロセスを使用した OS Login の設定
組織での OS Login の管理を確認する。

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

準備

Console

gcloud

REST

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

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

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

前提条件でのエラー

無効な引数

HTTP レスポンス コード: 503

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

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

OS Login ユーザーの表示

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

ログイン権限の確認

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

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

Google Cloud コンソール

Docker

次のステップ

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

HTTP レスポンスコード: 503

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

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