הדרכה בנושא שורת הפקודה gcloud בשירות Cloud Run

במדריך הזה יוצרים מלאי של שירותי Cloud Run באמצעות Google Cloud CLI בתוך שירות Cloud Run. אתם יכולים ליישם את מה שתלמדו במדריך הזה בסקריפטים קיימים של פעולות ב-Cloud, או לבנות הוכחת היתכנות לפני שתשתמשו בספריות לקוח כדי לבנות שירות חזק יותר.

משתמשים ב-CLI של gcloud כמו בכל סקריפט מעטפת בתוך שירות אינטרנט, כמו שמוצג במדריך למתחילים בנושא מעטפת. ב-Cloud Run, שני הכלים פועלים עם שירותים על ידי אימות אוטומטי באמצעות זהות השירות של Cloud Run. Google Cloudכל ההרשאות שניתנות לזהות השירות זמינות ל-CLI של gcloud.

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

  • הפעלת האפשרות לגלות כתובות IP של מכונות וירטואליות פרטיות
  • הפעלת גישה לנתונים פרטיים ממסד נתונים באותו פרויקט
  • הפעלת מחיקה של שירותים אחרים שפועלים

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

כתיבת סקריפטים באמצעות כלי שורת הפקודה בתוך שירות Cloud Run דומה לשימוש בשורת הפקודה באופן מקומי. ההבדל העיקרי הוא ההגבלות הנוספות שצריך להוסיף סביב הלוגיקה של הסקריפט הראשי.

מטרות

  • לכתוב ולבנות קונטיינר בהתאמה אישית באמצעות Dockerfile
  • כתיבה, פיתוח ופריסה של שירות Cloud Run
  • שימוש ב-CLI של gcloud בצורה בטוחה בשירות אינטרנט
  • יצירת דוח של שירותי Cloud Run ושמירה שלו ב-Cloud Storage

עלויות

במסמך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:

כדי להעריך את ההוצאות בהתאם לתחזית השימוש שלכם, אתם יכולים להיעזר במחשבון העלויות.

משתמשים חדשים של Google Cloud ? יכול להיות שאתם זכאים לתקופת ניסיון בחינם.

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

  1. נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. מפעילים את ממשקי ה-API של Artifact Registry,‏ Cloud Build,‏ Cloud Run ו-Cloud Storage.

    תפקידים שנדרשים להפעלת ממשקי API

    כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים

    הפעלת ממשקי ה-API

  7. מתקינים ומפעילים את ה-CLI של gcloud.

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות להשלמת המדריך, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

הגדרת ברירות מחדל ב-gcloud

כדי להגדיר את gcloud עם ערכי ברירת מחדל לשירות Cloud Run:

  1. מגדירים את פרויקט ברירת המחדל:

    gcloud config set project PROJECT_ID

    מחליפים את PROJECT_ID בשם הפרויקט שיצרתם לצורך המדריך הזה.

  2. מגדירים את gcloud לאזור שבחרתם:

    gcloud config set run/region REGION

    מחליפים את REGION באזור נתמך ב-Cloud Run לבחירתכם.

מיקומים של Cloud Run

‫Cloud Run הוא שירות אזורי, כלומר התשתית שמריצה את שירותי Cloud Run ממוקמת באזור ספציפי ומנוהלת על ידי Google כך שתהיה זמינה באופן יתירתי בכל התחומים באותו אזור.

הקריטריונים העיקריים לבחירת האזור שבו יפעלו שירותי Cloud Run הם זמן האחזור, הזמינות או העמידות שנדרשים לכם. בדרך כלל אפשר לבחור את האזור הקרוב ביותר למשתמשים, אבל כדאי לקחת בחשבון את המיקום של מוצרים Google Cloud אחרים שבהם נעשה שימוש בשירות Cloud Run. השימוש במוצרים של Google Cloud Google Cloud יחד בכמה מיקומים יכול להשפיע על זמן האחזור ועל העלות של השירות.

‫Cloud Run זמין באזורים הבאים:

בכפוף לתמחור ברמה 1

