הגדרת התראות על סוד

בדף הזה מוסבר איך להגדיר התראות על אירועים בסודות שלכם ב-Secret Manager ואיך להשתמש בהן.

סקירה כללית

‫Secret Manager משתלב עם Pub/Sub כדי לספק התראות על אירועים שקשורים לשינויים בסודות ובגרסאות של סודות. אפשר להשתמש בהתראות האלה כדי להפעיל תהליכי עבודה, כמו הפעלה מחדש של אפליקציה כשמוסיפים גרסה חדשה של סוד, או שליחת התראה למהנדסי אבטחה כשסוד נמחק. במסמכי העזרה של Pub/Sub יש מידע נוסף על השימוש בהתראות האלה כדי להתחיל תהליכי עבודה.

איך פועלות התראות על אירועים ב-Secret Manager

אפשר להגדיר סודות עם רשימה של עד 10 נושאי Pub/Sub. בכל פעם שמבצעים פעולה שמשנה את הסוד או אחת מהגרסאות שלו, Secret Manager מפרסם באופן אוטומטי הודעה בכל אחד מנושאי ה-Pub/Sub שקשורים לסוד הזה. הקריאות Get, List ו-Access לא גורמות לפרסום הודעות.

להודעות Pub/Sub יש קבוצה של צמדי מפתח-ערך של מאפיינים שמכילים מטא-נתונים על האירוע, וגם שדה data שמכיל סריאליזציה מלאה ב-JSON של משאב Secret או SecretVersion שנוצר או שונה. קובץ ה-JSON הוא מחרוזת בקידוד UTF-8 שמייצגת את המשאב Secret או SecretVersion בדיוק בפורמט שצוין ב-API הציבורי של Secret Manager, בקידוד JSON כמו שצוין במיפוי JSON של proto3.

סוגי אירועים

אלה סוגי האירועים שנתמכים ב-Secret Manager.

פורמט ההתראות

ההתראות שנשלחות לנושא Pub/Sub כוללות שני חלקים:

• מאפיינים: קבוצה של צמדי מפתח/ערך שמתארים את האירוע.

• נתונים: מחרוזת שמכילה את המטא-נתונים של האובייקט שהשתנה.

מאפיינים

המאפיינים הם צמדי מפתח/ערך שכלולים בהתראות שנשלחות מ-Secret Manager לנושא Pub/Sub. כל ההתראות, למעט הודעות הבדיקה TOPIC_CONFIGURED, תמיד מכילות את הקבוצה הבאה של צמדי מפתח/ערך, בלי קשר לנתוני ההתראה:

בנוסף, לפעמים ההתראות מכילות את הקבוצה הבאה של צמדי מפתח/ערך:

נתונים

שדה הנתונים הוא מחרוזת בקידוד UTF-8 שמכילה את המטא-נתונים של האובייקט שהשתנה. הנתונים הם סוד או גרסה של סוד.

בהתראות של SECRET_DELETE, המטא-נתונים שכלולים בשדה הנתונים מייצגים את המטא-נתונים של האובייקט כפי שהיו לפני המחיקה. בכל ההתראות האחרות, המטא-נתונים שכלולים בשדה הנתונים מייצגים את המטא-נתונים של האובייקט אחרי ביצוע השינוי.

מגבלות

• התראות על אירועים זמינות רק ב-API של Secret Manager‏ v1 וב-Google Cloud CLI.

• אי אפשר להשתמש באופן מהימן בהתראות על אירועים עם נושאי Pub/Sub שיש להם מדיניות אחסון הודעות שבה enforceInTransit מוגדר כ-true.

  ‫Secret Manager מפרסם את כל ההתראות על אירועים מנקודת קצה גלובלית. אם נושא Pub/Sub מוגדר עם enforceInTransit כ-true, הוא מגביל את הפרסום לallowedPersistenceRegions ספציפיים. ההגבלה האזורית מתנגשת עם נקודת הקצה הגלובלית לפרסום ב-Secret Manager, ולכן בקשת הפרסום נכשלת עם השגיאה FAILED_PRECONDITION.

לפני שמתחילים

אתם יכולים לאחסן את כל המשאבים באותו פרויקט, או לאחסן סודות ונושאי Pub/Sub בפרויקטים נפרדים.

