שימוש ב-Secret Manager עם Python

1. סקירה כללית

ב-Codelab הזה תתמקדו בשימוש ב-Secret Manager ב-Python.

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

‫Secret Manager מתאים לאחסון של פרטי הגדרה כמו סיסמאות למסדי נתונים, מפתחות API או אישורי TLS שנדרשים לאפליקציה בזמן הריצה.

מה תלמדו

איך משתמשים ב-Cloud Shell?
איך מתקינים את ספריית הלקוח של Secret Manager ל-Python
איך יוצרים סודות וניגשים אליהם באמצעות ספריית הלקוח של Python
איך ניגשים לסודות ב-Cloud Functions באמצעות ספריית הלקוח של Python

מה תצטרכו

פרויקט ב-Google Cloud
דפדפן, כמו Chrome או Firefox
היכרות עם Python 3

סקר

איך תשתמשו במדריך הזה?

רק לקרוא

לקרוא ולבצע את התרגילים

איך היית מדרג את חוויית השימוש שלך ב-Python?

מתחילים

ביניים

מומחים

איזה דירוג מתאים לדעתך לחוויית השימוש שלך בשירותי Google Cloud?

מתחילים

ביניים

מומחים

2. הגדרה ודרישות

הגדרת סביבה בקצב אישי

נכנסים ל-מסוף Google Cloud ויוצרים פרויקט חדש או משתמשים בפרויקט קיים. אם עדיין אין לכם חשבון Gmail או Google Workspace, אתם צריכים ליצור חשבון.

שם הפרויקט הוא השם המוצג של הפרויקט הזה למשתתפים. זו מחרוזת תווים שלא נמצאת בשימוש ב-Google APIs. אפשר לעדכן את המיקום הזה בכל שלב.
מזהה הפרויקט חייב להיות ייחודי בכל הפרויקטים ב-Google Cloud, והוא קבוע (אי אפשר לשנות אותו אחרי שמגדירים אותו). מסוף Cloud יוצר באופן אוטומטי מחרוזת ייחודית, ובדרך כלל לא צריך לדעת מה היא. ברוב ה-Codelabs, תצטרכו להפנות למזהה הפרויקט (בדרך כלל הוא מסומן כ-PROJECT_ID). אם אתם לא אוהבים את המזהה שנוצר, אתם יכולים ליצור מזהה אקראי אחר. אפשר גם לנסות שם משתמש משלכם ולבדוק אם הוא זמין. אי אפשר לשנות את ההגדרה הזו אחרי השלב הזה, והיא תישאר כזו למשך הפרויקט.
לידיעתכם, יש ערך שלישי, מספר פרויקט, שחלק מממשקי ה-API משתמשים בו. במאמרי העזרה מפורט מידע נוסף על שלושת הערכים האלה.

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

מפעילים את Cloud Shell

אפשר להפעיל את Google Cloud מרחוק מהמחשב הנייד, אבל ב-codelab הזה תשתמשו ב-Google Cloud Shell, סביבת שורת פקודה שפועלת בענן.

הפעלת Cloud Shell

ב-Cloud Console, לוחצים על Activate Cloud Shell .

אם זו הפעם הראשונה שאתם מפעילים את Cloud Shell, יוצג לכם מסך ביניים (מתחת לקו הקיפול) עם תיאור של הכלי. במקרה כזה, לוחצים על המשך (והמסך הזה לא יוצג לכם יותר). כך נראה המסך החד-פעמי:

הקצאת המשאבים והחיבור ל-Cloud Shell נמשכים רק כמה רגעים.

המכונה הווירטואלית הזו כוללת את כל הכלים שדרושים למפתחים. יש בה ספריית בית בנפח מתמיד של 5GB והיא פועלת ב-Google Cloud, מה שמשפר מאוד את הביצועים והאימות ברשת. אפשר לבצע את רוב העבודה ב-codelab הזה, אם לא את כולה, באמצעות דפדפן או Chromebook.

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

מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שעברתם אימות:

gcloud auth list

פלט הפקודה

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שפקודת gcloud מכירה את הפרויקט:

gcloud config list project

פלט הפקודה

[core]
project = <PROJECT_ID>

אם לא, אפשר להגדיר אותו באמצעות הפקודה הבאה:

gcloud config set project <PROJECT_ID>

פלט הפקודה

Updated property [core/project].

3. הפעלת Secret Manager API

כדי להתחיל להשתמש ב-Secret Manager API, צריך להפעיל את ה-API. כדי להפעיל את ה-API באמצעות Cloud Shell, מריצים את הפקודה הבאה:

gcloud services enable secretmanager.googleapis.com

הפלט אמור להיראות כך:

