העברת פרמטרים לפריסה

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

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

במאמר הזה מוסבר איך עושים את זה.

למה כדאי להשתמש בפרמטרים של פריסה?

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

איך זה עובד

בשלבים הבאים מוסבר התהליך הכללי להגדרת פרמטרים של פריסה ולציון ערכים:

1. מגדירים פרמטרים לפריסה, כמו שמתואר כאן.

   הדוגמאות הבאות ממחישות את המצב הזה:

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

   • מוסיפים ערכים ל-placeholders.

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

2. כשיוצרים גרסה, קובץ המניפסט מעובד.

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

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

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

   הערה: אם מוקצה יותר מערך אחד לפרמטר פריסה (מפתח) מסוים, הפריסה נכשלת.

3. אחרי העיבוד, Cloud Deploy מחליף את הערכים של פרמטרי הפריסה.

   אלה הערכים שהגדרתם בשלב הראשון.

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

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

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

דרכים שונות להעברת ערכים

יש שלוש דרכים לספק פרמטרים וערכים לפרמטרים האלה:

• בהגדרת צינור ההפצה

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

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

• בהגדרת היעד

  מגדירים את הפרמטר ואת הערך שלו בהגדרה של היעד עצמו. השיטה הזו מאפשרת להחליף ערך של יעד מסוים בכל הגרסאות.

• בשורת הפקודה, כשיוצרים גרסה

  כדי לכלול את הפרמטר ואת הערך שלו, משתמשים בדגל --deploy-parameters בפקודה gcloud deploy releases create.

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

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

אפשר להשתמש ביותר מאחת מהשיטות האלה?

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

מה ההבדל בין זה לבין תבניות של קובצי מניפסט

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

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

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

מגבלות

• לכל סוג פרמטר, אפשר ליצור עד 50 פרמטרים.

• בנוסף, יעד צאצא יכול לקבל בירושה עד 50 פרמטרים מיעד האב מרובה היעדים שלו, עד למקסימום של 200 פרמטרים ביעדים, כולל הפרמטרים שהוגדרו בשלב הצינור.

• שם המפתח מוגבל למקסימום 63 תווים, והוא צריך להתאים לביטוי הרגולרי הבא:

  ^[a-zA-Z0-9]([-A-Za-z0-9_.]{0,61}[a-zA-Z0-9])?$
  

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

• הקידומת CLOUD_DEPLOY_ שמורה ואי אפשר להשתמש בה בשם של מפתח.

• אי אפשר להחיל שני מפתחות עם אותו שם על אותו יעד.

• הערך יכול להיות ריק, אבל האורך המקסימלי שלו הוא 512 תווים.

• אי אפשר להשתמש בפלייסהולדרים של פרמטרים של פריסה עבור ערכי הגדרה של Helm, אבל חובה להעביר אותם לפי המוסכמה.

הגדרת פרמטרים לפריסה

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

בנוסף להגדרת צמדי המפתח/ערך האלה, צריך להוסיף את ה-placeholder או את ה-placeholders למניפסט, כמו שמתואר בקטע הזה.

הוספת placeholder למניפסט

במניפסט של Kubernetes (ב-GKE) או ב-YAML של השירות (ב-Cloud Run), מוסיפים placeholders לכל הערכים שרוצים להחליף אחרי העיבוד.

תחביר

בגרסאות שלא משתמשות ב-renderer של Helm עם Skaffold, צריך להשתמש בתחביר הבא לערכי ה-placeholder:

[PROPERTY]: [DEFAULT_VALUE] # from-param: ${VAR_NAME}

בשורה הזו...

• PROPERTY:

  המאפיין של ההגדרה נמצא במניפסט של Kubernetes או ב-YAML של שירות Cloud Run.

• DEFAULT_VALUE

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

• # from-param:

  משתמש בתו הערה כדי להגדיר את ההנחיה deploy-parameters של Cloud Deploy, וההנחיה from-param: מציינת ל-Cloud Deploy שאחריה מופיע placeholder של deploy-parameters.

• ${VAR_NAME}

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

אפשר גם להשתמש בכמה פרמטרים בשורה אחת, ולהשתמש בפרמטרים כחלק ממחרוזת ארוכה יותר, למשל:

image: my-image # from-param: ${artifactRegion}-docker.pkg.dev/my-project/my-repo/my-image@sha256:${imageSha}

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

פרמטרים לערכים של תרשים Helm