בכפוף לתמחור ברמה 2

  • africa-south1 (יוהנסבורג)
  • asia-east2 (הונג קונג)
  • asia-northeast3 (סיאול, קוריאה הדרומית)
  • asia-southeast1 (סינגפור)
  • asia-southeast2 (ג'אקארטה)
  • asia-south2 (דלהי, הודו)
  • australia-southeast1 (סידני)
  • australia-southeast2 (מלבורן)
  • europe-central2 (ורשה, פולין)
  • europe-west10 (Berlin)
  • europe-west12 (טורינו)
  • europe-west2 (לונדון, בריטניה) סמל של עלה רמה נמוכה של CO2
  • europe-west3 (פרנקפורט, גרמניה)
  • europe-west6 (ציריך, שווייץ) סמל של עלה רמה נמוכה של CO2
  • me-central1 (דוחה)
  • me-central2 (דמאם)
  • northamerica-northeast1 (מונטריאול) סמל של עלה רמה נמוכה של CO2
  • northamerica-northeast2 (טורונטו) סמל של עלה רמה נמוכה של CO2
  • southamerica-east1 (סאו פאולו, ברזיל) סמל של עלה רמה נמוכה של CO2
  • southamerica-west1 (סנטיאגו, צ'ילה) סמל של עלה רמה נמוכה של CO2
  • us-west2 (לוס אנג'לס)
  • us-west3 (סולט לייק סיטי)
  • us-west4 (לאס וגאס)

אם כבר יצרתם שירות Cloud Run, תוכלו לראות את האזור בלוח הבקרה של Cloud Run בGoogle Cloud מסוף.

אחזור של דוגמת הקוד

כדי לאחזר את דוגמת קוד לשימוש:

  1. משכפלים את מאגר האפליקציה לדוגמה ומעבירים אותו למכונה המקומית:

    git clone https://github.com/GoogleCloudPlatform/cloud-run-samples.git

    אפשרות נוספת היא להוריד את הדוגמה כקובץ ZIP ולחלץ אותה.

  2. עוברים לספרייה שמכילה את הקוד לדוגמה של Cloud Run:

    cd cloud-run-samples/gcloud-report/

בדיקת הקוד

בקטע הזה מופיע מידע על דוגמת הקוד שאותרה.

יצירת דוח והעלאה שלו ל-Cloud Storage

סקריפט מעטפת זה יוצר דוח של שירותי Cloud Run בפרויקט ובאזור הנוכחיים, ומעלה את התוצאה ל-Cloud Storage. הפונקציה מפרטת את השירותים שהשם שלהם מכיל את הארגומנט search של המחרוזת שסופקה.

הסקריפט משתמש בפקודה gcloud run services list, בgcloudאפשרויות מתקדמות של פורמט ובמצב העתקה של gcloudהעברת סטרימינג.

set -eo pipefail

# Check for required environment variables.
requireEnv() {
  test "${!1}" || (echo "gcloud-report: '$1' not found" >&2 && exit 1)
}
requireEnv GCLOUD_REPORT_BUCKET

# Prepare formatting: Default search term to include all services.
search=${1:-'.'}
limits='spec.template.spec.containers.resources.limits.flatten("", "", " ")'
format='table[box, title="Cloud Run Services"](name,status.url,metadata.annotations.[serving.knative.dev/creator],'${limits}')'

# Create a specific object name that will not be overridden in the future.
obj="gs://${GCLOUD_REPORT_BUCKET}/report-${search}-$(date +%s).txt"

# Write a report containing the service name, service URL, service account or user that
# deployed it, and any explicitly configured service "limits" such as CPU or Memory.
gcloud run services list \
  --format "${format}" \
  --filter "metadata.name~${search}" | gcloud storage cp --gzip-in-flight-all - "${obj}"

# /dev/stderr is sent to Cloud Logging.
echo "gcloud-report: wrote to ${obj}" >&2
echo "Wrote report to ${obj}"

אפשר להריץ את הסקריפט הזה בבטחה כשירות, כי הפעלות חוזרות שלו מעדכנות את הדוח בלי לגרום לעלויות נוספות. סקריפטים אחרים שמשתמשים ב-CLI של gcloud יכולים להיות יקרים יותר אם מפעילים אותם שוב ושוב, למשל אם הם יוצרים משאבי Cloud חדשים או מבצעים משימות יקרות. סקריפטים אידמפוטנטיים, שמניבים את אותה תוצאה בהפעלות חוזרות, בטוחים יותר להפעלה כשירות.

הפעלת הסקריפט בבקשת HTTP

קוד Go זה מגדיר שירות אינטרנט שמריץ סקריפט מעטפת כדי ליצור דוח. מכיוון ששאילתת החיפוש היא קלט של משתמשים, הקוד מאמת אותה כדי לוודא שהיא מכילה רק אותיות, מספרים או מקפים, וכך למנוע פקודות זדוניות כקלט. הקבוצה הזו של תווים מצומצמת מספיק כדי למנוע מתקפות של החדרת פקודות.

שירות האינטרנט מעביר את פרמטר החיפוש כארגומנט לסקריפט מעטפת.


// Service gcloud-report is a Cloud Run shell-script-as-a-service.
package main

import (
	"log"
	"net/http"
	"os"
	"os/exec"
	"regexp"
)

func main() {
	http.HandleFunc("/", scriptHandler)

	// Determine port for HTTP service.
	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
		log.Printf("defaulting to port %s", port)
	}

	// Start HTTP server.
	log.Printf("listening on port %s", port)
	if err := http.ListenAndServe(":"+port, nil); err != nil {
		log.Fatal(err)
	}
}

func scriptHandler(w http.ResponseWriter, r *http.Request) {
	search := r.URL.Query().Get("search")
	re := regexp.MustCompile(`^[a-z]+[a-z0-9\-]*$`)
	if !re.MatchString(search) {
		log.Printf("invalid search criteria %q, using default", search)
		search = "."
	}

	cmd := exec.CommandContext(r.Context(), "/bin/bash", "script.sh", search)
	cmd.Stderr = os.Stderr
	out, err := cmd.Output()
	if err != nil {
		log.Printf("Command.Output: %v", err)
		http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
		return
	}
	w.Write(out)
}

בקובץ go.mod מוצהרים יחסי התלות של האפליקציה במודול Go:

module github.com/GoogleCloudPlatform/cloud-run-samples/gcloud-report

go 1.19

הגדרת סביבת המאגר

קובץ ה-Dockerfile מגדיר איך הסביבה מורכבת בשביל השירות. הוא דומה לקובץ Dockerfile מהמדריך המהיר helloworld-shell, אבל תמונת הקונטיינר הסופית מבוססת על תמונת Google Cloud CLI‏ gcloud. כך השירות יכול להשתמש ב-gcloud בלי שתצטרכו לבצע שלבי התקנה והגדרה מותאמים אישית עבור Google Cloud CLI.


# Use the official golang image to create a binary.
# This is based on Debian and sets the GOPATH to /go.
# https://hub.docker.com/_/golang
FROM golang:1.20-buster 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 invoke.go ./

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

# Use a gcloud image based on debian:buster-slim for a lean production container.
# https://docs.docker.com/develop/develop-images/multistage-build/#use-multi-stage-builds
FROM gcr.io/google.com/cloudsdktool/cloud-sdk:slim

WORKDIR /app

# Copy the binary to the production image from the builder stage.
COPY --from=builder /app/server /app/server
COPY *.sh /app/
RUN chmod +x /app/*.sh

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

יצירת מאגר רגיל ב-Artifact Registry

יוצרים מאגר רגיל של Artifact Registry לאחסון קובץ האימג' של הקונטיינר:

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

מחליפים את:

  • REPOSITORY בשם ייחודי למאגר.
  • REGION עם Google Cloud האזור של Artifact Registry.

הגדרת קטגוריה של Cloud Storage

יוצרים קטגוריה של Cloud Storage להעלאת דוחות:

gcloud storage buckets create gs://REPORT_ARCHIVE_BUCKET

מחליפים את REPORT_ARCHIVE_BUCKET בשם ייחודי לקטגוריה.

הגדרת הזהות בשירות

כדי להגביל את ההרשאות שיש לשירות לגשת לתשתית אחרת, אתם יוצרים זהות שירות ומגדירים את הרשאות ה-IAM הספציפיות שנדרשות לביצוע העבודה.

במקרה הזה, ההרשאות הנדרשות הן הרשאה לקריאת שירותים של Cloud Run והרשאה לקריאה וכתיבה בקטגוריה של Cloud Storage.

  1. יוצרים חשבון שירות:

    gcloud iam service-accounts create gcloud-report-identity

  2. נותנים לחשבון השירות הרשאה לקרוא שירותי Cloud Run:

    gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:gcloud-report-identity@PROJECT_ID.iam.gserviceaccount.com \
      --role roles/run.viewer
  3. נותנים לחשבון השירות הרשאה לקרוא ולכתוב בקטגוריה של Cloud Storage:

    gcloud storage buckets add-iam-policy-binding gs://REPORT_ARCHIVE_BUCKET \
      --member=serviceAccount:gcloud-report-identity@PROJECT_ID.iam.gserviceaccount.com \
      --role=roles/storage.objectUser

הגישה המוגבלת של זהות השירות המותאמת הזו מונעת מהשירות לגשת למשאבים אחרים של Google Cloud .

משלוח השירות

קוד המשלוח כולל שלושה שלבים:

  • יצירת קובץ אימג' של קונטיינר באמצעות Cloud Build
  • העלאת קובץ האימג' של הקונטיינר אל Artifact Registry
  • פריסת קובץ האימג' של הקונטיינר ב-Cloud Run.

כדי לשלוח את הקוד:

  1. יוצרים את הקונטיינר ומפרסמים אותו ב-Artifact Registry:

    gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/gcloud-report

    מחליפים את:

    • PROJECT_ID במזהה הפרויקט ב- Google Cloud
    • REPOSITORY בשם המאגר ב-Artifact Registry.
    • REGION עם Google Cloud האזור של Artifact Registry.

    gcloud-report הוא השם של השירות.

    אם הפעולה תצליח, תוצג הודעה עם המזהה, זמן היצירה ושם התמונה. התמונה מאוחסנת ב-Artifact Registry ואפשר לעשות בה שימוש חוזר אם צריך.

  2. מריצים את הפקודה הבאה כדי לפרוס את השירות:

    gcloud run deploy gcloud-report \
       --image REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/gcloud-report \
       --update-env-vars GCLOUD_REPORT_BUCKET=REPORT_ARCHIVE_BUCKET \
       --service-account gcloud-report-identity \
       --no-allow-unauthenticated

    מחליפים את:

    • PROJECT_ID במזהה הפרויקט ב- Google Cloud .
    • REPOSITORY בשם המאגר ב-Artifact Registry.
    • REGION עם האזור Google Cloud של השירות.

    gcloud-report הוא חלק משם הקונטיינר ומשם השירות. קובץ האימג' של הקונטיינר נפרס בשירות ובאזור (Cloud Run) שהגדרתם קודם בקטע הגדרת gcloud.

    הדגל --no-allow-unauthenticated מגביל את הגישה הציבורית לשירות. אם השירות פרטי, אפשר להסתמך על האימות המובנה של Cloud Run כדי לחסום בקשות לא מורשות. לפרטים נוספים על אימות שמבוסס על ניהול זהויות והרשאות גישה (IAM), אפשר לעיין במאמר ניהול גישה באמצעות IAM.

    מחכים עד שהפריסה תסתיים. הפעולה עשויה להימשך כחצי דקה. אם הפעולה בוצעה ללא שגיאות, כתובת ה-URL של השירות מוצגת בשורת הפקודה.

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

במאמר ניהול גישה באמצעות IAM מוסבר איך להעניק Google Cloud למשתמשים גישה להפעלת השירות הזה. לעורכים ולבעלים של הפרויקט יש גישה אוטומטית.

יצירת דוח

כדי ליצור דוח של שירותי Cloud Run:

  1. משתמשים ב-curl כדי לשלוח בקשה מאומתת:

    curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" SERVICE_URL

    מחליפים את SERVICE_URL בכתובת ה-URL ש-Cloud Run מספק אחרי השלמת הפריסה.

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

    Wrote report to gs://REPORT_ARCHIVE_BUCKET/report-.-DATE.txt

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

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

    curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" SERVICE_URL?search=gcloud

    הפלט שיוחזר מהשאילתה הזו ייראה בערך כך:

    Wrote report to gs://REPORT_ARCHIVE_BUCKET/report-gcloud-DATE.txt
  2. מאחזרים את הקובץ באמצעות ה-CLI של gcloud באופן מקומי:

    gcloud storage cp gs://REPORT_FILE_NAME .

    הסימן . בפקודה מציין את ספריית העבודה הנוכחית.

    מחליפים את REPORT_FILE_NAME בשם האובייקט ב-Cloud Storage שמופיע בפלט מהשלב הקודם.

פותחים את הקובץ כדי לראות את הדוח. הוא אמור להיראות כך:

צילום מסך של רשימת שירותי Cloud Run בפרויקט עם עמודות של ארבעה מאפייני שירות.
ארבע העמודות נלקחות מתיאור השירות. הם כוללים את השם של השירות, כתובת ה-URL שהוקצתה בהפריסה הראשונה, היוצר הראשוני של השירות והמגבלות של השירות על השימוש המקסימלי במעבד ובזיכרון.

שיפור החוסן לעתיד

אם אתם מתכוונים להמשיך לפתח את השירות הזה, כדאי לשקול לכתוב אותו מחדש בשפת תכנות חזקה יותר ולהשתמש ב-Cloud Run Admin API ובספריית הלקוח של Cloud Storage.

כדי לבדוק את הקריאות ל-API שמתבצעות (ולראות פרטים מסוימים של אימות), מוסיפים --log-http לפקודות של ה-CLI של gcloud.

אוטומציה של הפעולה הזו

עכשיו אפשר להפעיל את הדוח של שירותי Cloud Run באמצעות בקשת HTTP, ולכן אפשר להשתמש באוטומציה כדי ליצור דוחות כשצריך אותם:

הסרת המשאבים

כדי להימנע מחיובים נוספים בחשבון Google Cloud , מוחקים את כל המשאבים שהצבתם באמצעות המדריך הזה.

מחיקת הפרויקט

אם יצרתם פרויקט חדש בשביל המדריך הזה, מוחקים את הפרויקט. אם השתמשתם בפרויקט קיים ואתם רוצים לשמור אותו בלי השינויים שהוספתם במדריך הזה, תצטרכו למחוק את המשאבים שיצרתם לצורך המדריך.

הדרך הקלה ביותר לבטל את החיוב היא למחוק את הפרויקט שיצרתם בשביל המדריך.

כדי למחוק את הפרויקט:

  1. במסוף Google Cloud , נכנסים לדף Manage resources.

    כניסה לדף Manage resources

  2. ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
  3. כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

מחיקת משאבי הדרכה

  1. מוחקים את שירות Cloud Run שפרסתם במדריך הזה. שירותי Cloud Run לא צוברים עלויות עד שהם מקבלים בקשות.

    כדי למחוק את שירות Cloud Run, מריצים את הפקודה הבאה:

    gcloud run services delete SERVICE-NAME

    מחליפים את SERVICE-NAME בשם השירות.

    אפשר גם למחוק שירותים של Cloud Run מGoogle Cloud המסוף.

  2. מסירים את הגדרת ברירת המחדל של האזור gcloud שהוספתם במהלך ההגדרה של המדריך:

     gcloud config unset run/region
    
  3. מסירים את הגדרות הפרויקט:

     gcloud config unset project
    
  4. מחיקת משאבים אחרים Google Cloud שנוצרו במדריך הזה:

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