关于打包应用的要求

本页面介绍了打包 Kubernetes 应用的要求以及满足这些要求的指南。

您的应用软件包是一组部署到用户 Kubernetes 集群的容器映像和配置文件。为了支持从 Google Cloud 控制台将应用部署到 Google Kubernetes Engine,应用软件包必须包含一个部署容器。该容器会将配置文件和显示元数据推送到 Kubernetes API。

您的应用软件包使 Google Cloud 用户可以:

  • 在 Cloud Marketplace 目录中发现您的应用
  • 使用 Google Cloud 控制台将应用部署到其 GKE 或 GKE Enterprise 集群
  • 使用 Google Cloud 控制台与正在运行的应用互动

除了支持通过 Google Cloud 控制台的部署之外,您的软件包还必须包含供用户在命令行界面 (CLI) 中使用 kubectlHelm 等工具部署应用的步骤。

如需查看应用软件包的示例,请参阅 Google 一键部署解决方案的 GitHub 代码库。 该代码库包含常用开源应用(例如 WordPress 和 Elasticsearch)的软件包。

准备工作

  • 确保您已设置 Google Cloud 环境
  • 为配置文件、用户指南和其他资源创建公共 Git 代码库以运行您的应用。您可以使用 GitHub、Cloud Source Repositories 等提供程序来托管代码库,也可以在您自己的服务器上托管代码库。我们建议您为要分发的每种产品提供专用代码库。

概览

该应用必须满足以下要求:

  • 您的 Git 代码库必须包含一个 LICENSE 文件,其中包含代码库的开源许可证。

  • 您的代码库必须包含一个用于部署您的应用的配置文件。配置文件可以是 Kubernetes YAML 清单,也可以是 Helm 图表。

    配置必须包含用于描述应用的应用自定义资源。

    请参阅配置要求

  • 您的应用必须在使用 x86 处理器的节点上运行。

  • (可选)如果您希望应用与 Istio 兼容,请查看运行 Istio 的集群的限制

  • 如果您的应用是商业(非 BYOL)应用,则必须向 Google 报告其使用情况,以便准确地向您的客户收费。我们建议您将应用与基于用量的结算代理集成,此代理会将使用情况报告发送给 Google。

    请参阅集成结算代理的要求

  • 您所有应用的容器映像都必须上传到 Artifact Registry 或 Container Registry 中的注册表中。您的注册表还必须包含部署者deployer映像,当用户从 Google Cloud 控制台部署应用时,该映像会将应用的配置推送到 Kubernetes API。

    请参阅构建应用映像的要求

  • 您必须添加应用的集成测试。

    请参阅验证流程的要求

  • 您必须添加用户指南,其中包含从命令行安装应用、配置应用以及使用该应用的步骤。

    请参阅用户指南的要求

配置要求

您可以用 Kubernetes 清单或 Helm 图表的方式提供配置。

您的配置必须满足以下要求:

  • 要保护用户免受不稳定 API 的影响,请仅使用测试版或正式版 Kubernetes 资源。

  • 您的配置必须部署应用自定义资源。Application 资源包含用户在通过 Cloud Marketplace 界面部署应用时看到的信息。

    Application 资源是一个自定义资源,该资源聚合了与您的应用关联的 Kubernetes 组件,并允许用户将这些资源作为一个组进行管理。

    如需了解如何创建 Application 资源以及查看示例,请参阅应用 GitHub 代码库

  • 您的配置必须使用可通过 envsubst 或作为标志被替换的参数。

    必须能够替换以下参数:

    • 命名空间:您所有配置的资源都必须属于一个命名空间。Cloud Marketplace 用户在部署您的应用时配置此命名空间。避免对清单中的命名空间进行硬编码,以便在用户选择的命名空间中创建指定的资源。命名空间有时也出现在资源定义中,例如在 RoleBinding 中引用 ServiceAccount 时。任何此类引用都必须参数化。

    • 应用名称:应用资源的实例名称。该字符串必须包含在每个应用资源的名称中,如果在单个名称空间中部署了多个应用实例,则可以避免名称冲突。

    • 容器映像:每个映像引用(例如在 PodSpec 中)都必须是可替换的,这允许 Cloud Marketplace 替换这些引用以指向在我们的 Artifact Registry 中发布的映像。它还允许客户替换修改后的图片。

    • 许可密钥:如果您的应用正在执行商业计量,则必须接受 Secret 资源的名称作为参数。该密钥包含使用情况报告凭据,您的应用使用该凭据将使用情况数据发送给 Google。

      GitHub 上详细了解配置参数。

  • 必须能使用客户端工具来部署您的应用。例如,如果您使用的是 Helm,则安装程序必须可使用 --client-only 命令行标志。

使用 Istio 的集群的限制

如果您希望应用与 Istio 兼容,请查看本部分中描述的限制。如需大致了解 Istio,请参阅什么是 Istio?