Operation "operations/acf.cc11852d-40af-47ad-9d59-477a12847c9e" finished successfully.

4. התקנת ספריית הלקוח של Secret Manager ל-Python

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

pip3 install --user google-cloud-secret-manager==2.10.0

5. הפעלת Python אינטראקטיבי

בחלק מהמדריך הזה משתמשים במפרש Python אינטראקטיבי שנקרא IPython, שמותקן מראש ב-Cloud Shell. כדי להתחיל סשן, מריצים את הפקודה ipython ב-Cloud Shell:

ipython

אתם אמורים לראות משהו כזה:

Python 3.9.2 (default, Feb 28 2021, 17:03:44)
Type 'copyright', 'credits' or 'license' for more information
IPython 8.3.0 -- An enhanced Interactive Python. Type '?' for help.

In [1]:

6. יצירת סודות

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

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

מגדירים את מזהה הפרויקט ב-IPython:

PROJECT_ID = "<PROJECT_ID>"

יצירת סוד

מעתיקים את הקוד הבא להפעלה של IPython:

from google.cloud import secretmanager

def create_secret(secret_id):
    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the parent project.
    parent = f"projects/{PROJECT_ID}"

    # Build a dict of settings for the secret
    secret = {'replication': {'automatic': {}}}

    # Create the secret
    response = client.create_secret(secret_id=secret_id, parent=parent, secret=secret)

    # Print the new secret name.
    print(f'Created secret: {response.name}')

קוראים לפונקציה כדי ליצור סוד חדש בשם my_secret_value:

create_secret("my_secret_value")

הפלט הבא אמור להתקבל:

Created secret: projects/<PROJECT_NUM>/secrets/my_secret_value

הוספת גרסה של סוד

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

מעתיקים את הקוד הבא להפעלה של IPython:

def add_secret_version(secret_id, payload):
    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the parent secret.
    parent = f"projects/{PROJECT_ID}/secrets/{secret_id}"

    # Convert the string payload into a bytes. This step can be omitted if you
    # pass in bytes instead of a str for the payload argument.
    payload = payload.encode('UTF-8')

    # Add the secret version.
    response = client.add_secret_version(parent=parent, payload={'data': payload})

    # Print the new secret version name.
    print(f'Added secret version: {response.name}')

קוראים לפונקציה כדי ליצור גרסה חדשה של הסוד:

add_secret_version("my_secret_value", "Hello Secret Manager")

הפלט הבא אמור להתקבל:

Added secret version: projects/<PROJECT_NUM>/secrets/my_secret_value/versions/1

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

add_secret_version("my_secret_value", "Hello Again, Secret Manager")

הפלט הבא אמור להתקבל:

Added secret version: projects/<PROJECT_NUM>/secrets/my_secret_value/versions/2

שימו לב שהגרסה החדשה של הסוד ארוכה משמעותית מהגרסה המקורית. נחזור למאפיין הזה בהמשך.

7. גישה לסודות

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

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

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

מעתיקים את הקוד הבא להפעלה של IPython:

def access_secret_version(secret_id, version_id="latest"):
    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the secret version.
    name = f"projects/{PROJECT_ID}/secrets/{secret_id}/versions/{version_id}"

    # Access the secret version.
    response = client.access_secret_version(name=name)

    # Return the decoded payload.
    return response.payload.data.decode('UTF-8')
    
import hashlib

def secret_hash(secret_value): 
  # return the sha224 hash of the secret value
  return hashlib.sha224(bytes(secret_value, "utf-8")).hexdigest()

קוראים לפונקציה כדי לאחזר את הסוד כגיבוב של הערך שלו:

secret_hash(access_secret_version("my_secret_value"))

הפלט אמור להיראות כמו גיבוב (יכול להיות שהערך המדויק לא יהיה זהה לפלט הזה):

83f8a4edb555cde4271029354395c9f4b7d79706ffa90c746e021d11

לא ציינת גרסה, לכן אוחזר הערך האחרון.

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

secret_hash(access_secret_version("my_secret_value", version_id=2))

הפלט שיוצג יהיה זהה לזה של הפקודה הקודמת:

83f8a4edb555cde4271029354395c9f4b7d79706ffa90c746e021d11

מפעילים את הפונקציה שוב, אבל הפעם מציינים את הגרסה הראשונה:

secret_hash(access_secret_version("my_secret_value", version_id=1))

הפעם אמור להופיע גיבוב שונה, שמציין פלט שונה:

9a3fc8b809ddc611c82aee950c636c7557e220893560ec2c1eeeb177

8. שימוש ב-Secret Manager עם Cloud Functions

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

