IBM Cloud Docs
将可部署架构加入私有目录

将可部署架构加入私有目录

准备好与组织内其他成员共享可部署架构时，可以将其添加到私有目录中。 此外，您还可以使用入职流程来验证您的架构。

准备工作

在启用可部署架构之前，请确保完成以下先决条件。

  • 确认您使用的是“即用即付”或“订阅”账户。 详情请 查看查看账户类型。
  • 验证您是否拥有处理专用目录和可部署架构所需的权限。
    • IBM Cloud Schematics 服务的管理者角色
    • 目录管理服务的编辑角色
    • 账户中所有资源组的查看器角色
    • SecretsReader 如果您计划将安全值存储在 服务的 Secrets Manager Secrets Manager
    • Security and Compliance Center 服务中的读者角色
    • 自定义可部署架构中特定资源所需的其他角色。
  • 创建私人目录。
  • 确保将可部署架构的源代码存储在 GitHub 或 GitLab 代码库中。 有关将源代码放入版本库的帮助，请参阅 设置源代码版本库。

想了解其工作原理，但没有可部署的架构可供使用？ 使用我们的可部署架构示例。

打包源代码

要创建将可部署架构加入私有目录所需的 .tgz 文件，必须创建源代码的发布版本。 有关创建版本的帮助，请参阅 管理版本库中的版本。

如果您使用的是私有源代码库，请确保您拥有 Git 个人访问令牌或存储在 Secrets Manager.

在专用目录中添加可部署架构

要将可部署架构添加到私有目录中，可以使用以下步骤。

  1. 在 IBM Cloud 控制台中，转到控制台的管理 > 目录 > 私有目录页面。

  2. 选择要添加产品的私人目录。 打开目录详细信息页面。

  3. 单击添加产品。 侧板打开。

  4. 为产品类型选择可部署架构。

  5. 选择 地形 或 堆 作为交付方法。

  6. 选择源代码所在的版本库类型。

    如果您的源代码位于私有资源库中，您需要使用 Git 个人访问令牌或来自 Secrets Manager.

  7. 在源 URL 字段中添加源代码链接。 它应该与 https://github.com/IBM-Cloud/terraform-sample/archive/refs/tags/v1.1.0.tar.gz 类似。

    如果您是出于测试目的启用可部署架构，则不需要 .tgz 文件。 您可以提供与架构根层的链接。

  8. 选择变体。

    变体是一种可部署架构，它将不同的功能或复杂性应用于现有的可部署架构。 例如，您的可部署架构可能有一个快速启动变体，它具有简单、低成本部署的基本功能，可在内部进行测试。 此外，您还可能有一个更复杂的标准变体，可以在生产中使用。

  9. 以主要版本、次要版本和修订版的格式输入软件版本。 例如，1.0.0。 通常，该版本与发布快照的版本号一致。

  10. 选择您希望在目录中将可部署架构分组的类别。

  11. 单击添加产品。 显示产品概览页面。

编辑目录条目

成功将可部署架构加入私有目录后，必须指定用户在尝试使用架构时看到的信息。 这些信息包括产品描述、文档链接和关键字，以确保您的产品易于查找。

  1. 转到控制台的管理 > 目录 > 私有目录页面。

  2. 选择您添加产品的私人目录。 打开目录详细信息页面。

  3. 选择您之前登录的产品。

  4. 编辑条目在目录中的显示方式。

    1. 在目录条目详细信息部分，单击编辑。
    2. 查看与可部署架构一起导入的信息，并根据需要进行编辑。
    3. 检查目录条目预览，确认条目显示符合预期。
    4. 完成选择后，单击保存。

  5. 编辑产品的“**关于 **”页面。 当用户从目录中选择您的产品时，会显示“关于”部分，让他们了解更多关于您的产品和可用功能的信息。

    1. 在“操作”下拉菜单中，选择“编辑产品页面”。
    2. 输入产品描述，说明产品对用户的价值和好处。
    3. 要添加特定功能信息，请单击功能 > 添加功能。
    4. 添加产品层面的功能，解释产品的过程、能力和结果。 用户可以在产品页面的开头看到适用于整个产品的高级产品功能，而不受版本或架构差异的影响。 例如，如果您的产品创建虚拟私有云，您可以添加 Creates Virtual Private Clouds 作为功能标题，添加 Virtual Private Clouds are created for you with the necessary underlying network components. 作为功能描述。 要为特定变体或版本添加功能，可以通过 添加亮点 来实现。
    5. 单击更新。

