Operator Notes 操作员备注

  1. HTTP Backoff and Retry
    HTTP 退避和重试
  2. AWS S3 access AWS S3 访问
  3. HTTP headers HTTP 头部
  4. Filesystem-Reuse Semantics
    文件系统重用语义
  5. Path Traversal and Following Symlinks
    路径遍历和跟随符号链接
  6. SELinux
  7. Partition Reuse Semantics
    分区重用语义
    1. Partition Matching 分区匹配
    2. Partition number 0 分区编号 0
    3. Partition start 0 分区起始位置 0
    4. Unspecified partition start
      未指定的分区起始位置
    5. Partition size 0 分区大小为 0
    6. Unspecified partition size
      未指定的分区大小
  8. Config Merging 配置合并
    1. Child configs take precedence when specified
      当指定时，子配置优先
    2. Most lists are deduplicated
      大多数列表都会去重
    3. Files, Directories, and Links are deduplicated across each other
      文件、目录和链接在彼此之间进行了去重
    4. Configs are merged in a depth first traversal
      配置在深度优先遍历中合并
    5. HTTP headers merging HTTP 头合并
  9. LUKS
    1. Clevis Based Devices Clevis 基础设备
  10. Secrets 秘密
    1. Automatic config deletion
      自动配置删除

HTTP Backoff and Retry
HTTP 退避和重试

When Ignition is fetching a resource over http(s), if the resource is unavailable Ignition will continually retry to fetch the resource with an exponential backoff between requests.
当 Ignition 通过 http(s) 获取资源时，如果资源不可用，Ignition 将不断重试获取资源，并在请求之间采用指数退避。

For a given retry attempt, Ignition will wait 10 seconds for the server to send the response headers for the request. If response headers are not received in this time, or an HTTP 5XX error code is received, the request is cancelled, Ignition waits for the backoff, and a new request is made.
对于给定的重试尝试，Ignition 将等待 10 秒钟，以便服务器发送请求的响应头。如果在此时间内未收到响应头，或者收到 HTTP 5XX 错误代码，则请求将被取消，Ignition 等待退避，并发出新的请求。

Any HTTP response code less than 500 results in the request being completed, and either the resource will be fetched or Ignition will fail.
任何小于 500 的 HTTP 响应代码都会导致请求完成，资源将被获取，或者 Ignition 将失败。

Ignition will initially wait 100 milliseconds between failed attempts, and the amount of time to wait doubles for each failed attempt until it reaches 5 seconds.
Ignition 最初在失败尝试之间等待 100 毫秒，每次失败尝试等待的时间加倍，直到达到 5 秒。

AWS S3 access AWS S3 访问

Ignition has built-in support for fetching resources from the Amazon Simple Storage Service (AWS S3). Several URL formats are supported:
Ignition 内置支持从亚马逊简单存储服务 (AWS S3) 获取资源。支持多种 URL 格式：

URL format URL 格式Supported specs 支持的规范SemanticsIgnition behavior in Amazon EC2 instance
亚马逊 EC2 实例中的点火行为		Ignition behavior outside EC2
EC2 外部的点火行为
s3://<bucket>/<object-path>3.0.0+Fetch the object. 获取对象。Fetch from the same AWS partition as the instance. Authenticate using the instance’s IAM role, or fetch anonymously if no role is available.
从与实例相同的 AWS 分区获取。使用实例的 IAM 角色进行身份验证，如果没有角色可用，则匿名获取。		Fetch anonymously from the aws (public AWS) partition.
从 aws （公共 AWS）分区匿名获取。
arn:<partition>:s3:::<bucket>/<object-path>3.4.0+Fetch the object from the specified partition.
从指定的分区获取对象。		Authenticate using the instance’s IAM role, or fetch anonymously if no role is available.
使用实例的 IAM 角色进行身份验证，如果没有角色可用，则匿名获取。		Fetch anonymously. 匿名获取。
arn:<partition>:s3:<region>:<account>:accesspoint/<access-point>/object/<object-path>3.4.0+Fetch the object from the specified access point. Multi-region access points are not supported.
从指定的访问点获取对象。不支持多区域访问点。		Authenticate using the instance’s IAM role, or fail if no role is available.
使用实例的 IAM 角色进行身份验证，如果没有可用的角色则失败。		Fail. Access points don’t support anonymous access.
失败。访问点不支持匿名访问。