如果您的客户在其集群中运行 Istio,则默认情况下 Istio 会控制应用的 Pod 之间的网络流量。在以下情况下,这可能会阻止网络通信:

  • 如果 Pod 运行使用集群 IP 地址的 kubectl 命令,则该命令可能会失败。

  • 如果应用使用 Pod 到 Pod 的通信或基于 IP 的通信,则集群形成步骤可能会失败。

  • 与第三方服务(例如操作系统软件包代码库)的外部连接可能被阻止。客户必须配置 Istio 出站流量才能启用对外部服务的访问权限。

我们建议使用 Istio Gateway 而不是 LoadBalancer 或 Ingress 资源来配置传入连接。

如果您要将 Helm 用于配置,请在部署映像的架构中使用 x-google-marketplace ISTIO_ENABLED 属性。如果此属性为 true,则部署者必须修改部署,例如等待 Istio Sidecar 准备就绪。

为帮助您的客户设置应用 Pod 之间的通信,我们建议在文档的部署后部分添加相关步骤。

集成结算代理的要求

如果您要销售商业应用,我们建议您将应用与基于用量的结算代理集成。

该代理可以处理身份验证并向 Google 的用量报告端点 Service Control 报告。 提交价格模式后,Cloud Marketplace 团队会创建一项服务以供您的应用向其报告,以及创建用于衡量用量的结算指标。

该代理还管理局部聚合、崩溃恢复和重试。对于用量/小时指标,代理可以配置为自动报告检测信号。

该代理还会公开报告状态,以便应用能够检测代理是否成功报告用量数据。

客户在 Cloud Marketplace 中购买应用以获取许可,该许可将在部署时附加到应用。

如果要与结算代理集成,请考虑用量报告失败(可能表示以下某种情况)时应用应如何应对:

  • 客户已取消其订阅。

  • 客户可能意外停用了报告渠道。例如,客户可能会无意中移除或误配置了代理,或者网络可能会阻止代理访问 Google 的报告端点。

按照最佳做法报告使用情况,以及处理 Google 未收到用量数据且未向客户收取费用的情况。

集成结算代理

您可以将代理集成为辅助信息容器(该容器和您的应用在同一 Pod 中运行),也可以使用 SDK 来集成代理。

在辅助信息方法中,代理在专属容器中运行,该容量和应用容器位于同一 Kubernetes Pod 中。您的应用与代理的本地 REST 接口进行通信。

如果您使用 SDK 方法,则必须将代理编译或链接到应用二进制文件。该 SDK 以原生方式针对 Go 实现,而且提供用于 Python 的绑定。

通常,辅助信息方法需要较少的集成工作,而 SDK 在防范意外停用方面更可靠。

如需详细的集成步骤,请参阅基于用量的结算代理 GitHub 代码库中的 README。要查看实现示例,请参阅示例应用工具代码库。

用于报告使用率的凭据

结算代理需要凭据才能将使用情况报告发送给 Google。当用户从 Cloud Marketplace 部署应用时,Cloud Marketplace 会生成这些凭据,并确保在部署应用之前,这些凭据在目标 Kubernetes 命名空间中作为 Secret 存在。此 Secret 的名称将作为 REPORTING_SECRET 架构属性传递给应用。

如需查看使用报告 Secret 的示例清单,请参阅 GitHub 中的 WordPress 应用示例

Secret 包含以下字段:

entitlement-id

此标识符表示客户同意购买和使用该软件。

consumer-id

此标识符与某一权益相关联,而该权益与使用情况报告一起传递给 Google Service Control。

reporting-key

此 Google Cloud Service 账号 JSON 密钥用于向 Google Cloud Service 进行身份验证。

如果您的产品除了提供应用外,还提供 SaaS 组件,您可以选择让该 SaaS 组件使用 Cloud Marketplace 采购服务定期检查权益 ID 的有效性。要访问采购服务,请与合作伙伴工程师联系。

如需了解传递给应用的其他参数,请参阅本节后面的传递给应用的参数

构建容器映像的要求

您的应用包含一个或多个应用容器映像。此外,您的代码库还必须包含部署容器,客户从 Cloud Marketplace 界面部署应用时会使用该容器。

容器映像通常是使用 Dockerfiledocker build 命令行工具构建的。我们建议您在应用的公共代码库中发布 Dockerfile 和容器构建说明。发布它们可以让客户修改或重建映像,有时候,为企业生产环境验证映像必需这样做。

如果您的应用映像依赖于 Debian 等基本映像或者 Python 或 OpenJDK 等语言运行时映像,我们强烈建议您使用 Cloud Marketplace 的认证容器映像之一。这样做可确保及时更新基本映像,尤其是对于安全补丁而言。

构建应用映像后,将其推送到您设置环境时在 Artifact Registry 或 Container Registry 中创建的临时注册表。