1. כדי להגדיר את Secret Manager, מבצעים את הפעולות הבאות:

   • יוצרים פרויקט או משתמשים בפרויקט קיים כדי לאחסן את המשאבים של Secret Manager.

   • אם צריך, משלימים את השלבים שמפורטים במאמר הפעלת Secret Manager API.

2. כדי להגדיר את Pub/Sub, מבצעים את הפעולות הבאות:

   • יוצרים פרויקט או משתמשים בפרויקט קיים כדי לאחסן את משאבי Pub/Sub.

   • במידת הצורך, מפעילים את Pub/Sub API.

3. מריצים את הפקודה הבאה כדי לבצע אימות ב- Google Cloud :

       $ gcloud auth login --update-adc
       

יצירת זהות של סוכן שירות

כדי ליצור זהות של סוכן שירות לכל פרויקט שנדרשים בו סודות עם התראות על אירועים, מבצעים את השלבים הבאים:

1. כדי ליצור זהות שירות באמצעות Google Cloud CLI, מריצים את הפקודה הבאה:

         $ gcloud beta services identity create \
             --service "secretmanager.googleapis.com" \
             --project "PROJECT_ID"
       

   הפקודה הזו מחזירה את השם של חשבון השירות בפורמט הבא:

       service-PROJECT_NUMBER@gcp-sa-secretmanager.iam.gserviceaccount.com
       

2. נותנים לחשבון השירות הזה הרשאה לפרסם בנושאי Pub/Sub שהוגדרו בסודות.

3. שומרים את השם של חשבון השירות כמשתנה סביבה באמצעות הפקודה הבאה:

       # This is from the output of the command above
       $ export SM_SERVICE_ACCOUNT="service-...."
       

משתני הסביבה של פרויקט Secret Manager, פרויקט Pub/Sub וחשבון השירות של Secret Manager צריכים להיות מוגדרים לאורך כל התהליך.

יצירת נושאים ב-Pub/Sub

פועלים לפי המדריך לתחילת העבודה עם Pub/Sub כדי ליצור נושאים בפרויקט Pub/Sub במסוף Google Cloud . אפשר גם ליצור נושאים ב-Google Cloud CLI באמצעות הפקודה הבאה:

gcloud pubsub topics create "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"

gcloud pubsub topics create "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"

gcloud pubsub topics create "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"

אם רוצים ליצור כמה נושאים ב-Pub/Sub בסוד, חוזרים על הפעולה הזו כמה פעמים.

מעניקים לחשבון השירות של Secret Manager הרשאה לפרסם בנושאים

אפשר להעניק הרשאות לחשבון השירות של Secret Manager דרך Google Cloud המסוף או דרך Google Cloud CLI.

כדי להעניק את התפקיד 'פרסום הודעות ב-Pub/Sub' (roles/pubsub.publisher) בנושא ב-Pub/Sub, משתמשים בפקודה הבאה:

gcloud pubsub topics add-iam-policy-binding PUBSUB_TOPIC_NAME \
    --member "serviceAccount:${SM_SERVICE_ACCOUNT}" \
    --role "roles/pubsub.publisher"

gcloud pubsub topics add-iam-policy-binding PUBSUB_TOPIC_NAME `
    --member "serviceAccount:${SM_SERVICE_ACCOUNT}" `
    --role "roles/pubsub.publisher"

gcloud pubsub topics add-iam-policy-binding PUBSUB_TOPIC_NAME ^
    --member "serviceAccount:${SM_SERVICE_ACCOUNT}" ^
    --role "roles/pubsub.publisher"

יצירת מינויים ל-Pub/Sub

כדי לראות את ההודעות שפורסמו בנושא, צריך גם ליצור מינוי לנושא. כדי ליצור מינויים בפרויקט Pub/Sub במסוף Google Cloud , פועלים לפי ההוראות שבמדריך לתחילת העבודה עם Pub/Sub. אפשר גם ליצור נושאים ב-Google Cloud CLI באמצעות הפקודה הבאה:

gcloud pubsub subscriptions create projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME \
  --topic projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME

