設定 Secret (第 1 代)

您可以使用 Secret Manager 安全地儲存 API 金鑰、密碼和其他機密資訊。本指南說明如何設定 Cloud Run functions，存取儲存在 Secret Manager 中的 Secret。

本文將介紹兩種將 Secret 提供給函式使用的方法：

• 將 Secret 掛接為磁碟區，如此可讓函式以檔案形式存取 Secret。如果將 Secret 參照為磁碟區，函式每次從磁碟讀取檔案時，都會從 Secret Manager 存取 Secret值。若要參照最新版本而非固定版本的 Secret，將 Secret 掛接為磁碟區就是個好策略。若您規劃實作 Secret 輪換，也很適合採用這種方法。

• 以環境變數形式傳遞 Secret。系統會在執行個體啟動時解析環境變數值，如果使用這個方法，建議參照固定版本而非最新版本的 Secret。

想進一步瞭解如何使用 Secret Manager，請參閱「Secret Manager 總覽」。如要瞭解如何建立及存取 Secret，請參閱「建立 Secret」。

事前準備

1. Enable the Secret Manager API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

2. 如果是初次操作，請按照「建立 Secret」一文的說明，在 Secret Manager 中建立 Secret。

授予 Secret 存取權限

函式可存取相同專案或其他專案中的 Secret。如要存取 Secret，必須向函式的執行階段服務帳戶授予 Secret 存取權限。

根據預設，Cloud Run functions 會使用預設 App Engine 服務帳戶向 Secret Manager 進行驗證。若要用於正式環境，Google 建議將函式設定為透過使用者自行管理的服務帳戶進行驗證，並依照函式任務的需求，指派一組必要的最低權限角色。

如要搭配 Cloud Run functions 使用 Secret Manager，請將 roles/secretmanager.secretAccessor 角色指派給函式相關聯的服務帳戶：

1. 前往 Google Cloud 控制台的「Secret Manager」頁面：
   前往 Secret Manager

2. 按一下 Secret 旁邊的核取方塊。

3. 若面板尚未開啟，請按一下「Show Info Panel」(顯示資訊面板) 以開啟面板。

4. 在資訊面板中，按一下「Add Principal」(新增主體)。

5. 在「New principals」(新增主體) 欄位中，輸入函式所用服務帳戶的識別資訊。函式的服務帳戶為下列其中之一：

   • 在部署時指派給函式的使用者自行管理服務帳戶。如要瞭解如何透過使用者自行管理服務帳戶部署函式，請參閱「為函式使用個別服務帳戶」。

   • App Engine 預設服務帳戶 (不建議用於正式環境)。

6. 在「Select a role」(請選擇角色) 下拉式選單中，依序選擇「Secret Manager」和「Secret Manager Secret Accessor」(Secret Manager 密鑰存取者)。

準備函式以存取 Secret

有兩種方法可將 Secret 提供給函式使用：

• 以環境變數形式傳遞 Secret。
• 將 Secret 掛接為磁碟區。

環境變數

使用環境變數為函式提供 Secret 的方法如下：

1. 在函式部署期間設定執行階段環境變數。
2. 將 Secret 設為環境變數以供函式存取。
3. 在執行階段透過程式輔助來存取環境變數。

將 Secret 掛接為磁碟區。

將 Secret 掛接為磁碟區的方法如下：

1. 建立一個包含 Secret 的檔案。

2. 選擇未使用的非系統目錄 (例如 /mnt/secrets) 作為 Secret 的掛接路徑。掛接 Secret 後，除了 Secret 及其版本以外，該目錄下的任何既有檔案或子目錄都會變得無法存取。

3. 將 Secret 設為掛接磁碟區以供函式存取。

4. 在執行階段透過程式輔助來讀取檔案內容，以存取 Secret 值。

例如，Secret 若已掛接至 /mnt/secrets/secret1，則函式必須讀取此檔案。以下是使用 Node.js 同步讀取檔案的範例：

fs.readFileSync('/mnt/secrets/secret1')

讓函式存取 Secret

如要從函式參照 Secret，必須先讓函式存取 Secret。您可以使用 Google Cloud 控制台或 Google Cloud CLI，讓新建或既有的函式存取 Secret：

控制台

讓函式存取 Secret 的方法如下：

1. 前往 Google Cloud 控制台的 Cloud Run functions 頁面：
   前往 Cloud Run functions 頁面

2. 按一下要存取 Secret 的函式名稱。

3. 按一下「Edit」(編輯)。

4. 點按「Runtime, build…」(執行階段，版本…)，展開進階設定選項。

5. 按一下「Security and image repo」(安全性和映像檔存放區) 以開啟分頁。

6. 按一下「Add a Secret Reference」(新增 Secret 參照設定) 來設定函式要使用的 Secret。

