对工具链进行故障诊断
使用工具链的常规问题可能包括工具集成配置或工具链模板问题。 在许多情况下,只需执行几个简单的步骤即可解决这些问题。
为什么无法通过使用其他区域中专用存储库的模板来创建工具链?
您使用的工具链模板引用的是专用 Git Repos and Issue Tracking 存储库。
Git Repos and Issue Tracking 是特定于区域的。 尝试通过模板创建工具链并将该专用存储库不在其中的区域设定为目标时,Git 集成设置会失败。
将 Git Repos and Issue Tracking 存储库添加到特定区域中的工具链时,您的 IBM 标识会映射到 GitLab 用户名,这将授予您对该区域中 GitLab 的访问权。 尽管您的 GitLab 用户名在所有区域中显示为相同,每个区域中关联的 GitLab 用户也是不同的,因为每个区域都有一个单独的 GitLab 安装。 对于其他区域中的 GitLab 用户,即使他们的 GitLab 用户名显示为相同,也不会自动授予这些用户对工具链的访问权。
使 Git Repos and Issue Tracking 存储库成为公共的,以便可以从任何位置对其进行访问,包括其他 IBM Cloud 区域。
如果存储库必须是专用的,那么存储库所有者可以通过在源存储库所在的 GitLab 服务器上创建个人访问令牌来授予对该存储库的访问权。 在创建工具链期间,您只需要对专用存储库的访问权就可克隆内容。 可以创建具有到期日期的个人访问令牌,以将令牌的生命周期限制为一天后到期。
拥有个人访问令牌后,可以创建用于访问其他区域中存储库的 URL。 在配置工具集成时,在源存储库 URL 字段中,更新存储库 URL 以使用您的用户名和访问令牌。
https://user:XXXXXXX@us-south.git.cloud.ibm.com/group/node-hello-world
其中,"user
是GitLab用户名,"XXXXXXX
是访问令牌,"group"是存储 repo 的组,"node-hello-world
是 repo 名称。
如果 GitLab 存储库不在 GitLab 组中,说明 group
的值与您的用户名相同。
我为工具链配置了工具集成,为什么未配置成功?
如果在设置过程中发生错误,或者工具链与工具之间的通信没有正确完成,那么配置会失败。
为工具链添加并配置工具集成后,会显示一条错误消息,指示设置失败。
当您添加工具集成时,工具链会与工具集成所代表的工具进行通信,以供应任何必要资源,并将它们与工具链相关联。 如果在设置过程中发生错误,或者工具链与工具之间的通信没有正确完成,那么工具集成会置于错误状态。
您可以再次尝试配置工具集成:
-
在其工具卡上,将鼠标悬停在
Setup failed
消息上并单击重新配置。* 重新配置工具 -
请确保您使用有效的配置参数。 如果错误是由无效配置导致的,那么将显示一条错误消息; 例如,
The integration could not be set up. Check the settings and try again. Reason: Invalid api_key:fakeKey
。 请更新工具集成的设置并单击保存集成。 -
如果错误由通信问题引起,请单击保存集成,然后重试。
为什么无法使用 ibmcloud
CLI 来删除工具链?
目前,无法使用 ibmcloud resource CLI 来删除工具链。
我尝试在命令行中使用 ibmcloud resource service-instance-delete
命令来删除工具链,但该命令失败并返回以下错误消息:
Error Code: RC-ServiceBrokerErrorResponse Message: description : Toolchain delete must be performed from the toolchain dashboard
工具链是云平台上的一种特殊类型的资源,目前无法使用 ibmcloud resource
CLI 来删除该资源。
要删除工具链,请执行以下操作:
- 从IBM Cloud控制台,单击菜单图标
>平台自动化>工具链。 在工具链页面,单击要删除的工具链。 或者,在应用程序“概述”页面的“持续交付”卡上,单击查看工具链。
- 单击“操作”菜单,然后选择“删除”。 删除工具链将除去其所有工具集成,这可能删除由那些集成管理的资源。
- 通过输入工具链的名称并单击删除,以确认删除。
您可以使用 IBM Cloud CLI Developer Tools (ibmcloud dev
) 命令来删除工具链。 安装 IBM Cloud CLI 后,可以使用 ibmcloud dev toolchain-delete
命令从命令行删除工具链。
为什么我在 DevOps 仪表板上看不到工具链?
转至 DevOps 仪表板时,没有显示您的工具链。
除非选择了正确的位置,否则工具链不会显示在工具链中。DevOps Insights 仅在以下三个位置可用: 达拉斯,法兰克福和伦敦。
在“工具链”页面上,将位置更改为达拉斯、法兰克福或伦敦以显示所有 DevOps Insights 集成的工具链。
为何无法在禁用根密钥时创建工具链?
尝试创建工具链时,将显示以下通知: The root key of the Key Management Service instance that was configured for the Continuous Delivery service in the selected resource group and region is disabled
。
创建工具链时,必须使用已启用的根密钥对其进行保护。
使用下列其中一种方法来启用根密钥以进行加密:
禁用根密钥时,为何无法查看在“工具链”页面上创建的服务实例?
打开工具链时,将显示以下通知: The root key of the key management service instance that was used to encrypt this toolchain is disabled.
因为在打开工具链时将解密查看工具链的服务实例所需的信息,所以必须确保启用加密的根密钥。
使用下列其中一种方法来启用根密钥以进行加密:
当我使用 Terraform 或 API 来配置工具集成时,配置为何会因 Could not find value for secret reference...
错误而失败?
工具集成配置为使用对私钥的引用,但工具链找不到引用的私钥或私钥库。
使用 Terraform 或 API 来创建或更新工具集成时,配置将失败并显示 Could not find value for secret reference...
错误消息。
许多工具集成都包含分类为私钥的配置属性。 在 Terraform 资源或 API 调用中设置这些属性时,可以将其设置为 私钥引用。 私钥引用是一个特殊格式的字符串,用于标识集成到工具链中的私钥存储库中的私钥名称和位置。 此错误指示工具链找不到标识的私钥,或者私钥库未集成到工具链中。
如果私钥引用 {vault:...}
字符串中的一个或多个段不正确,或者如果私钥存储库中不存在指定组,名称或字段的键,那么可能会发生按名称的私钥引用错误。 如果私钥 CRN 引用了已删除的私钥,那么对于由 CRN 引用的私钥,可能会发生此错误。
错误消息包含无法解析的私钥引用字符串。
对于按名称列出的私钥引用,请完成以下任务:
- 请检查私钥存储库是否作为工具集成到工具链中,以及是否正确配置了工具集成以通过服务实例名称进行标识。 如果工具集成配置错误,请编辑工具集成以更正错误情况,然后保存配置。
- 检查
{vault::...}
私钥引用的第一个分段是否与私钥存储工具集成的名称匹配。 例如,私钥引用{vault::my-secret-store.my-secret}
期望工具链具有名为my-secret-store
的私钥存储工具集成。 此值是工具集成的名称,不是 密钥库服务实例的名称。 - 如果私钥存储在 Key Protect中,请检查
{vault::...}
私钥引用的第二个分段是否与要在 Key Protect 服务实例中使用的密钥的名称匹配。 例如,私钥引用{vault::my-kms.my-key}
期望在 Key Protect 服务实例中找到名为my-key
的密钥。 此服务实例通过名为my-kms
的 Key Protect 工具集成集成到工具链中。 - 如果私钥存储在 Secrets Manager中,请检查
{vault::...}
私钥引用的第二段和第三段是否与要在 Secrets Manager 服务实例中使用的私钥组和私钥的名称匹配。 例如,私钥引用{vault::my-sm.my-group.my-key}
期望在名为my-group
的私钥组中找到名为my-key
的私钥。 此私钥和私钥组存储在 Secrets Manager 服务实例中,该服务实例通过使用名为my-sm
的 Secrets Manager 工具集成来集成到工具链中。 - 如果私钥存储在 HashiCorp 保险库文件中,请检查
{vault::...}
私钥引用的第二和第三段是否与 HashiCorp 保险库文件服务器中的私钥和私钥字段的名称匹配。 例如,私钥引用{vault::my-hcv.my-secret.my-field}
期望在 HashiCorp 保险库服务器中找到名为my-secret
的私钥,并在该私钥中找到名为my-field
的字段。 此服务器通过使用名为my-hcv
的 HashiCorp 保险库文件工具集成集成到工具链中。
针对 CRN 的私钥引用完成以下任务:
- 请检查是否将密钥库作为工具集成到工具链中,以及是否正确配置了工具集成以由服务实例 CRN 进行标识。 如果工具集成配置错误,请编辑工具集成以更正错误情况,然后保存配置。
- 检查在工具集成中配置的 Secrets Manager 服务实例的 CRN 是否引用了与失败密钥的 CRN 相同的实例。
当我使用 Terraform 或 API 来配置工具集成时,配置为何会因 A problem was encountered while attempting to resolve secret reference...
错误而失败?
工具集成配置了对私钥的引用,但工具链无权从私钥所在的私钥存储库中检索私钥。
使用 Terraform 或 API 来创建或更新工具集成时,配置将失败并显示 A problem was encountered while attempting to resolve secret reference...
错误消息。
许多工具集成都包含分类为私钥的配置属性。 在 Terraform 资源或 API 调用中设置这些属性时,可以将其设置为 私钥引用。 私钥引用是一个特殊格式的字符串,用于标识集成到工具链中的私钥存储库中的私钥名称和位置。 对于 IBM Cloud 私钥存储服务,例如 Key Protect 和 Secrets Manager,该错误指示工具链可以联系私钥存储服务,但无权从服务检索私钥。 通常,发生此问题的原因是 IBM Cloud Identity and Access Management (IAM) 没有允许工具链从服务读取私钥的服务到服务授权策略。
错误消息包含无法解析的私钥引用字符串。
对于按名称列出的私钥引用,请完成以下任务:
- 检查
{vault::...}
私钥引用的第一个段。 此段是工具链中密钥库工具集成的名称。 例如,{vault::my-kms.my-key}
私钥引用标识名为my-kms
的私钥存储工具集成。 - 检查密钥库工具集成配置以确保
name
参数与密钥库工具集成的名称相匹配。 此外,请确保将工具集成正确配置为由服务实例名称标识,并确保选择正确的 Key Protect 或 Secrets Manager 服务实例。 - 通过使用 IAM,将服务到服务授权策略从工具链添加到 Key Protect 或 Secrets Manager 服务实例。 在授权策略中,工具链是 源 服务,密钥库是 目标 服务。 以 Key Protect为目标时,请确保策略授予
Viewer
和ReaderPlus
角色。 以 Secrets Manager为目标时,请确保策略授予Viewer
和SecretsReader
角色。
针对 CRN 的私钥引用完成以下任务:
- 请检查私钥存储工具集成配置,以确保将其正确配置为由服务实例 CRN 进行标识。 此外,请确保 Secrets Manager 服务实例的 CRN 正确。
- 使用 IAM 将服务到服务授权策略从工具链添加到 Secrets Manager 服务实例。 在授权策略中,工具链是 源 服务,Secrets Manager 实例是 目标 服务。 确保策略授予
Viewer
和SecretsReader
角色。
有关服务到服务授权策略的更多信息,请参阅 使用授权在服务之间授予访问权。
有关如何使用 Terraform 配置从工具链到私钥存储服务实例的服务到服务授权策略的示例,请参阅 使用 Terraform 指定私钥引用。
当我使用 Terraform 或 API 来配置 Key Protect,Secrets Manager或 App Configuration 工具集成时,配置为何失败?
工具集成引用不存在的 Key Protect,Secrets Manager或 App Configuration 服务实例。
使用 Terraform 或 API 来创建或更新 Key Protect,Secrets Manager或 App Configuration 工具集成时,配置失败并显示 There was a problem with the provided service parameters, please check that they are valid
错误消息。
工具集成使用无法找到或访问的 Key Protect,Secrets Manager或 App Configuration 服务实例的名称或标识进行配置。 如果使用 Terraform 来管理服务实例和工具集成,那么 Terraform 可能会在创建服务实例之前尝试创建或更新工具集成。
如果要使用 Terraform,请检查 Terraform 配置以确保 ibm_cd_toolchain_tool_keyprotect
,ibm_cd_toolchain_tool_secretsmanager
或 ibm_cd_toolchain_tool_appconfig
工具集成资源依赖于 Key Protect,Secrets Manager或工具集成所表示的 App Configuration ibm_resource_instance
资源。 您可以在工具集成资源中通过引用服务实例资源的属性或通过指定引用服务实例资源的 depends_on
元参数来指定此依赖关系。 您可以直接引用服务实例资源,也可以通过其他中间资源间接引用。 通过正确声明资源之间的依赖关系,可以强制 Terraform 以正确的顺序创建,更新和删除资源。
有关 Terraform 资源之间的依赖关系如何工作的示例,请参阅 使用 Terraform 指定私钥引用。
如果要使用 API,请检查您尝试创建或更新的 Key Protect,Secrets Manager或 App Configuration 工具集成的配置参数。 验证是否在工具集成的配置中正确指定了您尝试集成的服务实例的名称或标识。