Cloud Audit Logs チュートリアル

前提条件

1. Google Cloud Console で [IAM と管理] > [監査ログ] ページを開きます。

   [IAM と管理] > [監査ログ] ページに移動

2. Compute Engine API で、Cloud Audit Logs の管理読み取り、データ読み取り、データ書き込みの各ログタイプを有効にします。

   

3. Compute Engine サービス アカウントに Editor ロールがあるかどうかを確認します。このサービス アカウントは、Cloud Run functions のサービス ID として使用されます。

   [IAM と管理] > [IAM] ページに移動します

   テーブルで PROJECT_NUMBER-compute@developer.gserviceaccount.com エントリを見つけて、Roles 列を確認します。列に Editor が含まれている場合は、次の手順をスキップできます。それ以外の場合は、次の手順に進んで、必要なロールをサービス アカウントに割り当てます。

4. プロジェクトの Compute Engine サービス アカウントに eventarc.eventReceiver ロールを付与します。

   PROJECT_ID=$(gcloud config get-value project)
   PROJECT_NUMBER=$(gcloud projects list --filter="project_id:$PROJECT_ID" --format='value(project_number)')
   
   # Allow service account token creation
   gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role roles/eventarc.eventReceiver
   

5. Pub/Sub トリガーが関数を実行できるように、プロジェクトの Compute Engine サービス アカウントに run.invoker ロールを付与します。

   PROJECT_ID=$(gcloud config get-value project)
   PROJECT_NUMBER=$(gcloud projects list --filter="project_id:$PROJECT_ID" --format='value(project_number)')
   
   # Allow service account token creation
   gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role roles/run.invoker
   

6. プロジェクトの Compute Engine サービス アカウントに compute.instanceAdmin ロールを付与して、VM インスタンスを取得してラベルを設定するために必要な権限を関数コードに付与します。

   PROJECT_ID=$(gcloud config get-value project)
   PROJECT_NUMBER=$(gcloud projects list --filter="project_id:$PROJECT_ID" --format='value(project_number)')
   
   # Allow service account token creation
   gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role roles/compute.instanceAdmin
   

アプリケーションの準備

1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。

   Node.js

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

   または、zip 形式のサンプルをダウンロードし、ファイルを抽出してもかまいません。

   Python

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

   または、zip 形式のサンプルをダウンロードし、ファイルを抽出してもかまいません。

   Go

   git clone https://github.com/GoogleCloudPlatform/golang-samples.git

   または、zip 形式のサンプルをダウンロードし、ファイルを抽出してもかまいません。

   Java

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

   または、zip 形式のサンプルをダウンロードしてファイルを抽出してもかまいません。

2. Cloud Audit Logs にアクセスするための Cloud Run functions のサンプルコードがあるディレクトリに移動します。

   Node.js

   cd nodejs-docs-samples/functions/v2/autoLabelInstance/

   Python

   cd python-docs-samples/functions/v2/label_gce_instance/

   Go

   cd golang-samples/functions/functionsv2/label_gce_instance/

   Java

   cd java-docs-samples/functions/v2/label-compute-instance/