7. 選取要讓函式存取的 Secret。如有需要，請自行建立 Secret。

   • 如要參照與函式位於同一專案中的 Secret：

     1. 從下拉式清單中選取 Secret。

   • 如要參照其他專案中的 Secret：

     1. 確認專案的服務帳戶已取得 Secret 存取權限。

     2. 選取「Enter secret manually」(手動輸入 Secret)。

     3. 請輸入 Secret 的資源 ID，格式如下：

        projects/PROJECT_ID/secrets/SECRET_NAME

        更改下列內容：

        • PROJECT_ID：Secret 所在的專案 ID。

        • SECRET_NAME：Secret Manager 中的 Secret 名稱。

8. 選取 Secret 的參照方法。您可以將 Secret 掛接為磁碟區或將其設為環境變數。

   • 將 Secret 掛接為磁碟區的方法如下：

     1. 選取「Mounted as volume」(掛接為磁碟區)。

     2. 在「Mount path」(掛接路徑)欄位輸入此 Secret 的掛接路徑。所有 Secret 版本都會放置在此目錄下。

     3. 在「Path1」欄位中輸入要掛接的檔案名稱。此名稱會與上一步驟中的掛接路徑串連，形成 Secret 的完整掛接路徑。

     4. 從「Version1」下拉式選單選取要參照的 Secret 版本。

     5. 如要掛接此 Secret 的其他版本，請按一下「+Add」(+新增) 以定義其他路徑和要掛接的 Secret 版本。

   • 將 Secret 設定為環境變數的方法如下：

     1. 選取「Exposed as environment variable」(設為環境變數)。

     2. 在「Name1」欄位輸入環境變數的名稱。

     3. 從「Version1」下拉式選單選取要參照的 Secret 版本。

     4. 如要向函式提供此 Secret 的其他版本，請按一下「+Add」(+新增)以定義其他環境變數，以及要儲存於其中的 Secret 版本。

9. 點按「Done」(完成)。

10. 點按「Next」(下一步)。

11. 點按「Deploy」(部署)。

此時，函式的程式碼即可參照 Secret。

gcloud

如要讓函式存取 Secret，請輸入下列其中一個指令。

• 如要將 Secret 掛接為磁碟區，請輸入下列指令：

  gcloud functions deploy FUNCTION_NAME \
  --no-gen2 \
  --runtime RUNTIME \
  --set-secrets 'SECRET_FILE_PATH=SECRET:VERSION'
  

  更改下列內容：

  • FUNCTION_NAME：函式名稱。

  • RUNTIME：函式所屬的執行階段。

  • SECRET_FILE_PATH：Secret 的完整路徑。以 /mnt/secrets/primary/latest 為例，/mnt/secrets/primary/ 是掛接路徑，latest 則是 Secret 路徑。您也可以分別指定掛接路徑和 Secret 路徑：

    --set-secrets 'MOUNT_PATH:SECRET_PATH=SECRET:VERSION'

  • SECRET：Secret Manager 中的 Secret 名稱。

  • VERSION：要使用的 Secret 版本。例如：1 或 latest。

  --set-secrets 旗標會覆寫所有現有 Secret。如要保留函式現有的 Secret，請改用 --update-secrets 旗標。

• 如要將 Secret 設為環境變數，請輸入下列指令：

  gcloud functions deploy FUNCTION_NAME \
  --no-gen2 \
  --runtime RUNTIME \
  --set-secrets 'ENV_VAR_NAME=SECRET:VERSION'
  

  更改下列內容：

  • FUNCTION_NAME：函式名稱。

  • RUNTIME：函式所屬的執行階段。

  • ENV_VAR_NAME：環境變數的名稱。

  • SECRET：Secret Manager 中的 Secret 名稱。

  • VERSION：要使用的 Secret 版本。例如：1 或 latest。

  --set-secrets 旗標會覆寫所有現有 Secret。如要保留函式現有的 Secret，請改用 --update-secrets 旗標。

• 如果函式的服務帳戶已取得 Secret 存取權限，就可以參照其他專案中的 Secret。如要參照其他專案中的 Secret，請使用 Secret 的資源路徑：

  gcloud functions deploy FUNCTION_NAME \
  --no-gen2 \
  --runtime RUNTIME \
  --update-secrets 'SECRET_FILE_PATH=SECRET_RESOURCE_PATH:VERSION'
  

  更改下列內容：

  • FUNCTION_NAME：函式名稱。

  • SECRET_RESOURCE_PATH：位於其他專案的 Secret 資源路徑。資源路徑的格式如下：

    projects/PROJECT_ID/secrets/SECRET_NAME

    更改下列內容：

    • PROJECT_ID：Secret 所在的專案 ID。

    • SECRET_NAME：Secret Manager 中的 Secret 名稱。

  • RUNTIME：函式所屬的執行階段。

  • SECRET_FILE_PATH：Secret 的完整路徑。以 /mnt/secrets/primary/latest 為例，/mnt/secrets/primary/ 是掛接路徑，latest 則是 Secret 路徑。您也可以分別指定掛接路徑和 Secret 路徑：

    --set-secrets 'MOUNT_PATH:SECRET_PATH=SECRET:VERSION'

  • SECRET：Secret Manager 中的 Secret 名稱。

  • VERSION：要使用的 Secret 版本。例如：1 或 latest。

