為管線資料設定 COS

若要將 COS 與 pipelinectl 檔案操作功能搭配使用，請完成以下設定步驟：

1. 建立資料儲存桶

• 您可以使用現有的 Cloud Object Storage 實例，或建立一個新的實例。 請依照《 Cloud Object Storage 設定指南 》中的指示，執行以下操作：
• 建立一個資料儲存桶（必須與您的證據儲存桶分開）
• 為儲存桶建立服務憑證

2. 設定 IAM 權限

請為您的資料儲存桶服務憑證指派以下角色：寫入者、物件寫入者、讀取者及內容讀取者。

如需詳細說明，請參閱「儲存桶存取權限」。

3. 設定環境屬性

請將以下環境屬性新增至您的 DevSecOps 管線中：

要查找您的 COS 端點 URL，請前往儲存桶的 「設定」 頁面，並複製該儲存桶所在區域的端點（例如：s3.us-south.cloud-object-storage.appdomain.cloud ）。為獲得更好的效能與安全性，請盡可能使用直接端點或私有端點。

請將 API 金鑰儲存為安全屬性，以保護敏感的憑證資訊。

4. 設定儲存桶的生命週期（建議）

設定生命週期政策，以自動刪除舊的管道資料。 建議對大多數管線資料採用 7 天過期規則。 有關說明，請參閱「生命週期政策」。

了解 COS 資料範圍

與 save_result 和 set_env 指令不同，後者會自動限定於個別的管線執行範圍內；而使用 COS 後端（--storage=cos ）的檔案操作，則是在一個共享儲存桶上進行，該儲存桶會持續存在於所有管線執行之間。

關鍵行為：

無自動執行隔離：來自不同管線執行程序且使用相同金鑰儲存的檔案會互相覆寫。

共用儲存桶命名空間：所有使用相同 COS 設定的管線執行皆共用同一個儲存桶命名空間。

持久儲存：檔案會保留在 COS 中，直到被明確刪除，或因儲存桶生命週期規則而過期為止。

範圍比較：

當您使用 list_files --storage=cos`` 時，此指令會返回已設定儲存桶中的所有檔案，而不僅是當前管線執行所產生的檔案。 使用前綴篩選來縮小搜尋結果範圍。

COS 檔案操作的最佳實務

請遵循以下最佳實務，以在 Cloud Object Storage 中有效率地整理和管理檔案，並避免意外覆寫資料。

# Pipeline Run 1
save_file --storage=cos build-artifact ./dist/app-v1.0.0.tar.gz
# Pipeline Run 2 (overwrites Run 1's file!)
save_file --storage=cos build-artifact ./dist/app-v2.0.0.tar.gz

# Pipeline Run 1
save_file --storage=cos "build-artifact-${PIPELINE_RUN_ID}" ./dist/app-v1.0.0.tar.gz
# Pipeline Run 2 (separate key, no conflict)
save_file --storage=cos "build-artifact-${PIPELINE_RUN_ID}" ./dist/app-v2.0.0.tar.gz

# Good: Organized, descriptive
save_file --storage=cos "artifacts/build/${PIPELINE_RUN_ID}/app.tar.gz" ./dist/app.tar.gz
save_file --storage=cos "reports/security/${BUILD_NUMBER}/scan.json" ./scan-results.json
# Avoid: Flat, generic
save_file --storage=cos "artifact" ./dist/app.tar.gz

# Good: Clear purpose
save_file --storage=cos "ui-service-image-${VERSION}" ./image.tar
# Avoid: Ambiguous
save_file --storage=cos "img" ./image.tar

# List all artifacts for a specific project
list_files --storage=cos "myproject/artifacts/"
# List security reports for a specific date
list_files --storage=cos "reports/security/2024-01-15"

remove_file --storage=cos "temp/build-${PIPELINE_RUN_ID}/cache.tar"

安全考量

• API 金鑰管理：請務必將 data-cos-api-key 儲存為安全屬性。 切勿在腳本或設定檔中硬編碼 API 金鑰。
• 最小權限原則：僅授予上述所列的最低必要 IAM 權限。
• 儲存桶分離：請為管道資料使用專用的儲存桶，並與您的證據儲存桶分開。

