数据驻留

问题

部署有时需要——根据合同、监管要求或租户自身的策略——在特定国家/地区内运行。必须有人将此要求转化为部署的属性而非运行手册中的注释，并且必须进行双向检查：要求本身必须格式正确，且其运行的机器必须确实位于其所声明的位置。

难点不在于检查本身，而在于需求被错误地记录下来时会发生什么。以自由文本形式表达的约束，即使拼写错误也不会被拒绝——它只是默默地匹配不到任何东西，也无法约束任何东西，而这恰恰发生在那个其全部目的就是为了该约束的部署上。

它强制执行的内容：放置

驻留策略决定哪台机器运行容器。仅此而已。

在部署的 placement 块中声明它：

apiVersion: odysseus/v1
kind: Deployment
metadata:
  name: ledger-api
spec:
  image: registry.example.com/ledger-api:1.4.0
  replicas: 2
  placement:
    residency:
      country: CA

这表示：仅在报告自身位于加拿大的节点上运行此部署。当管辖范围跨越多个国家时，可以使用 region —— 即您所连接的控制平面声明的名称 —— 作为替代方案，而 blockedCountries 则表示相反类型的规则，即排除规则。每个键、其类型、默认值以及每个键引发的拒绝错误，均在部署参考] 中列出。

声明在写入时即被检查。 国家必须是已分配的 ISO 3166-1 alpha-2 代码，且区域必须是此控制平面所声明的——任何其他值在写入时都会被拒绝，系统会引用该值并说明可接受的格式。这正是将其设为类型化字段而非标签的全部意义所在。

手动设置底层标签是被拒绝的，而非弃用。 调度器读取三个标签——odysseus.io/data-residency-country、odysseus.io/data-residency-region 和 odysseus.io/blocked-countries——而类型化块编译后恰好生成这些标签。但自己编写它们会被直接拒绝，因为标签是自由文本，没有东西检查其值。拼写错误的标签不是被拒绝的约束；它是没有约束，且被静默应用。拒绝时会以接受的形式打印回您自己的值，因此修复方法是复制粘贴。

节点的国家是节点自身报告的事实。 每个代理程序都会从其自身配置中广播 odysseus.io/country 和 odysseus.io/geo-region。控制平面无法通过任何 API 来断言机器的位置——那将使驻留成为一种声明，而非机器的属性。

当没有匹配项时，部署将保持待定状态。 它绝不会作为后备被放置到其他地方。调度器的拒绝会指明您要求的国家和节点报告的国家，因此不匹配是可见的，而非推断得出。如果始终没有标签匹配，请参阅部署永远不会离开调度阶段。

它不强制执行的内容：出站流量

部署在加拿大的部署仍然可以调用世界任何地方的服务。

这是本页需要记住的关键点。驻留限制仅限于容器的放置位置。平台不会基于您声明的驻留来检查、过滤、代理或阻止容器的出站网络流量，声明驻留也不会创建任何形式的网络策略。运行在加拿大节点上的容器可以自由地连接到其他国家的 API、写入其他国家的数据库，或将其遥测数据发送到其镜像配置的任何位置。如果这对您的义务很重要，那么需要负责的是您的镜像和网络设计，而不是此字段。

基于同样的原因，它还有四件事不做——这些都超出了放置过滤器所能决定的范围：

它不会移动已存在于其他位置的数据。 驻留从容器被放置的那一刻起生效；它不涉及存储在节点外部的卷、对象存储或数据库。
它不管理平台存储自身记录的位置。 部署规范、其事件和审计日志由控制平面保存，无论控制平面运行在哪里。驻留约束的是您的容器，而不是平台自身的存储。
它不限制镜像的来源。 镜像从部署指定的任何注册表拉取。
它不是证明。 节点报告其自身所在的国家。驻留的可信度与您注册的机器的配置完全相同，不会执行任何地理定位查询来质疑它。

区域由每个控制平面声明，而非产品本身

区域是操作员对国家/地区的分组——包含名称、描述及其覆盖的国家/地区列表——在控制平面自身的配置中通过 scheduler.geo_awareness.regions 声明。没有固定的产品级列表，因此此处合法的名称在另一个控制平面上不一定合法。

询问您正在沟通的对象：GET /api/v1/scheduler/regions 会返回其声明的区域，并在同一响应中说明是否已启用驻留强制执行。一个区域可以通过其 odysseus.io/geo-region 标签命名该区域的节点来满足，也可以通过其国家/地区属于该区域所列国家/地区之一的节点来满足。

无法满足的约束应被声明，而非隐藏

两种情况下会接受部署并发出警告，而不是拒绝它：

此控制平面上的强制执行已关闭。 该约束会被保存但不会被应用；响应中会说明这一点，并指出可以将其开启的设置项。操作员必须能够在启用之前声明意图，因此这并不是一次拒绝。
该租户可以访问的节点中，没有任何一个声明了匹配的标签。 响应会说明该租户的节点实际声明了哪些国家与区域取值 — 只给出取值，绝不指出是哪一个节点 — 从而使差距立即可见，而不是等到部署已经长时间无法放置之后才被发现。租户必须能够在操作员为机器打上标签之前声明数据驻留要求，而这正是现实中这些事情发生的先后顺序。

两者都不是静默的，两者也都不是悄然成功的。在放置时的拒绝仍然会发生；部署只是在等待。

在依赖它之前值得了解的限制

除非控制平面开启，否则强制执行不会生效。 地理过滤器仅在 scheduler.geo_awareness.enabled 为真时才会添加到调度器中。当其关闭时，数据驻留声明会被存储但被忽略——这就是响应会告知您的原因。
当区域要求已满足时，不会评估被阻止的国家/地区。 过滤器会首先响应 region 并在此停止，因此将 region 与 blockedCountries 配对并不能从该区域中开辟出一个例外。请使用 country 来表达排除条件，或者通过不声明包含该排除条件的区域。
平台施加的变体尚不可用。 调度器会读取 …-country-enforced 和 …-region-enforced 标签，平台运营商可以通过这些标签施加租户无法移除的数据驻留要求。目前没有任何设置会使用这些标签，并且面向租户的 API 也无法设置它们。

Not this

此页面未列出每个键的可接受值、默认值或拒绝代码—— 这些内容已生成到部署参考和拒绝与修改中，因此它们不会与代码产生偏差。

这也不是一份合规声明。它描述了一种放置约束及其限制；该约束是否满足特定义务是一个关于义务的问题，而本页有意不对此作答。

在哪里查看

键及其规则：部署清单。
通常如何决定放置：放置与分配。
为何居住声明被拒绝，以及应改写什么：拒绝与修改。
一个被接受但从未被放置的部署：部署永不离开调度阶段。