Append ?versionId=<version> to any of the URL formats to fetch the specified object version.
将 ?versionId=<version> 添加到任何 URL 格式中，以获取指定的对象版本。

HTTP headers HTTP 头

When fetching data from an HTTP URL for config references, CA references and file contents, additional headers can be attached to the request using the httpHeaders attribute. This allows downloading data from servers that require authentication or some additional parameters from your request.
从 HTTP URL 获取配置引用、CA 引用和文件内容时，可以使用 httpHeaders 属性附加额外的标头到请求中。这允许从需要身份验证或从您的请求中获取一些额外参数的服务器下载数据。

Headers can be attached only when source has http or https scheme.
只有当 source 具有 http 或 https 方案时才能附加标头。

If multiple values are to be set for the same header, they must be separated by a comma. Example: {"name": "Accept", "value": "text/html, application/json"}.
如果要为同一标头设置多个值，则它们必须用逗号分隔。示例： {"name": "Accept", "value": "text/html, application/json"} 。

If the remote HTTP server returns a redirect status code (3xx), then additional headers are not included in the redirected request.
如果远程 HTTP 服务器返回重定向状态码（3xx），则重定向请求中不包括附加标头。

If a specified header is one that Ignition sets by default, such as Accept or User-Agent, the specified value overrides Ignition’s default.
如果指定的标头是 Ignition 默认设置的标头之一，例如 Accept 或 User-Agent ，则指定的值将覆盖 Ignition 的默认设置。

Filesystem-Reuse Semantics
文件系统重用语义

When a machine first boots, it’s possible that an earlier installation or other process has already provisioned the disks. The Ignition config can specify the intended filesystem for a given device, and there are three possibilities when Ignition runs:
当计算机首次启动时，可能早期安装或其他进程已经为磁盘提供了空间。Ignition 配置可以指定给定设备的预期文件系统，在 Ignition 运行时有三种可能性：

  • There is no preexisting filesystem.
    不存在预先存在的文件系统。
  • There is a preexisting filesystem of the correct type, label, or UUID (e.g. the Ignition config says /dev/sda should be ext4, and it is ext4).
    存在正确类型、标签或 UUID 的预先存在的文件系统（例如，Ignition 配置指定 /dev/sda 应为 ext4 ，而实际为 ext4 ）。
  • There is a preexisting filesystem of an incorrect type, label, or UUID (e.g. the Ignition config says /dev/sda should be ext4, and it is btrfs).
    存在不正确类型、标签或 UUID 的预先存在的文件系统（例如，Ignition 配置指定 /dev/sda 应为 ext4 ，而实际为 btrfs ）。

In the first case, when there is no preexisting filesystem, Ignition will always create the desired filesystem.
在第一种情况下，当没有现有文件系统时，Ignition 将始终创建所需的文件系统。

In the second two cases, where there is a preexisting filesystem, Ignition’s behavior is controlled by the wipeFilesystem flag in the filesystem section.
在后两种情况中，如果存在现有文件系统，则 Ignition 的行为受 wipeFilesystem 标志在 filesystem 部分中的控制。

If wipeFilesystem is set to true, Ignition will always wipe any preexisting filesystem and create the desired filesystem (or skip creation if the format is set to none). Note this will result in any data on the old filesystem being lost.
如果 wipeFilesystem 设置为 true，则 Ignition 将始终擦除任何现有文件系统并创建所需的文件系统（或者如果格式设置为 none 则跳过创建）。请注意，这将导致旧文件系统上的任何数据丢失。

If wipeFilesystem is set to false, Ignition will then attempt to reuse the existing filesystem. If the filesystem is of the correct type, has a matching label, and has a matching UUID, then Ignition will reuse the filesystem. If the label or UUID is not set in the Ignition config, they don’t need to match for Ignition to reuse the filesystem. Any preexisting data will be left on the device and will be available to the installation. If the preexisting filesystem is not of the correct type, then Ignition will fail, and the machine will fail to boot. Similarly, if the format is set to none, then any preexisting filesystem will cause Ignition to fail.
如果 wipeFilesystem 设置为 false，则 Ignition 将尝试重用现有文件系统。如果文件系统是正确类型的，具有匹配的标签和匹配的 UUID，则 Ignition 将重用文件系统。如果在 Ignition 配置中未设置标签或 UUID，则它们不需要匹配以便 Ignition 重用文件系统。任何现有数据都将保留在设备上，并可供安装使用。如果现有文件系统不是正确类型，则 Ignition 将失败，机器将无法启动。同样，如果格式设置为 none ，则任何现有文件系统都将导致 Ignition 失败。

