שימוש בפרטי כניסה מוצפנים מ-Cloud KMS

‫Cloud Key Management Service הוא שירות Google Cloud שמאפשר לכם לנהל ולהשתמש במפתחות קריפטוגרפיים. בדף הזה מוסבר איך להשתמש במידע מוצפן מ-Cloud KMS ב-Cloud Build.

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

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

• מפעילים את Cloud Build API ואת Cloud KMS API.

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

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

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

• כדי להשתמש בדוגמאות של שורת הפקודה במדריך הזה, צריך להתקין ולהגדיר את Google Cloud CLI.

  הערה: אם התקנתם את ה-CLI של gcloud בעבר, צריך לוודא שפועלת אצלכם הגרסה העדכנית ביותר של gcloud components update.

• הצפנה של המידע האישי הרגיש באמצעות Cloud KMS. ‫Cloud KMS שומר את התוכן המוצפן בקובץ.

• [אופציונלי] כדי להגדיר את ה-build כך שישתמש בנתונים מוצפנים, ממירים את ENCRYPTED_FILE ל-base64 (השלב הזה לא נדרש להגדרות build שמשתמשות בקבצים מוצפנים):

      base64 ENCRYPTED_FILE
  

הרשאות IAM נדרשות

מקצים לחשבון השירות של ה-Build את תפקיד ה-IAM‏ Cloud KMS CryptoKey Decrypter (roles/cloudkms.cryptoKeyDecrypter):

1. במסוף Google Cloud , נכנסים לדף Settings של Cloud Build:

   פתיחת דף ההגדרות

2. מאתרים את השורה עם התפקיד Cloud KMS CryptoKey Decrypter ומגדירים את הסטטוס שלו ל-ENABLED.

אזהרה: מתן התפקיד Cloud KMS CryptoKey Decrypter לחשבון השירות שמוגדר כברירת מחדל ב-Cloud Build מאפשר לחשבון השירות לפענח את המידע המוצפן. טריגרים של גרסאות build משתמשים בחשבון השירות שמוגדר כברירת מחדל ב-Cloud Build כדי להריץ גרסאות build. לכן, לכל משתמש שמשתמש בטריגרים של build כדי להריץ גרסאות build יהיו הרשאות שניתנו לחשבון השירות בזמן ה-build. כך משתמשים בלי התפקיד CryptoKey Decrypter יכולים להשתמש בטריגרים של בנייה כדי לבצע בנייה שמפענחת את המידע המוצפן. הפעולה הזו מתועדת בהיסטוריית הבנייה של הפרויקט.

הגדרת בנייה לשימוש בנתונים מוצפנים

1. בתיקיית השורש של הפרויקט, יוצרים קובץ הגדרות build של Cloud Build בשם cloudbuild.yaml או cloudbuild.json.

2. בקובץ תצורת ה-build:

   • אחרי כל גרסת build steps, מוסיפים שדה availableSecrets כדי לציין את הערך המוצפן כמשתנה סביבה ואת kmsKeyName שבו יש להשתמש כדי לפענח אותו. אפשר להשתמש במשתני החלפה בערך של kmsKeyName.
   • בשלב הבנייה שבו רוצים לציין את הסוד:
     • כדי להשתמש בכלי bash בשלב build, מוסיפים שדה entrypoint שמפנה אל bash. הפעולה הזו נדרשת כדי להתייחס למשתנה הסביבה של הסוד.
     • מוסיפים שדה secretEnv שבו מציינים את משתנה הסביבה של הערך המוצפן.
     • בשדה args, מוסיפים את הדגל -c כארגומנט הראשון. כל מחרוזת שמעבירים אחרי ‎-c נחשבת לפקודה. מידע נוסף על הפעלת פקודות bash עם ‎-c זמין במסמכי התיעוד של bash.
     • כשמציינים את הערך המוצפן בשדה args, צריך לציין אותו באמצעות משתנה הסביבה עם הקידומת $$.
   Note: You can refer to encrypted values using environment variables only in the args field of a build step.

   The following example build config file shows how to login to Docker and pull a private image:

   YAML

    steps:
    - name: 'gcr.io/cloud-builders/docker'
      entrypoint: 'bash'
      args: ['-c', 'docker login --username=$$USERNAME --password=$$PASSWORD']
      secretEnv: ['USERNAME', 'PASSWORD']
    - name: 'gcr.io/cloud-builders/docker'
      entrypoint: 'bash'
      args: ['-c', 'docker pull $$USERNAME/IMAGE:TAG']
      secretEnv: ['USERNAME']
    availableSecrets:
      inline:
      - kmsKeyName: projects/PROJECT_ID/locations/global/keyRings/USERNAME_KEYRING_NAME/cryptoKeys/USERNAME_KEY_NAME
        envMap:
          USERNAME: 'ENCRYPTED_USERNAME'
      - kmsKeyName: projects/PROJECT_ID/locations/global/keyRings/PASSWORD_KEYRING_NAME/cryptoKeys/PASSWORD_KEY_NAME
        envMap:
          PASSWORD: 'ENCRYPTED_PASSWORD'
   
    JSON 
   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker login --username=$$USERNAME --password=$$PASSWORD"
       ],
       "secretEnv": [
         "USERNAME",
         "PASSWORD"
       ]
     },
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker pull $$USERNAME/REPOSITORY:TAG"
        ],
        "secretEnv": [
         "USERNAME"
       ]
     }
     ],
     "availableSecrets": {
       "inline": [{
         "kmsKeyName":  "projects/PROJECT_ID/locations/global/keyRings/USERNAME_KEYRING_NAME/cryptoKeys/USERNAME_KEY_NAME",
         "envMap": {
           "USERNAME": "ENCRYPTED_USERNAME"
          }
      },
      {
       "kmsKeyName": "projects/PROJECT_ID/locations/global/keyRings/PASSWORD_KEYRING_NAME/cryptoKeys/PASSWORD_KEY_NAME",
       "envMap": {
           "PASSWORD": "ENCRYPTED_PASSWORD"
          }
      }]
    }
   }
   
   

   Replace the placeholder values in the above commands with the following:

   • PROJECT_ID: The ID of the Google Cloud project which contains your Cloud KMS service.
   • USERNAME_KEYRING_NAME: The key ring name of your Docker username.
   • USERNAME_KEY_NAME: The key name of your Docker username.
   • ENCRYPTED_USERNAME: Your encrypted Docker username in base64 format.
   • PASSWORD_KEYRING_NAME: The key ring name of your Docker password.
   • PASSWORD_KEY_NAME: The key name of your Docker password.
   • ENCRYPTED_PASSWORD: Your encrypted Docker password in base64 format.
   • REPOSITORY: The name of your Docker repository from where you're pulling the image.

   • TAG: The tag name of your image.

     Note: The secretEnv field does not support substitution variables. If the Google Cloud project hosting the key changes, the encrypted contents within that project also change.