通过控制台指定详细信息

您的用户会看到您定义的版本级信息，该信息是您产品目录条目的一部分。 作为流程一部分提供的信息可以帮助用户了解与之相关的各个组件的功能。

为确保您的选择能延续到下一个版本，您可以生成一个清单文件。 清单文件 ibm_catalog.json 是目录条目的真实来源。 它包含有关您的产品和您所做选择的所有信息。 生成文件后，必须将其添加到源代码库的根级。 如果您喜欢在代码中工作，可以直接通过 mainfest 文件配置以下部分。 有关如何构建文件的详细信息，请参阅 本地编辑清单文件。

了解细节

将可部署架构添加到私有目录后，就可以使用控制台中的逐步演示来更新产品的一般信息。 要进入控制台页面，可以使用以下步骤。

  1. 转到控制台的管理 > 目录 > 私有目录页面。
  2. 选择您添加产品的私人目录。 打开目录详细信息页面。
  3. 选择您之前登录的产品。
  4. 在“版本”选项卡上，选择要提供信息的产品版本。
  5. 将以下信息用作配置可部署架构详细信息的指南。

配置版本详细信息

在“配置版本”选项卡上，可以查看和更新有关架构特定版本的信息。 您可以配置部署细节，定义所需的 IAM 访问权限，并详细说明希望用户了解的变更通知。

如果想扩展可部署架构，可以通过与其他架构堆叠来实现。 您可以包含架构所需的依赖项，以及有助于针对特定用例扩展解决方案的可选架构。 如需了解更多信息，请参阅 在入职过程中扩展可部署架构。

如果你的可部署架构需要特定的 Terraform 运行时版本，你可以覆盖默认版本。 如果您将 TF_VERSION 作为输入变量包含在源代码库中，那么在创建目录条目时，它就会自动更新。

输入变量是用户在使用产品时指定的参数。 您可以查看并修改与源代码一起导入的输入和输出变量，也可以在此步骤中将变量添加到可部署架构中。 添加变量时，可以更新变量是否为必填项、是否可见，或提供变量的格式。

当您发布产品的新版本时，可能会有一些更改，您希望在用户开始使用新版本之前通知他们。 您可以将信息分为三类--重大变更、新功能和一般更新。

  • 破坏性更改：详细说明对新版本代码的任何改动，这些改动可能会对使用旧版本的用户造成不便。
  • 新功能：突出显示新版本中提供的、用户可能希望利用的任何新功能。
  • 更新：说明对新版本进行的任何一般更新。 例如，错误修复或现有功能的改进。

包括前置和后置脚本

您可以在验证、部署和取消部署之前或之后为可部署架构运行前脚本或后脚本。 脚本根据目录清单文件中指定的可部署架构的特定版本进行配置，必须通过项目运行和验证。

对于产品来说，脚本是可选的，但如果使用脚本，就必须将其放在名为 scripts 的存储库中。 脚本文件本身必须符合以下命名约定 <action>-<stage>-ansible-playbook.yaml. action 的选项包括 deploy, validate，和 undeploy。 stage 的选项包括 pre 和 post。 目前只支持 playbook 格式的 ansible 脚本。

所有脚本必须能够运行多次而不会失败。 例如，部署前或部署后脚本必须正确运行，即使运行多次也是如此。 部署后脚本可能会将资源添加到目录管理数据库中，如果运行多次，必须确保不会添加重复的资源。

有关更多信息（包括示例），请参阅 为可部署架构创建脚本。

添加可部署架构细节

在云中向其他用户提供可部署架构时，必须提供以下信息：

  • 架构图，详细说明可部署架构中的组件如何协同工作。
  • 任何可以帮助用户区分哪个版本或变体的架构最适合其需求的亮点。

添加许可协议

如果用户需要接受 IBM Cloud 服务协议之外的任何许可协议，请提供每份协议的 URL。

编辑自述文件

在自述文件中记录安装可部署架构的说明。

验证版本

选择验证目标。 产品通过验证后，就可以部署资源。 对于独立的可部署架构，目标可以是当前账户中的 Schematics 工作区或特定项目。 对于可部署架构栈，必须使用项目。 根据您选择的选项，可能需要更多配置信息。 目标配置完成后，您必须提供输入和输出变量的值，这是架构成功部署到目标所必需的。 配置好变量后，就可以验证版本了。

在运行“管理安全性和合规性”部分中的合规性评估后，再清理账户中的资源。

