Anleitung: Routingereignisse an Cloud Run debuggen

In dieser Anleitung erfahren Sie, wie Sie Laufzeitfehler beheben, die auftreten, wenn Sie Eventarc verwenden, um Ereignisse von Cloud Storage mithilfe von Cloud-Audit-Logs an einen nicht authentifizierten Cloud Run-Dienst weiterzuleiten.

Artifact Registry-Standard-Repository erstellen

Erstellen Sie ein Artifact Registry-Standard-Repository zum Speichern des Docker-Container-Images:

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=$REGION

Ersetzen Sie REPOSITORY durch einen eindeutigen Namen für das Repository.

Cloud Storage-Bucket erstellen

Erstellen Sie in jeder von zwei Regionen einen Cloud Storage-Bucket als Ereignisquelle für den Cloud Run-Dienst:

  1. Bucket in us-east1 erstellen:

    export BUCKET1="troubleshoot-bucket1-PROJECT_ID"
gcloud storage buckets create gs://${BUCKET1} --location=us-east1

  2. Bucket in us-west1 erstellen:

    export BUCKET2="troubleshoot-bucket2-PROJECT_ID"
gcloud storage buckets create gs://${BUCKET2} --location=us-west1

Nachdem die Ereignisquelle erstellt wurde, stellen Sie den Ereignisempfängerdienst in Cloud Run bereit.

Ereignisempfänger bereitstellen

Stellen Sie einen Cloud Run-Dienst bereit, der Ereignisse empfängt und loggt.

  1. Rufen Sie das Codebeispiel ab, indem Sie das GitHub-Repository klonen:

    Go

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

    Java

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
cd java-docs-samples/eventarc/audit-storage

    .NET

    git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git
cd dotnet-docs-samples/eventarc/audit-storage

    Node.js

    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
cd nodejs-docs-samples/eventarc/audit-storage

    Python

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
cd python-docs-samples/eventarc/audit-storage

  2. Sehen Sie sich den Code für diese Anleitung an. Er besteht aus folgenden Elementen:

    • Ein Event-Handler, der das eingehende Ereignis als CloudEvent in der HTTP-POST-Anfrage empfängt:

      Go

      
// Processes CloudEvents containing Cloud Audit Logs for Cloud Storage
package main

import (
	"fmt"
	"log"
	"net/http"
	"os"

	cloudevent "github.com/cloudevents/sdk-go/v2"
)

// HelloEventsStorage receives and processes a Cloud Audit Log event with Cloud Storage data.
func HelloEventsStorage(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodPost {
		http.Error(w, "Expected HTTP POST request with CloudEvent payload", http.StatusMethodNotAllowed)
		return
	}

	event, err := cloudevent.NewEventFromHTTPRequest(r)
	if err != nil {
		log.Printf("cloudevent.NewEventFromHTTPRequest: %v", err)
		http.Error(w, "Failed to create CloudEvent from request.", http.StatusBadRequest)
		return
	}
	s := fmt.Sprintf("Detected change in Cloud Storage bucket: %s", event.Subject())
	fmt.Fprintln(w, s)
}

      Java

      import io.cloudevents.CloudEvent;
import io.cloudevents.rw.CloudEventRWException;
import io.cloudevents.spring.http.CloudEventHttpUtils;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class EventController {

  @RequestMapping(value = "/", method = RequestMethod.POST, consumes = "application/json")
  public ResponseEntity<String> receiveMessage(
      @RequestBody String body, @RequestHeader HttpHeaders headers) {
    CloudEvent event;
    try {
      event =
          CloudEventHttpUtils.fromHttp(headers)
              .withData(headers.getContentType().toString(), body.getBytes())
              .build();
    } catch (CloudEventRWException e) {
      return new ResponseEntity<>(e.getMessage(), HttpStatus.BAD_REQUEST);
    }

    String ceSubject = event.getSubject();
    String msg = "Detected change in Cloud Storage bucket: " + ceSubject;
    System.out.println(msg);
    return new ResponseEntity<>(msg, HttpStatus.OK);
  }
}

      .NET

      
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env, ILogger<Startup> logger)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        logger.LogInformation("Service is starting...");

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapPost("/", async context =>
            {
                logger.LogInformation("Handling HTTP POST");

                var ceSubject = context.Request.Headers["ce-subject"];
                logger.LogInformation($"ce-subject: {ceSubject}");

                if (string.IsNullOrEmpty(ceSubject))
                {
                    context.Response.StatusCode = 400;
                    await context.Response.WriteAsync("Bad Request: expected header Ce-Subject");
                    return;
                }

                await context.Response.WriteAsync($"GCS CloudEvent type: {ceSubject}");
            });
        });
    }
}

      Node.js

      const express = require('express');
