CloudFormation Provider
cloudformation provider 将 Aggrega Recipes 渲染为 AWS CloudFormation 栈模板。在该 provider 下渲染到同一输出目录的每个组件都会组装进同一个栈,并输出为一个使用长格式内置函数的纯 JSON 模板。因此,在一般情况下一个边界对应一个栈;而两个 directory: 解析到同一路径的边界会一起组装进同一个栈,共享该模板的名称。与所有 Aggrega provider 一样,它是离线且封闭的:Aggrega 构建是一种预先编译,因此该 provider 从不调用 AWS,从不解析由账户生成的标识符,也从不运行 CloudFormation。仅在运行时存在的值保留为 CloudFormation 内置函数引用(Fn::GetAtt、Fn::ImportValue、Fn::GetStackOutput),由 CloudFormation 在部署时解析。
组装成一个栈的片段 recipe
cloudformation Recipe 编写的是一个片段——单个 component 贡献的 CloudFormation 资源——而不是完整的模板。当一个边界的各个 component 渲染时,provider 将分派组中的每个片段组装成一个栈模板:资源合并到单个 Resources 映射下,每个 component 的 provides 值作为栈的 Outputs 呈现,模板的其他顶层部分则在组装栈中的顶层部分中逐一说明。接受两种编写形式:
- 片段(artifacts)输入。 Recipe 直接编写资源片段;provider 将其规范化为纯 JSON 长格式内部函数,并合并到组装后的栈中。
- 引用源输入。 Recipe 引用一个现有的 CloudFormation 模板(YAML 或 JSON);provider 将其规范化为长格式 JSON,并在组装前验证其结构,根据 Recipe 的
valuesMapping填充模板声明的参数——参见引用源模板参数的值——并省略 Recipe 的omits:条目指定的任何资源——参见从引用源模板中省略资源。
组装后的模板是纯 JSON。内部函数按原样输出,在构建时从不求值——编译器无法解析只在栈部署后才存在的值,而对其求值会破坏预先编译的契约。
附加到 component 的 Feature 会向同一个栈贡献内容
附加到 component 的 Feature 会将其资源贡献到其宿主 component 所组装进的栈中,条件与宿主 component 自身的 Recipe 相同。它旁边没有单独的模板:组装后的栈就是此 provider 为一个输出目录输出的全部内容,因此附加的 Feature 的资源要么在该栈中,要么根本不会部署。分离该 Feature 会恰好移除这些资源,而宿主 component 自身的资源保持不变。
由于这些资源落在组装后的栈中,它们共享该栈的名称。附加的 Feature 的资源逻辑 ID 与宿主 component 的逻辑 ID 以及与其一同附加的其他每个 Feature 的逻辑 ID 处于同一空间中,因此组装栈中的名称同样适用于它们。当两个贡献者在同一名称上相遇时,终止信息会指出该 component 以及该 Feature 所附加的键,因此冲突的双方都可以在你自己的文件中搜索到。
附加的 Feature 的输出以其宿主 component 的名称发布,而其资源逻辑 ID 则不然。 栈的这两部分按不同规则命名,因此对这一问题的回答不同。资源逻辑 ID 完全按照 FeatureRecipe 编写的方式输出,与任何 Recipe 的一样。输出则以发布 component 与条目共同命名——对于附加到 component 的 Feature,发布 component 就是宿主:附加到 payments-db 并发布 alarm 的 Feature 会得到 paymentsXzhdbXXalarm,与宿主 component 自己发布该条目时得到的名称相同。因此,宿主也发布的条目名称会与附加项的条目在同一输出名称上相遇,构建将终止,并指出该 component 及该 Feature 所附加的键,以及该 component 本身。选择读起来属于 Feature 自身的条目名称——用 backup-alarm 而不是 alarm——可以使其避开宿主的名称。
Feature 贡献的每个资源,在构建写入其上的来源信息中,保留的是为该附加项组合的标识,而不是宿主 component 的标识,因此在双方都有贡献的栈中,二者仍可区分。标签和注解介绍了该标识的构建方式。
组装后的栈中的顶级节
多个组件组装成一个栈,因此 CloudFormation 模板允许的每个顶级节都必须在组装中得到处理——包括 Globals 和 Hooks,即 CloudFormation 托管的转换为模板语言新增的两个节。每个节恰好归入下列分组之一;组件写入的顶级键如果根本不是任何节,会收到一条指明该组件和该键的警告,因此不会有任何内容被无声地丢弃。
在提供程序限定作用域的名称下组装,或按原样读取。 Resources 和 Outputs,组装后的栈中的名称对其有完整说明。AWSTemplateFormatVersion 由提供程序写入,而不是从任何组件读取:模板语言只允许它取一个值,因此组件无需对此做出决定。
完全按你所写的名称携带。 Parameters、Mappings、Conditions、Metadata 和 Rules。它们都是以你所选名称为键的映射,因此每个组件的条目以这些名称进入组装后的栈,不经改写——正因如此,资源的 Condition:、Fn::FindInMap 或指向参数的 Ref 才能解析到随其一同到达的声明。每个节都单独携带,因为每个节都是单独编写的:规则针对同一文档中的参数进行断言,条件可能完全不引用任何参数,而 CloudFormation 不允许在映射中引用参数。
这里同一个词涵盖两个不同的位置,只有第一个属于你。上面列表中的 Metadata 是模板自身的顶级节,即由你所选名称构成的映射。单个资源也有自己的 Metadata 属性,构建正是在那里写入来源信息——位于单个保留的 aggrega.ai/ 键下,与你在那里写的内容并存,而不是替换它。因此,资源中出现的来源条目既不是你编写的,也不是顶级节携带的。
Parameters、Mappings、Conditions 和 Rules 以逻辑 ID 命名其条目。 由于提供程序完全按你所写的样子携带名称,逻辑 ID 允许的字母表也适用于这些节:这四个节之一中的名称若含有字母和数字以外的任何字符,构建就会中止——参见携带的节名称超出字母表时中止。提供程序不要求顶级 Metadata 节的名称符合该字母表:这些名称命名的是你存储的信息,而不是模板寻址的任何内容。
两个组件在这些节之一中声明不同名称时,两者都会保留。两个组件以相同内容声明同一名称时,会合并为单个条目,构建继续进行。两个组件以不同内容声明同一名称时,构建中止,并指明该节、该名称和两个组件——因为否则两份内容之一会被丢弃,使编写它的组件留下一个栈中并不存在的声明。这与资源名称和输出名称遵循的协调方式相同,重命名其中任一个即可解决。
指明而不携带。 Description 是关于整个模板的单一陈述,而不是由你所选名称构成的映射,因此汇集多个组件的组装无法为它给出答案:两段描述是对同一问题的两个答案,哪一个都不属于这个栈。Hooks 只由 AWS::CodeDeployBlueGreen 转换读取,而组装后的栈从不携带该转换(见下文)。因此组装后的栈两者都不携带,编写了其中之一的每个组件都会收到一条指明该组件和该节的警告。写入 Globals 却未声明读取它的 AWS::Serverless-2016-10-31 转换的组件同样如此。该警告仅供参考且在带外输出:生成的模板与没有该警告时逐字节相同,--no-unsupported-field-warnings 会将其与同类其他警告一并静默。
Transform 由每个组件的转换构建而成。 转换是 CloudFormation 在部署任何内容之前对整个模板运行的宏,因此组装后的栈的 Transform 是其组件所声明转换的并集——来源模板和片段的转换一视同仁——并按 CloudFormation 文档规定的顺序排列:你的账户定义的宏位于 CloudFormation 托管的转换之前,AWS::LanguageExtensions 位于 AWS::Serverless-2016-10-31 之前。每个组件自身的顺序得到保留,没有任何规则确定顺序的两个转换按组件首次声明它们的顺序运行,因此相同的组件生成相同的栈。一个转换写为字符串,多个转换写为列表。只有一个组件的栈,若该组件在一个模板或片段中声明其 Transform,则在下表携带它的情况下完全按原样保留;组件未声明任何转换的栈则不携带任何转换。组件的转换不会引发警告:它要么被携带,要么构建中止并指明它。
由于转换处理整个模板,携带一个转换会改变其他每个组件内容的部署方式,除非它的作用仅限于为它编写的内容。因此,每个转换采用 CloudFormation 自身文档所支持的处理方式,而栈无法携带的组合会使构建中止,并指明该转换和栈中的每个组件:
| 转换 | 在组装后的栈中 |
|---|---|
AWS::Serverless-2016-10-31 | 连同声明它的组件的 Globals 一起携带。当这些 Globals 会影响到另一个组件的无服务器资源时,或当其某个资源的事件源指向另一个组件声明的资源时,构建中止,因为该转换会改写事件所指向的资源。 |
AWS::LanguageExtensions | 单独携带,或与同一组件的 AWS::Serverless-2016-10-31 一起携带。与另一个组件的无服务器内容并存时中止,因为语言扩展解析其值后,无服务器转换对其生成内容的命名方式会不同。 |
AWS::SecretsManager-2020-07-23, AWS::SecretsManager-2024-09-16 | 携带:它们只处理请求它们的轮换计划。 |
AWS::ServiceCatalog | 在只有一个组件的栈中携带。与任何其他组件并存时中止,因为它会在模板的任何位置替换其引用模式。 |
AWS::CodeDeployBlueGreen | 即使单独存在也中止:CloudFormation 拒绝在声明它的模板中的任何位置出现 Outputs 和 Fn::ImportValue,而组装后的栈会携带其组件发布的输出。 |
AWS::Include | 即使单独存在也中止:它在栈部署时插入从 S3 获取的内容,而构建无法读取这些内容。 |
| 你的账户定义的宏 | 在只有一个组件的栈中携带。与任何其他组件并存时中止,因为构建无法得知它会对模板的其余部分做什么。 |
两个组件以相反顺序声明同一对转换时,构建同样中止,并指明两种顺序和两个组件,因为栈只能按一种顺序运行它们。需要栈无法携带的转换的组件应放在单独的边界中。
组装后栈中的名称
CloudFormation 逻辑 ID 在一个模板内唯一,且只允许字母和数字,而组装进该模板的每个组件都共享其中的名称——包括来自第二个边界的组件,只要两者解析到同一个输出目录。因此,栈用来指代某个对象的每个名称,都必须在提供它的所有组件之间互不相同,而提供者的集合并不总是只有一个边界。
资源逻辑 ID 来自 Recipe。 provider 按原样输出这些 ID,不改写其中任何一个,因此你在组装后的模板中读到的名称就是 Recipe 写下的名称。标准库中的 CloudFormation Recipes 根据组件实例自身的名称推导出它,并把该名称中的分隔符视为单词边界:实例 payments-db 将其资源命名为 PaymentsDb。因此,同一类型的两个实例描述的是两个资源,而不会争用同一个。
输出名称按发布它的组件划分作用域。 每个 provides 条目都会以一个由发布组件和该条目共同命名的输出呈现——组件 payments-db 发布 host,呈现为 paymentsXzhdbXXhost——因此两个组件发布同一条目会得到两个独立的输出,而且当另一个组件加入栈时,某个输出的含义不会改变。同一账户和区域内的跨栈使用方按导出名称而不是按这个名称导入,因此导出名称不受影响;跨账户或跨区域的读取则使用这个输出名称,由 provider 为你写好(参见跨栈连接)。
输出名称如何构建
逻辑 ID 不允许任何分隔符字符,因此由你所写内容构建的名称必须以某种方式保留你的分隔符。直接丢弃会造成信息丢失:payments-db 和 payments_db 是两个组件,丢弃标点的名称无法标识其中任何一个。因此,provider 改为对字母表拒绝的字符进行编码,用字母表允许的字符逐一拼写出每个被拒绝的字符。
该方案保留一个字符用于开启转义——大写的 X——其他一切都按你输入的原样写出,包括大写字母。只有大写字母被保留,因此像 nginx-proxy 这样的名称中的小写 x 会按你所写的原样保留:
| 你所写的 | 变成的结果 | 原因 |
|---|---|---|
字母或数字,X 除外 | 其本身 | 字母表允许它 |
- | Xzh | 字母表拒绝连字符 |
_ | Xzu | 字母表拒绝下划线 |
. | Xzd | 字母表拒绝句点 |
/ | Xzs | 字母表拒绝斜杠,而嵌套的组件标识中含有斜杠 |
X | Xzx000058 | 保留用于开启转义,因此按码位拼写 |
| 其他任何结尾 | Xzx 加上该字符的码位 | 一条规则涵盖所有其余字符 |
| 两半的连接处 | XX | 两个连续的开启符,任何一半都不可能包含 |
反向解读的结果是无歧义的,这正是要点所在,而非锦上添花。只有当其后的字符是字母表所接受的字符时,X 才会保留为其自身,因此一个编码后的半部分既不会以它结尾,也不会连续包含两个——这就使 XX 可以专门表示连接,且只表示连接。
因此,三个仅在标点位置上不同的名称仍然彼此区分:
component payments-db publishing host → paymentsXzhdbXXhostcomponent payments_db publishing host → paymentsXzudbXXhostcomponent payments publishing db-host → paymentsXXdbXzhhost这些名称比你所写的组件名称更长,也不那么一目了然,这就是取舍。 一个恰好标识一个条目的名称,比一个更短却无法区分两个条目的名称更有价值——而且你是通过导出名称而不是手动输入这个名称来引用输出的,所以代价只是阅读输出模板时需要多看一眼。
资源逻辑 ID 遵循不同的规则,因为 provider 并不构建它们:它输出的是 Recipe 所写的内容。标准库中的 CloudFormation Recipes 通过把实例名称中的分隔符视为单词边界来推导——实例 payments-db 将其资源命名为 PaymentsDb——而这种推导会丢弃分隔符,因此两个仅在标点或仅在某个字母大小写上不同的实例名称,仍会推导出同一个资源名称。此时构建会中止,列出得到该名称的每个实例以及它们落到的名称,而不是在声明了两个组件的地方只输出一个资源。之所以列出全部而非部分实例,是因为冲突本身无法说明哪个实例的推导才是预期的。将其中除一个以外的全部重命名即可解决。
超出字母表的资源逻辑 ID 会中止构建
唯一性和字母表是两项独立的要求,一组名称可能满足前者而不满足后者。由于 provider 按 Recipe 所写的原样输出资源逻辑 ID,Recipe 编写的 ID 必须是 CloudFormation 模板本身能够容纳的:只含字母和数字,别无其他。
这正是推导出的名称与透传名称分道扬镳之处。输出名称由 provider 构建,它会对发布组件和条目进行编码,因此无论两半如何拼写,输出名称都落在字母表之内。资源逻辑 ID 是透传的,因此 Recipe 写了什么,模板就得到什么。
因此,只要 Recipe 把组件实例的名称直接写入逻辑 ID,这也就成了对组件名称的约束。组件名称可以包含连字符或下划线;逻辑 ID 则不可以。因此,通过这类 Recipe 以此 provider 为目标的组件,只能用字母和数字命名——用 paymentsdb 而不是 payments-db——否则构建会中止。
中止信息会列出其 Recipe 编写了该 ID 的提供者、该 ID 本身,以及其中每个不允许出现的字符,并说明你可以改写成什么。有两种方法可以解决,其中第一种始终可用:
- 让 Recipe 自行编写逻辑 ID,而不是直接透传名称。标准库中的 CloudFormation Recipes 就采用这种方式——它们把实例名称中的分隔符视为单词边界,因此实例
payments-db将其资源命名为PaymentsDb,你也可以保留自己选择的组件名称。以这种方式推导 ID,是用上文的冲突规则换掉这次中止:两个仅在标点上不同的实例名称会推导出同一个资源名称。 - 如果 Recipe 确实直接透传名称,就把它所透传的内容改为只用字母和数字命名。对于组件自身的 Recipe,这指的是组件名称。附加到组件上的 Feature 会根据它自己的 FeatureRecipe 为其资源命名,因此重命名宿主组件影响不到这些资源——需要修改的是该 Recipe 写入的 ID。
provider 会拒绝,而不会悄悄修复。 替你改写 ID 看似是贴心之举,其实不然。逻辑 ID 是 CloudFormation 在多次更新之间识别资源的方式,因此修改它并不是重命名——而是指向另一个资源。provider 替换后的 ID 将指向别处,而不是已在你所写 ID 下部署的资源;而且这种替换是你从未要求过的,只能从输出模板中自行发现。构建中止则会在问题仍由你掌控、可以修复时把它指出来。
超出字母表的携带段名会导致停止
资源逻辑 ID 并不是 provider 原样携带的唯一名称。Parameters、Mappings、Conditions 和 Rules 同样用逻辑 ID 命名其条目,这四者各自以作者选定的名称进入组装后的栈。因此要求是相同的,只是作用于另外四个层面:名称必须是 CloudFormation 模板本身能够容纳的名称——仅限字母和数字,别无其他——否则构建会停止。
在携带该名称的段之外还有一个后果,这也是此处停止而非警告的原因。这些名称是资源的 Condition:、Fn::FindInMap 或指向参数的 Ref 进行解析的依据。因此,字母表不接受的名称会使指向它的引用连同声明本身一起脱离可部署的模板,单个编写的名称就会让两者同时无法使用——而如果没有停止,这一问题要到部署时才会被发现,发现者是执行部署的人,而非编写该名称的人。
停止信息会指明其 Recipe 编写了该名称的贡献者、名称所在的段、名称本身,以及其中每个不允许出现的字符。段名是在你的 Recipes 中搜索的关键词:这些名称恰好在你编写它们的段下携带,因此它是同时出现在消息和你自己文件中的那个词。仅用字母和数字重命名该条目即可消除停止,这也是全部的补救办法——对资源逻辑 ID 而言,还可以让 Recipe 派生一个 ID 而不是直接传递名称,但这里没有可派生的内容,因为段中的名称就是你所写的内容。
**只有段自身的名称受字母表约束,条目内部的键则不受约束。**映射的第二级键可以由你自由选择——RegionCidr 映射下的 us-east-1 就是常见情况,它会原封不动地进入生成的模板。参数、条件或规则主体中的键命名的是属性、断言和内部函数,而非栈所寻址的任何对象:规则的 Assertions 以及写在其中的 Fn::Contains 都是这类键。它们都不是逻辑 ID,也都不会被检查。
你分开编写的两个条目名称保持分开
有三类条目名称彼此接近,足以在同一个输出名称处相遇,而且它们都不罕见。由于两半是经过编码而非折叠的,并且在一个两半都不可能包含的序列处相接,这三类都会得到各自的名称:
- 仅标点不同的条目。同时发布
db-host和db_host的组件会得到dbXzhhost和dbXzuhost。 - 仅字母大小写不同的条目。
host和Host会得到host和Host,因为字母按你书写的大小写携带。 - 在连接处相遇的条目。Component
payments-db发布host得到paymentsXzhdbXXhost;Componentpayments发布db-host得到paymentsXXdbXzhhost。
当两个条目确实命名同一事物时,它们仍会相遇。输出名称由发布组件和条目构建,因此两者都相同的任何内容无论如何编码都会得到同一个名称。你最可能遇到的情况是同一个 Feature 被两次附加到单个组件上:附加项以其宿主的名义发布,因此一个组件上同一 Feature 的两个附加项都会从 payments-db 发布 alarm-id,而这一对之间没有任何可区分之处。构建会停止,而不是在编写了两个输出的地方只生成一个,并指明组件以及每一方所携带的附加键,使两端都能在你自己的文件中搜索到。要么只附加该 Feature 一次,要么使用一个其发布条目名称体现该附加项自身的 Feature。
无论两个条目是否携带相同的值,这一点都成立。值相同的两个条目仍然描述了作者要求的两个输出,因此将它们合并为一个会使其中一个已编写的输出从栈中缺失。
Recipe 在模板中组合的名称不在此范围内
上述编码属于 provider,适用于 provider 构建的输出名称。**在 Recipe 模板内部你无法使用它,因此你的模板组合出的名称不具备它的任何保证。**之所以要明确说明,是因为从模板内部看不到这一隐患:那里可用的折叠函数把其参数读作单词,并丢弃单词之间的一切,因此在折叠之前连接两个值,会连同标点一起丢失连接处。
需要留意的形式是:一个 FeatureRecipe 用实例和附加键命名资源,两者以空格连接后再折叠——app 加 cache 与 app-cache 加空值都会折叠为 AppCache,二者在折叠的任何特性生效之前就已冲突。有两种做法可以使这类名称保持区分,二者都由你而非 provider 负责:
- 让组合的各部分只包含字母和数字,这样就没有任何内容被丢弃,也无需区分任何内容。
- **不要连接两个各自都可能包含对方分隔符的值。**当名称必须由两部分组成时,让其中一部分成为另一部分不可能包含的固定字面量。
组合名称一旦冲突,它是作为资源逻辑 ID 而非输出名称冲突的,因此你遇到的停止是上文所述的资源名称停止。
在同一映射中重复书写的键会导致停止
CloudFormation 片段被当作映射读取,而映射每个键只保存一个值,因此重复书写的键会保留最后出现的主体并丢弃另一个。当该映射是 Resources 或 Outputs 块时,被丢弃的主体就是一个已编写却不会出现在栈中的资源或输出。
构建会改为停止,并指明重复的键以及它被书写的两行。这是一条针对整个片段的规则,而非针对栈名称的规则:它适用于片段中的任何映射,包括资源的 Properties。最常见的触发方式是 Recipe 从编写的值派生逻辑 ID,而两个编写的值仅标点不同——app-cache 和 app_cache 都派生为 AppCache,于是片段两次写入 AppCache。
同一键名出现在文档中不同位置是正常的,不会受影响:无论片段携带多少资源和输出,Type 在每个资源中出现一次,Value 在每个输出中出现一次。只有同一映射内的重复才会丢失主体。
**单个组件也可能两次声明同一名称。**一个 Recipe 会贡献多个片段——多个 artifacts: 条目,或包含多个模板的源目录——而每个片段都组装进同一个栈,因此一个组件自身的片段之间共享栈的名称,与跨组件共享的方式完全相同。两个片段为同一名称提供两个不同的主体时,构建会停止,停止信息会指明该名称所在的键空间——资源逻辑 ID 或输出名称——以及组件和名称本身。两种空间都可能以这种方式触及:两个片段可能为不同资源编写同一个资源逻辑 ID;而一个组件通过两条途径得到其输出名称,即显式的 Outputs: 块和它的 provides: 条目,因此两者各有一个条目携带同一名称时也会在此相遇。
重复声明某个名称本身并不构成冲突。以相同内容多次书写的名称无论如何都指向同一事物,因此这些重复声明会合并为单个条目,构建继续进行——普通的重复不会带来任何代价。会导致停止的是丢失内容的情况:两个主体之一必须被丢弃,Recipe 声明的资源或输出随之从栈中缺失。重命名其中任意一个即可消除停止。
结构性输入校验
源模板(sourced template)形式的 CloudFormation 模板在渲染之前会经过结构性校验:provider 解析模板并规范化其中的内部函数,当模板格式有误时,以一条指明出错节点的清晰消息中止构建。解析只检查形状,不检查语义——它不会连接 AWS、不解析引用,也不求值内部函数。
能够解析的模板并不因此被完整保留。 解析只说明文档格式良好;哪些内容进入组装后的堆栈,是另行按节决定的,见组装后堆栈中的顶层节——源模板与片段经过同样的取舍处理。
解析也不检查模板中的引用能否解析。一个 Ref 是否指向某个参数,或一个 Fn::FindInMap 是否指向某个映射,是关于组装后堆栈的问题,而不是关于任何单个输入文档的问题,应由 CloudFormation 在部署时回答。构建会说明它没有保留的内容,而不去判断结果所引用的对象。它确实会判断的引用,是构建自身造成悬空的那些:一种指向被源模板绑定填充的参数,下一节介绍;另一种指向被 omits: 条目从模板中排除的资源,再下一节介绍。
为来源模板的参数提供值
来源模板接收值的方式与 CloudFormation 本身为模板提供值的方式相同:通过它声明的 Parameters。引入它的一方——某个 component 的 Recipe,或某个附加 Feature 的 FeatureRecipe——其 valuesMapping 为它要填充的每个参数写一个键,provider 会在该来源的每个模板中绑定每个键:Resources、Outputs、Conditions、Rules 以及 SAM 的 Globals 中对该参数的每个 Ref 都变为该值,每个将该参数作为变量的 Fn::Sub 通过其变量映射接收该值,且该参数从每个声明它的模板的 Parameters 中移除。没有任何键指定的参数保持模板原样,留待部署栈时传入值或使用其 Default。
**声明参数的单位是来源。**目录来源的模板会组装成一个栈,因此一个模板可以引用同一来源中另一个模板声明的参数。填充该参数时也会在那里填充:仅引用该参数的模板接收的值,与该来源中第一个声明它的模板转换后的值相同,来源中不会留下任何引用其声明已被绑定移除的参数的内容。
**栈中的其他内容都不能引用已填充的参数。**来源之外的内容——同一栈中另一个 component 的片段或来源模板——如果通过 Ref、Fn::Sub 变量或规则的 Fn::ValueOf 指向来源绑定已填充的参数,就会指向组装后的栈不再声明的内容,而 CloudFormation 在部署栈时会拒绝这种情况。因此构建会停止,并指明每个 component、其模板和该参数,以及其 valuesMapping 填充了该参数的 component——Recipe 的,或附加 Feature 的 FeatureRecipe 的;附加到 component 的 Feature 以该 component 指称,附加到边界的 Feature 以其资源作为 aggrega.ai/component-id 携带的标识指称,该标识由边界路径和附加名称组成(边界 stack 上的附加 aux 为 bfr--stack--aux)。Feature 所附加的 component 的片段,或其所附加边界中某个 component 的片段,若引用了该附加绑定已填充的参数,同样会使构建停止。栈仍声明的名称不受影响:若另一个 component 自己声明了同名参数,或某个资源以该名称作为逻辑 ID,则对它的引用解析到该声明并保持原样。要传递该值,可让填充它的 component 发布该值、在引用它的模板中声明该参数,或从 valuesMapping 中移除该键。
spec: capability: cloudformation implements: core/delivery-stream:1.0.0 source: kind: git-repository url: https://github.com/aws-cloudformation/aws-cloudformation-templates.git ref: a0f43bc6d20813052892546f445037cf84c75b54 module_subdir: DataFirehose valuesMapping: | CloudWatchLogGroupRetention: {{ .values.retention_days }} DestinationBucketName: "{{ .context.inject.env.BUCKET_NAME }}"**只有 valuesMapping 会填充参数。**它写入的键是你为模板设定的参数名,因此每个键都必须指向该来源某个模板声明的参数:不指向任何参数的键会使构建停止,并指明该键以及每个模板实际声明的参数——这正是 CloudFormation 对未知参数会报告的错误,只是在你仍能修复时就报告出来。未声明 valuesMapping 的 Recipe 或 FeatureRecipe 不填充任何参数:component 或附加自身的值以其原名到达 provider,供其他输入使用,且不会被读取。
值的类型决定到达模板的内容。
- 字面量——字符串、数字、布尔值或由它们组成的列表——会写入模板,其转换方式与 CloudFormation 在部署栈时对按参数
Type传入的相同值的转换方式一致:Number变为对其Ref所得到的字符串,因此7以"7"到达;CommaDelimitedList或List<…>类型变为字符串列表,可接受列表或成员会被去除首尾空白的逗号分隔字符串;其他所有类型接受一个字符串。字面量会根据参数自身的AllowedValues、AllowedPattern、MinLength、MaxLength、MinValue和MaxValue进行检查,被拒绝的字面量会使构建停止,并指明该参数和约束,因此填充参数不会移除模板声明的任何检查。若模式使用了构建无法读取的正则表达式语法,则留待 CloudFormation 在部署栈时检查。 - 完全由单个 CloudFormation 内部函数构成的值,会以该内部函数的形式到达引用位置,由 CloudFormation 在部署栈时求值:例如长格式映射
{"Fn::GetAtt": [Queue, Arn]},或恰好是一个短格式的字符串——!GetAtt Queue.Arn、!Ref Bucket、!Sub …以及 CloudFormation 定义的其他格式。另一个 component 发布的引用正是这样到达参数的:目录中的 CloudFormation Recipes 以短格式文本发布此类引用,从注入上下文读取它的valuesMapping会将其传递下去。拼接的引用无论加不加引号,读取结果都相同。加引号时——"{{ .context.inject.env.BUCKET_NAME }}"——映射传递的是字符串!GetAtt Queue.Arn;不加引号时,映射自身的 YAML 会把!GetAtt Queue.Arn读作标签,而该标签会连同其参数一起保留,不会被丢弃。两种方式都会以内部函数的形式到达参数。仅以感叹号开头、或不对应任何 CloudFormation 短格式的值,仍为文本。 - 动态引用——
{{resolve:ssm:…}}、{{resolve:ssm-secure:…}}或{{resolve:secretsmanager:…}}——按原样到达引用位置,由 CloudFormation 在部署栈时解析,因此它所指的值永远不会出现在模板中。 - 另一个 component 从不同栈发布的值,会在模板引用该参数的每个位置以跨栈引用的形式到达模板,即片段所接收的同样的
Fn::ImportValue或Fn::GetStackOutput(参见跨栈连接)。
CloudFormation 从 Parameter Store 读取其类型的参数——AWS::SSM::Parameter::Value<…>——没有任何字面量能重现 CloudFormation 对它的处理,因此绑定到此类参数的字面量会使构建停止;请绑定 {{resolve:ssm:…}} 引用或内部函数,或保持其未绑定。绑定到模板作为 Fn::Sub 变量使用的参数的列表同样会使构建停止,因为变量只替换一个字符串。valuesMapping 设为 null 的键也会使构建停止并指明该参数,因为参数需要一个值,而 null 不是值;若要让参数留待部署栈时传入值或使用其 Default,请将其键从映射中省略。
**按名称读取参数的规则会使其保持未绑定。**模板 Rules 中的 Fn::ValueOf 通过逻辑 ID 而非 Ref 指向已声明的参数,而填充参数会移除其声明,因此绑定以这种方式被规则读取的参数会使构建停止,并指明该规则和参数。
**可能携带机密的字面量会被拒绝;内部函数按给定内容写入。**写入模板的值对任何能读取该栈模板的人都是可读的:
- 模板声明为
NoEcho的参数接受动态引用或内部函数,绑定到它的字面量会使构建停止。 - 若
valuesMapping读取了作者声明为敏感的值,其输出都无法追溯到来源值,因此它绑定的每个字面量都会使构建停止。它绑定的动态引用和内部函数按给定内容写入——包括内部函数中的文本。因此,例如映射拼接进Fn::Sub文本中的机密,会以该文本的形式到达模板:只有动态引用能让机密本身不进入模板。此类构建继续进行时,还会为每个已声明的叶子打印一条提示,无论是 Recipe 的映射,还是附加到 component 的 Feature 的 FeatureRecipe 的映射,均会指明该叶子及其映射所属的实体——参见 A declared-sensitive value reaches the target through a values mapping(声明为敏感的值通过值映射到达目标)。 - 若某个动态引用的参数在资源的
UserData属性、AWS::CloudFormation::Init元数据或Outputs中被引用,该动态引用会使构建停止:CloudFormation 不会解析 EC2 用户数据或该元数据中的动态引用,而Outputs会展示给任何读取该堆栈的人。
每一次此类拒绝都会指出相关参数,但不会引用任何值。
从来源模板中省略资源
来源模板的资源属于模板自身:值只能通过模板声明的参数传入,因此,从 git 仓库获取的模板若声明了 Release 不应创建的资源(例如运维方已提供的存储桶,或平台在别处管理的密钥),无法通过值来更改。这正是 Recipe 或 FeatureRecipe 的 omits: 条目的用途。此 provider 仅对来源模板应用这些条目,对其他内容一概不应用:artifacts: 条目编写的片段在渲染时不受其影响。
spec: capability: cloudformation implements: core/store:1.0.0 source: kind: git-repository url: https://git.example.com/platform/templates.git ref: v3.2.0 module_subdir: store omits: # The template bundles an access-log bucket; this Release logs elsewhere. - kind: AWS::S3::Bucket name: StoreLogs一个条目通过资源的 Type 和逻辑 ID 指定一个资源。 条目的 kind 是资源的 Type,例如 AWS::S3::Bucket,其 name 是资源的逻辑 ID,即该资源在 Resources 下的键;两者都按原样精确比较,且必须同时匹配,因此 Type 正确而逻辑 ID 不正确的条目不会省略任何内容。模板没有命名空间,因此带有 namespace 的条目会在该 component 渲染时终止构建,并指出该条目;在省略任何内容之前,所有条目都会先经过检查。
来源中的每个模板都会参与匹配。 单文件来源只有一个模板。目录来源(从 git 仓库获取的来源总是目录来源)包含所有以 .yaml、.yml、.json 或 .template 结尾的文件,条目会在其中任一文件中省略它所指定的每个资源;与模板一同携带的其他文件从不读取。provider 会报告每个条目在所有模板中共省略了多少资源,未省略任何资源的条目会终止构建;参见 An omits entry left out nothing the source rendered(omits 条目未省略来源渲染的任何内容)。
被省略的资源在其他任何环节读取模板之前就已移除。 它不会被标记来源信息,也不计入堆栈所含的名称(因此另一个 component 可以以相同逻辑 ID 提供资源,两者不会冲突),并且永远不会进入组装后的堆栈。模板中的其他内容的写出结果,与编写模板时本就没有该资源完全相同;所有资源都被省略的模板会保留一个空的 Resources 部分。
被省略的资源不得仍被剩余内容引用,因为 CloudFormation 会拒绝引用了未声明资源的模板。资源移除后,剩余模板中对其中任一资源的每个引用都会终止构建,消息会指出模板、资源、引用指定该资源的方式,以及引用所在位置(以从模板根开始的路径表示,例如 /Resources/Store/Properties/LoggingConfiguration/DestinationBucketName)。引用是指 CloudFormation 模板参考中定义为通过逻辑 ID 指定资源的写法,会在每个资源的主体(包括其属性、元数据和策略)以及每个输出中读取:
Ref,以逻辑 ID 为参数;Fn::GetAtt,可以是首项为逻辑 ID 的列表,也可以是一个字符串(如!GetAtt StoreLogs.Arn),其第一个点之前的文本为逻辑 ID;- 资源的
DependsOn,可以是一个逻辑 ID 或逻辑 ID 列表; Fn::Sub的每个变量,包括字符串形式和列表形式:${StoreLogs}和${StoreLogs.Arn}都指定StoreLogs。
有些值只是看起来像引用,不会被当作引用读取。${!StoreLogs} 是字面文本,列表形式的映射所命名的变量取该映射中的值。资源的 Condition 和 Fn::If 的第一个参数指定的是条件,Fn::FindInMap 指定的是映射,Fn::ImportValue 指定的是另一个堆栈的导出值,Fn::GetAZs 指定的是区域。Conditions、Mappings、Parameters 和 Rules 部分不能指定资源,而模板自身的顶层 Metadata 部分是 CloudFormation 存储而非读取的信息,因此这些都不检查。逻辑 ID 本身以内部函数写出的 Ref 或 Fn::GetAtt 仅在 AWS::LanguageExtensions 转换下有效,该转换在堆栈部署时解析它(参见组装后堆栈中的顶层部分),因此它不指定检查能够读取的资源,会保持原样;对来源从未声明的资源的引用同样如此。
检查会一并读取声明条目的 Recipe 或 FeatureRecipe 自身的模板。 这些模板组装为一个堆栈,因此对其中另一个模板仍声明的逻辑 ID 的引用不会终止构建。除此之外不读取其他内容:即使另一个 component 声明了相同逻辑 ID 的资源,对被省略资源的引用仍会终止构建;而组装进该堆栈的其他内容(另一个 component、附加的 Feature,或该 Recipe 自身的 artifacts: 条目)所做的引用不在此检查范围内,因此 CloudFormation 会在部署时拒绝该堆栈。若要保留引用,就保留该资源。绑定到参数的值只会替换对该参数的引用,因此对资源的引用属于模板自身,无法通过值更改:应同时省略发出该引用的资源,或移除该条目。输出不是资源,也没有条目指定输出,因此模板的 Outputs 所引用的资源无法从中省略:省略它会终止构建。
云目标注解
三个边界注解告诉 provider 栈部署到何处,以便它正确地连接跨栈引用:
aggrega.ai/aws-account— 栈部署到的 AWS 账户。aggrega.ai/aws-region— 栈部署到的 AWS 区域。aggrega.ai/aws-assume-role-arn— 跨账户的栈读取为访问对等栈导出的值而承担的 IAM 角色 ARN。
这些注解对编译器不透明——编译器将它们的值原样传递给 provider,而不加以解释(参见 well-known-annotations.md)。它们编写在生产者边界上,即拥有导出值的栈。跨账户读取会承担角色进入生产者的账户,因此描述该读取的账户、区域和角色都来自生产者边界的注解,而不是消费者的注解。
栈内引用
当一条 uses 边连接的两个组件落在同一个边界(即同一个栈)中时,被消费的值会在同一个模板内以 Fn::GetAtt 的形式连接到生产者资源的逻辑 ID。生产者的 provides 值作为原生的栈内引用流入消费者渲染后的输入,无需导出或导入。消费者的片段可以直接写出这样的值——Value: {{ .context.inject.env.DB_HOST }}——也可以写在引号内——Value: "{{ .context.inject.env.DB_HOST }}":无论哪种方式,模板都会将 !GetAtt Db.Endpoint.Address 读作内置函数,因为恰好是一个短格式的字符串,在片段中与在 valuesMapping 中一样,都会作为该内置函数到达栈。aws-rds-and-ecs-service 示例展示了这一点:在一个栈中,Amazon ECS 任务定义读取 RDS 实例的地址。
跨栈连接
当一条 uses 边从一个边界跨到另一个边界时——即两个组件组装到不同的栈中——引用不能是普通值,因为所产生的值在生产者栈部署之前并不存在。provider 将其连接为 CloudFormation 跨栈引用。生产者栈将该值发布为一个栈 Output,并带有 Export,使用确定性的导出名称(由 release、边界、组件和所提供的键派生)。消费者栈通过两个内置函数之一读取它,具体使用哪个由比较两个边界声明的部署位置决定:
Fn::ImportValue——同账户、同区域的情况。CloudFormation 在该账户和区域内,根据匹配的导出名称解析导入。Fn::GetStackOutput——真正的跨账户或跨区域读取。消费者通过承担生产者边界的aws-assume-role-arn进入生产者的账户和区域,直接读取生产者栈的输出。
检测语义。 仅当两个端点都声明了部署位置(账户/区域)且这些位置不同时,provider 才使用 Fn::GetStackOutput。在其他所有情况下——两者都未声明、只有一个声明,或两者声明了相同的位置——它使用 Fn::ImportValue。这是一条保守的规则:同账户的跨栈读取仍是普通导入,直接读取的内置函数只留给真正的跨账户或跨区域跳转。
生产者栈总是发布 Export,即使某个消费者通过 Fn::GetStackOutput 跨账户读取它。未被使用的导出不产生任何作用,而无条件发布它可以让生产者模板独立于每个消费者选择如何读取该值。
一个值的多个消费者读取同一个导出。 当多个组件跨边界读取同一个所提供的值时——同一栈中的两个消费者,或多个栈中的消费者——生产者栈只发布该值的 Export 一次,每个消费者都读取这一个名称:每个 Fn::ImportValue 都导入同一个导出,而位于另一账户或区域的消费者则通过 Fn::GetStackOutput 读取同一个输出。如果某个消费者还读取了其他消费者都不读取的值,则只为该值额外添加导出。
aws-rds-and-ecs-service 示例构建了同账户的情况:RDS 实例的栈导出服务器的边所消费的每个条目,服务器的栈则通过 Fn::ImportValue 逐一读回。
版本说明。
Fn::GetStackOutput是 CloudFormation 的原生内置函数。用它渲染的跨账户引用需要能识别该内置函数的 CloudFormation 工具。同账户路径使用Fn::ImportValue,它在所有环境中都可用。
从连接中读取而非注入的值
消费者的 Recipe 可以通过 .context.uses.<alias>.provides 直接从连接中读取生产者的值,而不是通过连接的 inject 块接收它们。跨越栈边界时,这样的读取与注入的值以相同方式连接:
- 属于 CloudFormation 内置函数的值——例如
!GetAtt Db.Endpoint.Address这样的短格式标签,或长格式的Ref或Fn::映射——指向只有生产者的栈才声明的内容,因此消费者会收到与注入值相同的跨栈引用:生产者栈为该键发布一个Export,消费者用Fn::ImportValue读取它;若两个边界声明的放置位置不同,则用Fn::GetStackOutput读取。 - 纯文本值——端口、协议、数据库名称——在任一栈中含义相同,因此消费者收到的是值本身,也不会为它发布导出。它以 CloudFormation 读取它的形式落地:整体写出的值,其渲染结果与没有边界时相同;写在引号内的数字形式的值则作为数字落地。
一个值是否为内置函数由此 provider 判定,它读取该值的方式与读取生产者自身 provides 块的方式相同。编译器按生产者的 Recipe 所写的原样交出该值,不对其进行解释。
**模板只能复制这样的值。**模板可以整体写出该值,也可以将其写在更长的字符串中,或将其传给一个保持其原样的函数,例如 quote。比较、分支、取长度或改变该值的函数——eq、if、len、upper——都会针对该值以外的东西作出判断,因为在这样的连接上,模板拿到的是一个替身,provider 会在两个栈都组装完成后将其替换。因此构建会停止,指出该模板及其读取的每个值,以及读取该值的连接和两端的组件;请改为依据消费组件自身的值进行分支。附加的 FeatureRecipe 的 injectMapping,以及读取边界连接的边界作用域 FeatureRecipe,也同样如此。写在更长字符串中的值还会遇到 provider 自身的限制:跨栈引用只能作为完整的值存在,因此写在更长字符串中的内置函数会使构建停止,这与注入值的情况相同。
导出名称的构建方式
四个部分用双连字符连接,每个部分都被写成构成导出名称的字母、数字和连字符。字母或数字按原样保留,部分内部的连字符也是如此——payments-db 仍为 payments-db。其他任何字符都写成以 -z 开头的短转义:斜杠写作 -zs,下划线写作 -zu,点写作 -zd。完全没有值的部分写作 -ze。栈名称以相同方式由 release 和边界构建。
因此,在 release orders 中、其输出目录在 dist/ 下为 stack-a/cloudformation 的边界内,从组件 db 发布 host 的导出为:
aggrega--orders--stack-a-zscloudformation--db--host反向解读不会产生歧义,这正是要点而非锦上添花:由于一个部分从不包含两个连续的连字符,也从不以连字符结尾,双连字符总是连接处。因此,两组不同的部分总会产生两个不同的名称。payments-db 和 payments_db 对应两个独立的导出,而不会汇聚为一个,一个部分边缘的连字符也不会被解读为属于相邻部分。
导出名称在什么范围内唯一,以及这一范围止于何处
在一次构建中,一个导出名称恰好标识一个 release、边界、组件和所提供的键——其中任意两个都不会汇聚到同一个名称,因此构建不会让一个导出值被另一个遮盖而丢失。
CloudFormation 还要求导出名称在栈所在账户和区域中已部署的所有内容中唯一。这是部署的属性而非构建的属性,超出了任何构建时派生所能触及的范围:编译器不向 AWS 进行身份验证,不查询它,也无法读取另一次构建的输出,因此任何预先计算的结果都无法观察到那里已经部署了什么。
跨越这条界线保持区分的,是位于每个导出名称和栈名称开头的 release 标识。共享同一账户和区域的两个部署,通过以不同名称发布来使各自的导出互不冲突——这是你能掌控的手段,也是 release 标识位于名称开头而非末尾的原因。
Outputs 条目可以声明自己的导出名称
Recipe 的 Outputs: 块是手写的 CloudFormation,其中的条目可以带有自己的 Export: 和 Name:。该名称按原样进入组装后的栈——provider 不会改写它,不会为它添加前缀,也不要求它看起来像派生名称。
通常对此无需多言。与 provider 派生的任何名称都不匹配的手写导出名称会与派生名称一同发布,且不会被提示。手写是受支持的;只有一种巧合不受支持。
当手写的导出名称与 provider 在同一构建中为跨边界链接派生的名称相同时,构建会中止。 两个声明都会进入组装后的模板,导致同一栈中同一导出名称被声明两次——而导出名称必须唯一,因此两者不能同时存在。中止信息会给出派生的导出名称及构建它的四个部分,以便你看出是哪条链接产生了它;它还会指出手写声明所在的栈输出,并将其标记为由 provider 组装的名称,而非 Recipe 编写的名称。导出名称就是你在 Recipes 中搜索的关键词。 手写条目的写法与中止信息完全一致——正是这种一致构成了冲突——因此它是同时出现在消息和你自己文件中的唯一字符串。重命名该条目声明的导出名称即可消除中止,删除该条目的 Export: 块、让跨栈连接自行发布导出也同样可以。
该检查是构建范围的检查,其范围是单个栈。 它将组装后的栈声明的导出名称,与 provider 为发布到同一栈的跨边界链接派生的名称进行比较——这是构建根据其已组装内容所能进行的比较。两个栈之间不会相互比较。而手写名称与某个账户和区域中已部署的导出之间的关系是部署的属性,超出了任何构建时派生所能触及的范围,原因见 导出名称在什么范围内唯一,以及这一范围止于何处:编译器不向 AWS 进行身份验证,不查询它,也无法读取另一次构建的输出。以内置函数而非普通字符串写成的导出名称同样位于这条界线的另一侧——它在部署时解析,而这里没有任何东西会求值内置函数,因此构建没有可比较的名称。
当跨边界链接发布所用的输出已带有一个并非该链接写入的 Export 时,构建同样会中止。 该输出是 provider 为消费者读取的所提供键而组装的输出,因此,如果某个 Recipe 的 Outputs: 块在同一个键下写了一个条目,并带有自己的 Export:,它的导出就恰好处在链接的导出所在的位置。除非该导出的名称与 provider 派生的名称完全相同——此时它就是链接自己的导出,每个消费者都会导入它——否则两者不能同时存在于该处:写入链接的导出会覆盖你的导出,而保留你的导出则会让每个消费者导入一个链接并未发布的名称。中止信息会给出派生的导出名称及构建它的四个部分,并说明它在该输出处发现了什么:该条目声明的导出名称、以内置函数写成的名称、未指定任何名称的 Export: 块,或以普通值而非块写成的 Export:。删除该条目的 Export: 块即可消除中止,随后跨栈连接会发布每个消费者所导入的导出。
部署顺序
Release 边界的 syncWave: 值决定该边界所汇编到的栈的预配顺序。边界中的每个组件都继承该边界的波次;当多个边界解析到同一输出目录时(因而它们的片段汇编到同一个模板中),该栈包含不止一个波次,provider 会将它们之间的顺序表示为 DependsOn。
每个资源都会列出紧邻其前、且含有资源的那个 wave 中的所有资源,不会列出更早的 wave。 其余部分由 CloudFormation 串联起来:wave 2 中的资源依赖 wave 1,而后者又依赖 wave 0,因此整个序列是有序的,同时每个资源自身的列表只有一个 wave 的规模,而不是整个栈的规模。wave 不必连续,负值也很常见——对于栈中其余部分要读取的存储桶或角色,-1 是常用的选择。最低的 wave 不列出任何资源,因为它之前没有任何内容。
该顺序是什么:创建顺序,反过来即删除顺序。 CloudFormation 会尽可能并行地操作资源,而 DependsOn 会覆盖这种并行性,按指定的顺序操作所列出的资源。该属性同时作用于两个方向,因此较早创建资源的波次也会较晚删除它——正确的拆除顺序随该顺序一并获得,无需其他任何处理。
它不是就绪顺序。 栈模板不表达资源是否可用的概念,因此这里不会等待资源就绪,只会等待 CloudFormation 完成创建。这与 compose 上的同一波次确有不同:在那里,声明了 healthcheck 的服务会被等待,直到其报告健康为止;compose 有可用于把关的就绪原语,而栈模板没有。创建顺序就是该目标所提供的,直白地说明这一点,比给一个无法兑现的承诺附加说明更有用。
手写的 DependsOn 会被扩展,而不会被替换。 声明了自身顺序约束的片段会保留该约束:它所写的条目保持在前,按其书写顺序排列,波次的条目跟在后面。两项要求都成立,且互不遮蔽。单个逻辑 ID 和列表都可被读取,合并后的值以列表形式输出,无论合并产生多少条目,这都是唯一适用的写法。
所有资源都属于同一波次的栈不会因此受到任何影响。 完全未声明 syncWave 的 Release 也是如此:每个贡献者都带有该字段的默认值 0,汇编后的模板只包含一个波次,输出与 provider 不表达任何波次顺序时完全相同。
跨两个栈的顺序无法表达,也不会被近似处理。 DependsOn 指向同一模板内的资源,而汇编到另一个栈中的组件位于该模板之外。因此,波次只对它所汇编到的栈中的每个资源排序,不涉及栈以外的任何内容。为两个栈排定顺序是运维人员的事,正如跨栈引用是在部署时而非构建时解析的。
波次未表达的顺序仍由 CloudFormation 自己负责,而资源之间的引用已经承载了其中很大一部分:针对生产者资源的 Fn::GetAtt 会让 CloudFormation 先创建该资源。若片段需要的约束既不由引用也不由波次隐含,则由它自己编写 DependsOn,这正是上述合并所保留的情形。
确定性
在输入相同时,provider 在多次运行中输出逐字节相同的堆栈模板:逻辑 ID、输出键、导出名称和资源顺序都是确定的,因此 CloudFormation 堆栈模板在 GitOps 审查中可以得到干净的 diff。