設定環境變數

# <key>: The name of the environment variable e.g. pipeline-namespace, app-name
# <value>: Value of the key
set_env <key> # reads <value> from `stdin`
set_env <key> <value>

儲存一串任意字串，日後可透過 get_env. 符號檢索該字串。

若 <value> 未提供參數 set_env，則從標準輸入讀取。set_env 同時支援一次傳遞多個鍵值對進行設定。

範例：

# set value provided as argument
set_env app-name "my-app-name"
# set value provided via stdin
echo "my-app-name" | set_env app-name
set_env my-api-key < /config/my-api-key
# set multiple key value pairs
set_env key-1 "value-1" \
  key-2 "value-2" \
  key-n "value-n"

設定環境變數

# <key>: The name of the environment variable e.g. pipeline-namespace, app-name
# <value>: Value of the key
set_envc <key> # reads <value> from `stdin`
set_envc <key> <value>

儲存一個不可變的任意字串，日後可透過 get_env. 取回。 一旦以 儲存，便無法透過後續的 set_env``set_envc / set_envc 呼叫進行修改。

若 <value> 未提供參數 set_envc，則從標準輸入讀取。set_envc 同時支援一次傳遞多個鍵值對進行設定。

• 一旦透過 設定 set_envc，該鍵便無法透過後續的 set_envc 或 呼叫進行 set_env 覆寫。
• 已透過 set_env 設定過的變數，無法再以 set_envc. 覆寫。

範例：

# set value provided as argument
set_envc app-name "my-app-name"
# set value provided via stdin
echo "my-app-name" | set_envc app-name
set_envc my-api-key < /config/my-api-key
# set multiple key value pairs
set_envc key-1 "value-1" \
  key-2 "value-2" \
  key-n "value-n"

取得環境變數

# <key>: The name of the environment variable e.g. pipeline-namespace, app-name
get_env <key> [default]

列印儲存的配置值 (依此順序):

• 如果 set_env 先前與 key 搭配使用，則它會擷取該值
• 它會嘗試讀取檔案 $CONFIG_DIR/$key (CONFIG_DIR 預設為 /config)
• 它會列印指定的預設值 (如果有的話)
• 它會列印錯誤訊息，並傳回非零結束碼

範例：

get_env app-name "default-app-name"

清單環境

list_env

顯示 set_env 進程中儲存的金鑰和環境變數。

範例：

list_env

設定密鑰

# <key>: The name of the secret e.g. artifactory-token, (short-lived) iam-token
# <value>: Value of the secret
set_secret <key> # reads <value> from `stdin`
set_secret <key> <value>

儲存秘密，稍後可以使用 get_secret.

如果缺少 <value> 參數，set_secret 會從標準輸入讀取。

• set_secret 設定的內容不會被序列化，因此無法跨子管道 / async pipelineruns 使用。
• 請停用此命令執行過程中的除錯記錄，以確保儲存的機密內容即使在除錯日誌中也不會顯示。
• 確保腳本和任何邏輯不依賴 set_secret 的任何輸出（利用 ::add-mask:: 功能 列印語句來遮蔽秘密值）

範例：

# set value provided as argument
set_secret my-secret-key "my-secret-content"
# set value provided via stdin
echo "my-secret-content" | set_secret my-secret
set_secret my-api-key < /config/my-api-key
# set multiple key value pairs
set_secret secret-key-1 "value-1" \
  secret-key-2 "value-2" \
  secret-key-n "value-n"

取得密鑰

# <key>: The name of the secret set with set_secret or set as Secure Value in pipeline UI
get_secret <key> [default]

讀取儲存的秘密值（依此順序）：

• 如果 set_secret 先前與 key 搭配使用，則它會擷取該值
• 它會嘗試讀取檔案 $SECRET_CONFIG_DIR/$key (SECRET_CONFIG_DIR 預設為 /config/secure-properties)
• 它會列印指定的預設值 (如果有的話)
• 它會列印錯誤訊息，並傳回非零結束碼

範例：

get_secret cookie-token "default-token"

get_secret specific-account-ibmcloud-api-key "$(get_secret ibmcloud-api-key "")"

