IBM Cloud Docs
管道传输

管道传输

pipelinectl 是一个轻量级键值存储,您可以在 DevSecOps 管道中使用它在任务和合规性自动化脚本之间共享数据。

有关此工具的使用位置的更多信息,请参阅 向管道添加测试和构建步骤

用途

pipelinectl 提供了单个二进制文件。 其行为取决于其名称 (如 busybox中)。 作为 pipelinectl 调用时,必须提供程序作为第一个自变量,例如 pipelinectl get_data

可用的别名和方法:

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>

如果缺少 <value> 自变量,那么 set_env 会从标准输入中读取该自变量。 保存稍后可使用 get_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

格特恩夫

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

save_file

# <key>:  File name
# <value>: Path, where the file will be stored
save_file <key> <value>

保存稍后可使用 load_file 检索的任意文件。 不支持目录。

示例:

save_file some_config ./config.yaml

load_file

# <key>:  File name
load_file <key>

将保存的文件打印到 stdout

示例:

load_file some_config > some_config.yaml

萨沃雷波

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

使用 stdin 作为值源

如果满足以下条件,那么可以从 stdin 提供值:

  • 该命令的内容以流式方法传输
  • 一个属性没有值,并且 =

示例:

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

如果 = 缺少多个值,那么该命令将退出并产生错误,因为它无法确定哪个属性属于 stdin 上的值。

没有值但仍附加 = 的属性具有空字符串作为值。

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

list_repos

list_repos

列出存储到 stdout 的存储库的 <key>

示例:

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

load_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> 打印到 stdout

示例:

REPO_SHA=$(load_repo app_ui commit)

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'

save_result

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

list_results

# <stage>: Stage name
list_results <stage>

列出阶段的已保存文件名。

示例:

list_results test
# mocha_results.json
# coverage.xml

load_result

# <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> ...]

向管道注册新的构建工件或更新现有构建工件。

容器映像

可以使用的一些建议属性:

  • type: 可以是任何工件类型,包括 image
  • name: 工件的标准名称。 例如,对于映像,可以由 docker pull 使用的内容。
  • signature: 有效签名。
  • digest: sha256 摘要。
  • source: 例如,http://<some-git-url>/blob/<commithash>/<path-to-file>

可以在这些属性的基础上设置任何属性。

对于映像,name 属性还必须包含映像的标记。

示例:

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

使用 stdin 作为值源

如果满足以下条件,那么可以从 stdin 提供值:

  • 该命令的内容以流式方法传输
  • 一个属性没有值,并且 =

示例:

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

如果 = 缺少多个值,那么命令将退出并返回错误,因为它无法确定哪个属性属于 stdin 上的值。

没有值但仍附加 = 的属性具有空字符串作为值。

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> 打印到 stdout

示例:

SIGNATURE=$(load_artifact ui_service signature)

list_artifacts 一起使用

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

序列化

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 显式

反序列化

pipelinectl 从 JSON 反序列化为文件,因此 pipelinectl 可以在触发的管道中工作。 使用 pipelinectl serialize 命令序列化的 JSON 作为自变量。

示例:

pipelinectl deserialize ./foo.json

此命令不是别名,需要 pipelinectl 显式

低级方法

这些方法只是为了完整而暴露的。 仅在极少数情况下使用这些方法。

普数据

# <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 时,返回非零退出代码。

save_asset

# <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> 对的同一组合调用两次。

load_asset

# <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> 对的同一组合调用两次。

load_evidence

# <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 中的字符串。