Consuming Service Catalog

本文档描述了从 Service Catalog 正确查找服务端点的过程。

注意

本文档中描述的过程与所有已知的 OpenStack 公有云兼容，并且与 keystoneauth python 库的行为相匹配，keystoneauth 是使用 keystone 进行身份验证和从 catalog 消费信息的参考实现。在某些情况下，可以提出不同的过程，但考虑到 keystoneauth 的广泛使用和参考性质，我们选择保持与 keystoneauth 行为的向后兼容性，而不是设计一个全新的完美过程。keystoneauth 本身也在内部记录了它为了保持与早期库的兼容性而做出的地方。关于库或框架可以选择实施的更严格行为，已留下注释。

注意

本文档中“对象”一词指的是 JSON 对象，而不是任何特定编程语言中的对象。

用户请求

注意

值得注意的是，“用户”是一个可塑的概念。例如，shade 库代表其用户执行服务发现，因此不期望其用户提供“服务类型”。在这种情况下，shade 是 keystoneauth 库的“用户”，它是发现实现。并非所有 OpenStack 云的消费者都需要了解所有这些信息。

此过程的最终目标是让用户找到给定某些输入的服务端点信息。用户将从知道这些参数中的一些开始。每个需要用户提供且没有“他们从哪里学习这些信息”答案的额外输入都会增加用户消费服务的难度，因此强烈建议客户端库和工具尽一切努力帮助用户提出正确的问题。

注意

对你接受的内容宽容，对你输出的内容严格。

以下是作为用户输入可以提供的信息列表。当实现暴露允许用户表达这些参数的能力时，强烈建议使用这些名称，因为它们出现在整个 OpenStack 生态系统中，并使讨论更容易。

假设用户拥有 {auth-url} 和身份验证信息。身份验证过程本身不在本文档的范围内。

必需输入

用户绝对需要知道的一条信息。

service-type

服务的官方名称，例如 compute、image 或 block-storage，如 OpenStack 服务类型权威机构 中所述。必需。如果用户不知道他们想要发现的服务，则无法消费服务发现。

可选过滤器

用户可能知道的几个可选信息，或者用户可能希望表达的附加约束，以控制选择服务的端点的方式。

region-name

用户希望使用的服务的区域。根据云是否具有多个区域，这可能是可选的。所有服务都存在于区域内，但有些云只有一个区域。如果提供了 {be-strict}（见下文），则需要 {region-name}。

注意

强烈建议始终需要 {region-name}，以防止单区域云在未来添加区域。但是，当前的规范 OpenStack 实现 *keystoneauth* 允许省略区域名称，并且存在大量只有一个名为 RegionOne 的区域的云。对于全新的库或主要版本，其中破坏性行为是可以接受的，默认情况下需要区域名称是首选的，但不鼓励仅仅为了引入限制而破坏用户。

interface

用户想要使用的 API 接口，例如 public、internal 或 admin。用户应该能够请求他们认为可接受的接口列表，并按其偏好顺序排列，例如 ['internal', 'public']（可选，默认为 public）

endpoint-version 或 min-endpoint-version、max-endpoint-version

用户希望使用的服务的主要版本。可选。

端点版本本质上是一个具有最小值和最大值的范围。它是否以单个参数或参数对的形式呈现给用户是一个实现细节。

每个端点版本都是一个字符串，包含一个（3）或两个（3.1）数字，用点分隔。

警告

需要小心不要将由两个数字组成的主要版本与微版本混淆。微版本通常存在于某个主要版本中，并且也采用 X.Y 的形式。目前没有服务同时使用主要版本和微版本，形式均为 X.Y。

版本字符串不是小数，而是用点连接的两个数字的元组。因此，3.10 高于 3.9。

用户可以省略端点版本，表示他们想要使用 {service-catalog} 中的任何端点。

用户可以希望使用最新版本，在这种情况下，{endpoint-version} 应该为 latest。如果 {min-endpoint-version} 为 latest，则 {max-endpoint-version} 必须省略或也为 latest。

可以指定一个次要值为 latest 的版本，以指示给定主要版本的最高次要版本。例如，3.latest 将匹配 3.3 和 3.4 的最高版本，但不匹配 4.0。

如果参数以单个字符串的形式呈现，则应将单个值解释为 {min-endpoint-version} 是给定的值，而 {max-endpoint-version} 是 MAJOR.latest。例如，如果 3.4 作为单个值给出，则 {min-endpoint-version} 是 3.4，而 {max-endpoint-version} 是 3.latest。

从单个用户角度来看，想要一个范围或 latest 似乎很奇怪 - 但从库和框架的角度来看，像 shade 或 terraform 这样的东西可能有内部逻辑可以处理服务的多个版本，并希望使用可用的最佳版本。