3. サンプルコードを見てみましょう。

   Node.js

   const functions = require('@google-cloud/functions-framework');
   
   const compute = require('@google-cloud/compute');
   const instancesClient = new compute.InstancesClient();
   
   // Register a CloudEvent callback with the Functions Framework that labels
   // newly-created GCE instances with the entity (person or service account)
   // that created them.
   functions.cloudEvent('autoLabelInstance', async cloudEvent => {
     // Extract parameters from the CloudEvent + Cloud Audit Log data
     const payload = cloudEvent.data && cloudEvent.data.protoPayload;
     const authInfo = payload && payload.authenticationInfo;
     let creator = authInfo && authInfo.principalEmail;
   
     // Get relevant VM instance details from the CloudEvent's `subject` property
     // Example value:
     //   compute.googleapis.com/projects/<PROJECT>/zones/<ZONE>/instances/<INSTANCE>
     const params = cloudEvent.subject && cloudEvent.subject.split('/');
   
     // Validate data
     if (!creator || !params || params.length !== 7) {
       throw new Error('Invalid event structure');
     }
   
     // Format the 'creator' parameter to match GCE label validation requirements
     creator = creator.toLowerCase().replace(/\W/g, '_');
   
     // Get the newly-created VM instance's label fingerprint
     // This is required by the Compute Engine API to prevent duplicate labels
     const getInstanceRequest = {
       project: params[2],
       zone: params[4],
       instance: params[6],
     };
     const [instance] = await instancesClient.get(getInstanceRequest);
   
     // Label the instance with its creator
     const setLabelsRequest = Object.assign(
       {
         instancesSetLabelsRequestResource: {
           labels: {creator},
           labelFingerprint: instance.labelFingerprint,
         },
       },
       getInstanceRequest
     );
   
     return instancesClient.setLabels(setLabelsRequest);
   });

   Python

   import re
   
   from google.api_core.exceptions import GoogleAPIError
   from google.cloud import compute_v1
   from google.cloud.compute_v1.types import compute
   
   instances_client = compute_v1.InstancesClient()
   
   
   # CloudEvent function that labels newly-created GCE instances
   # with the entity (user or service account) that created them.
   #
   # @param {object} cloudevent A CloudEvent containing the Cloud Audit Log entry.
   # @param {object} cloudevent.data.protoPayload The Cloud Audit Log entry.
   def label_gce_instance(cloudevent):
       # Extract parameters from the CloudEvent + Cloud Audit Log data
       payload = cloudevent.data.get("protoPayload", dict())
       auth_info = payload.get("authenticationInfo", dict())
       creator = auth_info.get("principalEmail")
   
       # Get relevant VM instance details from the cloudevent's `subject` property
       # Example value:
       #   compute.googleapis.com/projects/<PROJECT_ID>/zones/<ZONE_ID>/instances/<INSTANCE_NAME>
       instance_params = cloudevent["subject"].split("/")
   
       # Validate data
       if not creator or not instance_params or len(instance_params) != 7:
           # This is not something retries will fix, so don't throw an Exception
           # (Thrown exceptions trigger retries *if* you enable retries in GCF.)
           print("ERROR: Invalid `principalEmail` and/or CloudEvent `subject`.")
           return
   
       instance_project = instance_params[2]
       instance_zone = instance_params[4]
       instance_name = instance_params[6]
   
       # Format the 'creator' parameter to match GCE label validation requirements
       creator = re.sub("\\W", "_", creator.lower())
   
       # Get the newly-created VM instance's label fingerprint
       # This is required by the Compute Engine API to prevent duplicate labels
       instance = instances_client.get(
           project=instance_project, zone=instance_zone, instance=instance_name
       )
   
       # Construct API call to label the VM instance with its creator
       request_init = {
           "project": instance_project,
           "zone": instance_zone,
           "instance": instance_name,
       }
       request_init[
           "instances_set_labels_request_resource"
       ] = compute.InstancesSetLabelsRequest(
           label_fingerprint=instance.label_fingerprint, labels={"creator": creator}
       )
       request = compute.SetLabelsInstanceRequest(request_init)
   
       # Perform instance-labeling API call
       try:
           instances_client.set_labels_unary(request)
           print(f"Labelled VM instance {instance_name} with creator: {creator}")
       except GoogleAPIError as e:
           # Swallowing the exception means failed invocations WON'T be retried
           print("Label operation failed", e)
   
           # Uncomment the line below to retry failed invocations.
           # (You'll also have to enable retries in Cloud Functions itself.)
           # raise e
   
       return
   
   

   Go

   
   // Package helloworld provides a set of Cloud Functions samples.
   package helloworld
   
   import (
   	"context"
   	"fmt"
   	"log"
   	"regexp"
   	"strings"
   
   	compute "cloud.google.com/go/compute/apiv1"
   	"cloud.google.com/go/compute/apiv1/computepb"
   	"github.com/GoogleCloudPlatform/functions-framework-go/functions"
   	"github.com/cloudevents/sdk-go/v2/event"
   	"google.golang.org/protobuf/proto"
   )
   
   // AuditLogEntry represents a LogEntry as described at
   // https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry
   type AuditLogEntry struct {
   	ProtoPayload *AuditLogProtoPayload `json:"protoPayload"`
   }
   
   // AuditLogProtoPayload represents AuditLog within the LogEntry.protoPayload
   // See https://cloud.google.com/logging/docs/reference/audit/auditlog/rest/Shared.Types/AuditLog
   type AuditLogProtoPayload struct {
   	MethodName         string                 `json:"methodName"`
   	ResourceName       string                 `json:"resourceName"`
   	AuthenticationInfo map[string]interface{} `json:"authenticationInfo"`
   }
   
   var client *compute.InstancesClient
   
   func init() {
   	// Create an Instances Client
   	var err error
   	client, err = compute.NewInstancesRESTClient(context.Background())
   	if err != nil {
   		log.Fatalf("Failed to create instances client: %s", err)
   	}
   
   	functions.CloudEvent("label-gce-instance", labelGceInstance)
   }
   
   // Cloud Function that receives GCE instance creation Audit Logs, and adds a
   // `creator` label to the instance.
   func labelGceInstance(ctx context.Context, ev event.Event) error {
   	// Extract parameters from the Cloud Event and Cloud Audit Log data
   	logentry := &AuditLogEntry{}
   	if err := ev.DataAs(logentry); err != nil {
   		err = fmt.Errorf("event.DataAs() : %w", err)
   		log.Printf("Error parsing proto payload: %s", err)
   		return err
   	}
   	payload := logentry.ProtoPayload
   	creator, ok := payload.AuthenticationInfo["principalEmail"]
   	if !ok {
   		err := fmt.Errorf("principalEmail not found in cloud event payload: %v", payload)
   		log.Printf("creator email not found: %s", err)
   		return err
   	}
   
   	// Get relevant VM instance details from the event's `subject` property
   	// Subject format:
   	// compute.googleapis.com/projects/<PROJECT>/zones/<ZONE>/instances/<INSTANCE>
   	paths := strings.Split(ev.Subject(), "/")
   	if len(paths) < 6 {
   		return fmt.Errorf("invalid event subject: %s", ev.Subject())
   	}
   	project := paths[2]
   	zone := paths[4]
   	instance := paths[6]
   
   	// Sanitize the `creator` label value to match GCE label requirements
   	// See https://cloud.google.com/compute/docs/labeling-resources#requirements
   	labelSanitizer := regexp.MustCompile("[^a-z0-9_-]+")
   	creatorstring := labelSanitizer.ReplaceAllString(strings.ToLower(creator.(string)), "_")
   
   	// Get the newly-created VM instance's label fingerprint
   	// This is a requirement of the Compute Engine API and avoids duplicate labels
   	inst, err := client.Get(ctx, &computepb.GetInstanceRequest{
   		Project:  project,
   		Zone:     zone,
   		Instance: instance,
   	})
   	if err != nil {
   		err = fmt.Errorf("could not retrieve GCE instance: %s", err)
   		log.Print(err)
   		return err
   	}
   	if v, ok := inst.Labels["creator"]; ok {
   		// Instance already has a creator label.
   		log.Printf("instance %s already labeled with creator: %s", instance, v)
   		return nil
   	}
   
   	// Add the creator label to the instance
   	op, err := client.SetLabels(ctx, &computepb.SetLabelsInstanceRequest{
   		Project:  project,
   		Zone:     zone,
   		Instance: instance,
   		InstancesSetLabelsRequestResource: &computepb.InstancesSetLabelsRequest{
   			LabelFingerprint: proto.String(inst.GetLabelFingerprint()),
   			Labels: map[string]string{
   				"creator": creatorstring,
   			},
   		},
   	})
   	if err != nil {
   		log.Fatalf("Could not label GCE instance: %s", err)
   	}
   	log.Printf("Creator label added to %s in operation %v", instance, op)
   	return nil
   }
   

   Java

   import com.google.cloud.compute.v1.GetInstanceRequest;
   import com.google.cloud.compute.v1.Instance;
   import com.google.cloud.compute.v1.InstancesClient;
   import com.google.cloud.compute.v1.InstancesSetLabelsRequest;
   import com.google.cloud.compute.v1.SetLabelsInstanceRequest;
   import com.google.cloud.functions.CloudEventsFunction;
   import com.google.gson.Gson;
   import com.google.gson.JsonObject;
   import com.google.gson.JsonSyntaxException;
   import io.cloudevents.CloudEvent;
   import java.nio.charset.StandardCharsets;
   import java.util.logging.Logger;
   
   public class AutoLabelInstance implements CloudEventsFunction {
     private static final Logger logger = Logger.getLogger(AutoLabelInstance.class.getName());
   
     @Override
     public void accept(CloudEvent event) throws Exception {
       // Extract CloudEvent data
       if (event.getData() != null) {
         String cloudEventData = new String(event.getData().toBytes(), StandardCharsets.UTF_8);
   
         // Convert data to JSON
         JsonObject eventData;
         try {
           Gson gson = new Gson();
           eventData = gson.fromJson(cloudEventData, JsonObject.class);
         } catch (JsonSyntaxException error) {
           throw new RuntimeException("CloudEvent data is not valid JSON: " + error.getMessage());
         }
   
         // Extract the Cloud Audit Logging entry from the data's protoPayload
         JsonObject payload = eventData.getAsJsonObject("protoPayload");
         JsonObject auth = payload.getAsJsonObject("authenticationInfo");
   
         // Extract the email address of the authenticated user
         // (or service account on behalf of third party principal) making the request
         String creator = auth.get("principalEmail").getAsString();
         if (creator == null) {
           throw new RuntimeException("`principalEmail` not found in protoPayload.");
         }
         // Format the 'creator' parameter to match GCE label validation requirements
         creator = creator.toLowerCase().replaceAll("\\W", "-");
   
         // Get relevant VM instance details from the CloudEvent `subject` property
         // Example: compute.googleapis.com/projects/<PROJECT>/zones/<ZONE>/instances/<INSTANCE>
         String subject = event.getSubject();
         if (subject == null || subject == "") {
           throw new RuntimeException("Missing CloudEvent `subject`.");
         }
         String[] params = subject.split("/");
   
         // Validate data
         if (params.length < 7) {
           throw new RuntimeException("Can not parse resource from CloudEvent `subject`: " + subject);
         }
         String project = params[2];
         String zone = params[4];
         String instanceName = params[6];
   
         // Instantiate the Compute Instances client
         try (InstancesClient instancesClient = InstancesClient.create()) {
           // Get the newly-created VM instance's label fingerprint
           // This is required by the Compute Engine API to prevent duplicate labels
           GetInstanceRequest getInstanceRequest =
               GetInstanceRequest.newBuilder()
                   .setInstance(instanceName)
                   .setProject(project)
                   .setZone(zone)
                   .build();
           Instance instance = instancesClient.get(getInstanceRequest);
           String fingerPrint = instance.getLabelFingerprint();
   
           // Label the instance with its creator
           SetLabelsInstanceRequest setLabelRequest =
               SetLabelsInstanceRequest.newBuilder()
                   .setInstance(instanceName)
                   .setProject(project)
                   .setZone(zone)
                   .setInstancesSetLabelsRequestResource(
                       InstancesSetLabelsRequest.newBuilder()
                           .putLabels("creator", creator)
                           .setLabelFingerprint(fingerPrint)
                           .build())
                   .build();
   
           instancesClient.setLabelsAsync(setLabelRequest);
           logger.info(
               String.format(
                   "Adding label, \"{'creator': '%s'}\", to instance, \"%s\".",
                   creator, instanceName));
         } catch (Exception error) {
           throw new RuntimeException(
               String.format(
                   "Error trying to label VM instance, %s: %s", instanceName, error.toString()));
         }
       }
     }
   }