export API_KEY=$(get_secret my-api-key)
# Unsafe: a multi-line secret value is not passed intact.
# Parts of the secret may appear unmasked in the pipeline log.
some-cli login --apikey $API_KEY

export API_KEY=$(get_secret my-api-key)
# Safe: the value is passed as a single, intact string.
some-cli login --apikey "$API_KEY"

# Safe
curl -H "Authorization: Bearer $API_KEY" https://example.com/api
echo "$API_KEY" > /tmp/credentials.txt

清單秘密

list_secrets

顯示 set_secret 程序中儲存的金鑰，以及管道使用者介面中的 Secure Value 類型環境變數。

範例：

list_secrets

移除秘密

remove_secret <key>

此指令會取消設定儲存在 pipelinectl 內的秘密，這些秘密是使用 set_secret 保存的。

儲存檔案

# <identifier>: Name used to store and retrieve the file (for example, 'build-artifact', 'my-report')
# <path>: Path to the file on the local filesystem (for example, './dist/app.tar.gz')
save_file <identifier> <path>

儲存可稍後使用 load_file 擷取的任意檔案。

不支援目錄。

本地儲存 (預設)：

檔案儲存於管線工作區中，且其作用範圍僅限於當前的管線執行。

save_file some_config ./config.yaml

COS 儲存：

檔案儲存於 Cloud Object Storage，並會在各次管線執行間持續保留。 請參閱「資料範圍與持久性」以了解有關共用儲存桶行為的重要資訊。

先決條件：請確保已設定 COS。 請參閱 Cloud Object Storage 的設定。

# Save with run-specific key
save_file --storage=cos "build-artifact-${PIPELINE_RUN_ID}" ./dist/app-v1.2.3.tar.gz
# Save with hierarchical key
save_file --storage=cos "artifacts/ui-service/${BUILD_NUMBER}/image.tar" ./image.tar
# Save report with timestamp
save_file --storage=cos "reports/security/$(date +%Y%m%d)/scan.json" ./scan-results.json

載入檔案

# <identifier>: Name of the file to retrieve (for example, 'build-artifact', 'my-report')
load_file <identifier>

將已儲存的檔案列印至 stdout。

本地儲存 (預設)：

檢索儲存於當前執行程序的管線工作區中的檔案。

load_file some_config > some_config.yaml

COS 儲存：

從 Cloud Object Storage 擷取檔案。

先決條件：請確保已設定 COS。 請參閱 Cloud Object Storage 的設定。

# Load file and print to stdout
load_file --storage=cos "build-artifact-${PIPELINE_RUN_ID}"
# Load file and save to local filesystem
load_file --storage=cos "artifacts/ui-service/${BUILD_NUMBER}/image.tar" > ./downloaded-image.tar

檔案清單

列出透過 save_file 儲存的所有儲存檔案，可選擇以 key prefix 篩選。

# <prefix>: (optional) Filter results to keys starting with this prefix
list_files <prefix>

將檔案金鑰清單輸出至 stdout。

本地儲存 (預設)：

列出當前執行階段中儲存於管線工作區的檔案。

list_files # lists all saved files
list_files saved-reports- # lists files with "saved-reports-" prefix

COS 儲存：

列出 Cloud Object Storage 中的檔案。 會返回設定的儲存桶中的所有檔案，而不僅限於當前管線執行所產生的檔案。 使用可選的前綴參數來篩選結果，並鎖定特定檔案。

先決條件：請確保已設定 COS。 請參閱 Cloud Object Storage 的設定。

# List all files in bucket (may include files from multiple runs)
list_files --storage=cos
# List files with specific prefix to narrow results
list_files --storage=cos "artifacts/ui-service/"
# List files for specific date
list_files --storage=cos "reports/security/20240115"

移除檔案

刪除儲存的檔案。

# <identifier>: Name of the file to remove (for example, 'build-artifact', 'my-report')
remove_file <identifier>

本地儲存 (預設)：

從當前執行階段的管線工作區中移除檔案。

remove_file my-report

COS 儲存：

從 Cloud Object Storage 移除檔案。

先決條件：請確保已設定 COS。 請參閱 Cloud Object Storage 的設定。