• 您可以一次更新多個 Secret。請以半形逗號分隔每個 Secret 的設定選項。下列指令會更新一個掛接為磁碟區的 Secret，以及另一個設為環境變數的Secret。

  如要更新現有 Secret，請輸入下列指令：

  gcloud functions deploy FUNCTION_NAME \
  --no-gen2 \
  --runtime RUNTIME \
  --update-secrets 'ENV_VAR_NAME=SECRET:VERSION, \
  SECRET_FILE_PATH=SECRET:VERSION'
  

  更改下列內容：

  • FUNCTION_NAME：函式名稱。

  • RUNTIME：函式所屬的執行階段。

  • ENV_VAR_NAME：環境變數的名稱。

  • SECRET：Secret Manager 中的 Secret 名稱。

  • VERSION：要使用的 Secret 版本。例如：1 或 latest。

  • SECRET_FILE_PATH：Secret 的完整路徑。以 /mnt/secrets/primary/latest 為例，/mnt/secrets/primary/ 是掛接路徑，latest 則是 Secret 路徑。您也可以分別指定掛接路徑和 Secret 路徑：

    --set-secrets 'MOUNT_PATH:SECRET_PATH=SECRET:VERSION'

從函式中移除 Secret

您可以使用 Google Cloud 控制台或 gcloud CLI 來移除函式中的 Secret：

控制台

1. 前往 Google Cloud 控制台的 Cloud Run functions 頁面：
   前往 Cloud Run functions 頁面

2. 按一下函式名稱，移除其中一個 Secret。

3. 按一下「Edit」(編輯)。

4. 點按「Runtime, build and connections settings」(執行階段、建構和連線設定) 以展開進階設定選項。

5. 按一下「Security and image repo」(安全性和映像檔存放區) 以開啟分頁。

6. 將指標懸停在要移除的 Secret 上，然後按一下「Delete」(刪除)。

7. 點按「Next」(下一步)。

8. 點按「Deploy」(部署)。

gcloud

您可以移除函式的所有 Secret，或指定移除其中一或多個 Secret：

• 如要移除所有 Secret，請執行下列指令：

  gcloud functions deploy FUNCTION_NAME \
  --no-gen2 \
  --runtime RUNTIME \
  --clear-secrets
  

  更改下列內容：

  • FUNCTION_NAME：函式名稱。

  • RUNTIME：函式所屬的執行階段。

  系統會清除函式中的所有 Secret。

• 如需指定要移除的 Secret 清單，請使用 --remove-secrets 旗標。下列指令會移除一個掛接為磁碟區的 Secret，以及另一個設為環境變數的 Secret：

  gcloud functions deploy FUNCTION_NAME \
  --no-gen2 \
  --runtime RUNTIME \
  --remove-secrets='ENV_VAR_NAME,SECRET_FILE_PATH, ...'
  

  更改下列內容：

  • FUNCTION_NAME：函式名稱。

  • RUNTIME：函式所屬的執行階段。

  • ENV_VAR_NAME：環境變數的名稱。

  • SECRET_FILE_PATH：Secret 的完整路徑。以 /mnt/secrets/primary/latest 為例，/mnt/secrets/primary/ 是掛接路徑，latest 則是 Secret 路徑。您也可以分別指定掛接路徑和 Secret 路徑：

    --set-secrets 'MOUNT_PATH:SECRET_PATH=SECRET:VERSION'

  系統會移除函式中指定的 Secret。

查看函式可存取的 Secret

您可以使用 Google Cloud 控制台或 gcloud CLI 查看函式可存取的Secret：

控制台

1. 前往 Google Cloud 控制台的 Cloud Run functions 頁面：
   前往 Cloud Run functions 頁面

2. 點按函式名稱即可查看可用的 Secret。

3. 按一下「Edit」(編輯)。

4. 點按「Runtime, build and connections settings」(執行階段、建構和連線設定) 以展開進階設定選項。

5. 按一下「Security」(安全性)以開啟安全性分頁。

安全性分頁會列出函式可存取的 Secret。

gcloud

如要查看函式可用的 Secret，請使用 gcloud functions describe 指令：

gcloud functions describe FUNCTION_NAME

請將 FUNCTION_NAME 替換成函式名稱。

後續步驟

• 建議您使用 Secret Manager 用戶端程式庫來開發使用 Secret Manager 的函式。