const app = express();

app.use(express.json());
app.post('/', (req, res) => {
  if (!req.header('ce-subject')) {
    return res
      .status(400)
      .send('Bad Request: missing required header: ce-subject');
  }

  console.log(
    `Detected change in Cloud Storage bucket: ${req.header('ce-subject')}`
  );
  return res
    .status(200)
    .send(
      `Detected change in Cloud Storage bucket: ${req.header('ce-subject')}`
    );
});

module.exports = app;

      Python

      @app.route("/", methods=["POST"])
def index():
    # Create a CloudEvent object from the incoming request
    event = from_http(request.headers, request.data)
    # Gets the GCS bucket name from the CloudEvent
    # Example: "storage.googleapis.com/projects/_/buckets/my-bucket"
    bucket = event.get("subject")

    print(f"Detected change in Cloud Storage bucket: {bucket}")
    return (f"Detected change in Cloud Storage bucket: {bucket}", 200)

    • Ein Server, der den Event-Handler verwendet:

      Go

      
func main() {
	http.HandleFunc("/", HelloEventsStorage)
	// Determine port for HTTP service.
	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}
	// Start HTTP server.
	log.Printf("Listening on port %s", port)
	if err := http.ListenAndServe(":"+port, nil); err != nil {
		log.Fatal(err)
	}
}

      Java

      
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class Application {
  public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
  }
}

      .NET

          public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }
    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var port = Environment.GetEnvironmentVariable("PORT") ?? "8080";
        var url = $"http://0.0.0.0:{port}";

        return Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>().UseUrls(url);
            });
    }

      Node.js

      const app = require('./app.js');
const PORT = parseInt(process.env.PORT) || 8080;

app.listen(PORT, () =>
  console.log(`nodejs-events-storage listening on port ${PORT}`)
);

      Python

      import os

from cloudevents.http import from_http

from flask import Flask, request

app = Flask(__name__)
if __name__ == "__main__":
    app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

    • Ein Dockerfile, das die Betriebsumgebung für den Dienst definiert. Der Inhalt des Dockerfile variiert je nach Sprache:

      Go

      
# Use the official Go image to create a binary.
# This is based on Debian and sets the GOPATH to /go.
# https://hub.docker.com/_/golang
FROM golang:1.24-bookworm as builder

# Create and change to the app directory.
WORKDIR /app

# Retrieve application dependencies.
# This allows the container build to reuse cached dependencies.
# Expecting to copy go.mod and if present go.sum.
COPY go.* ./
RUN go mod download

# Copy local code to the container image.
COPY . ./

# Build the binary.
RUN go build -v -o server