関数のデプロイ

Cloud Audit Logs トリガーを使用して関数をデプロイするには、サンプルコード（Java の場合は pom.xml ファイル）を含むディレクトリで次のコマンドを実行します。

gcloud functions deploy nodejs-cal-function \
--gen2 \
--runtime=nodejs22 \
--region=REGION \
--source=. \
--entry-point=autoLabelInstance \
--trigger-location=REGION \
--trigger-event-filters="type=google.cloud.audit.log.v1.written" \
--trigger-event-filters="serviceName=compute.googleapis.com" \
--trigger-event-filters="methodName=v1.compute.instances.insert"

gcloud functions deploy python-cal-function \
--gen2 \
--runtime=python312 \
--region=REGION \
--source=. \
--entry-point=label_gce_instance \
--trigger-location=REGION \
--trigger-event-filters="type=google.cloud.audit.log.v1.written" \
--trigger-event-filters="serviceName=compute.googleapis.com" \
--trigger-event-filters="methodName=v1.compute.instances.insert"

gcloud functions deploy go-cal-function \
--gen2 \
--runtime=go122 \
--region=REGION \
--source=. \
--entry-point=label-gce-instance \
--trigger-location=REGION \
--trigger-event-filters="type=google.cloud.audit.log.v1.written" \
--trigger-event-filters="serviceName=compute.googleapis.com" \
--trigger-event-filters="methodName=v1.compute.instances.insert"