如果由于 CRA 扫描导致版本验证失败，账户管理员可以选择覆盖失败并继续部署。 如果由于其他原因导致验证失败，强烈建议您在发布产品之前解决发现的任何问题。

审查成本

确保充分了解部署架构的相关成本。 在生成估计成本之前，必须先验证版本。

合规管理

向组织内其他人员提供可部署架构时，可以通过使用默认安装来指定架构所符合的特定合规性控制。 IBM Cloud Security and Compliance Center 对监管控制的遵守情况进行评估。 如需了解更多信息，请参阅“锁定评估资源”。

  1. 单击添加索赔。

  2. 选择概要文件。 个人资料来自 Security and Compliance Center 服务。 您可以选择预定义的配置文件，也可以登录 Security and Compliance Center 创建自己的配置文件。

  3. 指明您的可部署架构是否符合配置文件中的所有控制要求，或是否能满足控制要求中的一个子集。

  4. 如果您的架构只能满足部分控制要求，那么您必须选择可以满足的控制要求，并将其添加为权利要求。

  5. 使用 Security and Compliance Center 来确认您所确定的主张。

    1. 在 IBM Cloud 控制台中，单击菜单图标 菜单 图标 > 管理安全性和合规性 访问 Security and Compliance Center。
    2. 使用您选择的配置文件创建附件。

    作为创建附件的一部分而定义的范围必须包含在验证产品时部署的资源。

    1. 运行扫描并等待结果。

  6. 在目录用户界面的管理合规性选项卡中，单击添加扫描。

  7. 选择要添加的实例、配置文件和特定扫描。

  8. 单击添加

审查要求

完成演示后，您必须查看您的选择，并确认您已准备好将产品共享到目录中。 准备就绪后，单击“准备共享”。

下载清单

每当通过控制台对产品配置进行更改时，最好的做法是生成并下载清单文件，以确保产品的未来版本能接收到您的更改。

下载清单的步骤如下。

  1. 转到控制台的管理 > 目录 > 私有目录页面。
  2. 选择之前已登录的产品。 打开详情页面。
  3. 在“版本”选项卡上，选择要生成清单的版本。
  4. 从“操作”下拉菜单中选择“导出为代码”。
  5. 将该文件添加到源代码库的根文件夹中，文件名为 ibm_catalog.json。

下载目录配置

如果使用的是可部署架构栈，除了清单文件外，还会生成其他文件。 如果使用控制台对目录配置进行了更新，最佳做法是下载文件并将其添加到源代码库中，以便将更改延续到下一个版本中。

  1. 转到控制台的管理 > 目录 > 私有目录页面。
  2. 选择之前已登录的产品。 打开详情页面。
  3. 在“版本”选项卡上，选择要生成清单的版本。
  4. 从“操作”下拉菜单中选择“导出为代码”。
  5. 将文件添加到源代码库的根文件夹中。

添加变化

您可以添加更多的变体，这些变体是架构的新版本，旨在以基本可部署架构的功能为基础。 如果在源码包中的不同工作目录下 创建了多个变体，并在 ibm_catalog.json 清单文件的 flavors 数组中指定了它们，则必须分别导入每个变体。

此时，您已经有了第一个变体。 现在，您可以重新开始 添加可部署架构，以加入下一个变体。 以下是一些关于新员工入职的建议：

  • 版本库发布的源 URL 对于该版本库中的所有变体都是一样的，导入时应使用相同的版本号。 产品名称和版本号是将变体连接在一起的方式，然后将其作为同一目录瓦片上的选项。
  • 在“添加可部署架构详细信息”页面上，步骤 3 包括添加亮点。 这些在 ibm_catalog.json 清单文件中被称为功能。 您可能已经在清单中添加了这些内容，因此可以在这里查看。 如果没有，就继续添加一些亮点。 这些应该是该特定架构的短期能力、流程、容量或其他特征。 您将在所有变体中使用相同的高亮“名称”。 说明是应该有区别的地方。 这样，用户就可以通过目录详细信息页面上的文本高亮来评估架构的差异。

下一步：共享和出版

现在，您已将可部署架构添加到私有目录中，并设置了详细信息，您就可以与组织中的其他成员共享产品了。 有关共享的帮助，请参阅 共享您的产品。

如果您想将可部署架构发布到 IBM Cloud 目录中，您可以使用合作伙伴中心获得批准并发布，以便所有用户都能利用您构建的解决方案。 有关详细信息，请参阅 发布可部署架构。