אם אתם מעבדים תרשים Helm שמקבל ערכי הגדרה, ואתם רוצים להגדיר את הערכים האלה באמצעות פרמטרים של פריסה, השמות של פרמטרים הפריסה צריכים להיות זהים לשמות של ערכי ההגדרות של Helm שאתם רוצים להגדיר. כל פרמטרים הפריסה מועברים אל Helm כארגומנטים בזמן רינדור, ללא צורך בשינוי של skaffold.yaml.--set

לדוגמה, אם skaffold.yaml מתקין תרשים Helm שמשתמש בפרמטר הגדרה webserver.port כדי לציין את היציאה שבה שרת האינטרנט יתחיל לפעול, ואתם רוצים להגדיר את זה באופן דינמי מפרמטר פריסה, תצטרכו ליצור פרמטר פריסה בשם webserver.port עם הערך שאתם רוצים עבור היציאה של שרת האינטרנט.

לכן, אם אתם לא רק מפנים לתבניות Helm ב-skaffold.yaml, אלא גם יוצרים אותן, אתם יכולים להשתמש בתחביר הרגיל של משתני Helm של {{ .Values.VAR_NAME }} בתבניות Helm.

לדוגמה, אם הגדרנו פרמטר פריסה של webserver.port, נוכל להשתמש בו כך:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: webserver
spec:
  replicas: 3
  selector:
    matchLabels:
      app: webserver
  template:
    metadata:
      labels:
        app: webserver
    spec:
      containers:
      - name: webserver
        image: gcr.io/example/webserver:latest
        ports:
        - containerPort: {{ .Values.webserver.port }} # replaced by deploy parameter `webserver.port`.
          name: web
        env:
        - name: WEBSERVER_PORT
          value: {{ .Values.webserver.port }} # replaced by deploy parameter `webserver.port`.

הוספת פרמטר לשלב בצינור

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

1. מוסיפים את ה-placeholders למניפסט של Kubernetes או לשירות Cloud Run, כמו שמתואר כאן.

   הנה דוגמה:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
    name: nginx-deployment
    labels:
      app: nginx
   spec:
    replicas: 1 # from-param: ${deploy_replicas}
    selector:
      matchLabels:
        app: nginx
    template:
      metadata:
        labels:
          app: nginx
      spec:
        containers:
        - name: nginx
          image: nginx:1.14.2
          ports:
          - containerPort: 80
   

2. מגדירים את צינור עיבוד הנתונים להעברה כך שיכלול את deployParameters בשלב הרלוונטי של צינור עיבוד הנתונים.

   קובץ ה-YAML הבא הוא ההגדרה של שלב בצינור, שהיעד שלו הוא יעד מרובה, שבמקרה הזה יש לו שני יעדי צאצא:

   serialPipeline:
    stages:
      - targetId: dev
        profiles: []
      - targetId: prod  # multi-target
        profiles: []
        deployParameters:
          - values:
              deploy_replicas: 1
              log_level: "NOTICE"
            matchTargetLabels: # optional, applies to all resources if unspecified; AND'd
              my-app: "post-render-config-1"
          - values:
              deploy_replicas: 2
              log_level: "WARNING"
            matchTargetLabels: # optional, applies to all resources if unspecified; AND'd
              my-app: "post-render-config-2"
   

   בהגדרת צינור ההפצה הזו, ה-stanza‏ deployParameters כולל שני values, שלכל אחד מהם יש את המאפיינים הבאים:

   • שם המשתנה, שהוא אותו שם כמו המשתנה שהגדרתם בקובץ המניפסט

   • ערך למשתנה הזה

   • תווית אחת או יותר (אופציונלי) להתאמה לתוויות ספציפיות ליעד

     אם לא מציינים תווית, ב-matchTargetLabels stanza, הערך הזה משמש לכל היעדים בשלב.

3. אם הוספתם matchTargetLabels, אתם צריכים גם להוסיף תוויות ליעדים כדי להתאים אותם. כך תוכלו לזהות איזה ערך להקצות לכל יעד צאצא.

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

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

אחרי שכל מניפסט מעובד, Cloud Deploy מוסיף את הערך של כל משתנה למניפסט המעובד.