אם אתם רוצים להשתמש ב-Python ב-Cloud Functions, אתם יכולים לעקוב אחרי ה-Codelab בנושא HTTP Google Cloud Functions ב-Python.

סוגרים את IPython על ידי קריאה לפונקציה exit:

exit

תועברו בחזרה אל Cloud Shell:

yourname@cloudshell:~ (<PROJECT_ID>)$

לפני שמתחילים להשתמש ב-Cloud Functions API, צריך להפעיל את ה-API. כדי להפעיל את ה-API באמצעות Cloud Shell, מריצים את הפקודה הבאה:

gcloud services enable cloudfunctions.googleapis.com cloudbuild.googleapis.com

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

mkdir secret-manager-api-demo
cd secret-manager-api-demo
touch main.py
touch requirements.txt

פותחים את עורך הקוד בפינה השמאלית העליונה של Cloud Shell:

עוברים לקובץ main.py בתוך התיקייה secret-manager-api-demo. כאן תזינו את כל הקוד.

9. כתיבת פונקציה של Cloud Functions לגישה לסודות

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

אפשר להשתמש בפונקציה access_secret_version שיצרתם קודם כבסיס לפונקציה של Cloud Functions.

מעתיקים את הקוד הבא לקובץ main.py:

main.py

import os

from google.cloud import secretmanager

project_id = os.environ["PROJECT_ID"]

client = secretmanager.SecretManagerServiceClient()
name = f"projects/{project_id}/secrets/my_secret_value/versions/latest"
response = client.access_secret_version(name=name)
my_secret_value = response.payload.data.decode("UTF-8")


def secret_hello(request):
    if "Again" in my_secret_value:
        return "We meet again!\n"

    return "Hello there.\n"

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

יוצרים קובץ חדש בשם requirements.txt ומוסיפים אליו את חבילת google-cloud-secret-manager:

requirements.txt

google-cloud-secret-manager==2.10.0

עכשיו אמורה להיות לכם תיקייה שמכילה רק main.py ו-requirements.txt.

מתן גישה לסוד

כדי לפרוס את הפונקציה, צריך לאפשר ל-Cloud Functions לגשת לסוד.

עוברים חזרה לטרמינל:

מעניקים לחשבון השירות של Cloud Functions גישה לסוד:

export PROJECT_ID=$(gcloud config get-value core/project)

gcloud secrets add-iam-policy-binding my_secret_value \
    --role roles/secretmanager.secretAccessor \
    --member serviceAccount:${PROJECT_ID}@appspot.gserviceaccount.com

הפלט הבא אמור להתקבל:

Updated IAM policy for secret [my_secret_value].
bindings:
- members:
  - serviceAccount:<PROJECT_ID>@appspot.gserviceaccount.com
  role: roles/secretmanager.secretAccessor
etag: BwWiRUt2oB4=
version: 1

10. פריסת הפונקציה של Cloud Functions

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

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

gcloud functions deploy secret_hello \
    --runtime python39 \
    --set-env-vars PROJECT_ID=${PROJECT_ID} \
    --trigger-http \
    --allow-unauthenticated

הפלט הבא אמור להתקבל (חלק מהפלט הושמט):

Deploying function (may take a while - up to 2 minutes)...done.

...

entryPoint: secret_hello
httpsTrigger:
  url: https://<REGION>-<PROJECT_ID>.cloudfunctions.net/secret_hello
...
status: ACTIVE
...

מאחזרים את כתובת ה-URL של הפונקציה (httpsTrigger.url metadata) באמצעות הפקודה הבאה:

FUNCTION_URL=$(gcloud functions describe secret_hello --format 'value(httpsTrigger.url)')

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

curl $FUNCTION_URL

הפלט הבא אמור להתקבל:

We meet again!

הפונקציה הזו מפנה לגרסה האחרונה של הסוד, שהוגדרה להכיל את המחרוזת 'Again', ולכן הפונקציה פועלת כמצופה.

‫11. מעולה!

למדתם איך להשתמש ב-Secret Manager API באמצעות Python.

הסרת המשאבים

כדי להימנע מחיובים בחשבון Google Cloud בגלל השימוש במשאבים שנעשה במסגרת המדריך הזה:

במסוף Cloud, נכנסים לדף Manage resources.
ברשימת הפרויקטים, בוחרים את הפרויקט ולוחצים על מחיקה.
כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

מידע נוסף

‫Secret Manager: https://cloud.google.com/secret-manager/
‫Python ב-Google Cloud: https://cloud.google.com/python/
ספריות לקוח של Cloud ל-Python: ‏ https://googlecloudplatform.github.io/google-cloud-python/

רישיון

עבודה זו מורשית תחת רישיון Creative Commons שמותנה בייחוס 2.0 כללי.