3. Use the build config file to manually start a build or to automate builds using triggers.

Configuring builds to use encrypted files

1. In your project root directory, create a Cloud Build build config file named cloudbuild.yaml or cloudbuild.json.

2. In your build config file, before any build steps that interact with the decrypted file, add a gcloud build step to decrypt the encrypted file using the encryption key. The following example build config file shows how to login to Docker using the encrypted file with Docker password:

   YAML

   steps:
   - name: gcr.io/cloud-builders/gcloud
     args:
     - kms
     - decrypt
     - "--ciphertext-file=ENCRYPTED_PASSWORD_FILE"
     - "--plaintext-file=PLAINTEXT_PASSWORD_FILE"
     - "--location=global"
     - "--keyring=KEYRING_NAME"
     - "--key=KEY_NAME"
   - name: gcr.io/cloud-builders/docker
     entrypoint: bash
     args:
     - "-c"
     - docker login --username=DOCKER_USERNAME --password-stdin < PLAINTEXT_PASSWORD_FILE
   

   JSON

   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/gcloud",
       "args": [
         "kms",
         "decrypt",
         "--ciphertext-file=ENCRYPTED_PASSWORD_FILE",
         "--plaintext-file=PLAINTEXT_PASSWORD_FILE",
         "--location=global",
         "--keyring=KEYRING_NAME",
         "--key=KEY_NAME"
       ]
     },
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker login --username=DOCKER_USERNAME --password-stdin < PLAINTEXT_PASSWORD_FILE"
       ]
      }
     ]
   }
   

   Replace the placeholder values in the above commands with the following:

   • KEYRING_NAME: The key ring name of your Docker password.
   • KEY_NAME: The key name of your Docker password.
   • ENCRYPTED_PASSWORD_FILE: Encrypted file with your Docker password.
   • PLAINTEXT_PASSWORD_FILE: Plaintext file with your Docker password.

3. Use the build config file to manually start a build or to automate builds using triggers.

Configuring builds to use encrypted data (legacy)

Warning: This is the legacy method of using Cloud KMS with Cloud Build. This method will continue to work, but we recommend that you use the newer way of configuring builds to use encrypted data.

To encrypt sensitive data using Cloud KMS and use that data in a build config file:

1. In your build config file, add a secrets field to specify the encrypted value and the CryptoKey to use to decrypt it. Then, in the build step where you want to use the encrypted variable, add a secretEnv field to specify the variable as an environment variable. Include the variable's name in the secretEnv field. If you specify the variable value, or a non-secret environment variable with the same name, Cloud Build throws an error.

   YAML

   steps:
   - name: 'gcr.io/cloud-builders/docker'
     entrypoint: 'bash'
     args: ['-c', 'docker login --username=user-name --password=$$PASSWORD']
     secretEnv: ['PASSWORD']
   - name: 'gcr.io/cloud-builders/docker'
     args: ['push', 'user-name/myubuntu']
   secrets:
   - kmsKeyName: projects/project-id/locations/global/keyRings/keyring-name/cryptoKeys/key-name
     secretEnv:
       PASSWORD: 'encrypted-password'
   

   JSON

   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker login --username=user-name --password=$$PASSWORD"
       ],
       "secretEnv": [
         "PASSWORD"
        ]
      },
      {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
          "push",
          "user-name/myubuntu"
         ]
      }
      ],
      "secrets": [
      {
        "kmsKeyName": "projects/project-id/locations/global/keyRings/keyring-name/cryptoKeys/key-name",
        "secretEnv": {
          "PASSWORD": "encrypted-password"
        }
      }
      ]
   }
   

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

• איך מגדירים את ה-builds כך שתהיה להם גישה לסודות מ-Secret Manager
• איך מקבלים גישה למאגרים פרטיים ב-GitHub