הוספת פרמטר להגדרת היעד

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

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

   הנה דוגמה:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
    name: nginx-deployment
    labels:
      app: nginx
   spec:
    selector:
      matchLabels:
        app: nginx
    template:
      metadata:
        labels:
          app: nginx
      spec:
        containers:
        - name: nginx
          image: nginx:1.14.2
          env:
          - name: envvar1
            value: example1 # from-param: ${application_env1}
          - name: envvar2
            value: example2 # from-param: ${application_env2}
   

   במניפסט הזה, הפרמטר envvar1 מוגדר כברירת מחדל ל-example1, והפרמטר envvar2 מוגדר כברירת מחדל ל-example2.

2. מגדירים את היעדים כך שיכללו את deployParameters.

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

   • שם המפתח, שהוא אותו שם כמו המפתח (המשתנה) שהגדרתם בקובץ המניפסט.

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

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

   apiVersion: deploy.cloud.google.com/v1beta1
   kind: Target
   metadata:
     name: prod1
     labels:
       my-app: "post-render-config-1"
   description: development cluster
   deployParameters:
     application_env1: "newValue1"
   ---
   
   apiVersion: deploy.cloud.google.com/v1beta1
   kind: target
   metadata:
     name: prod2
     labels:
       my-app: "post-render-config-2"
   description: development cluster
   deployParameters:
     application_env1: "newValue2"
   

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

העברת פרמטר בזמן יצירת גרסה

כדי להעביר פרמטרים וערכים לגרסה, פועלים לפי השלבים הבאים:

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

   הנה דוגמה:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
    name: nginx-deployment
    labels:
      app: nginx
   spec:
    selector:
      matchLabels:
        app: nginx
    template:
      metadata:
        labels:
          app: nginx
      annotations:
        commit: defaultShaValue # from-param: ${git-sha}
      spec:
        containers:
        - name: nginx
          image: nginx:1.14.2
   

   בדוגמה הזו, ה-SHA של הקומיט מוגדר כמשתנה שנקרא ${git-sha}. ערך של המאפיין הזה מועבר בזמן יצירת הגרסה באמצעות האפשרות --deploy-parameters=, כמו שמוצג בשלב הבא.

   התחביר של המשתנה הזה הוא $ בתוספת שם המשתנה בסוגריים מסולסלים. בדוגמה הזו, זה ${git-sha}.

2. כשיוצרים גרסה, כוללים את האפשרות --deploy-parameters בפקודה gcloud deploy releases create.

   ‫--deploy-parameters מקבלת רשימה מופרדת בפסיקים של צמדי מפתח/ערך, כאשר המפתח הוא הפלייסולדר שהוספתם למניפסט.

   הפקודה תיראה כך:

   gcloud deploy releases create test-release-001 \
   --project=my-example-project \
   --region=us-central1 \
   --delivery-pipeline=my-params-demo-app-1 \
   --images=my-app-image=gcr.io/google-containers/nginx@sha256:f49a843c290594dcf4d193535d1f4ba8af7d56cea2cf79d1e9554f077f1e7aaa \
   --deploy-parameters="git-sha=f787cac"
   
   

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

פריסת פרמטרים באמצעות מיקודים בהתאמה אישית

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

פרמטרים שמיועדים כקלט ליעדים מותאמים אישית יכולים להתחיל ב-customTarget/, לדוגמה customTarget/vertexAIModel. אם משתמשים בקידומת הזו, צריך להשתמש בתחביר הבא כשמפנים לפרמטר פריסה כמשתנה סביבה:

CLOUD_DEPLOY_customTarget_[VAR_NAME]

כאשר VAR_NAME הוא השם שאחרי קו הנטוי בשם פרמטר הפריסה. לדוגמה, אם מגדירים פרמטר פריסה בשם customTarget/vertexAIModel, צריך להפנות אליו כאל CLOUD_DEPLOY_customTarget_vertexAIModel.

פריסת פרמטרים באמצעות ווים של פריסה

אפשר להשתמש בכל פרמטר פריסה כמשתנה סביבה בוובינרים לפריסה.

פריסת פרמטרים עם אימות פריסה

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

הצגת כל הפרמטרים של גרסה

אפשר לראות את הפרמטרים שהוגדרו לפריט תוכן מסוים. הם מוצגים בטבלה בדף פרטי פריט התוכן ובשורת הפקודה (gcloud deploy releases describe).

1. בדף הראשי של Cloud Deploy, לוחצים על צינור העברת התוכן שכולל את הגרסה שרוצים לראות.

2. בדף Release details, בוחרים בכרטיסייה Artifacts.

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

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

• אפשר לנסות את המדריך להתחלה מהירה: שימוש בפרמטרים של פריסה.

• מידע נוסף על שימוש בפריסות מקבילות