# Use the official Debian slim image for a lean production container.
# https://hub.docker.com/_/debian
# https://docs.docker.com/develop/develop-images/multistage-build/#use-multi-stage-builds
FROM debian:bookworm-slim
RUN set -x && apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y \
    ca-certificates && \
    rm -rf /var/lib/apt/lists/*

# Copy the binary to the production image from the builder stage.
COPY --from=builder /app/server /server

# Run the web service on container startup.
CMD ["/server"]

      Java

      
# Use the official maven image to create a build artifact.
# https://hub.docker.com/_/maven
FROM maven:3-eclipse-temurin-17-alpine as builder

# Copy local code to the container image.
WORKDIR /app
COPY pom.xml .
COPY src ./src

# Build a release artifact.
RUN mvn package -DskipTests

# Use Eclipse Temurin for base image.
# https://docs.docker.com/develop/develop-images/multistage-build/#use-multi-stage-builds
FROM eclipse-temurin:17.0.16_8-jre-alpine

# Copy the jar to the production image from the builder stage.
COPY --from=builder /app/target/audit-storage-*.jar /audit-storage.jar

# Run the web service on container startup.
CMD ["java", "-Djava.security.egd=file:/dev/./urandom", "-jar", "/audit-storage.jar"]

      .NET

      
# Use Microsoft's official build .NET image.
# https://hub.docker.com/_/microsoft-dotnet-core-sdk/
FROM mcr.microsoft.com/dotnet/sdk:8.0-alpine AS build
WORKDIR /app

# Install production dependencies.
# Copy csproj and restore as distinct layers.
COPY *.csproj ./
RUN dotnet restore

# Copy local code to the container image.
COPY . ./
WORKDIR /app

# Build a release artifact.
RUN dotnet publish -c Release -o out


# Use Microsoft's official runtime .NET image.
# https://hub.docker.com/_/microsoft-dotnet-core-aspnet/
FROM mcr.microsoft.com/dotnet/aspnet:8.0-alpine AS runtime
WORKDIR /app
COPY --from=build /app/out ./

# Run the web service on container startup.
ENTRYPOINT ["dotnet", "AuditStorage.dll"]

      Node.js

      
# Use the official lightweight Node.js image.
# https://hub.docker.com/_/node
FROM node:20-slim
# Create and change to the app directory.
WORKDIR /usr/src/app

# Copy application dependency manifests to the container image.
# A wildcard is used to ensure both package.json AND package-lock.json are copied.
# Copying this separately prevents re-running npm install on every code change.
COPY package*.json ./

# Install dependencies.
# if you need a deterministic and repeatable build create a 
# package-lock.json file and use npm ci:
# RUN npm ci --omit=dev
# if you need to include development dependencies during development
# of your application, use:
# RUN npm install --dev

RUN npm install --omit=dev

# Copy local code to the container image.
COPY . .

# Run the web service on container startup.
CMD [ "npm", "start" ]

      Python

      
# Use the official Python image.
# https://hub.docker.com/_/python
FROM python:3.11-slim

# Allow statements and log messages to immediately appear in the Cloud Run logs
ENV PYTHONUNBUFFERED True

# Copy application dependency manifests to the container image.
# Copying this separately prevents re-running pip install on every code change.
COPY requirements.txt ./

# Install production dependencies.
RUN pip install -r requirements.txt

# Copy local code to the container image.
ENV APP_HOME /app
WORKDIR $APP_HOME
COPY . ./

# Run the web service on container startup. 
# Use gunicorn webserver with one worker process and 8 threads.
# For environments with multiple CPU cores, increase the number of workers
# to be equal to the cores available.
CMD exec gunicorn --bind :$PORT --workers 1 --threads 8 --timeout 0 main:app

  3. Erstellen Sie das Container-Image mit Cloud Build und laden Sie es in Artifact Registry hoch:

    export PROJECT_ID=$(gcloud config get-value project)
export SERVICE_NAME=troubleshoot-service
gcloud builds submit --tag $REGION-docker.pkg.dev/${PROJECT_ID}/REPOSITORY/${SERVICE_NAME}:v1

  4. Stellen Sie das Container-Image in Cloud Run bereit:

    gcloud run deploy ${SERVICE_NAME} \
    --image $REGION-docker.pkg.dev/${PROJECT_ID}/REPOSITORY/${SERVICE_NAME}:v1 \
    --allow-unauthenticated

    Wenn die Bereitstellung erfolgreich war, wird in der Befehlszeile die Dienst-URL angezeigt.

Trigger erstellen

Nachdem Sie einen Cloud Run-Dienst bereitgestellt haben, richten Sie einen Trigger ein, um über Audit-Logs Ereignisse aus Cloud Storage aufzuzeichnen.

  1. So erstellen Sie einen Eventarc-Trigger, der auf Cloud Storage-Ereignisse wartet, die über Cloud-Audit-Logs weitergeleitet werden:

    gcloud eventarc triggers create troubleshoot-trigger \
    --destination-run-service=troubleshoot-service \
    --event-filters="type=google.cloud.audit.log.v1.written" \
    --event-filters="serviceName=storage.googleapis.com" \
    --event-filters="methodName=storage.objects.create" \
    --service-account=${PROJECT_NUMBER}-compute@developer.gserviceaccount.com

    Dadurch wird ein Trigger mit dem Namen troubleshoot-trigger erstellt.

  2. Führen Sie diesen Befehl aus, um zu prüfen, ob troubleshoot-trigger erstellt wurde:

    gcloud eventarc triggers list

    Die Ausgabe sollte in etwa so aussehen:

    NAME: troubleshoot-trigger
TYPE: google.cloud.audit.log.v1.written
DESTINATION: Cloud Run service: troubleshoot-service
ACTIVE: By 20:03:37
LOCATION: us-central1

Ereignis erstellen und abrufen

Prüfen Sie, ob der Dienst erfolgreich bereitgestellt wurde und Ereignisse aus Cloud Storage empfangen werden können.

  1. Erstellen Sie eine Datei und laden Sie sie in den Storage-Bucket BUCKET1 hoch:

     echo "Hello World" > random.txt
 gcloud storage cp random.txt gs://${BUCKET1}/random.txt

  2. Beobachten Sie die Logs, um zu prüfen, ob der Dienst ein Ereignis empfangen hat. So rufen Sie den Logeintrag auf:

    1. Filtern Sie die Logeinträge und geben Sie die Ausgabe im JSON-Format zurück:

      gcloud logging read "resource.labels.service_name=troubleshoot-service \
    AND textPayload:random.txt" \
    --format=json

    2. Suchen Sie nach einem Logeintrag wie dem folgenden:

      "textPayload": "Detected change in Cloud Storage bucket: ..."

Beachten Sie, dass anfangs kein Logeintrag zurückgegeben wird. Das bedeutet, dass es ein Problem bei der Einrichtung gibt, das du untersuchen musst.

Problem untersuchen

Ermitteln Sie den Grund dafür, warum der Dienst keine Ereignisse empfängt.

Initialisierungszeit

Der Trigger wird zwar sofort erstellt, es kann jedoch bis zu zwei Minuten dauern, bis er wirksam wird und Ereignisse filtert. Führen Sie den folgenden Befehl aus, um zu prüfen, ob ein Trigger aktiv ist:

gcloud eventarc triggers list

Die Ausgabe gibt den Status des Triggers an. Im folgenden Beispiel ist troubleshoot-trigger um 14:16:56 Uhr aktiv:

NAME                  TYPE                               DESTINATION_RUN_SERVICE  ACTIVE
troubleshoot-trigger  google.cloud.audit.log.v1.written  troubleshoot-service     By 14:16:56

Laden Sie eine Datei in den Speicher-Bucket hoch, sobald der Trigger aktiv ist. Ereignisse werden in die Cloud Run-Dienstlogs geschrieben. Wenn der Dienst keine Ereignisse empfängt, kann dies mit der Größe der Ereignisse zusammenhängen.

Audit-Logs

In dieser Anleitung werden Cloud Storage-Ereignisse über Cloud-Audit-Logs weitergeleitet und an Cloud Run gesendet. Prüfen Sie, ob die Audit-Logs für Cloud Storage aktiviert sind.

  1. Rufen Sie in der Google Cloud Console die Seite Audit-Logs auf.

    Zu den Audit-Logs

  2. Markieren Sie das Kästchen Google Cloud Storage.
  3. Achten Sie darauf, dass die Logtypen Lesen durch Administrator, Daten lesen und Daten schreiben ausgewählt sind.

Nachdem Sie Cloud-Audit-Logs aktiviert haben, laden Sie die Datei noch einmal in den Speicher-Bucket hoch und prüfen Sie die Logs. Wenn der Dienst immer noch keine Ereignisse empfängt, kann dies mit dem Triggerstandort zusammenhängen.

Triggerstandort

Es können mehrere Ressourcen an verschiedenen Standorten vorhanden sein und Sie müssen nach Ereignissen aus Quellen filtern, die sich in derselben Region wie das Cloud Run-Ziel befinden. Weitere Informationen finden Sie unter Von Eventarc unterstützte Standorte und Informationen zu Eventarc-Standorten.

In dieser Anleitung haben Sie den Cloud Run-Dienst in us-central1 bereitgestellt. Da Sie eventarc/location auf us-central1 gesetzt haben, haben Sie am selben Standort auch einen Trigger erstellt.

Sie haben jedoch zwei Cloud Storage-Buckets an den Standorten us-east1 und us-west1 erstellt. Um Ereignisse von diesen Standorten zu erhalten, müssen Sie Eventarc-Trigger an diesen Standorten erstellen.

Eventarc-Trigger in us-east1 erstellen:

  1. Bestätigen Sie den Standort des vorhandenen Triggers:

    gcloud eventarc triggers describe troubleshoot-trigger

  2. Legen Sie den Standort und die Region auf us-east1 fest:

    gcloud config set eventarc/location us-east1
gcloud config set run/region us-east1

  3. Stellen Sie den Ereignisempfänger noch einmal bereit, indem Sie das Container-Image erstellen und in Cloud Run bereitstellen.

  4. Erstellen Sie einen neuen Trigger am Standort us-east1:

    gcloud eventarc triggers create troubleshoot-trigger-new \
  --destination-run-service=troubleshoot-service \
  --event-filters="type=google.cloud.audit.log.v1.written" \
  --event-filters="serviceName=storage.googleapis.com" \
  --event-filters="methodName=storage.objects.create" \
  --service-account=${PROJECT_NUMBER}-compute@developer.gserviceaccount.com

  5. Prüfen Sie, ob der Trigger erstellt wird:

    gcloud eventarc triggers list

    Die Initialisierung eines Triggers kann bis zu zwei Minuten dauern, bevor Ereignisse weitergeleitet werden.

  6. Generieren Sie ein Ereignis und sehen Sie es sich an, um zu prüfen, ob der Trigger jetzt richtig bereitgestellt wurde.

Andere mögliche Probleme

Bei der Verwendung von Eventarc können auch andere Probleme auftreten.

Termingröße

Die von Ihnen gesendeten Ereignisse dürfen die Limits für die Ereignisgröße nicht überschreiten.

Ein Trigger, der Ereignisse bisher bereitgestellt hat, funktioniert nicht mehr

  1. Prüfen Sie, ob die Quelle Ereignisse generiert. Prüfen Sie in den Cloud-Audit-Logs, ob der überwachte Dienst Logs ausgibt. Wenn Logs aufgezeichnet, aber keine Ereignisse zugestellt werden, wenden Sie sich an den Support.

  2. Prüfen Sie, ob ein Pub/Sub-Thema mit demselben Triggernamen vorhanden ist. Eventarc verwendet Pub/Sub als Transportschicht und verwendet entweder ein vorhandenes Pub/Sub-Thema oder erstellt automatisch ein Thema und verwaltet es für Sie.

    1. Informationen zum Auflisten von Triggern finden Sie unter gcloud eventarc triggers list.

    2. Führen Sie folgenden Befehl aus, um die Pub/Sub-Themen aufzulisten:

      gcloud pubsub topics list

    3. Prüfen Sie, ob der Name des Pub/Sub-Themas den Namen des erstellten Triggers enthält. Beispiel:

      name: projects/PROJECT_ID/topics/eventarc-us-east1-troubleshoot-trigger-new-123

    Wenn das Pub/Sub-Thema fehlt, erstellen Sie den Trigger noch einmal für einen bestimmten Anbieter, einen Ereignistyp und ein Cloud Run-Ziel.

  3. Prüfen Sie, ob der Trigger für den Dienst konfiguriert wurde.

    1. Rufen Sie in der Google Cloud Console die Seite Dienste auf.

      Zu Dienste

    2. Klicken Sie auf den Namen des Dienstes, um die Seite Dienstdetails zu öffnen.

    3. Klicken Sie auf den Tab Trigger.

      Der mit dem Dienst verknüpfte Eventarc-Trigger sollte aufgeführt sein.

  4. Prüfen Sie den Status des Pub/Sub-Themas und -Abos anhand von Pub/Sub-Messwerttypen.

    • Mit dem Messwert subscription/dead_letter_message_count können Sie weitergeleitete unzustellbare Nachrichten überwachen. Dieser Messwert zeigt die Anzahl der nicht zustellbaren Nachrichten, die Pub/Sub von einem Abo weiterleitet.

      Wenn keine Nachrichten zum Thema veröffentlicht werden, prüfen Sie in den Cloud-Audit-Logs, ob der überwachte Dienst Logs ausgibt. Wenn Logs aufgezeichnet, aber keine Ereignisse zugestellt werden, wenden Sie sich an den Support.

    • Sie können Push-Abos überwachen, indem Sie den Messwert subscription/push_request_count verwenden und nach response_code und subcription_id gruppieren.

      Wenn Übertragungsfehler gemeldet werden, prüfen Sie die Cloud Run-Dienstlogs. Wenn der empfangende Endpunkt einen Statuscode zurückgibt, der nicht „OK“ ist, bedeutet dies, dass der Cloud Run-Code nicht wie erwartet funktioniert. Wenden Sie sich in diesem Fall an den Support.

    Weitere Informationen finden Sie unter Benachrichtigungsrichtlinien mit Messwertschwellen erstellen.