注意

关于“latest”的指导与 微版本规范 中找到的不同。客户端库或框架对可用最新版本感兴趣是可以接受的，但这种规范是内部的，不会发送到服务器。在客户端的情况下，对于主要版本，latest 作为版本发现过程的输入。

service-name

部署者赋予服务的任意名称。可选。

注意

在绝大多数情况下，这永远不应该需要，并且部署者将其用作有意义的标识符的使用强烈 discouraged。但是，消费者无法通过其他方式缓解情况，如果他们的部署者提供了需要使用 service-name 的 catalog，则必须接受 service-name 作为输入。如果请求了 {be-strict}（见下文），则提供 {service-name} 应该是一个错误。

service-id

catalog 中端点的唯一标识符。可选。

注意

在具有良好格式的 catalog 的云中，永远不需要 service-id。如果请求了 {be-strict}，则提供 {service-id} 应该是一个错误。

endpoint-override

用户从其他来源获得的服务的端点。 (可选，默认为省略。)

发现行为修改器

用户可能还希望表达对一般算法的更改。实现可以将这些标志以任何有意义的名称呈现，或者可以选择不将它们作为行为修改选项呈现。

be-strict

放弃宽容的向后兼容性让步，并在输入和输出验证方面更加严格。默认为 False。

skip-discovery

如果用户想要完全跳过版本发现过程，即使逻辑会执行它。如果用户指定了 {endpoint-override}，或者他们知道只想使用 catalog 中的内容，而不需要有关端点的其他元数据，这很有用。默认为 False

fetch-version-information

如果用户指定了 {endpoint-version}，可以仅通过查看 URL 就能知道它匹配，则版本发现过程不会获取版本信息文档。但是，用户可能需要该信息，例如微版本范围。使用 {fetch-version-information} 允许他们请求即使过程中的优化会允许跳过获取文档，也获取版本文档。默认为 False。

发现结果

在发现过程结束时，用户应该知道以下内容

如果该过程成功

  • 所有上述输入值的实际值。

    找到的值将在这些文档中称为 found-{value}，以区分。因此，如果用户请求 {endpoint-version} 为 latest，则 {found-endpoint-version} 可能是 3.5。

  • service-endpoint 作为服务根使用的端点。

  • max-version 如果服务支持微版本，则服务支持的最高微版本是什么。可选，默认为省略，这意味着不支持微版本。

  • min-version 如果服务支持微版本，则服务支持的最低微版本是什么。可选，默认为省略，这意味着不支持微版本。

如果该过程不成功，应返回一个错误，说明哪一部分失败了。例如，是否根本找不到匹配的服务，或者找不到匹配的版本。如果找不到匹配的版本，则该错误应包含找到的版本列表。

在以下描述中，每个上述输入和输出都将像 {endpoint-override} 一样引用，以便清楚地了解用户是否向过程提供了输入，或者正在讨论预期的输出之一。在过程的某个点被获取并在稍后点引用的其他值也类似地引用为 {service-catalog}。名称不会在过程中被重用以在不同时间保存不同的内容。

发现算法

服务应使用其 {service-type} 从 OpenStack 服务类型权威机构 注册到 {service-catalog}。但是，由于历史原因，有一些服务具有在野外发现的旧服务类型。为了便于使用正确的 {service-type} 名称，同时支持现有用户和安装，OpenStack 服务类型权威机构包含此类服务的历史别名列表。

客户端需要复制 OpenStack 服务类型权威机构中发布的数据才能完成完整的发现算法。客户端库可以保留本地副本或从 https://service-types.openstack.org/service-types.json 获取数据并可能对其进行缓存。建议客户端库处理其用户的历史数据，但也允许用户提供更新的数据版本（如果需要）。

基本过程是

  1. 在 {auth-url} 上向 keystone 进行身份验证，检索包含 {service-catalog} 的 token。

    注意

    显然，对于没有身份验证的云，可以跳过此步骤。

  2. 如果用户提供了 {endpoint-override}，则将其用作 {catalog-endpoint}。

  3. 如果用户没有提供 {endpoint-override}，则使用 端点发现 中解释的过程从 {service-catalog} 中检索匹配的 {catalog-endpoint}。

  4. 如果 {skip-discovery} 为 true，则停止并使用 {catalog-endpoint} 作为 {service-endpoint}。否则，发现可用的 API 版本，并使用来自 版本发现 的版本发现过程找到合适的 {service-endpoint}。

  5. 如果请求的 {service-type} 是 OpenStack 服务类型权威机构中官方类型的一个别名，并且任何端点都匹配官方类型，则 查找匹配最佳服务类型的端点。

目录