您的 Artifact Registry 或 Container Registry 代码库结构必须如下所示:

  • 应用的主映像必须位于代码库的根目录中。例如,如果您的 Artifact Registry 或 Container Registry 代码库是 gcr.io/exampleproject/exampleapp,则应用的映像应位于 gcr.io/exampleproject/exampleapp

  • 部署容器的映像必须位于名为 deployer 的文件夹中。在上面的示例中,部署映像必须位于 gcr.io/exampleproject/exampleapp/deployer 中。

  • 如果您的应用使用其他容器映像,则每个附加映像必须位于自己的文件夹中。例如,如果应用需要使用 proxy 映像,请将该映像添加到 gcr.io/exampleproject/exampleapp/proxy

  • 您所有应用的映像都必须标记有发布轨道和当前版本。例如,如果要在 2.0 发布轨道上发布版本 2.0.5,则所有映像都必须标记有 2.02.0.5了解如何整理版本

例如,下图显示了 Grafana 集群 Kubernetes 应用的 Artifact Registry 和 Container Registry 代码库。发布轨道是 5.3,该应用包含主应用映像、部署者的映像(在自己的文件夹中)以及 debian9 中的 Debian 9 映像。代码库中的所有映像都标记有相同的轨道 5.3 和该轨道上的版本 5.3.4。这还必须匹配应用资源自定义资源定义 (CRD) 的“版本”字段,如部署程序中所声明的。

Grafana Container Registry 代码库结构示例

该代码库位于 gcr.io/cloud-marketplace/google/grafana

使用您之前在选择产品标识符时选择的容器映像标识符。

如需将映像上传到 Artifact Registry 或 Container Registry,请使用注册表名称对其进行标记,然后使用 gcloud 推送该映像。例如,使用以下命令推送 example-pro 的映像:

docker build -t gcr.io/my-project/example-pro:4.0   # release track 4.0
docker tag gcr.io/my-project/example-pro:4.0 gcr.io/my-project/example-pro:4.0.3  # release version 4.0.3
docker push gcr.io/my-project/example-pro:4.0
docker push gcr.io/my-project/example-pro:4.0.3

如需对映像进行标记以及将映像推送到注册表的详细步骤,请参阅 Artifact RegistryContainer Registry 文档的相关文档。

部署容器的要求

客户从 Cloud Marketplace 部署您的产品时,将使用部署容器(或称为部署者)deployer。部署者映像会打包应用的 Kubernetes 配置以及可将该配置推送到 Kubernetes API 的客户端工具(例如 kubectl 或 Helm)。部署者通常应该使用用户为安装应用而运行的同一组命令行命令。

要创建部署者,请使用工具代码库 Marketplace 目录中的部署容器的某个基本映像:

基本映像具有内置实用程序,可执行分配所有者引用、生成密码和部署后清理等任务。

如需了解构建部署者映像的步骤,请参阅构建应用部署者

传递给应用的参数

部署容器必须声明在客户选择您的应用时需要从客户收集的参数。这些参数随后会在用户部署应用时提供给部署容器。

要配置这些参数,部署容器映像必须包含 YAML 格式的 JSON 架构,其路径为:/data/schema.yaml

如需了解如何创建 schema.yaml,请参阅部署者架构

GPU 集群请求

如果您的应用有特定的 GPU 需求或者您的应用属于 GPU 密集型,则您可以使用部署者架构指定集群中的 GPU 类型和数量。如果您指定了 GPU 需求,则系统会停用辅助集群创建功能。

您的应用可能会请求通用的 Nvidia GPU 或特定的 Nvidia 平台

验证流程的要求

应用在我们的验证系统中执行,以确保:

  • 安装成功:所有资源都已应用并等待正常运行。
  • 功能测试通过:部署者启动测试工具 Pod 并观察其退出状态。零表示成功,非零表示失败。
  • 卸载成功:应用及其所有资源都已成功从集群中移除。

获得成功的结果后才能将应用发布到 Google Cloud Marketplace。

如需详细了解如何打包、执行和验证这些功能测试,请按照验证集成文档中的说明操作。

用户指南的要求

您的用户指南必须包含以下信息:

概览

  • 一般应用概览,涵盖基本功能和配置选项。本部分还必须链接到 Cloud Marketplace 上的已发布产品。

一次性设置

  • 配置 kubectl 或 Helm 等客户端工具(如适用)。
  • 安装 Application CustomResourceDefinition (CRD),以便您的集群可以管理 Application 资源。
  • 如果您要销售商业应用,则需要添加从 Cloud Marketplace 获取并部署许可密钥的步骤。

安装

  • 用于部署应用的命令。
  • 传递界面配置中可用的参数。
  • 将映像引用固定到不可变摘要。
  • 如果将自定义输入字段添加到部署者架构,请添加有关预期值的信息(如适用)。

    了解如何将输入字段添加到部署者

基本用法

  • 连接到管理控制台(如适用)。
  • 连接客户端工具并运行示例命令(如适用)。
  • 修改用户名和密码。
  • 启用入站流量并安装 TLS 证书(如适用)。

备份和还原

  • 备份应用状态。
  • 从备份还原应用状态。

映像更新

  • 更新应用映像以获取修补程序或次要更新。

扩缩

  • 扩展应用(如适用)。

删除