インスタンスで実行するアプリでは、サービス アカウントを介して Google Cloud APIs を操作できます。サービス アカウントに適切な Compute Engine IAM のロールがあれば、アプリのコードから特定の API リクエストを実行できます。
サービス アカウントについては、サービス アカウントの概要をご覧ください。
始める前に
- このガイドのコマンドラインの例を使用する場合、以下を行ってください。
- gcloud コマンドライン ツールの最新バージョンをインストールするか、最新バージョンに更新します。
- デフォルトのリージョンとゾーンを設定します。
- このガイドの API の例を使用する場合、API アクセスを設定します。
- サービス アカウントの概要をご覧ください。
新しいサービス アカウントの作成
IAM を使用して新しいサービス アカウントを作成し、設定できます。アカウントを作成した後で、1 つ以上の IAM のロールをアカウントに付与し、そのサービス アカウントとして実行する仮想マシン インスタンスを承認します。
新しいサービス アカウントを作成するには:
サービス アカウントの作成の説明に従って、新しいサービス アカウントを作成します。
サービス アカウントのメールアドレスを取得します。このサービス アカウントとして実行するインスタンスを設定するには、メールアドレスが必要です。次の手順に従って、Console でサービス アカウントのメールアドレスを確認します。
- Cloud Console の [サービス アカウント] ページに移動します。
- プロンプトが表示されたら、プロジェクトを選択します。
- 新しいサービス アカウントを探し、サービス アカウントのメールアドレスをメモします。
通常、サービス アカウントのメールアドレスは、次の形式でサービス アカウント ID から取得されます。
[SERVICE-ACCOUNT-NAME]@[PROJECT_ID].iam.gserviceaccount.com
サービス アカウントに IAM のロールを付与します。役割を付与しないと、サービス アカウントがサービスにアクセスできなくなります。IAM のロールの一覧については、IAM ドキュメントのロールについてをご覧ください。
次に、サービス アカウントとして実行するようにインスタンスを設定します。手順に従い、サービス アカウントとして実行するようにインスタンスを設定します。
新しいインスタンスをサービス アカウントとして実行するように設定する
新しいサービス アカウントを作成したら、サービス アカウントとして実行する新しい仮想マシン インスタンスを作成できます。サービス アカウントの既存インスタンスへの割り当てや変更を行う場合は、インスタンスのサービス アカウントとアクセス スコープを変更するをご覧ください。
同じサービス アカウントを複数の仮想マシン インスタンスで使用できますが、1 つの仮想マシン インスタンスに設定できるサービス アカウント ID は 1 つだけです。同じサービス アカウントを複数の仮想マシン インスタンスに割り当てた場合、それ以降そのサービス アカウントに行った変更は、そのサービス アカウントを使用しているすべてのインスタンスに影響します。これには、そのサービス アカウントに付与されている IAM の役割に加えた変更も含まれます。たとえば、ロールを削除した場合、そのサービス アカウントを使用しているすべてのインスタンスは、そのロールによって付与されている権限を失います。
通常は、cloud-platform
アクセス スコープを設定してすべての Cloud APIs に対する完全アクセス権を付与してから、関連する IAM ロールのみをサービス アカウントに付与できます。仮想マシン インスタンスに付与したアクセス スコープとサービス アカウントに付与されている IAM ロールの組み合わせにより、インスタンスでサービス アカウントに許可されるアクセスのレベルが決まります。サービス アカウントで API メソッドを実行できるのは、アクセス スコープと IAM ロールの両方で許可されている場合に限ります。
または、サービスが呼び出す特定の API メソッドへのアクセスを許可する特定のスコープの設定を選択できます。たとえば、instances.insert
メソッドを呼び出すには、https://www.googleapis.com/auth/compute
スコープまたは https://www.googleapis.com/auth/cloud-platform
スコープを対象とした承認と、このメソッドへのアクセス権を付与する IAM ロールが必要です。cloud-platform
スコープの代わりに compute
スコープを設定できます。これにより、Compute Engine 内部のメソッドを呼び出すためのサービス アクセスが付与されますが、Compute Engine の外部の API メソッドを呼び出すためのアクセスは付与されません。
サービス アカウントとして実行する新しいインスタンスを設定するには、Google Cloud Console または gcloud
コマンドライン ツールを使用します。また、API で直接設定することもできます。
Console
- Cloud Console で、[VM インスタンス] ページに移動します。
- [インスタンスを作成] をクリックします。
- [新しいインスタンスの作成] ページで、インスタンスのプロパティを入力します。
- [ID と API へのアクセス] セクションで、使用するサービス アカウントをプルダウン リストから選択します。
- [作成] をクリックしてインスタンスを作成します。
gcloud
gcloud
コマンドライン ツールを使用して、新しいインスタンスを作成し、カスタム サービス アカウントとして実行することを承認するには、サービス アカウントのメールアドレスとインスタンスに必要なアクセス スコープを指定します。
gcloud compute instances create [INSTANCE_NAME] \
--service-account [SERVICE_ACCOUNT_EMAIL] \
--scopes [SCOPES,...]
ここで
[SERVICE_ACCOUNT_EMAIL]
は、使用するサービス アカウントのメールアドレスです。たとえば、my-sa-123@my-project-123.iam.gserviceaccount.com
です。メールアドレスがわからない場合は、サービス アカウントのメールアドレスの取得方法をご覧ください。[INSTANCE_NAME]
はインスタンス名です。[SCOPES]
は、完全なスコープ URI または--scopes
フラグの説明にあるスコープ エイリアスのカンマ区切りのリストです。
例:
gcloud compute instances create example-vm \
--service-account 123-my-sa@my-project-123.iam.gserviceaccount.com \
--scopes https://www.googleapis.com/auth/cloud-platform
gcloud
ツールは、長いスコープ URI の代わりになるスコープ エイリアスも提供します。たとえば、Cloud Storage への完全アクセス権のスコープは https://www.googleapis.com/auth/devstorage.full_control
です。このスコープのエイリアスは storage-full
です。
スコープとスコープ エイリアスの一覧については、instances create
ページの --scopes
フラグの説明をご覧ください。instances create
コマンドのヘルプでも、これらのスコープとエイリアスの一覧が記載されています。
gcloud compute instances create --help
エイリアスは、通常のスコープ URI の場合と同じ方法で指定します。例を次に示します。
gcloud compute instances create [INSTANCE_NAME] \
--service-account [SERVICE_ACCOUNT_EMAIL] \
--scopes cloud-platform
API
API では、インスタンスを作成するための標準のリクエストを作成しますが、これに serviceAccounts
プロパティを含めます。インスタンスのアクセス スコープに合わせて、サービス アカウントのメールアドレスを取得して、email
プロパティに含めます。
POST https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances { "machineType": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/machineTypes/[MACHINE_TYPE]", "name": "[INSTANCE_NAME]", "serviceAccounts": [ { "email": "[SERVICE_ACCOUNT_EMAIL]", "scopes": ["https://www.googleapis.com/auth/cloud-platform"] } ], ... }
サービス アカウントとして走行するインスタンスを設定すると、次のような方法でインスタンス内からサービス アカウントの認証情報を使用できます。
- アプリケーションのデフォルト認証情報とクライアント ライブラリを使用すると、アプリケーションを簡単に認証できます。
- アプリケーション内で直接アクセス トークンをリクエストして使用します。
gcloud
やgsutil
コマンドを使用します。両コマンドは、サービス アカウントと有効なスコープを自動的に認識して使います。
サービス アカウントの認証情報を使用したアプリケーションの認証
サービス アカウントとして実行するようにインスタンスを設定した後で、サービス アカウントの認証情報を使用してインスタンス上で実行するアプリケーションを承認できます。
クライアント ライブラリを使用したアプリケーションの認証
クライアント ライブラリは、Google API で認証するために、アプリケーションのデフォルト認証情報を使用し、それらの API にリクエストを送信できます。アプリケーションは、アプリケーションのデフォルト認証情報により、複数のソースから認証情報を取得できるため、アプリケーションをローカルでテストできます。テスト後は、アプリケーション コードを変更することなく、Compute Engine インスタンスにデプロイできます。アプリケーションをローカルで開発する際に、環境変数や Cloud SDK を使用してアプリケーションを認証できます。アプリケーションをインスタンス上で実行する場合は、そのインスタンスで有効になっているサービス アカウントを使用してアプリケーションを認証できます。
この例では、Python クライアント ライブラリを使用して認証を行い、プロジェクト内のバケットの一覧表示を行う Cloud Storage API にリクエストを行います。これは、次の手順により行います。
- Cloud Storage API に必要な認証情報を取得し、
build()
メソッドと認証情報を使用して Cloud Storage サービスを初期化します。 - Cloud Storage 内のバケットを一覧表示します。
このサンプルは、Cloud Storage 内のバケットを管理するためのアクセス権を持つインスタンスで実行できます。
アクセス トークンを使用したアプリケーション ディレクトリの認証
一部のアプリケーションでは、OAuth2 アクセス トークンをリクエストして、クライアント ライブラリを介さずにそのアクセス トークンを直接使用するか、または、gcloud
ツールや gsutil
ツールを使用する必要が生じる場合があります。アプリケーションを認証するために、これらのアクセス トークンを取得して使用する方法は複数あります。たとえば、curl
を使用してシンプルなリクエストを作成することや、Python などのプログラミング言語を使用して柔軟性を高めることが可能です。
cURL
curl
を使用してアクセス トークンをリクエストして、API にリクエストを送信するには:
アプリケーションが実行するインスタンス上で、次のコマンドによってアクセス トークンのメタデータ サーバーをクエリします。
$ curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \ -H "Metadata-Flavor: Google"
その結果、次のようなレスポンスが得られます。
{ "access_token":"ya29.AHES6ZRN3-HlhAPya30GnW_bHSb_QtAS08i85nHq39HE3C2LTrCARA", "expires_in":3599, "token_type":"Bearer" }
レスポンスから
access_token
プロパティの値をコピーし、その値を使用して API にリクエストを送信します。たとえば、次のリクエストでは、特定のゾーンからプロジェクト内のインスタンスのリストが出力されます。$ curl https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances \ -H "Authorization":"Bearer [ACCESS_TOKEN]"
ここで
[PROJECT_ID]
は、このリクエストのプロジェクト ID です。[ZONE]
は、インスタンスのリスト元のゾーンです。[ACCESS_TOKEN]
は、ステップ 1 で取得したアクセス トークンの値です。
リクエストに設定可能なパラメータの詳細については、パラメータのドキュメントを参照してください。
Python
この例では、Python アプリケーションで Cloud Storage API にアクセスするためにトークンをリクエストする方法を示します。これは、次の手順により行います。
- メタデータ サーバーのアクセス トークンをリクエストします。
- サーバーのレスポンスからアクセス トークンを取り出します。
- アクセス トークンを使用して Cloud Storage にリクエストを行います。
- リクエストが成功した場合、スクリプトによってレスポンスが出力されます。
アクセス トークンは短期間で失効します。メタデータ サーバーは、失効までの残り時間が 60 秒になるまで、アクセス トークンをキャッシュに保存します。新しいトークンは必要に応じてリクエストできますが、アプリケーションには API 呼び出しが成功するための有効なアクセス トークンが必要です。
サービス アカウントを使用してインスタンス上のツールを承認する
一部のアプリケーションでは、Compute Engine の大部分のイメージにデフォルトで含まれている gcloud
ツールや gsutil
ツールのコマンドが使用されることがあります。これらのツールは、インスタンスのサービス アカウントとそのアカウントに付与されている関連の権限を自動的に認識します。特に、サービス アカウントに正しいロールを付与すると、gcloud auth login
を使用せずに、インスタンスから gcloud
と gsutil
ツールを使用できます。
サービス アカウントの認識は自動的に行われ、インスタンスに含まれている gcloud
および gsutil
ツールにのみ適用されます。新しいツールを作成する場合や、カスタムツールを追加する場合は、クライアント ライブラリを使用するか、アプリケーション内で直接アクセス トークンを使用して、アプリケーションを承認する必要があります。
サービス アカウントの自動認識を利用するには、サービス アカウントに適切な IAM のロールを付与し、サービス アカウントとして実行されるようにインスタンスを設定します。たとえば、サービス アカウントに roles/storage.objectAdmin
の役割を付与すると、gsutil
ツールで、Cloud Storage のオブジェクトを自動的に管理してアクセスできます。
同様に、サービス アカウントに対して roles/compute.instanceAdmin.v1
を有効にすると、gcloud compute
ツールでインスタンスを自動管理できます。
インスタンスのサービス アカウントとアクセス スコープを変更する
VM を別の ID として実行する場合や、必要な API を呼び出すためインスタンスに別のスコープセットが必要であると判断した場合は、既存のインスタンスのサービス アカウントとアクセス スコープを変更できます。たとえば、アクセス スコープを変更して新しい API へのアクセスを許可したり、インスタンスを変更して Compute Engine のデフォルトのサービス アカウントとしてではなく作成したサービス アカウントとして実行したりできます。
インスタンスのサービス アカウントまたはアクセス スコープを変更する場合、インスタンスを一時的に停止する必要があります。インスタンスを停止する方法については、インスタンスの停止のドキュメントをご覧ください。サービス アカウントまたはアクセス スコープを変更した後、インスタンスを再起動してください。次のいずれかの方法で、停止したインスタンスのサービス アカウントまたはアクセス スコープを変更します。
Console
- Compute Engine で [VM インスタンス] ページに移動します。
- サービス アカウントを変更する VM インスタンスの名前をクリックします。
- インスタンスが停止していない場合には、[停止] ボタンをクリックします。インスタンスが停止するまで待機します。
- 次に、[編集] ボタンをクリックします。
- 下にスクロールして、[サービス アカウント] セクションに移動します。
- プルダウン メニューから、必要なサービス アカウントを選択します。
- スコープを変更するには、[アクセス スコープ] セクションで、必要に応じて適切なスコープを設定します。ベスト プラクティスとして、VM インスタンスに必要なアクセス スコープのみを指定します。設定する適切なアクセス スコープがわからない場合は、[すべての Cloud API に完全アクセス権を許可] を選択してから、IAM の役割を設定してアクセスを制限してください。
- [保存] ボタンをクリックして変更を保存します。
gcloud
コマンド instances set-service-account
を使用して、インスタンス名、サービス アカウントのメールアドレス、必要なスコープを指定します。インスタンスからサービス アカウントとアクセス スコープを削除することもできます。これにより、インスタンスが Google Cloud サービスにアクセスするのを効率的に回避できます。
gcloud compute instances set-service-account [INSTANCE_NAME] \
[--service-account [SERVICE_ACCOUNT_EMAIL] | --no-service-account] \
[--no-scopes | --scopes [SCOPES,...]]
ここで
[SERVICE_ACCOUNT_EMAIL]
は、使用するサービス アカウントのメールアドレスです。たとえば、my-sa-123@my-project-123.iam.gserviceaccount.com
です。[INSTANCE_NAME]
はインスタンス名です。[SCOPES]
は、完全なスコープ URI または--scopes
フラグの説明にあるスコープ エイリアスのカンマ区切りのリストです。インスタンスのスコープをすべて削除するには、--no-scopes
フラグを使用します。
たとえば、次のコマンドを実行すると、example-instance というインスタンスにサービス アカウント my-sa-123@my-project-123.iam.gserviceaccount.com
が割り当てられ、このインスタンスに Compute Engine に対する読み取り / 書き込みアクセスと Cloud Storage に対する読み取り専用アクセスを許可するアクセス スコープが設定されます。
gcloud compute instances set-service-account example-instance \
--service-account my-sa-123@my-project-123.iam.gserviceaccount.com \
--scopes compute-rw,storage-ro
API
API で、setServiceAccount
メソッドに対する POST
リクエストを行います。
https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]/setServiceAccount
ここで
[PROJECT_ID]
は、このリクエストのプロジェクト ID です。[ZONE]
は、このインスタンスが属するゾーンです。[INSTANCE_NAME]
はインスタンス名です。
リクエストの本文で、サービス アカウントのメールアドレスとインスタンスに必要なスコープ URI を指定します。
{
"email": "[SERVICE_ACCOUNT_EMAIL]",
"scopes": [
"[SCOPE_URI]",
"[SCOPE_URI]",
...
]
}
たとえば、次のリクエストではサービス アカウントのメールアドレス my-sa-123@my-project-123.iam.gserviceaccount.com
を使用して、Cloud Storage と BigQuery のスコープを設定しています。
{
"email": "my-sa-123@my-project-123.iam.gserviceaccount.com",
"scopes": [
"https://www.googleapis.com/auth/bigquery",
"https://www.googleapis.com/auth/devstorage.read_only"
]
}
サービス アカウントのメールアドレスの取得
サービス アカウントを識別するには、サービス アカウントのメールアドレスが必要です。サービス アカウントのメールアドレスは、次のいずれかの方法を使用して取得します。
Console
- Cloud Console の [サービス アカウント] ページに移動します。
- プロンプトが表示されたら、プロジェクトを選択します。[サービス アカウント] ページに、そのプロジェクトのすべてサービス アカウントとメールアドレスが一覧表示されます。
gcloud
ローカルマシンで、gcloud compute instances describe
コマンドを使用します。
gcloud compute instances describe [INSTANCE_NAME] --format json
{ ... "serviceAccounts":[ { "email":"123845678986-compute@developer.gserviceaccount.com", "scopes":[ "https://www.googleapis.com/auth/devstorage.full_control" ] } ] ... }
インスタンスがサービス アカウントを使用していない場合、serviceAccounts
プロパティのないレスポンスを受信します。
メタデータ サーバー
インスタンス内からメタデータ サーバーをクエリします。次のように http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/
にリクエストします。
user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/" \
-H "Metadata-Flavor: Google"
インスタンスの作成時に 1 つ以上のサービス アカウントを有効にしている場合、この curl
コマンドを実行すると、次のような出力が返されます。
123845678986-compute@developer.gserviceaccount.com/
default/
インスタンスがサービス アカウントを使用していない場合、空のレスポンスが返されます。
API
サービス アカウント API にリクエストを行います。
Compute Engine のデフォルトのサービス アカウントの使用
Compute Engine のデフォルトのサービス アカウントに関する詳しい知識があり、新しいサービス アカウントを作成する代わりにデフォルトのサービス アカウントによって提供される認証情報を使用する場合は、IAM の役割をデフォルトのサービス アカウントに付与できます。
デフォルトでは、すべての Compute Engine インスタンスは、デフォルトのサービス アカウントとして実行できます。gcloud
コマンドライン ツールまたは Cloud Console を使用してインスタンスを作成し、サービス アカウントの指定を省略した場合は、デフォルトのサービス アカウントがそのインスタンスに割り当てられます。
デフォルトのサービス アカウントに IAM の役割を付与する前に、次の点を確認してください。
IAM の役割をデフォルトのサービス アカウントに付与すると、デフォルトのサービス アカウントとして実行中のすべてのインスタンスに影響を及ぼします。たとえば、デフォルトのサービス アカウントに
roles/storage.objectAdmin
の役割を付与すると、必要なアクセス スコープが指定されたデフォルトのサービス アカウントとして実行しているすべてのインスタンスがroles/storage.objectAdmin
の役割によって付与される権限を持ちます。同様に、特定の役割を省略してアクセス権限を制限すると、デフォルトのサービス アカウントとして実行中のすべてのインスタンスに影響を及ぼします。サービス アカウントのプロジェクト編集者の権限は取り消す必要があります。デフォルトのサービス アカウントは、デフォルトでプロジェクト編集者としてプロジェクトに追加されます。IAM のロールを使用するには、プロジェクト編集者の権限を取り消す必要があります。
デフォルトのサービス アカウントに IAM ロールを付与すべきかどうか判断できない場合は、代わりに新しいサービス アカウントを作成します。
IAM の役割をデフォルトのサービス アカウントに付与するには、次の手順に従います。
- Cloud Console の IAM ページに移動します。
- プロンプトが表示されたら、プロジェクトを選択します。
- Compute Engine のデフォルトのサービス アカウントという名前のサービス アカウントを探します。
- [役割] 列で、Compute Engine のデフォルトのサービス アカウントのプルダウン メニューを展開します。
- 編集者のアクセス権を削除して、変更を保存します。
- 次に、サービス アカウントに IAM のロールを付与します。
現在デフォルトのサービス アカウントとして実行しているすべての仮想マシン インスタンスが、アカウントに付与した IAM の役割に従って他の Google Cloud API にアクセスできるようになります。
デフォルトのサービス アカウントとして実行する新しいインスタンスを設定する場合の手順は次のとおりです。
Console
- Cloud Console で、[VM インスタンス] ページに移動します。
- [インスタンスを作成] をクリックします。
- [新しいインスタンスの作成] ページで、インスタンスのプロパティを入力します。
- [ID と API へのアクセス] セクションで、プルダウン リストから [Compute Engine のデフォルトのサービス アカウント] を選択します。
- [作成] をクリックしてインスタンスを作成します。
gcloud
新しいインスタンスを作成し、そのインスタンスがデフォルトのサービス アカウントを使用してすべての Google Cloud サービスに対する完全アクセス権を持つことを承認するには、次のコマンドを使用します。
gcloud compute instances create [INSTANCE_NAME] \
--scopes cloud-platform
API
API では、インスタンスを作成するための標準のリクエストを作成しますが、これに serviceAccounts
プロパティを含めます。デフォルトのサービス アカウント ID を取得し、サービス アカウントの email
として指定します。次に、scopes
プロパティにスコープを少なくとも 1 つ設定します。
POST https://compute.googleapis.com/compute/v1/projects/zones/[ZONE]/instances { "machineType": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/machineTypes/[MACHINE_TYPE]", "name": "[INSTANCE_NAME]", "serviceAccounts": [ { "email": "[DEFAULT_SERVICE_ACCOUNT_EMAIL]", "scopes": ["https://www.googleapis.com/auth/cloud-platform"] } ], ... }
ベスト プラクティス
インスタンスで Google API を呼び出す必要がある場合、Google では、そのジョブの実行に必要な最低限の権限のみを持つサービス アカウントとしてインスタンスを実行することをおすすめしています。次のプロセスでインスタンスのサービス アカウントを構成してください。
- Compute Engine のデフォルトのサービス アカウントを使用せずに、新しいサービス アカウントを作成します。
- 必要なリソースについてのみ、このサービス アカウントに IAM 役割を付与します。
- このサービス アカウントとして走行するようにインスタンスを構成します。
- インスタンスに
https://www.googleapis.com/auth/cloud-platform
スコープを付与して、すべての Google Cloud APIs への完全アクセス権を許可します。これにより、インスタンスの IAM 権限は、インスタンスのサービス アカウントに付与した IAM ロールによって完全に決定されます。サービス アカウントは、アクセス スコープとサービス アカウント固有の IAM ロールで許可されている API メソッドのみを実行できます。
必要以上のロールを付与しないように、サービス アカウントの権限を定期的に確認し、最新の状態にしてください。
サービス アカウントの削除は慎重に行ってください。サービス アカウントを削除する前に、重要なアプリケーションがそのサービス アカウントを使用していないことを確認してください。サービス アカウントが使用されているかどうかわからない場合は、削除するのではなく、サービス アカウントを無効にすることをおすすめします。無効になっているサービス アカウントがまだ必要である場合は、再度有効にすることができます。
次のステップ
- サービス アカウントの詳細を確認する。
- Compute Engine IAM のロールの詳細を確認する。