When resolving paths, Ignition follows symlinks on all but the last element of a path. This ensures existing symlinks on a filesystem can be overwritten while still following symlinks as expected. When writing files, links, or directories, Ignition does not allow following symlinks outside the specified filesystem. When writing files, links, or directories on the root filesystem, Ignition follows symlinks as if it were executing in that root; a symlink to /etc is followed to /etc on the root filesystem. When writing files, links, or directories to any other filesystem, Ignition fails if it tries to follow a symlink outside that filesystem.
在解析路径时，Ignition 在路径的最后一个元素之外遵循符号链接。这确保了文件系统上的现有符号链接可以被覆盖，同时仍然按预期遵循符号链接。在写入文件、链接或目录时，Ignition 不允许跟随超出指定文件系统范围的符号链接。在写入文件、链接或目录到 root 文件系统时，Ignition 会按照在该根目录执行的方式来遵循符号链接；指向 /etc 的符号链接会在 root 文件系统上被跟随到 /etc 。在向任何其他文件系统写入文件、链接或目录时，如果尝试跟随超出该文件系统范围的符号链接，Ignition 将失败。

SELinux

Ignition fully supports distributions which have SELinux enabled. It requires that the distribution ships the setfiles utility. The kernel must be at least v5.5 or alternatively have this patch backported.
Ignition 完全支持启用 SELinux 的发行版。它要求发行版提供 setfiles 实用程序。内核必须至少为 v5.5，或者必须已经将此补丁进行了回溯。

Partition Reuse Semantics
分区重用语义

The wipePartitionEntry and shouldExist flags control what Ignition will do when it encounters an existing partition. wipePartitionEntry specifies whether Ignition is permitted to delete partition entries in the partition table. shouldExist specifies whether a partition with that number should exist or not (it is invalid to specify a partition should not exist and specify its attributes, such as size or label).
当 Ignition 遇到现有分区时， wipePartitionEntry 和 shouldExist 标志控制 Ignition 的操作。 wipePartitionEntry 指定 Ignition 是否允许删除分区表中的分区条目。 shouldExist 指定该编号的分区是否应存在（指定分区不应存在并指定其属性，如 size 或 label 是无效的）。

The following table shows the possible combinations of whether or not a partition with the specified number is present, shouldExist, and wipePartitionEntry, and the action Ignition will take:
以下表格显示了指定编号的分区是否存在， shouldExist 和 wipePartitionEntry ，以及 Ignition 将采取的操作的可能组合：

Partition present 分区存在shouldExistwipePartitionEntryAction Ignition takes 行动点火
falsefalsefalseDo nothing 什么都不做
falsefalsetrueDo nothing 什么都不做
falsetruefalseCreate specified partition
创建指定的分区
falsetruetrueCreate specified partition
创建指定的分区
truefalsefalseFail
truefalsetrueDelete existing partition
删除现有分区
truetruefalseVerify existing partition matches the specified one, otherwise resize it if resize field is true and partition matches in all respects except size, otherwise fail
验证现有分区是否与指定分区匹配，否则如果 resize 字段为 true 且分区在所有方面（除大小外）匹配，则调整其大小，否则失败
truetruetrueCheck if existing partition matches the specified one, delete existing partition and create specified partition if it does not match
检查现有分区是否与指定分区匹配，如果不匹配，则删除现有分区并创建指定分区

Partition Matching 分区匹配

A partition matches if all of the specified attributes (label, start, size, uuid, and typeGuid) are the same. Specifying uuid or typeGuid as an empty string is the same as not specifying them. When 0 is specified for start or size, Ignition checks if the existing partition’s start / size match what they would be if all of the partitions specified were to be deleted (if allowed by wipePartitionEntry), then recreated if shouldExist is true.
如果所有指定的属性（ label ， start ， size ， uuid 和 typeGuid ）都相同，则分区匹配。 将 uuid 或 typeGuid 指定为空字符串等同于不指定它们。 当为开始或大小指定 0 时，Ignition 会检查现有分区的开始/大小是否与如果删除了所有指定的分区（如果允许 wipePartitionEntry），然后如果 shouldExist 为 true，则重新创建的开始/大小匹配。

Partition number 0 分区号 0