gcloud pubsub subscriptions create projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME `
  --topic projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME

gcloud pubsub subscriptions create projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME ^
  --topic projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME

יצירת סוד עם נושאים מוגדרים

יוצרים סוד עם רשימה של עד 10 נושאים מוגדרים. כל הנושאים שהוגדרו בסוד מקבלים התראות על אירועים כשהסוד או אחת מהגרסאות שלו משתנים.

gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME

gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME

gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME

POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID

{
  "replication":{
    "automatic":{}
  },
  "topics":{
    "name": "TOPIC_NAME"
  }
}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID" | Select-Object -Expand Content

{
  "name": "/projects/my-project/locations/me-central2/secrets/my-drz-secret",
  "createTime": "2024-03-25T08:24:13.153705Z",
  "etag": "\"161477e6071da9\""
}

עדכון נושאים סודיים

כדי לשנות את נושאי Pub/Sub שהוגדרו בסוד, צריך לעדכן את הסוד עם שמות המשאבים החדשים של נושאי Pub/Sub. באמצעות Google Cloud CLI אפשר להוסיף נושא אחד או יותר לסוד או להסיר אותם ממנו, וגם לנקות את כל הנושאים מהסוד.

הוספת נושאים

כדי להוסיף נושא אחד או יותר לסוד, משתמשים בפקודה הבאה:

gcloud secrets update SECRET_ID \
  --project PROJECT_ID \
  --add-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME

gcloud secrets update SECRET_ID `
  --project PROJECT_ID `
  --add-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME

gcloud secrets update SECRET_ID ^
  --project PROJECT_ID ^
  --add-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME

הסרת נושאים

כדי להסיר נושא אחד או יותר מסוד, משתמשים בפקודה הבאה:

gcloud secrets update SECRET_ID \
  --project PROJECT_ID \
  --remove-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME

gcloud secrets update SECRET_ID `
  --project PROJECT_ID `
  --remove-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME

gcloud secrets update SECRET_ID ^
  --project PROJECT_ID ^
  --remove-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME

מחיקת הנושאים

כדי להסיר את כל הנושאים מסוד, משתמשים בפקודה הבאה:

gcloud secrets update SECRET_ID \
  --project PROJECT_ID \
  --clear-topics

gcloud secrets update SECRET_ID `
  --project PROJECT_ID `
  --clear-topics

gcloud secrets update SECRET_ID ^
  --project PROJECT_ID ^
  --clear-topics

שימוש בהתראות על אירועים באמצעות פונקציות Cloud Run

אפשר להשתמש בהתראות על אירועים כדי להפעיל תהליכי עבודה על ידי יצירת פונקציות Cloud Run לצריכת ההודעות ב-Pub/Sub. מידע נוסף זמין במאמרי העזרה בנושא פונקציות של Cloud Run. קוד הדוגמה הבא הוא לפונקציית Cloud Run שמדפיסה את eventType,‏ secretId ומטא-נתונים בכל פעם שמתפרסם אירוע בנושא.

using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using Google.Events.Protobuf.Cloud.PubSub.V1;
using System;
using System.Threading;
using System.Threading.Tasks;

// Triggered from a message on a Cloud Pub/Sub topic.
// The printed value will be visible in Cloud Logging
// (https://cloud.google.com/functions/docs/monitoring/logging).
namespace PubSubSample
{
    public class Function : ICloudEventFunction<MessagePublishedData>
    {
        public Task HandleAsync(CloudEvent cloudEvent, MessagePublishedData data, CancellationToken cancellationToken)
        {
          string eventType = data.Message.Attributes["eventType"];
          string secretId = data.Message.Attributes["secretId"];
          string secretMetadata = data.Message.TextData;
          Console.WriteLine($"Received {eventType} for {secretId}. New metadata: {secretMetadata}.");
          return Task.CompletedTask;
        }
    }
}

import (
	"context"
	"fmt"
)

// PubSubMessage is the payload of a Pub/Sub event.
type PubSubMessage struct {
	Attributes PubSubAttributes `json:"attributes"`
	Data       []byte           `json:"data"`
}

// PubSubAttributes are attributes from the Pub/Sub event.
type PubSubAttributes struct {
	SecretId  string `json:"secretId"`
	EventType string `json:"eventType"`
}

// ConsumeEventNotification demonstrates how to consume and process the Pub/Sub
// notification from Secret Manager.
func ConsumeEventNotification(ctx context.Context, m PubSubMessage) (string, error) {
	// The printed value will be visible in Cloud Logging:
	//
	//     https://cloud.google.com/functions/docs/monitoring/logging
	//
	eventType := m.Attributes.EventType
	secretID := m.Attributes.SecretId
	data := m.Data

	return fmt.Sprintf("Received %s for %s. New metadata: %q.",
		eventType, secretID, data), nil
}

import java.util.Base64;
import java.util.Map;
import java.util.logging.Logger;
import lombok.Data;

// Demonstrates how to consume and process a Pub/Sub notification from Secret Manager. Triggered
// by a message on a Cloud Pub/Sub topic.
// Ideally the class should implement a background function that accepts a Pub/Sub message.
// public class ConsumeEventNotification implements BackgroundFunction<PubSubMessage> { }
public class ConsumeEventNotification {

  // You can configure the logs to print the message in Cloud Logging.
  private static final Logger logger = Logger.getLogger(ConsumeEventNotification.class.getName());

  // Accepts a message from a Pub/Sub topic and writes it to logger.
  public static String accept(PubSubMessage message) {
    String eventType = message.attributes.get("eventType");
    String secretId = message.attributes.get("secretId");
    String data = new String(Base64.getDecoder().decode(message.data));
    String log = String.format("Received %s for %s. New metadata: %s", eventType, secretId, data);
    logger.info(log);
    return log;
  }

  // Event payload. Mock of the actual Pub/Sub message.
  @Data
  public static class PubSubMessage {

    byte[] data;
    Map<String, String> attributes;
    String messageId;
    String publishTime;
    String orderingKey;
  }
}

/**
* Triggered from a message on a Cloud Pub/Sub topic.
* The printed value will be visible in Cloud Logging
* (https://cloud.google.com/functions/docs/monitoring/logging).
*
* @param {!Object} event Event payload.
* @param {!Object} context Metadata for the event.
*/
exports.smEventsFunction = (event, context) => {
  const eventType = event.attributes.eventType;
  const secretID = event.attributes.secretId;
  const secretMetadata = Buffer.from(event.data, 'base64').toString();
  console.log(`Received ${eventType} for ${secretID}. New metadata: ${secretMetadata}.`);
};

import base64


def consume_event_notification(event: dict, unused_context: None) -> str:
    """
    consume_event_notification demonstrates how to consume and process a
    Pub/Sub notification from Secret Manager.
    Args:
          event (dict): Event payload.
          unused_context (google.cloud.functions.Context): Metadata for the event.
    """
    event_type = event["attributes"]["eventType"]
    secret_id = event["attributes"]["secretId"]
    secret_metadata = base64.b64decode(event["data"]).decode("utf-8")
    event_notification = (
        f"Received {event_type} for {secret_id}. New metadata: {secret_metadata}"
    )
    print(event_notification)
    return event_notification

require "functions_framework"
require "base64"

# Triggered from a message on a Cloud Pub/Sub topic.
# The printed value will be visible in Cloud Logging
# (https://cloud.google.com/functions/docs/monitoring/logging).
FunctionsFramework.cloud_event "sm_events_function" do |event|
  message = event.data["message"]
  event_type = message["attributes"]["eventType"]
  secret_id = message["attributes"]["secretId"]
  message_data = Base64.decode64 message["data"]
  FunctionsFramework.logger.info "Received %s for %s. New metadata: %s." % [event_type, secret_id, message_data]
end

רשימה של כל סוגי האירועים זמינה במאמר סוגי אירועים.

נושאים שהוגדרו בצורה שגויה

אם מוסיפים נושאים של Pub/Sub לסוד בפעולת יצירה או עדכון, אבל Secret Manager לא יכול לפרסם הודעות בנושא בגלל הגדרה שגויה, הפעולה נכשלת ומוצגת הודעת שגיאה שמציינת למה הפרסום נכשל. לדוגמה, זה יכול לקרות אם הנושא לא קיים, או אם לחשבון השירות של Secret Manager אין הרשאה לפרסם.

אם מוסיפים נושאי Pub/Sub לסוד ואחר כך משנים את הנושא כך ש-Secret Manager לא יכול יותר לפרסם הודעות (לדוגמה, הנושא נמחק או שההרשאות של חשבון השירות של Secret Manager הוסרו), Secret Manager כותב יומנים ל-Secret Manager Secret עם הודעה שמציינת למה הפרסום נכשל.

המאמרים הבאים

• איך מנתחים סודות באמצעות מאגר משאבי ענן