为管道数据配置 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 权限。
• 存储桶分离：请为管道数据使用一个专用存储桶，并与您的证据存储库存储桶分开。

set_env

# <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"

set_envc

# <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_envc，就无法通过后续的 set_env / 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

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 设置的内容不会被序列化，因此无法跨子管道/异步管道运行。
• 禁用与调用此命令相关的调试日志记录，以确保即使在调试日志中也不会显示已保存的密钥内容。
• 确保脚本和任何逻辑都不依赖于 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

list_secrets

在管道用户界面中显示 set_secret 进程中保存的密钥和安全值类型环境变量。

示例：

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 保存的所有存储文件，可选择按关键字前缀过滤。

# <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: 克隆的存储库相对于工作空间根的位置。

其他属性名称也可以使用，但为了避免命名冲突，它们必须以特定于服务的标识作为前缀，例如，使用 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> 的值，则打印存储库中指定属性的值。
• 当仅提供 时，列出该存储库的所有可用属性。
• 如果提供的 无效，则返回一个错误，表明未找到匹配的属性。

示例 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)

save_工件

# <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_工件

list_artifacts

列出 stdout 的已存储工件的 <key>。

示例：

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

load_工件

# <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> 的值，则打印存储库中指定属性的值。
• 当仅提供 时，列出该存储库的所有可用属性。

示例 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}

```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。

Get_data

# <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 属性是一个必须传递的保留属性，其对应的值应该是一个有效 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 中的字符串。