# Remove specific file
remove_file --storage=cos "build-artifact-${PIPELINE_RUN_ID}"
# Remove temporary file
remove_file --storage=cos "temp/cache-${BUILD_NUMBER}.tar"

儲存儲存庫

# <key>:  Key of the repository e.g. repository name
# <prop>: Type of the property, e.g. url, branch, commit etc.
# <value>: Value of the property
save_repo <key> [<prop>=<value> ...]

向管線登錄新的儲存庫，或更新現有的儲存庫。

支援的內容:

• url:可以用來克隆儲存庫的 URL。
• path: 所複製儲存庫相對於工作區根目錄的位置。

其他內容名稱也可以使用，但為了避免命名衝突，它們必須以服務特定 ID 作為字首，例如，不要使用 foo，請使用 my-service.foo。

範例：

save_repo app_ui "url=${REPO_URL}" "path=app_ui_repo"
save_repo app_ui "branch=${REPO_BRANCH}"
save_repo app_ui "commit=${REPO_SHA}"
# any additional property can be added
save_repo app_ui "commit=${REPO_SHA}"

command_with_large_output | save_repo app_ui "issues"
# this also works with multiple properties,
# but stdin can provide value for only a single one
command_with_large_output | save_repo app_ui "issues" "result=success" "commit=${REPO_SHA}"

save_repo app_ui "bar="
load_repo app_ui bar # returns an empty string

清單

list_repos

列出 stdout 所儲存儲存庫的 <key>。

範例：

list_repos
# returns the list of stored repository keys to stdout for example:
#  app_ui
#  app_repo

載入儲存庫

# <key>: Key of the repository, e.g. repository name
# <prop>: Name of the property, e.g. commit, branch, url
load_repo <key> [<prop>]

列印儲存庫的指定屬性的值。 僅提供儲存庫時列出儲存庫的所有可用屬性。 如果提供的儲存庫或屬性無效，則傳回錯誤，指示未找到符合的屬性。

說明：

• 若已提供 <key> 和 <prop> 的值，則會輸出儲存庫中指定屬性的值。
• 當僅提供 <key> 時，會列出該儲存庫的所有可用屬性。
• 若提供的 <key> 無效，則會傳回一個錯誤，表示未找到相符的屬性。

範例 1：取得特定屬性：

REPO_SHA=$(load_repo app_ui commit)

範例 2：列出給定儲存庫的所有屬性：

REPO_SHA=$(load_repo app_ui)

與 list_repos 一起使用以檢索屬性值

#
# iterate over all repos and print their URLs
#
while read -r key; do
  url=$(load_repo $key url)
  echo "Repository saved as '$key' is at: '$url'"
done < <(list_repos)

將下列各行輸出至主控台:

檢索特定屬性時：

 Repository saved as 'my-frontend' is at: 'github.com/my-team/frontend'
 Repository saved as 'my-backend' is at: 'github.com/my-team/backend'

列出給定存儲庫的所有屬性時：

 Properties available for '$key'.

儲存結果

# <stage>: Stage name e.g. test, detect-secrets, static-scan
# <path>: Path where will be stored the file, string
save_result  <stage> <path>

儲存階段的任意測試、掃描結果檔案。 稍後可以使用 load_result 來擷取此檔案。 依預設，會以工作區相對路徑作為索引鍵來儲存資料。

使用 PIPELINECTL_USE_PATH_AS_KEY 特性旗標，會以所提供的路徑作為索引鍵來儲存資料。

範例：

#
# save the contents of the file ./results/mocha_results.json
# as an entry named "mocha_results.json" for the "test" stage
#
save_result test ./results/mocha_results.json
#
# save the contents of the file ../data/coverage.xml
# as an entry named "coverage.xml" for the "test" stage
#
save_result test ../data/coverage.xml
#
# Using the `PIPELINECTL_USE_PATH_AS_KEY` environment variable
# save the contents of the file ../data/coverage.xml
# as an entry named "../data/coverage.xml" for the "test" stage
#
PIPELINECTL_USE_PATH_AS_KEY=1 save_result test ../data/coverage.xml

結果列表

# <stage>: Stage name
list_results <stage>

列出階段的已儲存檔名。

範例：