gcloud functions deploy java-cal-function \
--gen2 \
--runtime=java21 \
--region=REGION \
--source=. \
--entry-point=functions.AutoLabelInstance \
--memory=512MB \
--trigger-location=REGION \
--trigger-event-filters="type=google.cloud.audit.log.v1.written" \
--trigger-event-filters="serviceName=compute.googleapis.com" \
--trigger-event-filters="methodName=v1.compute.instances.insert"

上記のデプロイ コマンドでは、VM の作成に対応する次のイベント フィルタ パラメータを指定します。

• type: Cloud Audit Logs イベントタイプ（google.cloud.audit.log.v1.written）。
• serviceName: ログエントリを生成した Google Cloud サービスの名前。この場合は compute.googleapis.com です。
• methodName: ログエントリを生成した API メソッドの名前。この場合は v1.compute.instances.insert です。

関数のトリガー

関数がデプロイされたら、動作を確認します。

1. Compute Engine VM インスタンスを作成します。

   gcloud compute instances create YOUR_INSTANCE_NAME --zone YOUR_ZONE

   または、Google Cloud コンソールに移動して、[VM を作成] をクリックします。

2. 次のコマンドを実行して、インスタンスに適切なラベルが設定されていることを確認します。

   gcloud compute instances describe YOUR_INSTANCE_NAME \
       --zone YOUR_ZONE \
       --format 'value(labels)'

   creator=YOURNAMEYOUR_DOMAIN 形式のラベルが付いているはずです。