管道传输
pipelinectl
是一个轻量级键值存储,您可以在 DevSecOps 管道中使用它在任务和合规性自动化脚本之间共享数据。
有关此工具的使用位置的更多信息,请参阅 向管道添加测试和构建步骤。
用途
pipelinectl
提供了单个二进制文件。 其行为取决于其名称 (如 busybox中)。 作为 pipelinectl
调用时,必须提供程序作为第一个自变量,例如 pipelinectl get_data
。
可用的别名和方法:
- set_env
- get_env
- save_file
- 装入文件
- save_repo
- 列表存储库
- 装入存储库
- save_result
- 列表结果
- 装入结果
- save_工件
- 列表工件
- 装入工件
- 发布数据
- get_data
- 序列化
- 反序列化
- save_asset
- 装入资产
- save_evidence
- 装入证据
- 删除证据
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
中的字符串。