Specifying number as 0 will use the next available partition number. Partition number 0 is disallowed on disks with partitions that specify shouldExist as false. If number is not specified it will be treated as 0.
将 number 指定为 0 将使用下一个可用的分区号。 在指定 shouldExist 为 false 的分区上禁止使用分区号 0。 如果未指定 number ，则将视为 0。

Partition start 0 分区开始 0

Specifying start as 0 will use the starting sector of the largest available block. This is not necessarily the first available block large enough.
将 start 指定为 0 将使用最大可用块的起始扇区。这不一定是第一个足够大的可用块。

Unspecified partition start
未指定的分区开始

If start is not specified and a partition with the same number exists, Ignition will use the start of the existing partition, unless wipePartitionEntry is set. If start is not specified and there is no existing partition, or wipePartitionEntry is set, Ignition will use the starting sector of the largest block, as if start were set to 0.
如果未指定 start ，并且存在相同编号的分区，则 Ignition 将使用现有分区的起始位置，除非设置了 wipePartitionEntry。如果未指定 start ，并且不存在现有分区，或者设置了 wipePartitionEntry，则 Ignition 将使用最大块的起始扇区，就好像 start 设置为 0 一样。

Partition size 0 分区大小为 0

Specifying size as 0 means the partition should span to the end of the largest available block. If the starting sector is not within the largest available block, Ignition will fail.
将 size 指定为 0 意味着分区应跨越到最大可用块的末尾。如果起始扇区不在最大可用块内，则 Ignition 将失败。

Unspecified partition size
未指定的分区大小

If size is not specified and a partition with the same number exists, it will use the value of the existing partition, unless wipePartitionEntry is set. If size is not specified and there is no existing partition, or wipePartitionEntry is set, size act as if it were set to 0 and use the size of the largest block.
如果未指定 size ，并且存在相同编号的分区，则将使用现有分区的值，除非设置了 wipePartitionEntry。如果未指定 size ，并且不存在现有分区，或者设置了 wipePartitionEntry，则 size 将被视为设置为 0，并使用最大块的大小。

Config Merging 配置合并

Ignition supports fetching and merging multiple configs. This replaces the append functionality of the Ignition 2.x.0 specification. There are several rules that determine how configs get merged. When a child config is merged with a parent, generally the child config’s values override the parent config’s values.
Ignition 支持获取和合并多个配置。这取代了 Ignition 2.x.0 规范的 append 功能。有几条规则决定了如何合并配置。当子配置与父配置合并时，通常子配置的值会覆盖父配置的值。

Child configs take precedence when specified
指定子配置优先

If a parent and child object are being merged, the fields in the child object take precedence over the fields in the parent config. If a field in the child object is not specified, the field from the parent is used instead.
如果正在合并父对象和子对象，则子对象中的字段优先于父配置中的字段。如果子对象中的字段未指定，则使用父对象中的字段。

Most lists are deduplicated
大多数列表都已去重

All lists of objects have a field that uniquely identifies that object. If a child config contains an entry that matches an entry already specified in the parent config, those entries are merged. A few sections of the config are exempt from this behavior. See the configuration specification for a complete listing. Generally the only lists that are simply appended are those that specify arguments to commands like mkfs or mdadm.
所有对象列表都有一个字段，用于唯一标识该对象。如果子配置包含与父配置中已指定的条目匹配的条目，则这些条目将被合并。配置的一些部分不受此行为的影响。有关完整列表，请参阅配置规范。通常，仅追加的列表是那些指定命令参数的列表，如 mkfs 或 mdadm 。

Since files, directories, and links all describe filesystem entries can conflict, these lists are deduplicated across each other. This means a file in a child config can replace a link in the parent, or a directory in a child config can replace a file in the parent.
由于文件、目录和链接都描述文件系统条目，可能会发生冲突，因此这些列表在彼此之间进行了去重。这意味着子配置中的文件可以替换父级中的链接，或者子配置中的目录可以替换父级中的文件。

Configs are merged in a depth first traversal
配置以深度优先遍历方式合并

A child config can specify children of its own. Those children are merged into their parent config before that config is merged into its own parent. If a config specifies multiple children, those children are merged in the order they appear.
子配置可以指定自己的子项。这些子项在合并到其父配置之前会先合并到其父配置中。如果一个配置指定了多个子项，则这些子项会按照它们出现的顺序进行合并。

HTTP headers merging HTTP 头合并