list_results test
# mocha_results.json
# coverage.xml

載入結果

# <stage>: Stage name e.g. test, detect-secrets, static-scan
# <file>: File name e.g. mocha_results.json
load_result <stage> <file>

將已儲存的檔案金鑰列印至 stdout。 依預設，索引鍵是 save_result 中所提供檔案路徑的工作區相對路徑。 使用 PIPELINECTL_USE_PATH_AS_KEY 特性旗標時，金鑰是 save_result 中所提供檔案路徑的路徑。 若要取得確切的金鑰清單，請使用 list_results。

範例：

load_result test mocha_results.json
#
# Using the `PIPELINECTL_USE_PATH_AS_KEY` environment variable
PIPELINECTL_USE_PATH_AS_KEY=1 load_result test ../data/coverage.xml

與 list_results 一起使用

#
# iterate over all results stored for "test"
# and write them to the filename they were registered with
#
while read -r filename; do
  load_result test "$filename" > "./$filename"
done < <(list_results test)

保存文物

# <key>: Key of the artifact e.g. app-image, baseimage etc.
# <prop>: Type of property e.g. name, type, tags, signature
# <value>: Value of the property
save_artifact <key> [<prop>=<value> ...]

向管線登錄新的建置構件，或更新現有的建置構件。

save_artifact ui_service "name=us.icr.io/team_namespace/ui_service:2.4.3"
save_artifact ui_service "type=image"
# any additional property can be added
save_artifact ui_service "tags=latest,2.4.3,feat-something"
# later, when the image was signed, and we have signature data
save_artifact ui_service "signature=${SIGNATURE}"

command_with_large_output | save_artifact ui_service "issues"
# this also works with multiple properties,
# but stdin can provide value for only a single one
command_with_large_output | save_artifact ui_service "issues" "result=success" "signature=${SIGNATURE}"

save_artifact ui_service "bar="
load_artifact ui_service bar # returns an empty string

列出文物

list_artifacts

列出 stdout 所儲存構件的 <key>。

範例：

list_artifacts
# returns the list of stored artifact keys to stdout for example:
#
# ui_service
# app_service

載入工件

# <key>: Name of the artifact e.g. app-image, baseimage etc.
# <prop>: Type of property e.g. name, type, tags, signature
load_artifact <key> [<prop>]

說明：

• 若已提供 <key> 和 <prop> 的值，則會輸出儲存庫中指定屬性的值。
• 當僅提供 <key> 時，會列出該儲存庫的所有可用屬性。

範例 1：取得特定屬性：

SIGNATURE=$(load_artifact ui_service signature)

Example2:列出給定工件的所有屬性：

load_artifact ui_service

與 list_repos 一起使用以檢索屬性值

#
# iterate over all artifacts and print their image names
#
while read -r key; do
  image=$(load_artifact $key name)
  echo "Artifact saved as '$key' is named: '$image'"
done < <(list_artifacts)

將下列各行輸出至主控台:

檢索特定屬性時：

 Artifact saved as 'ui_service' is named: 'us.icr.io/team_namespace/ui_service:2.4.3'
 Artifact saved as 'backend_service' is named: 'us.icr.io/team_namespace/backend_service:2.4.3'

列出給定工件的所有屬性時：

 Properties available for 'ui_service': name, type, tags, signature

序列化

將 pipelinectl 資料序列化為可轉移的 JSON 檔案，以用作管線 Webhook 觸發程式的有效負載。 它可以序列化 save_repo 所設定的儲存庫、save_artifact 所設定的構件，以及 set_env 所設定的環境變數。

(選用) 旗標:

--all-repos         # all the repository information set by `pipelinectl`
--all-artifacts     # all the artifacts information set by `pipelinectl`

範例：

下列程式碼會將所有儲存庫、所有構件及 <env_variable1> <env_variable2> 儲存至 foo.json 檔:

pipelinectl serialize --all-repos --all-artifacts <env_variable1> <env_variable2> > foo.json
```此指令並非別名。 您需要 `pipelinectl` 明確。
{: note}


### 解除序列化 {: #deserialize}

將 `pipelinectl` 從 JSON 解除序列化為檔案，以便 `pipelinectl` 可以在觸發的管線中運作。 使用由 `pipelinectl serialize` 指令序列化的 JSON 作為引數。

範例：

```bash {: codeblock}
pipelinectl deserialize ./foo.json
```此指令並非別名，必須明確指定 ` `pipelinectl` `。
{: note}


## 低階方法 {: #low-level-methods}

這些方法只是為了完整性而公開。 僅在極少數情況下使用這些方法。

### put_data {: #put_data}

```bash {: codeblock}
# <key>: Name of the data
# <prop>: Type of property e.g. name, type, tags, signature
# <value>: Value of the property
put_data <key> <prop> <value>

針對 key 所定義的項目，將 prop 設為 value。

取得資料

# <key>: Key of data
# <prop>: Type of property e.g. name, type, tags, signature
# <value>: Value of the property
get_data <key>
get_data <key> <prop>

列印 key 所定義項目的 prop。 如果未提供 prop，則會傳回 key 的所有 prop。 當 key 沒有 prop 時，傳回非零結束碼。

儲存資產

# <prop>: Type of property; for example, uri, id, blob
# <value>: Value of the property
save_asset <prop1> <value1> blob <json_string or path to a json file>
save_asset <prop1> <value1> <prop2> <value2> blob <json_string  or path to a json file>

將資產資訊儲存至 pipelinectl 儲存體，以在整個管線中可存取。 容許任意數目的內容。 然而，blob 是必須傳遞的保留屬性，其對應的值應該是有效 json 檔案的檔案路徑或有效 json 字串。 save_asset 內容會建立不可變的項目。 對於相同的 <prop> <value> 配對組合，無法呼叫它兩次。

載入資產

# <prop>: Type of property; for example, uri, id
# <value>: Value of the property
load_asset # retrieves all assets stored by save_asset
load_asset <prop1> <value1> # retrieves one asset that matches prop1 = value1 saved during save_asset
load_asset <prop1> <value1> <prop2> <value2> # retrieves one asset that matches prop1 = value1 AND prop2 = value2 saved during save_asset

擷取符合所提供 <prop> <value> 配對的資產。 如果在沒有 <prop> <value> 組合的情況下呼叫，則它會擷取在 json 陣列內的管線中使用 save_asset 儲存的所有資產。 blob 內容是保留內容，因此無法用作 load_asset 的相符內容。

保存證據

# <prop>: Type of property; for example, blob, sha
# <value>: Value of the property
save_evidence <prop1> <value1> blob <json_string  or path to a json file>
save_evidence <prop1> <value1> <prop2> <value2> blob <json_string  or path to a json file>

將證明資訊儲存至 pipelinectl 儲存體，以在整個管線中可存取。 容許任意數目的內容。 但是，那 blob property 是必須傳遞的保留屬性，其對應的值應該是有效 json 檔案的檔案路徑或有效 json 字串。 save_evidence 內容會建立不可變的項目。 對於相同的 <prop> <value> 配對組合，無法呼叫它兩次。

載入證據

# <prop>: Type of property; for example, id, sha
# <value>: Value of the property
load_evidence # retrieves all evidences that are stored by save_evidence
load_evidence <prop1> <value1> # retrieves one evidence that matches prop1 = value1 saved during save_evidence
load_evidence <prop1> <value1> <prop2> <value2> # retrieves one evidence that matches prop1 = value1 AND prop2 = value2 saved during save_evidence

擷取符合所提供 <prop> <value> 配對的證明。 如果在沒有 <prop> <value> 組合的情況下呼叫，則它會擷取在 json 陣列內的管線中使用 save_evidence 儲存的所有證明。 blob 內容是保留內容，因此無法用作 load_evidence 的相符內容。

刪除證據

delete_evidences # deletes all the evidences stored inside pipelinectl so far using save_evidence

此指令會清除 pipelinectl 內儲存的所有證明，這些證明是使用 save_evidence 儲存的。

save_string (已淘汰)

save_string 已淘汰，請改用 set_env。

save_string <key> <value>

儲存可在稍後使用 load_string 擷取的任意字串。

load_string (已淘汰)

load_string 已淘汰，請改用 get_env。

load_string <key>

列印儲存在 key 中的字串。