If names of the parent and child headers match, the result will be to replace the value of the parent header with that of the child.
如果父头部和子头部的名称匹配，则结果将是用子头部的值替换父头部的值。

If a child header has no value, the parent header with the same name will be removed.
如果子头部没有值，则将删除具有相同名称的父头部。

LUKS

Ignition has support for creating both purely key-file based LUKS2 devices as well as Tang/TPM2 backed (via clevis) devices.
点火支持创建纯粹基于密钥文件的 LUKS2 设备，也支持 Tang/TPM2 支持的（通过 clevis）设备。

If a key-file is not specified one will be generated for the device. Key-files will be stored at /etc/luks/<deviceName> (this path can be overridden via build flags).
如果未指定密钥文件，将为设备生成一个。密钥文件将存储在 /etc/luks/<deviceName> （此路径可以通过构建标志进行覆盖）。

Ignition generates entries in /etc/crypttab for each device and expects that the operating system has hooks to be able to unlock the device (e.x.: systemd-cryptsetup-generator).
点火为每个设备生成 /etc/crypttab 中的条目，并期望操作系统具有钩子以能够解锁设备（例如： systemd-cryptsetup-generator ）。

Clevis Based Devices 基于 Clevis 的设备

When creating clevis based devices to utilize Tang or TPM2 Ignition will use an SSS Pin and will create the relevant configuration JSON from the provided attributes.
当创建基于 Clevis 的设备以利用 Tang 或 TPM2 时，Ignition 将使用 SSS Pin，并从提供的属性创建相关的配置 JSON。

Secrets 秘密

We do not recommend storing secrets in Ignition configs. Many platforms allow unprivileged software in a VM (including software running in a container) to retrieve the Ignition config from a networked metadata service or local API. To avoid any possibility of leaking sensitive information, it’s best to store secrets in a dedicated service such as Hashicorp Vault.
我们不建议在 Ignition 配置中存储秘密。许多平台允许在虚拟机中的非特权软件（包括在容器中运行的软件）从网络化的元数据服务或本地 API 检索 Ignition 配置。为了避免泄露敏感信息的可能性，最好将秘密存储在专用服务中，如 Hashicorp Vault。

If you must store secrets in an Ignition config, strongly consider applying mitigations. For example:
如果必须在 Ignition 配置中存储秘密，请强烈考虑应用缓解措施。例如：

  • Put secrets in a child Ignition config stored in a location under your control. Configure firewall rules to prevent unprivileged software from accessing this location. Merge the child config into your root config via an ignition.config.merge directive.
    将机密信息放入一个由您控制的位置存储的子 Ignition 配置中。配置防火墙规则，以防止非特权软件访问此位置。通过 ignition.config.merge 指令将子配置合并到根配置中。
  • On platforms with a networked instance metadata service (IMDS), configure firewall rules to prevent unprivileged software from contacting the metadata service. Some software uses the instance metadata service for other purposes (such as determining network addresses), so this may not be practical without a transparent proxy.
    在具有网络化实例元数据服务（IMDS）的平台上，配置防火墙规则，以防止非特权软件联系元数据服务。一些软件使用实例元数据服务进行其他目的（如确定网络地址），因此在没有透明代理的情况下可能不太实际。

Automatic config deletion
自动配置删除

On some platforms, Ignition 2.14.0 and later automatically deletes the Ignition config from VM metadata after provisioning succeeds. This helps limit access by unprivileged software to sensitive information in the Ignition config. This functionality is currently supported in VirtualBox and VMware VMs, and other platforms may be added in the future.
在某些平台上，Ignition 2.14.0 及更高版本在成功配置后会自动从 VM 元数据中删除 Ignition 配置。这有助于限制非特权软件对 Ignition 配置中敏感信息的访问。目前，此功能仅在 VirtualBox 和 VMware VM 中受支持，其他平台可能会在将来添加。

If you have external tools that require the Ignition config to remain available in VM metadata after provisioning, you can prevent automatic deletion by masking ignition-delete-config.service. For example:
如果您有需要在配置后保留 Ignition 配置在 VM 元数据中的外部工具，您可以通过屏蔽 ignition-delete-config.service 来阻止自动删除。例如：

{
  "ignition": {
    "version": "3.0.0"
  },
  "systemd": {
    "units": [
      {
        "name": "ignition-delete-config.service",
        "mask": true
      }
    ]
  }
}