From 1989f244916a8f32ed9d11028b85b15904e2e638 Mon Sep 17 00:00:00 2001 From: Benjamin Gilbert Date: Fri, 24 Mar 2023 05:18:35 -0400 Subject: [PATCH 1/6] Initial support for automatic spec doc generation Move all field descriptions to a single YAML file and generate version- specific spec docs from that. Use reflection to walk the config structs for each version and omit fields which don't exist in a particular spec version. We don't do this at a JSON Schema level because e.g. Resource is referenced in multiple places with different semantics and different doc strings. For now, keep the code out of the external API. The plan is to add functionality to support Butane docs generation, at which point internal/doc/generate will move to config/doc. Update the stabilization checklist to remove manual tweaking of spec docs. --- .github/ISSUE_TEMPLATE/stabilize-checklist.md | 8 +- .github/workflows/go.yml | 10 +- generate | 13 +- go.mod | 2 +- internal/doc/generate/generate.go | 140 ++++++ internal/doc/generate/ignition.yaml | 424 ++++++++++++++++++ internal/doc/generate/schema.go | 24 + internal/doc/main.go | 83 ++++ 8 files changed, 693 insertions(+), 11 deletions(-) create mode 100644 internal/doc/generate/generate.go create mode 100644 internal/doc/generate/ignition.yaml create mode 100644 internal/doc/generate/schema.go create mode 100644 internal/doc/main.go diff --git a/.github/ISSUE_TEMPLATE/stabilize-checklist.md b/.github/ISSUE_TEMPLATE/stabilize-checklist.md index 107f8cc96..edfc6ee39 100644 --- a/.github/ISSUE_TEMPLATE/stabilize-checklist.md +++ b/.github/ISSUE_TEMPLATE/stabilize-checklist.md @@ -30,7 +30,7 @@ The changes that are required to achieve these effects are typically the followi - [ ] Update `config/vX_(Y+1)_experimental/translate/translate_test.go` to point the `old` import to the new stable `vX_Y/types` package - [ ] Update `config/config.go` imports to point to the experimental version. - [ ] Update `config/config_test.go` to add the new experimental version to `TestConfigStructure`. -- [ ] Update `generate` to generate the new stable and experimental versions, and rerun `generate`. +- [ ] Update `generate` to generate the new stable and experimental versions. ## Update all relevant places to use the new experimental package @@ -48,9 +48,9 @@ The changes that are required to achieve these effects are typically the followi ## Update docs -- [ ] Rename `docs/configuration-vX_Y-experimental.md` to `docs/configuration-vX_Y.md` and make a copy as `docs/configuration-vX_(Y+1)_experimental.md`. -- [ ] In `docs/configuration-vX_Y.md`, drop `-experimental` from the version number in the heading and the `ignition.version` field, and drop the prerelease warning. Update the `nav_order` field in the Jekyll front matter to be one less than the `nav_order` of the previous stable spec. -- [ ] In `docs/configuration-vX_(Y+1)_experimental.md`, update the version of the experimental spec in the heading and the `ignition.version` field. +- [ ] Update `internal/doc/main.go` to add the new stable spec and reference the new experimental spec in `generate()`. +- [ ] Remove `docs/configuration-vX_Y-experimental.md`. +- [ ] Run `generate` to regenerate Go schemas and spec docs. - [ ] Add a section to `docs/migrating-configs.md`. - [ ] In `docs/specs.md`, update the list of stable and experimental spec versions (listing the latest stable release first) and update the table listing the Ignition release where a spec has been marked as stable. - [ ] Note the stabilization in `docs/release-notes.md`, following the format of previous stabilizations. Drop the `-exp` version suffix from any notes for the upcoming release. diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml index eb11978a0..b62d0d761 100644 --- a/.github/workflows/go.yml +++ b/.github/workflows/go.yml @@ -75,13 +75,13 @@ jobs: git clone -b gomod https://github.com/bgilbert/schematyper cd schematyper go install . - - name: Regenerate schema + - name: Regenerate schema and spec docs run: ./generate - - name: Check whether schema is current + - name: Check whether schema and spec docs are current run: | - if [ -n "$(git status --porcelain config)" ]; then - echo "Found local changes after regenerating schema:" - git --no-pager diff --color=always config + if [ -n "$(git status --porcelain config docs)" ]; then + echo "Found local changes after regenerating:" + git --no-pager diff --color=always config docs echo "Rerun './generate'." exit 1 fi diff --git a/generate b/generate index dc99d242a..a69e8bde3 100755 --- a/generate +++ b/generate @@ -16,6 +16,17 @@ specs="v3_0 v3_1 v3_2 v3_3 v3_4 v3_5_experimental" for spec in $specs do - echo "Generating schema..." + echo "Generating $spec schema..." schematyper --package=types "config/${spec}/schema/ignition.json" -o "config/${spec}/types/schema.go" --root-type=Config done + +echo "Generating docs..." +eval $(go env) +NAME="ignition" +ORG_PATH="github.com/coreos" +REPO_PATH="${ORG_PATH}/${NAME}/v2" +if [ -z ${BIN_PATH+a} ]; then + export BIN_PATH=${PWD}/bin/${GOARCH} +fi +go build -o ${BIN_PATH}/doc ${REPO_PATH}/internal/doc +${BIN_PATH}/doc ${PWD}/docs diff --git a/go.mod b/go.mod index 4493608f9..47400fcb3 100644 --- a/go.mod +++ b/go.mod @@ -21,6 +21,7 @@ require ( golang.org/x/oauth2 v0.6.0 golang.org/x/sys v0.6.0 google.golang.org/api v0.114.0 + gopkg.in/yaml.v3 v3.0.1 ) require ( @@ -44,5 +45,4 @@ require ( google.golang.org/genproto v0.0.0-20230320184635-7606e756e683 // indirect google.golang.org/grpc v1.53.0 // indirect google.golang.org/protobuf v1.29.1 // indirect - gopkg.in/yaml.v3 v3.0.1 // indirect ) diff --git a/internal/doc/generate/generate.go b/internal/doc/generate/generate.go new file mode 100644 index 000000000..10bb30476 --- /dev/null +++ b/internal/doc/generate/generate.go @@ -0,0 +1,140 @@ +// Copyright 2023 Red Hat, Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package generate + +import ( + "bytes" + _ "embed" + "fmt" + "io" + "reflect" + "strings" + + "gopkg.in/yaml.v3" + + "github.com/coreos/ignition/v2/config/util" +) + +//go:embed ignition.yaml +var ignitionDocs []byte + +func Generate(config any, w io.Writer) error { + decoder := yaml.NewDecoder(bytes.NewBuffer(ignitionDocs)) + decoder.KnownFields(true) + var docs FieldDocs + if err := decoder.Decode(&docs); err != nil { + return fmt.Errorf("unmarshaling documentation: %w", err) + } + if err := descendStruct(docs, reflect.TypeOf(config), 0, w); err != nil { + return err + } + return nil +} + +func descendStruct(docs FieldDocs, typ reflect.Type, level int, w io.Writer) error { + if typ.Kind() != reflect.Struct { + return fmt.Errorf("not a struct: %v (%v)", typ.Name(), typ.Kind()) + } + fieldsByTag, err := structFieldsByTag(typ) + if err != nil { + return err + } + // iterate in order of docs YAML + for _, doc := range docs { + field, ok := fieldsByTag[doc.Name] + if !ok { + // have documentation but no struct field + continue + } + var optional string + if !util.IsTrue(doc.Required) && (util.IsFalse(doc.Required) || !util.IsPrimitive(field.Type.Kind())) { + optional = "_" + } + // write the entry + if _, err := fmt.Fprintf(w, "%s* **%s%s%s** (%s): %s\n", strings.Repeat(" ", level), optional, doc.Name, optional, typeName(field.Type), doc.Description); err != nil { + return err + } + // recurse + if err := descend(&doc, field.Type, level+1, w); err != nil { + return err + } + // delete from map to keep track of fields we've seen + delete(fieldsByTag, doc.Name) + } + // check for undocumented fields + for _, field := range fieldsByTag { + return fmt.Errorf("undocumented field: %v.%v", typ.Name(), field.Name) + } + return nil +} + +func descend(doc *FieldDoc, typ reflect.Type, level int, w io.Writer) error { + kind := typ.Kind() + switch { + case util.IsPrimitive(kind): + return nil + case kind == reflect.Struct: + return descendStruct(doc.Children, typ, level, w) + case kind == reflect.Slice, kind == reflect.Ptr: + return descend(doc, typ.Elem(), level, w) + default: + return fmt.Errorf("%v has kind %v", typ.Name(), kind) + } +} + +func structFieldsByTag(typ reflect.Type) (map[string]reflect.StructField, error) { + ret := make(map[string]reflect.StructField, typ.NumField()) + for i := 0; i < typ.NumField(); i++ { + field := typ.Field(i) + if field.Anonymous { + // anonymous embedded structure; merge its fields + sub, err := structFieldsByTag(field.Type) + if err != nil { + return nil, err + } + for k, v := range sub { + ret[k] = v + } + } else { + tag, ok := field.Tag.Lookup("json") + if !ok { + return nil, fmt.Errorf("no field tag: %v.%v", typ.Name(), field.Name) + } + // extract the field name, ignoring omitempty etc. + tag = strings.Split(tag, ",")[0] + ret[tag] = field + } + } + return ret, nil +} + +func typeName(typ reflect.Type) string { + switch typ.Kind() { + case reflect.Bool: + return "boolean" + case reflect.Int: + return "integer" + case reflect.Pointer: + return typeName(typ.Elem()) + case reflect.Slice: + return fmt.Sprintf("list of %ss", typeName(typ.Elem())) + case reflect.String: + return "string" + case reflect.Struct: + return "object" + default: + panic(fmt.Errorf("unknown type kind: %v", typ.Kind())) + } +} diff --git a/internal/doc/generate/ignition.yaml b/internal/doc/generate/ignition.yaml new file mode 100644 index 000000000..6e10b848e --- /dev/null +++ b/internal/doc/generate/ignition.yaml @@ -0,0 +1,424 @@ +- name: ignition + desc: metadata about the configuration itself. + # required because ignition.version is + required: true + children: + - name: version + desc: the semantic version number of the spec. The spec version must be compatible with the latest version (`3.5.0-experimental`). Compatibility requires the major versions to match and the spec version be less than or equal to the latest version. `-experimental` versions compare less than the final version with the same number, and previous experimental versions are not accepted. + - name: config + desc: options related to the configuration. + children: + - name: merge + desc: a list of the configs to be merged to the current config. + children: + - name: source + desc: "the URL of the config. Supported schemes are `http`, `https`, `s3`, `arn`, `gs`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified." + # source is sometimes optional, but required here by validation + required: true + - name: compression + desc: the type of compression used on the config (null or gzip). Compression cannot be used with S3. + - name: httpHeaders + desc: a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. + children: + - name: name + desc: the header name. + - name: value + desc: the header contents. + - name: verification + desc: options related to the verification of the config. + children: + - name: hash + desc: the hash of the config, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed config. + - name: replace + desc: the config that will replace the current. + children: + - name: source + desc: "the URL of the config. Supported schemes are `http`, `https`, `s3`, `arn`, `gs`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified." + # source is sometimes optional, but required here by validation + required: true + - name: compression + desc: the type of compression used on the config (null or gzip). Compression cannot be used with S3. + - name: httpHeaders + desc: a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. + children: + - name: name + desc: the header name. + - name: value + desc: the header contents. + - name: verification + desc: options related to the verification of the config. + children: + - name: hash + desc: the hash of the config, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed config. + - name: timeouts + desc: options relating to `http` timeouts when fetching files over `http` or `https`. + children: + - name: httpResponseHeaders + desc: "the time to wait (in seconds) for the server's response headers (but not the body) after making a request. 0 indicates no timeout. Default is 10 seconds." + - name: httpTotal + desc: "the time limit (in seconds) for the operation (connection, request, and response), including retries. 0 indicates no timeout. Default is 0." + - name: security + desc: options relating to network security. + children: + - name: tls + desc: "options relating to TLS when fetching resources over `https`." + children: + - name: certificateAuthorities + desc: the list of additional certificate authorities (in addition to the system authorities) to be used for TLS verification when fetching over `https`. All certificate authorities must have a unique `source`. + children: + - name: source + desc: "the URL of the certificate bundle (in PEM format). The bundle can contain multiple concatenated certificates. Supported schemes are `http`, `https`, `s3`, `arn`, `gs`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified." + # source is sometimes optional, but required here by + # validation + required: true + - name: compression + desc: the type of compression used on the certificate (null or gzip). Compression cannot be used with S3. + - name: httpHeaders + desc: a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. + children: + - name: name + desc: the header name. + - name: value + desc: the header contents. + - name: verification + desc: options related to the verification of the certificate. + children: + - name: hash + desc: the hash of the certificate, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed certificate. + - name: proxy + desc: options relating to setting an `HTTP(S)` proxy when fetching resources. + children: + - name: httpProxy + desc: will be used as the proxy URL for HTTP requests and HTTPS requests unless overridden by `httpsProxy` or `noProxy`. + - name: httpsProxy + desc: will be used as the proxy URL for HTTPS requests unless overridden by `noProxy`. + - name: noProxy + desc: specifies a list of strings to hosts that should be excluded from proxying. Each value is represented by an `IP address prefix (1.2.3.4)`, `an IP address prefix in CIDR notation (1.2.3.4/8)`, `a domain name`, or `a special DNS label (*)`. An IP address prefix and domain name can also include a literal port number `(1.2.3.4:80)`. A domain name matches that name and all subdomains. A domain name with a leading `.` matches subdomains only. For example `foo.com` matches `foo.com` and `bar.foo.com`; `.y.com` matches `x.y.com` but not `y.com`. A single asterisk `(*)` indicates that no proxying should be done. +- name: storage + desc: "describes the desired state of the system's storage devices." + children: + - name: disks + desc: the list of disks to be configured and their options. Every entry must have a unique `device`. + children: + - name: device + desc: the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. + - name: wipeTable + desc: whether or not the partition tables shall be wiped. When true, the partition tables are erased before any further manipulation. Otherwise, the existing entries are left intact. + - name: partitions + desc: the list of partitions and their configuration for this particular disk. Every partition must have a unique `number`, or if 0 is specified, a unique `label`. + children: + - name: label + desc: the PARTLABEL for the partition. + - name: number + desc: the partition number, which dictates its position in the partition table (one-indexed). If zero, use the next available partition slot. + # non-pointer field, but can default to zero + required: false + - name: sizeMiB + desc: the size of the partition (in mebibytes). If zero, the partition will be made as large as possible. + - name: startMiB + desc: the start of the partition (in mebibytes). If zero, the partition will be positioned at the start of the largest block available. + - name: typeGuid + desc: the GPT [partition type GUID](http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs). If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data). + - name: guid + desc: the GPT unique partition GUID. + - name: wipePartitionEntry + desc: if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead. + - name: shouldExist + desc: whether or not the partition with the specified `number` should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on `wipePartitionEntry`. If false `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted. + - name: resize + desc: whether or not the existing partition should be resized. If omitted, it defaults to false. If true, Ignition will resize an existing partition if it matches the config in all respects except the partition size. + - name: raid + desc: the list of RAID arrays to be configured. Every RAID array must have a unique `name`. + children: + - name: name + desc: the name to use for the resulting md device. + - name: level + desc: the redundancy level of the array (e.g. linear, raid1, raid5, etc.). + # not part of the primary key, but required by validation + required: true + - name: devices + desc: the list of devices (referenced by their absolute path) in the array. + # required by validation + required: true + - name: spares + desc: the number of spares (if applicable) in the array. + - name: options + desc: any additional options to be passed to mdadm. + - name: filesystems + desc: the list of filesystems to be configured. `device` and `format` need to be specified. Every filesystem must have a unique `device`. + children: + - name: device + desc: the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. + - name: format + desc: the filesystem format (ext4, btrfs, xfs, vfat, swap, or none). + # not part of the primary key, but required by validation + required: true + - name: path + desc: the mount-point of the filesystem while Ignition is running relative to where the root filesystem will be mounted. This is not necessarily the same as where it should be mounted in the real root, but it is encouraged to make it the same. + - name: wipeFilesystem + desc: whether or not to wipe the device before filesystem creation, see [the documentation on filesystems](operator-notes.md#filesystem-reuse-semantics) for more information. Defaults to false. + - name: label + desc: the label of the filesystem. + - name: uuid + desc: the uuid of the filesystem. + - name: options + desc: any additional options to be passed to the format-specific mkfs utility. + - name: mountOptions + desc: any special options to be passed to the mount command. + - name: files + desc: the list of files to be written. Every file, directory and link must have a unique `path`. + children: + - name: path + desc: the absolute path to the file. + - name: overwrite + desc: whether to delete preexisting nodes at the path. `contents.source` must be specified if `overwrite` is true. Defaults to false. + - name: contents + desc: options related to the contents of the file. + children: + - name: compression + desc: the type of compression used on the contents (null or gzip). Compression cannot be used with S3. + - name: source + desc: "the URL of the file contents. Supported schemes are `http`, `https`, `tftp`, `s3`, `arn`, `gs`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. If source is omitted and a regular file already exists at the path, Ignition will do nothing. If source is omitted and no file exists, an empty file will be created." + - name: httpHeaders + desc: a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. + children: + - name: name + desc: the header name. + - name: value + desc: the header contents. + - name: verification + desc: options related to the verification of the file contents. + children: + - name: hash + desc: the hash of the contents, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed contents. + - name: append + desc: list of contents to be appended to the file. Follows the same stucture as `contents` + children: + - name: compression + desc: the type of compression used on the contents (null or gzip). Compression cannot be used with S3. + - name: source + desc: "the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `arn`, `gs`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified." + - name: httpHeaders + desc: a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. + children: + - name: name + desc: the header name. + - name: value + desc: the header contents. + - name: verification + desc: options related to the verification of the appended contents. + children: + - name: hash + desc: the hash of the contents, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed contents. + - name: mode + desc: the file's permission mode. Note that the mode must be properly specified as a **decimal** value (i.e. 0644 -> 420). Setuid/setgid/sticky bits are supported. If not specified, the permission mode for files defaults to 0644 or the existing file's permissions if `overwrite` is false, `contents.source` is unspecified, and a file already exists at the path. + - name: user + desc: "specifies the file's owner." + children: + - name: id + desc: the user ID of the owner. + - name: name + desc: the user name of the owner. + - name: group + desc: "specifies the file's group." + children: + - name: id + desc: the group ID of the group. + - name: name + desc: the group name of the group. + - name: directories + desc: the list of directories to be created. Every file, directory, and link must have a unique `path`. + children: + - name: path + desc: the absolute path to the directory. + - name: overwrite + desc: whether to delete preexisting nodes at the path. If false and a directory already exists at the path, Ignition will only set its permissions. If false and a non-directory exists at that path, Ignition will fail. Defaults to false. + - name: mode + desc: "the directory's permission mode. Note that the mode must be properly specified as a **decimal** value (i.e. 0755 -> 493). Setuid/setgid/sticky bits are supported. If not specified, the permission mode for directories defaults to 0755 or the mode of an existing directory if `overwrite` is false and a directory already exists at the path." + - name: user + desc: "specifies the directory's owner." + children: + - name: id + desc: the user ID of the owner. + - name: name + desc: the user name of the owner. + - name: group + desc: "specifies the directory's group." + children: + - name: id + desc: the group ID of the group. + - name: name + desc: the group name of the group. + - name: links + desc: the list of links to be created. Every file, directory, and link must have a unique `path`. + children: + - name: path + desc: the absolute path to the link + - name: overwrite + desc: whether to delete preexisting nodes at the path. If overwrite is false and a matching link exists at the path, Ignition will only set the owner and group. Defaults to false. + - name: user + desc: specifies the owner for a symbolic link. Ignored for hard links. + children: + - name: id + desc: the user ID of the owner. + - name: name + desc: the user name of the owner. + - name: group + desc: specifies the group for a symbolic link. Ignored for hard links. + children: + - name: id + desc: the group ID of the group. + - name: name + desc: the group name of the group. + - name: target + desc: the target path of the link + # not part of the primary key, but required by validation + required: true + - name: hard + desc: a symbolic link is created if this is false, a hard one if this is true. + - name: luks + desc: the list of luks devices to be created. Every device must have a unique `name`. + children: + - name: name + desc: the name of the luks device. + - name: device + desc: the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. + # not part of the primary key, but required by validation + required: true + - name: keyFile + desc: options related to the contents of the key file. + children: + - name: compression + desc: the type of compression used on the contents (null or gzip). Compression cannot be used with S3. + - name: source + desc: "the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `arn`, `gs`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified." + - name: httpHeaders + desc: a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. + children: + - name: name + desc: the header name. + - name: value + desc: the header contents. + - name: verification + desc: options related to the verification of the key file. + children: + - name: hash + desc: the hash of the contents, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed contents. + - name: label + desc: the label of the luks device. + - name: uuid + desc: the uuid of the luks device. + - name: options + desc: any additional options to be passed to `cryptsetup luksFormat`. + - name: discard + desc: whether to issue discard commands to the underlying block device when blocks are freed. Enabling this improves performance and device longevity on SSDs and space utilization on thinly provisioned SAN devices, but leaks information about which disk blocks contain data. If omitted, it defaults to false. + - name: openOptions + desc: any additional options to be passed to `cryptsetup luksOpen`. Supported options will be persistently written to the luks volume. + - name: wipeVolume + desc: whether or not to wipe the device before volume creation, see [the documentation on filesystems](operator-notes.md#filesystem-reuse-semantics) for more information. + - name: clevis + desc: describes the clevis configuration for the luks device. + children: + - name: tang + desc: describes a tang server. Every server must have a unique `url`. + children: + - name: url + desc: url of the tang server. + - name: thumbprint + desc: thumbprint of a trusted signing key. + # required by validation + required: true + - name: advertisement + desc: the advertisement JSON. If not specified, the advertisement is fetched from the tang server during provisioning. + - name: tpm2 + desc: whether or not to use a tpm2 device. + - name: threshold + desc: sets the minimum number of pieces required to decrypt the device. Default is 1. + - name: custom + desc: overrides the clevis configuration. The `pin` & `config` will be passed directly to `clevis luks bind`. If specified, all other clevis options must be omitted. + children: + - name: pin + desc: the clevis pin. + # required by validation + required: true + - name: config + desc: the clevis configuration JSON. + # required by validation + required: true + - name: needsNetwork + desc: whether or not the device requires networking. +- name: systemd + desc: describes the desired state of the systemd units. + children: + - name: units + desc: the list of systemd units. Every unit must have a unique `name`. + children: + - name: name + desc: the name of the unit. This must be suffixed with a valid unit type (e.g. "thing.service"). + - name: enabled + desc: whether or not the service shall be enabled. When true, the service is enabled. When false, the service is disabled. When omitted, the service is unmodified. In order for this to have any effect, the unit must have an install section. + - name: mask + desc: whether or not the service shall be masked. When true, the service is masked by symlinking it to `/dev/null`. When false, the service is unmasked by deleting the symlink to `/dev/null` if it exists. + - name: contents + desc: the contents of the unit. + - name: dropins + desc: the list of drop-ins for the unit. Every drop-in must have a unique `name`. + children: + - name: name + desc: the name of the drop-in. This must be suffixed with ".conf". + - name: contents + desc: the contents of the drop-in. +- name: passwd + desc: describes the desired additions to the passwd database. + children: + - name: users + desc: the list of accounts that shall exist. All users must have a unique `name`. + children: + - name: name + desc: the username for the account. + - name: passwordHash + desc: the encrypted password for the account. + - name: sshAuthorizedKeys + desc: "a list of SSH keys to be added as an SSH key fragment at `.ssh/authorized_keys.d/ignition` in the user's home directory. All SSH keys must be unique." + - name: uid + desc: the user ID of the account. + - name: gecos + desc: the GECOS field of the account. + - name: homeDir + desc: the home directory of the account. + - name: noCreateHome + desc: whether or not to create the user's home directory. This only has an effect if the account doesn't exist yet. + - name: primaryGroup + desc: the name of the primary group of the account. + - name: groups + desc: the list of supplementary groups of the account. + - name: noUserGroup + desc: "whether or not to create a group with the same name as the user. This only has an effect if the account doesn't exist yet." + - name: noLogInit + desc: "whether or not to add the user to the lastlog and faillog databases. This only has an effect if the account doesn't exist yet." + - name: shell + desc: the login shell of the new account. + - name: shouldExist + desc: whether or not the user with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified user. + - name: system + desc: "whether or not this account should be a system account. This only has an effect if the account doesn't exist yet." + - name: groups + desc: the list of groups to be added. All groups must have a unique `name`. + children: + - name: name + desc: the name of the group. + - name: gid + desc: the group ID of the new group. + - name: passwordHash + desc: the encrypted password of the new group. + - name: shouldExist + desc: whether or not the group with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified group. + - name: system + desc: "whether or not the group should be a system group. This only has an effect if the group doesn't exist yet." +- name: kernelArguments + desc: describes the desired kernel arguments. + children: + - name: shouldExist + desc: the list of kernel arguments that should exist. + - name: shouldNotExist + desc: the list of kernel arguments that should not exist. diff --git a/internal/doc/generate/schema.go b/internal/doc/generate/schema.go new file mode 100644 index 000000000..737a06858 --- /dev/null +++ b/internal/doc/generate/schema.go @@ -0,0 +1,24 @@ +// Copyright 2023 Red Hat, Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package generate + +type FieldDocs []FieldDoc + +type FieldDoc struct { + Name string `yaml:"name"` + Description string `yaml:"desc"` + Required *bool `yaml:"required"` + Children FieldDocs `yaml:"children"` +} diff --git a/internal/doc/main.go b/internal/doc/main.go new file mode 100644 index 000000000..97811892e --- /dev/null +++ b/internal/doc/main.go @@ -0,0 +1,83 @@ +// Copyright 2023 Red Hat, Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package main + +import ( + "fmt" + "os" + "path/filepath" + + "github.com/coreos/go-semver/semver" + + v30 "github.com/coreos/ignition/v2/config/v3_0/types" + v31 "github.com/coreos/ignition/v2/config/v3_1/types" + v32 "github.com/coreos/ignition/v2/config/v3_2/types" + v33 "github.com/coreos/ignition/v2/config/v3_3/types" + v34 "github.com/coreos/ignition/v2/config/v3_4/types" + v35 "github.com/coreos/ignition/v2/config/v3_5_experimental/types" + doc "github.com/coreos/ignition/v2/internal/doc/generate" +) + +func generate(dir string) error { + configs := []struct { + version string + config any + }{ + {"3.0.0", v30.Config{}}, + {"3.1.0", v31.Config{}}, + {"3.2.0", v32.Config{}}, + {"3.3.0", v33.Config{}}, + {"3.4.0", v34.Config{}}, + {"3.5.0-experimental", v35.Config{}}, + } + + if err := os.MkdirAll(dir, 0755); err != nil { + return err + } + + for _, c := range configs { + ver := semver.New(c.version) + + // open file + prerelease := "" + if ver.PreRelease != "" { + prerelease = "_" + string(ver.PreRelease) + } + path := filepath.Join(dir, fmt.Sprintf("configuration-v%d_%d%s.md", ver.Major, ver.Minor, prerelease)) + f, err := os.OpenFile(path, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0644) + if err != nil { + return err + } + defer f.Close() + + // write docs + err = doc.Generate(c.config, f) + if err != nil { + return fmt.Errorf("generating doc for %s: %w", c.version, err) + } + } + return nil +} + +func main() { + if len(os.Args) != 2 { + fmt.Fprintf(os.Stderr, "Usage: %s \n", os.Args[0]) + os.Exit(1) + } + if err := generate(os.Args[1]); err != nil { + fmt.Fprintf(os.Stderr, "%s\n", err) + os.Exit(1) + } +} From f7aac9e884ba85a8e917ea8c92d7bf2ba74553f2 Mon Sep 17 00:00:00 2001 From: Benjamin Gilbert Date: Fri, 24 Mar 2023 05:42:03 -0400 Subject: [PATCH 2/6] internal/doc: re-add header to spec docs --- internal/doc/header.md | 14 ++++++++++++++ internal/doc/main.go | 25 +++++++++++++++++++++++-- 2 files changed, 37 insertions(+), 2 deletions(-) create mode 100644 internal/doc/header.md diff --git a/internal/doc/header.md b/internal/doc/header.md new file mode 100644 index 000000000..46ac03977 --- /dev/null +++ b/internal/doc/header.md @@ -0,0 +1,14 @@ +--- +title: Config Spec v{{ .Version }} +parent: Configuration specifications +nav_order: {{ .NavOrder }} +--- + +# Configuration Specification v{{.Version}} + +{{ if .Version.PreRelease -}} +_NOTE_: This pre-release version of the specification is experimental and is subject to change without notice or regard to backward compatibility. + +{{ end -}} +The Ignition configuration is a JSON document conforming to the following specification, with **_italicized_** entries being optional: + diff --git a/internal/doc/main.go b/internal/doc/main.go index 97811892e..aaf6ca023 100644 --- a/internal/doc/main.go +++ b/internal/doc/main.go @@ -15,9 +15,11 @@ package main import ( + _ "embed" "fmt" "os" "path/filepath" + "text/template" "github.com/coreos/go-semver/semver" @@ -30,24 +32,31 @@ import ( doc "github.com/coreos/ignition/v2/internal/doc/generate" ) +var ( + //go:embed header.md + headerRaw string + header = template.Must(template.New("header").Parse(headerRaw)) +) + func generate(dir string) error { configs := []struct { version string config any }{ + // generate in inverse order of website navbar + {"3.5.0-experimental", v35.Config{}}, {"3.0.0", v30.Config{}}, {"3.1.0", v31.Config{}}, {"3.2.0", v32.Config{}}, {"3.3.0", v33.Config{}}, {"3.4.0", v34.Config{}}, - {"3.5.0-experimental", v35.Config{}}, } if err := os.MkdirAll(dir, 0755); err != nil { return err } - for _, c := range configs { + for i, c := range configs { ver := semver.New(c.version) // open file @@ -62,6 +71,18 @@ func generate(dir string) error { } defer f.Close() + // write header + args := struct { + Version *semver.Version + NavOrder int + }{ + Version: ver, + NavOrder: 50 - i, + } + if err := header.Execute(f, args); err != nil { + return fmt.Errorf("writing header for %s: %w", c.version, err) + } + // write docs err = doc.Generate(c.config, f) if err != nil { From ad540ac1bd49963de1df0f2458fc4318451abddc Mon Sep 17 00:00:00 2001 From: Benjamin Gilbert Date: Fri, 24 Mar 2023 06:43:30 -0400 Subject: [PATCH 3/6] internal/doc: support string replacements on specific spec versions --- internal/doc/generate/generate.go | 21 ++++--- internal/doc/generate/ignition.yaml | 94 +++++++++++++++++++++++++++++ internal/doc/generate/schema.go | 57 +++++++++++++++-- internal/doc/main.go | 2 +- 4 files changed, 161 insertions(+), 13 deletions(-) diff --git a/internal/doc/generate/generate.go b/internal/doc/generate/generate.go index 10bb30476..d21fa68c4 100644 --- a/internal/doc/generate/generate.go +++ b/internal/doc/generate/generate.go @@ -22,6 +22,7 @@ import ( "reflect" "strings" + "github.com/coreos/go-semver/semver" "gopkg.in/yaml.v3" "github.com/coreos/ignition/v2/config/util" @@ -30,20 +31,20 @@ import ( //go:embed ignition.yaml var ignitionDocs []byte -func Generate(config any, w io.Writer) error { +func Generate(ver *semver.Version, config any, w io.Writer) error { decoder := yaml.NewDecoder(bytes.NewBuffer(ignitionDocs)) decoder.KnownFields(true) var docs FieldDocs if err := decoder.Decode(&docs); err != nil { return fmt.Errorf("unmarshaling documentation: %w", err) } - if err := descendStruct(docs, reflect.TypeOf(config), 0, w); err != nil { + if err := descendStruct(ver, docs, reflect.TypeOf(config), 0, w); err != nil { return err } return nil } -func descendStruct(docs FieldDocs, typ reflect.Type, level int, w io.Writer) error { +func descendStruct(ver *semver.Version, docs FieldDocs, typ reflect.Type, level int, w io.Writer) error { if typ.Kind() != reflect.Struct { return fmt.Errorf("not a struct: %v (%v)", typ.Name(), typ.Kind()) } @@ -63,11 +64,15 @@ func descendStruct(docs FieldDocs, typ reflect.Type, level int, w io.Writer) err optional = "_" } // write the entry - if _, err := fmt.Fprintf(w, "%s* **%s%s%s** (%s): %s\n", strings.Repeat(" ", level), optional, doc.Name, optional, typeName(field.Type), doc.Description); err != nil { + desc, err := doc.RenderDescription(ver) + if err != nil { + return err + } + if _, err := fmt.Fprintf(w, "%s* **%s%s%s** (%s): %s\n", strings.Repeat(" ", level), optional, doc.Name, optional, typeName(field.Type), desc); err != nil { return err } // recurse - if err := descend(&doc, field.Type, level+1, w); err != nil { + if err := descend(ver, &doc, field.Type, level+1, w); err != nil { return err } // delete from map to keep track of fields we've seen @@ -80,15 +85,15 @@ func descendStruct(docs FieldDocs, typ reflect.Type, level int, w io.Writer) err return nil } -func descend(doc *FieldDoc, typ reflect.Type, level int, w io.Writer) error { +func descend(ver *semver.Version, doc *FieldDoc, typ reflect.Type, level int, w io.Writer) error { kind := typ.Kind() switch { case util.IsPrimitive(kind): return nil case kind == reflect.Struct: - return descendStruct(doc.Children, typ, level, w) + return descendStruct(ver, doc.Children, typ, level, w) case kind == reflect.Slice, kind == reflect.Ptr: - return descend(doc, typ.Elem(), level, w) + return descend(ver, doc, typ.Elem(), level, w) default: return fmt.Errorf("%v has kind %v", typ.Name(), kind) } diff --git a/internal/doc/generate/ignition.yaml b/internal/doc/generate/ignition.yaml index 6e10b848e..14d32ba47 100644 --- a/internal/doc/generate/ignition.yaml +++ b/internal/doc/generate/ignition.yaml @@ -15,6 +15,13 @@ desc: "the URL of the config. Supported schemes are `http`, `https`, `s3`, `arn`, `gs`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified." # source is sometimes optional, but required here by validation required: true + transforms: + - regex: "`gs`, " + replacement: "" + max: 3.1.0 + - regex: "`arn`, " + replacement: "" + max: 3.3.0 - name: compression desc: the type of compression used on the config (null or gzip). Compression cannot be used with S3. - name: httpHeaders @@ -29,6 +36,14 @@ children: - name: hash desc: the hash of the config, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed config. + transforms: + - regex: "either `sha512` or `sha256`" + replacement: '`sha512`' + max: 3.0.0 + # No compression field in 3.0.0 + - regex: " If `compression` .* config." + replacement: "" + max: 3.0.0 - name: replace desc: the config that will replace the current. children: @@ -36,6 +51,13 @@ desc: "the URL of the config. Supported schemes are `http`, `https`, `s3`, `arn`, `gs`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified." # source is sometimes optional, but required here by validation required: true + transforms: + - regex: "`gs`, " + replacement: "" + max: 3.1.0 + - regex: "`arn`, " + replacement: "" + max: 3.3.0 - name: compression desc: the type of compression used on the config (null or gzip). Compression cannot be used with S3. - name: httpHeaders @@ -50,6 +72,14 @@ children: - name: hash desc: the hash of the config, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed config. + transforms: + - regex: "either `sha512` or `sha256`" + replacement: '`sha512`' + max: 3.0.0 + # No compression field in 3.0.0 + - regex: " If `compression` .* config." + replacement: "" + max: 3.0.0 - name: timeouts desc: options relating to `http` timeouts when fetching files over `http` or `https`. children: @@ -71,6 +101,13 @@ # source is sometimes optional, but required here by # validation required: true + transforms: + - regex: "`gs`, " + replacement: "" + max: 3.1.0 + - regex: "`arn`, " + replacement: "" + max: 3.3.0 - name: compression desc: the type of compression used on the certificate (null or gzip). Compression cannot be used with S3. - name: httpHeaders @@ -85,6 +122,14 @@ children: - name: hash desc: the hash of the certificate, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed certificate. + transforms: + - regex: "either `sha512` or `sha256`" + replacement: '`sha512`' + max: 3.0.0 + # No compression field in 3.0.0 + - regex: " If `compression` .* certificate." + replacement: "" + max: 3.0.0 - name: proxy desc: options relating to setting an `HTTP(S)` proxy when fetching resources. children: @@ -153,6 +198,10 @@ desc: the filesystem format (ext4, btrfs, xfs, vfat, swap, or none). # not part of the primary key, but required by validation required: true + transforms: + - regex: "swap, or none" + replacement: "or swap" + max: 3.2.0 - name: path desc: the mount-point of the filesystem while Ignition is running relative to where the root filesystem will be mounted. This is not necessarily the same as where it should be mounted in the real root, but it is encouraged to make it the same. - name: wipeFilesystem @@ -179,6 +228,13 @@ desc: the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - name: source desc: "the URL of the file contents. Supported schemes are `http`, `https`, `tftp`, `s3`, `arn`, `gs`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. If source is omitted and a regular file already exists at the path, Ignition will do nothing. If source is omitted and no file exists, an empty file will be created." + transforms: + - regex: "`gs`, " + replacement: "" + max: 3.1.0 + - regex: "`arn`, " + replacement: "" + max: 3.3.0 - name: httpHeaders desc: a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. children: @@ -191,6 +247,10 @@ children: - name: hash desc: the hash of the contents, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed contents. + transforms: + - regex: "either `sha512` or `sha256`" + replacement: '`sha512`' + max: 3.0.0 - name: append desc: list of contents to be appended to the file. Follows the same stucture as `contents` children: @@ -198,6 +258,13 @@ desc: the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - name: source desc: "the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `arn`, `gs`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified." + transforms: + - regex: "`gs`, " + replacement: "" + max: 3.1.0 + - regex: "`arn`, " + replacement: "" + max: 3.3.0 - name: httpHeaders desc: a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. children: @@ -210,8 +277,16 @@ children: - name: hash desc: the hash of the contents, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed contents. + transforms: + - regex: "either `sha512` or `sha256`" + replacement: '`sha512`' + max: 3.0.0 - name: mode desc: the file's permission mode. Note that the mode must be properly specified as a **decimal** value (i.e. 0644 -> 420). Setuid/setgid/sticky bits are supported. If not specified, the permission mode for files defaults to 0644 or the existing file's permissions if `overwrite` is false, `contents.source` is unspecified, and a file already exists at the path. + transforms: + - regex: are supported + replacement: are not supported + max: 3.3.0 - name: user desc: "specifies the file's owner." children: @@ -235,6 +310,10 @@ desc: whether to delete preexisting nodes at the path. If false and a directory already exists at the path, Ignition will only set its permissions. If false and a non-directory exists at that path, Ignition will fail. Defaults to false. - name: mode desc: "the directory's permission mode. Note that the mode must be properly specified as a **decimal** value (i.e. 0755 -> 493). Setuid/setgid/sticky bits are supported. If not specified, the permission mode for directories defaults to 0755 or the mode of an existing directory if `overwrite` is false and a directory already exists at the path." + transforms: + - regex: are supported + replacement: are not supported + max: 3.3.0 - name: user desc: "specifies the directory's owner." children: @@ -292,6 +371,13 @@ desc: the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - name: source desc: "the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `arn`, `gs`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified." + transforms: + - regex: "`gs`, " + replacement: "" + max: 3.1.0 + - regex: "`arn`, " + replacement: "" + max: 3.3.0 - name: httpHeaders desc: a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. children: @@ -304,6 +390,14 @@ children: - name: hash desc: the hash of the contents, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed contents. + transforms: + - regex: "either `sha512` or `sha256`" + replacement: "`sha512`" + max: 3.0.0 + # No compression field in 3.0.0 + - regex: " If `compression` .* contents." + replacement: "" + max: 3.0.0 - name: label desc: the label of the luks device. - name: uuid diff --git a/internal/doc/generate/schema.go b/internal/doc/generate/schema.go index 737a06858..4836196e6 100644 --- a/internal/doc/generate/schema.go +++ b/internal/doc/generate/schema.go @@ -14,11 +14,60 @@ package generate +import ( + "fmt" + "regexp" + + "github.com/coreos/go-semver/semver" +) + type FieldDocs []FieldDoc type FieldDoc struct { - Name string `yaml:"name"` - Description string `yaml:"desc"` - Required *bool `yaml:"required"` - Children FieldDocs `yaml:"children"` + Name string `yaml:"name"` + Description string `yaml:"desc"` + Required *bool `yaml:"required"` + Transforms []Transform `yaml:"transforms"` + Children FieldDocs `yaml:"children"` +} + +type Transform struct { + Regex string `yaml:"regex"` + Replacement string `yaml:"replacement"` + MinVer *string `yaml:"min"` + MaxVer *string `yaml:"max"` +} + +func (doc *FieldDoc) RenderDescription(ver *semver.Version) (string, error) { + desc := doc.Description + for _, xfrm := range doc.Transforms { + if xfrm.MinVer != nil { + min, err := semver.NewVersion(*xfrm.MinVer) + if err != nil { + return "", fmt.Errorf("field %q: parsing min %q: %w", doc.Name, *xfrm.MinVer, err) + } + if ver.LessThan(*min) { + continue + } + } + if xfrm.MaxVer != nil { + max, err := semver.NewVersion(*xfrm.MaxVer) + if err != nil { + return "", fmt.Errorf("field %q: parsing max %q: %w", doc.Name, *xfrm.MaxVer, err) + } + if max.LessThan(*ver) { + continue + } + } + re, err := regexp.Compile(xfrm.Regex) + if err != nil { + return "", fmt.Errorf("field %q: compiling %q: %w", doc.Name, xfrm.Regex, err) + } + new := re.ReplaceAllString(desc, xfrm.Replacement) + if new == desc { + return "", fmt.Errorf("field %q: applying %q: transform didn't change anything", doc.Name, xfrm.Regex) + } + desc = new + } + return desc, nil } diff --git a/internal/doc/main.go b/internal/doc/main.go index aaf6ca023..c1ab0569f 100644 --- a/internal/doc/main.go +++ b/internal/doc/main.go @@ -84,7 +84,7 @@ func generate(dir string) error { } // write docs - err = doc.Generate(c.config, f) + err = doc.Generate(ver, c.config, f) if err != nil { return fmt.Errorf("generating doc for %s: %w", c.version, err) } From de75e463024e8048405e55d02402c9f9b132862e Mon Sep 17 00:00:00 2001 From: Benjamin Gilbert Date: Fri, 24 Mar 2023 06:46:48 -0400 Subject: [PATCH 4/6] internal/doc: allow substituting spec version into generated doc --- internal/doc/generate/ignition.yaml | 2 +- internal/doc/generate/schema.go | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/internal/doc/generate/ignition.yaml b/internal/doc/generate/ignition.yaml index 14d32ba47..11a2658e3 100644 --- a/internal/doc/generate/ignition.yaml +++ b/internal/doc/generate/ignition.yaml @@ -4,7 +4,7 @@ required: true children: - name: version - desc: the semantic version number of the spec. The spec version must be compatible with the latest version (`3.5.0-experimental`). Compatibility requires the major versions to match and the spec version be less than or equal to the latest version. `-experimental` versions compare less than the final version with the same number, and previous experimental versions are not accepted. + desc: the semantic version number of the spec. The spec version must be compatible with the latest version (`%VERSION%`). Compatibility requires the major versions to match and the spec version be less than or equal to the latest version. `-experimental` versions compare less than the final version with the same number, and previous experimental versions are not accepted. - name: config desc: options related to the configuration. children: diff --git a/internal/doc/generate/schema.go b/internal/doc/generate/schema.go index 4836196e6..0674d0169 100644 --- a/internal/doc/generate/schema.go +++ b/internal/doc/generate/schema.go @@ -17,6 +17,7 @@ package generate import ( "fmt" "regexp" + "strings" "github.com/coreos/go-semver/semver" ) @@ -39,7 +40,7 @@ type Transform struct { } func (doc *FieldDoc) RenderDescription(ver *semver.Version) (string, error) { - desc := doc.Description + desc := strings.ReplaceAll(doc.Description, "%VERSION%", ver.String()) for _, xfrm := range doc.Transforms { if xfrm.MinVer != nil { min, err := semver.NewVersion(*xfrm.MinVer) From 379d4814b9bb2784acdb8888b426bdf11686c9bd Mon Sep 17 00:00:00 2001 From: Benjamin Gilbert Date: Fri, 24 Mar 2023 18:38:05 -0400 Subject: [PATCH 5/6] docs: regenerate spec docs Move link URLs inline and fix various small errors. Fixes https://github.com/coreos/ignition/issues/1469. --- docs/configuration-v3_0.md | 31 ++++++++-------- docs/configuration-v3_1.md | 29 +++++++-------- docs/configuration-v3_2.md | 45 +++++++++++------------ docs/configuration-v3_3.md | 45 +++++++++++------------ docs/configuration-v3_4.md | 47 ++++++++++++------------- docs/configuration-v3_5_experimental.md | 47 ++++++++++++------------- docs/release-notes.md | 1 + 7 files changed, 114 insertions(+), 131 deletions(-) diff --git a/docs/configuration-v3_0.md b/docs/configuration-v3_0.md index c5e0a0e10..21239a7cb 100644 --- a/docs/configuration-v3_0.md +++ b/docs/configuration-v3_0.md @@ -10,24 +10,24 @@ The Ignition configuration is a JSON document conforming to the following specif * **ignition** (object): metadata about the configuration itself. * **version** (string): the semantic version number of the spec. The spec version must be compatible with the latest version (`3.0.0`). Compatibility requires the major versions to match and the spec version be less than or equal to the latest version. `-experimental` versions compare less than the final version with the same number, and previous experimental versions are not accepted. - * **_config_** (objects): options related to the configuration. + * **_config_** (object): options related to the configuration. * **_merge_** (list of objects): a list of the configs to be merged to the current config. - * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_verification_** (object): options related to the verification of the config. * **_hash_** (string): the hash of the config, in the form `-` where type is `sha512`. * **_replace_** (object): the config that will replace the current. - * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_verification_** (object): options related to the verification of the config. * **_hash_** (string): the hash of the config, in the form `-` where type is `sha512`. * **_timeouts_** (object): options relating to `http` timeouts when fetching files over `http` or `https`. - * **_httpResponseHeaders_** (integer) the time to wait (in seconds) for the server's response headers (but not the body) after making a request. 0 indicates no timeout. Default is 10 seconds. - * **_httpTotal_** (integer) the time limit (in seconds) for the operation (connection, request, and response), including retries. 0 indicates no timeout. Default is 0. + * **_httpResponseHeaders_** (integer): the time to wait (in seconds) for the server's response headers (but not the body) after making a request. 0 indicates no timeout. Default is 10 seconds. + * **_httpTotal_** (integer): the time limit (in seconds) for the operation (connection, request, and response), including retries. 0 indicates no timeout. Default is 0. * **_security_** (object): options relating to network security. * **_tls_** (object): options relating to TLS when fetching resources over `https`. * **_certificateAuthorities_** (list of objects): the list of additional certificate authorities (in addition to the system authorities) to be used for TLS verification when fetching over `https`. All certificate authorities must have a unique `source`. - * **source** (string): the URL of the certificate bundle (in PEM format). The bundle can contain multiple concatenated certificates. Supported schemes are `http`, `https`, `s3`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **source** (string): the URL of the certificate bundle (in PEM format). The bundle can contain multiple concatenated certificates. Supported schemes are `http`, `https`, `s3`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_verification_** (object): options related to the verification of the certificate. - * **_hash_** (string): the hash of the certificate, in the form `-` where type is sha512. + * **_hash_** (string): the hash of the certificate, in the form `-` where type is `sha512`. * **_storage_** (object): describes the desired state of the system's storage devices. * **_disks_** (list of objects): the list of disks to be configured and their options. Every entry must have a unique `device`. * **device** (string): the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. @@ -37,10 +37,10 @@ The Ignition configuration is a JSON document conforming to the following specif * **_number_** (integer): the partition number, which dictates its position in the partition table (one-indexed). If zero, use the next available partition slot. * **_sizeMiB_** (integer): the size of the partition (in mebibytes). If zero, the partition will be made as large as possible. * **_startMiB_** (integer): the start of the partition (in mebibytes). If zero, the partition will be positioned at the start of the largest block available. - * **_typeGuid_** (string): the GPT [partition type GUID][part-types]. If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data). + * **_typeGuid_** (string): the GPT [partition type GUID](http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs). If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data). * **_guid_** (string): the GPT unique partition GUID. - * **_wipePartitionEntry_** (boolean) if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead. - * **_shouldExist_** (boolean) whether or not the partition with the specified `number` should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on `wipePartitionEntry`. If false `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted. + * **_wipePartitionEntry_** (boolean): if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead. + * **_shouldExist_** (boolean): whether or not the partition with the specified `number` should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on `wipePartitionEntry`. If false `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted. * **_raid_** (list of objects): the list of RAID arrays to be configured. Every RAID array must have a unique `name`. * **name** (string): the name to use for the resulting md device. * **level** (string): the redundancy level of the array (e.g. linear, raid1, raid5, etc.). @@ -60,12 +60,12 @@ The Ignition configuration is a JSON document conforming to the following specif * **_overwrite_** (boolean): whether to delete preexisting nodes at the path. `contents.source` must be specified if `overwrite` is true. Defaults to false. * **_contents_** (object): options related to the contents of the file. * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the file contents. Supported schemes are `http`, `https`, `tftp`, `s3`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. If source is omitted and a regular file already exists at the path, Ignition will do nothing. If source is omitted and no file exists, an empty file will be created. + * **_source_** (string): the URL of the file contents. Supported schemes are `http`, `https`, `tftp`, `s3`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. If source is omitted and a regular file already exists at the path, Ignition will do nothing. If source is omitted and no file exists, an empty file will be created. * **_verification_** (object): options related to the verification of the file contents. * **_hash_** (string): the hash of the contents, in the form `-` where type is `sha512`. If `compression` is specified, the hash describes the decompressed contents. * **_append_** (list of objects): list of contents to be appended to the file. Follows the same stucture as `contents` * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_verification_** (object): options related to the verification of the appended contents. * **_hash_** (string): the hash of the contents, in the form `-` where type is `sha512`. If `compression` is specified, the hash describes the decompressed contents. * **_mode_** (integer): the file's permission mode. Note that the mode must be properly specified as a **decimal** value (i.e. 0644 -> 420). Setuid/setgid/sticky bits are not supported. If not specified, the permission mode for files defaults to 0644 or the existing file's permissions if `overwrite` is false, `contents.source` is unspecified, and a file already exists at the path. @@ -119,12 +119,9 @@ The Ignition configuration is a JSON document conforming to the following specif * **_noUserGroup_** (boolean): whether or not to create a group with the same name as the user. This only has an effect if the account doesn't exist yet. * **_noLogInit_** (boolean): whether or not to add the user to the lastlog and faillog databases. This only has an effect if the account doesn't exist yet. * **_shell_** (string): the login shell of the new account. - * **_system_** (bool): whether or not this account should be a system account. This only has an effect if the account doesn't exist yet. + * **_system_** (boolean): whether or not this account should be a system account. This only has an effect if the account doesn't exist yet. * **_groups_** (list of objects): the list of groups to be added. All groups must have a unique `name`. * **name** (string): the name of the group. * **_gid_** (integer): the group ID of the new group. * **_passwordHash_** (string): the encrypted password of the new group. - * **_system_** (bool): whether or not the group should be a system group. This only has an effect if the group doesn't exist yet. - -[part-types]: http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs -[rfc2397]: https://tools.ietf.org/html/rfc2397 + * **_system_** (boolean): whether or not the group should be a system group. This only has an effect if the group doesn't exist yet. diff --git a/docs/configuration-v3_1.md b/docs/configuration-v3_1.md index 104f29b52..7ec7c98fc 100644 --- a/docs/configuration-v3_1.md +++ b/docs/configuration-v3_1.md @@ -10,9 +10,9 @@ The Ignition configuration is a JSON document conforming to the following specif * **ignition** (object): metadata about the configuration itself. * **version** (string): the semantic version number of the spec. The spec version must be compatible with the latest version (`3.1.0`). Compatibility requires the major versions to match and the spec version be less than or equal to the latest version. `-experimental` versions compare less than the final version with the same number, and previous experimental versions are not accepted. - * **_config_** (objects): options related to the configuration. + * **_config_** (object): options related to the configuration. * **_merge_** (list of objects): a list of the configs to be merged to the current config. - * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_compression_** (string): the type of compression used on the config (null or gzip). Compression cannot be used with S3. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. @@ -20,7 +20,7 @@ The Ignition configuration is a JSON document conforming to the following specif * **_verification_** (object): options related to the verification of the config. * **_hash_** (string): the hash of the config, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed config. * **_replace_** (object): the config that will replace the current. - * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_compression_** (string): the type of compression used on the config (null or gzip). Compression cannot be used with S3. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. @@ -28,12 +28,12 @@ The Ignition configuration is a JSON document conforming to the following specif * **_verification_** (object): options related to the verification of the config. * **_hash_** (string): the hash of the config, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed config. * **_timeouts_** (object): options relating to `http` timeouts when fetching files over `http` or `https`. - * **_httpResponseHeaders_** (integer) the time to wait (in seconds) for the server's response headers (but not the body) after making a request. 0 indicates no timeout. Default is 10 seconds. - * **_httpTotal_** (integer) the time limit (in seconds) for the operation (connection, request, and response), including retries. 0 indicates no timeout. Default is 0. + * **_httpResponseHeaders_** (integer): the time to wait (in seconds) for the server's response headers (but not the body) after making a request. 0 indicates no timeout. Default is 10 seconds. + * **_httpTotal_** (integer): the time limit (in seconds) for the operation (connection, request, and response), including retries. 0 indicates no timeout. Default is 0. * **_security_** (object): options relating to network security. * **_tls_** (object): options relating to TLS when fetching resources over `https`. * **_certificateAuthorities_** (list of objects): the list of additional certificate authorities (in addition to the system authorities) to be used for TLS verification when fetching over `https`. All certificate authorities must have a unique `source`. - * **source** (string): the URL of the certificate bundle (in PEM format). The bundle can contain multiple concatenated certificates. Supported schemes are `http`, `https`, `s3`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **source** (string): the URL of the certificate bundle (in PEM format). The bundle can contain multiple concatenated certificates. Supported schemes are `http`, `https`, `s3`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_compression_** (string): the type of compression used on the certificate (null or gzip). Compression cannot be used with S3. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. @@ -53,10 +53,10 @@ The Ignition configuration is a JSON document conforming to the following specif * **_number_** (integer): the partition number, which dictates its position in the partition table (one-indexed). If zero, use the next available partition slot. * **_sizeMiB_** (integer): the size of the partition (in mebibytes). If zero, the partition will be made as large as possible. * **_startMiB_** (integer): the start of the partition (in mebibytes). If zero, the partition will be positioned at the start of the largest block available. - * **_typeGuid_** (string): the GPT [partition type GUID][part-types]. If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data). + * **_typeGuid_** (string): the GPT [partition type GUID](http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs). If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data). * **_guid_** (string): the GPT unique partition GUID. - * **_wipePartitionEntry_** (boolean) if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead. - * **_shouldExist_** (boolean) whether or not the partition with the specified `number` should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on `wipePartitionEntry`. If false `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted. + * **_wipePartitionEntry_** (boolean): if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead. + * **_shouldExist_** (boolean): whether or not the partition with the specified `number` should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on `wipePartitionEntry`. If false `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted. * **_raid_** (list of objects): the list of RAID arrays to be configured. Every RAID array must have a unique `name`. * **name** (string): the name to use for the resulting md device. * **level** (string): the redundancy level of the array (e.g. linear, raid1, raid5, etc.). @@ -77,7 +77,7 @@ The Ignition configuration is a JSON document conforming to the following specif * **_overwrite_** (boolean): whether to delete preexisting nodes at the path. `contents.source` must be specified if `overwrite` is true. Defaults to false. * **_contents_** (object): options related to the contents of the file. * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the file contents. Supported schemes are `http`, `https`, `tftp`, `s3`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. If source is omitted and a regular file already exists at the path, Ignition will do nothing. If source is omitted and no file exists, an empty file will be created. + * **_source_** (string): the URL of the file contents. Supported schemes are `http`, `https`, `tftp`, `s3`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. If source is omitted and a regular file already exists at the path, Ignition will do nothing. If source is omitted and no file exists, an empty file will be created. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. * **_value_** (string): the header contents. @@ -85,7 +85,7 @@ The Ignition configuration is a JSON document conforming to the following specif * **_hash_** (string): the hash of the contents, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed contents. * **_append_** (list of objects): list of contents to be appended to the file. Follows the same stucture as `contents` * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. * **_value_** (string): the header contents. @@ -142,12 +142,9 @@ The Ignition configuration is a JSON document conforming to the following specif * **_noUserGroup_** (boolean): whether or not to create a group with the same name as the user. This only has an effect if the account doesn't exist yet. * **_noLogInit_** (boolean): whether or not to add the user to the lastlog and faillog databases. This only has an effect if the account doesn't exist yet. * **_shell_** (string): the login shell of the new account. - * **_system_** (bool): whether or not this account should be a system account. This only has an effect if the account doesn't exist yet. + * **_system_** (boolean): whether or not this account should be a system account. This only has an effect if the account doesn't exist yet. * **_groups_** (list of objects): the list of groups to be added. All groups must have a unique `name`. * **name** (string): the name of the group. * **_gid_** (integer): the group ID of the new group. * **_passwordHash_** (string): the encrypted password of the new group. - * **_system_** (bool): whether or not the group should be a system group. This only has an effect if the group doesn't exist yet. - -[part-types]: http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs -[rfc2397]: https://tools.ietf.org/html/rfc2397 + * **_system_** (boolean): whether or not the group should be a system group. This only has an effect if the group doesn't exist yet. diff --git a/docs/configuration-v3_2.md b/docs/configuration-v3_2.md index 8cbe7a1e5..6d5a4dea7 100644 --- a/docs/configuration-v3_2.md +++ b/docs/configuration-v3_2.md @@ -10,9 +10,9 @@ The Ignition configuration is a JSON document conforming to the following specif * **ignition** (object): metadata about the configuration itself. * **version** (string): the semantic version number of the spec. The spec version must be compatible with the latest version (`3.2.0`). Compatibility requires the major versions to match and the spec version be less than or equal to the latest version. `-experimental` versions compare less than the final version with the same number, and previous experimental versions are not accepted. - * **_config_** (objects): options related to the configuration. + * **_config_** (object): options related to the configuration. * **_merge_** (list of objects): a list of the configs to be merged to the current config. - * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `gs`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `gs`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_compression_** (string): the type of compression used on the config (null or gzip). Compression cannot be used with S3. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. @@ -20,7 +20,7 @@ The Ignition configuration is a JSON document conforming to the following specif * **_verification_** (object): options related to the verification of the config. * **_hash_** (string): the hash of the config, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed config. * **_replace_** (object): the config that will replace the current. - * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `gs`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `gs`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_compression_** (string): the type of compression used on the config (null or gzip). Compression cannot be used with S3. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. @@ -28,12 +28,12 @@ The Ignition configuration is a JSON document conforming to the following specif * **_verification_** (object): options related to the verification of the config. * **_hash_** (string): the hash of the config, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed config. * **_timeouts_** (object): options relating to `http` timeouts when fetching files over `http` or `https`. - * **_httpResponseHeaders_** (integer) the time to wait (in seconds) for the server's response headers (but not the body) after making a request. 0 indicates no timeout. Default is 10 seconds. - * **_httpTotal_** (integer) the time limit (in seconds) for the operation (connection, request, and response), including retries. 0 indicates no timeout. Default is 0. + * **_httpResponseHeaders_** (integer): the time to wait (in seconds) for the server's response headers (but not the body) after making a request. 0 indicates no timeout. Default is 10 seconds. + * **_httpTotal_** (integer): the time limit (in seconds) for the operation (connection, request, and response), including retries. 0 indicates no timeout. Default is 0. * **_security_** (object): options relating to network security. * **_tls_** (object): options relating to TLS when fetching resources over `https`. * **_certificateAuthorities_** (list of objects): the list of additional certificate authorities (in addition to the system authorities) to be used for TLS verification when fetching over `https`. All certificate authorities must have a unique `source`. - * **source** (string): the URL of the certificate bundle (in PEM format). The bundle can contain multiple concatenated certificates. Supported schemes are `http`, `https`, `s3`, `gs`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **source** (string): the URL of the certificate bundle (in PEM format). The bundle can contain multiple concatenated certificates. Supported schemes are `http`, `https`, `s3`, `gs`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_compression_** (string): the type of compression used on the certificate (null or gzip). Compression cannot be used with S3. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. @@ -53,11 +53,11 @@ The Ignition configuration is a JSON document conforming to the following specif * **_number_** (integer): the partition number, which dictates its position in the partition table (one-indexed). If zero, use the next available partition slot. * **_sizeMiB_** (integer): the size of the partition (in mebibytes). If zero, the partition will be made as large as possible. * **_startMiB_** (integer): the start of the partition (in mebibytes). If zero, the partition will be positioned at the start of the largest block available. - * **_typeGuid_** (string): the GPT [partition type GUID][part-types]. If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data). + * **_typeGuid_** (string): the GPT [partition type GUID](http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs). If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data). * **_guid_** (string): the GPT unique partition GUID. - * **_wipePartitionEntry_** (boolean) if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead. - * **_shouldExist_** (boolean) whether or not the partition with the specified `number` should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on `wipePartitionEntry`. If false `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted. - * **_resize_** (boolean) whether or not the existing partition should be resized. If omitted, it defaults to false. If true, Ignition will resize an existing partition if it matches the config in all respects except the partition size. + * **_wipePartitionEntry_** (boolean): if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead. + * **_shouldExist_** (boolean): whether or not the partition with the specified `number` should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on `wipePartitionEntry`. If false `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted. + * **_resize_** (boolean): whether or not the existing partition should be resized. If omitted, it defaults to false. If true, Ignition will resize an existing partition if it matches the config in all respects except the partition size. * **_raid_** (list of objects): the list of RAID arrays to be configured. Every RAID array must have a unique `name`. * **name** (string): the name to use for the resulting md device. * **level** (string): the redundancy level of the array (e.g. linear, raid1, raid5, etc.). @@ -78,7 +78,7 @@ The Ignition configuration is a JSON document conforming to the following specif * **_overwrite_** (boolean): whether to delete preexisting nodes at the path. `contents.source` must be specified if `overwrite` is true. Defaults to false. * **_contents_** (object): options related to the contents of the file. * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the file contents. Supported schemes are `http`, `https`, `tftp`, `s3`, `gs`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. If source is omitted and a regular file already exists at the path, Ignition will do nothing. If source is omitted and no file exists, an empty file will be created. + * **_source_** (string): the URL of the file contents. Supported schemes are `http`, `https`, `tftp`, `s3`, `gs`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. If source is omitted and a regular file already exists at the path, Ignition will do nothing. If source is omitted and no file exists, an empty file will be created. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. * **_value_** (string): the header contents. @@ -86,7 +86,7 @@ The Ignition configuration is a JSON document conforming to the following specif * **_hash_** (string): the hash of the contents, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed contents. * **_append_** (list of objects): list of contents to be appended to the file. Follows the same stucture as `contents` * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `gs`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `gs`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. * **_value_** (string): the header contents. @@ -123,9 +123,9 @@ The Ignition configuration is a JSON document conforming to the following specif * **_luks_** (list of objects): the list of luks devices to be created. Every device must have a unique `name`. * **name** (string): the name of the luks device. * **device** (string): the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. - * **_keyFile_** (string): options related to the contents of the key file. + * **_keyFile_** (object): options related to the contents of the key file. * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `gs`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `gs`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. * **_value_** (string): the header contents. @@ -139,12 +139,12 @@ The Ignition configuration is a JSON document conforming to the following specif * **_tang_** (list of objects): describes a tang server. Every server must have a unique `url`. * **url** (string): url of the tang server. * **thumbprint** (string): thumbprint of a trusted signing key. - * **_tpm2_** (bool): whether or not to use a tpm2 device. - * **_threshold_** (int): sets the minimum number of pieces required to decrypt the device. Default is 1. + * **_tpm2_** (boolean): whether or not to use a tpm2 device. + * **_threshold_** (integer): sets the minimum number of pieces required to decrypt the device. Default is 1. * **_custom_** (object): overrides the clevis configuration. The `pin` & `config` will be passed directly to `clevis luks bind`. If specified, all other clevis options must be omitted. * **pin** (string): the clevis pin. * **config** (string): the clevis configuration JSON. - * **_needsNetwork_** (bool): whether or not the device requires networking. + * **_needsNetwork_** (boolean): whether or not the device requires networking. * **_systemd_** (object): describes the desired state of the systemd units. * **_units_** (list of objects): the list of systemd units. Every unit must have a unique `name`. * **name** (string): the name of the unit. This must be suffixed with a valid unit type (e.g. "thing.service"). @@ -168,14 +168,11 @@ The Ignition configuration is a JSON document conforming to the following specif * **_noUserGroup_** (boolean): whether or not to create a group with the same name as the user. This only has an effect if the account doesn't exist yet. * **_noLogInit_** (boolean): whether or not to add the user to the lastlog and faillog databases. This only has an effect if the account doesn't exist yet. * **_shell_** (string): the login shell of the new account. - * **_shouldExist_** (boolean) whether or not the user with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified user. - * **_system_** (bool): whether or not this account should be a system account. This only has an effect if the account doesn't exist yet. + * **_shouldExist_** (boolean): whether or not the user with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified user. + * **_system_** (boolean): whether or not this account should be a system account. This only has an effect if the account doesn't exist yet. * **_groups_** (list of objects): the list of groups to be added. All groups must have a unique `name`. * **name** (string): the name of the group. * **_gid_** (integer): the group ID of the new group. * **_passwordHash_** (string): the encrypted password of the new group. - * **_shouldExist_** (boolean) whether or not the group with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified group. - * **_system_** (bool): whether or not the group should be a system group. This only has an effect if the group doesn't exist yet. - -[part-types]: http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs -[rfc2397]: https://tools.ietf.org/html/rfc2397 + * **_shouldExist_** (boolean): whether or not the group with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified group. + * **_system_** (boolean): whether or not the group should be a system group. This only has an effect if the group doesn't exist yet. diff --git a/docs/configuration-v3_3.md b/docs/configuration-v3_3.md index 28431b22d..41da9f764 100644 --- a/docs/configuration-v3_3.md +++ b/docs/configuration-v3_3.md @@ -10,9 +10,9 @@ The Ignition configuration is a JSON document conforming to the following specif * **ignition** (object): metadata about the configuration itself. * **version** (string): the semantic version number of the spec. The spec version must be compatible with the latest version (`3.3.0`). Compatibility requires the major versions to match and the spec version be less than or equal to the latest version. `-experimental` versions compare less than the final version with the same number, and previous experimental versions are not accepted. - * **_config_** (objects): options related to the configuration. + * **_config_** (object): options related to the configuration. * **_merge_** (list of objects): a list of the configs to be merged to the current config. - * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `gs`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `gs`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_compression_** (string): the type of compression used on the config (null or gzip). Compression cannot be used with S3. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. @@ -20,7 +20,7 @@ The Ignition configuration is a JSON document conforming to the following specif * **_verification_** (object): options related to the verification of the config. * **_hash_** (string): the hash of the config, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed config. * **_replace_** (object): the config that will replace the current. - * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `gs`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `gs`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_compression_** (string): the type of compression used on the config (null or gzip). Compression cannot be used with S3. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. @@ -28,12 +28,12 @@ The Ignition configuration is a JSON document conforming to the following specif * **_verification_** (object): options related to the verification of the config. * **_hash_** (string): the hash of the config, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed config. * **_timeouts_** (object): options relating to `http` timeouts when fetching files over `http` or `https`. - * **_httpResponseHeaders_** (integer) the time to wait (in seconds) for the server's response headers (but not the body) after making a request. 0 indicates no timeout. Default is 10 seconds. - * **_httpTotal_** (integer) the time limit (in seconds) for the operation (connection, request, and response), including retries. 0 indicates no timeout. Default is 0. + * **_httpResponseHeaders_** (integer): the time to wait (in seconds) for the server's response headers (but not the body) after making a request. 0 indicates no timeout. Default is 10 seconds. + * **_httpTotal_** (integer): the time limit (in seconds) for the operation (connection, request, and response), including retries. 0 indicates no timeout. Default is 0. * **_security_** (object): options relating to network security. * **_tls_** (object): options relating to TLS when fetching resources over `https`. * **_certificateAuthorities_** (list of objects): the list of additional certificate authorities (in addition to the system authorities) to be used for TLS verification when fetching over `https`. All certificate authorities must have a unique `source`. - * **source** (string): the URL of the certificate bundle (in PEM format). The bundle can contain multiple concatenated certificates. Supported schemes are `http`, `https`, `s3`, `gs`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **source** (string): the URL of the certificate bundle (in PEM format). The bundle can contain multiple concatenated certificates. Supported schemes are `http`, `https`, `s3`, `gs`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_compression_** (string): the type of compression used on the certificate (null or gzip). Compression cannot be used with S3. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. @@ -53,11 +53,11 @@ The Ignition configuration is a JSON document conforming to the following specif * **_number_** (integer): the partition number, which dictates its position in the partition table (one-indexed). If zero, use the next available partition slot. * **_sizeMiB_** (integer): the size of the partition (in mebibytes). If zero, the partition will be made as large as possible. * **_startMiB_** (integer): the start of the partition (in mebibytes). If zero, the partition will be positioned at the start of the largest block available. - * **_typeGuid_** (string): the GPT [partition type GUID][part-types]. If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data). + * **_typeGuid_** (string): the GPT [partition type GUID](http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs). If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data). * **_guid_** (string): the GPT unique partition GUID. - * **_wipePartitionEntry_** (boolean) if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead. - * **_shouldExist_** (boolean) whether or not the partition with the specified `number` should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on `wipePartitionEntry`. If false `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted. - * **_resize_** (boolean) whether or not the existing partition should be resized. If omitted, it defaults to false. If true, Ignition will resize an existing partition if it matches the config in all respects except the partition size. + * **_wipePartitionEntry_** (boolean): if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead. + * **_shouldExist_** (boolean): whether or not the partition with the specified `number` should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on `wipePartitionEntry`. If false `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted. + * **_resize_** (boolean): whether or not the existing partition should be resized. If omitted, it defaults to false. If true, Ignition will resize an existing partition if it matches the config in all respects except the partition size. * **_raid_** (list of objects): the list of RAID arrays to be configured. Every RAID array must have a unique `name`. * **name** (string): the name to use for the resulting md device. * **level** (string): the redundancy level of the array (e.g. linear, raid1, raid5, etc.). @@ -78,7 +78,7 @@ The Ignition configuration is a JSON document conforming to the following specif * **_overwrite_** (boolean): whether to delete preexisting nodes at the path. `contents.source` must be specified if `overwrite` is true. Defaults to false. * **_contents_** (object): options related to the contents of the file. * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the file contents. Supported schemes are `http`, `https`, `tftp`, `s3`, `gs`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. If source is omitted and a regular file already exists at the path, Ignition will do nothing. If source is omitted and no file exists, an empty file will be created. + * **_source_** (string): the URL of the file contents. Supported schemes are `http`, `https`, `tftp`, `s3`, `gs`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. If source is omitted and a regular file already exists at the path, Ignition will do nothing. If source is omitted and no file exists, an empty file will be created. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. * **_value_** (string): the header contents. @@ -86,7 +86,7 @@ The Ignition configuration is a JSON document conforming to the following specif * **_hash_** (string): the hash of the contents, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed contents. * **_append_** (list of objects): list of contents to be appended to the file. Follows the same stucture as `contents` * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `gs`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `gs`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. * **_value_** (string): the header contents. @@ -123,9 +123,9 @@ The Ignition configuration is a JSON document conforming to the following specif * **_luks_** (list of objects): the list of luks devices to be created. Every device must have a unique `name`. * **name** (string): the name of the luks device. * **device** (string): the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. - * **_keyFile_** (string): options related to the contents of the key file. + * **_keyFile_** (object): options related to the contents of the key file. * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `gs`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `gs`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. * **_value_** (string): the header contents. @@ -139,12 +139,12 @@ The Ignition configuration is a JSON document conforming to the following specif * **_tang_** (list of objects): describes a tang server. Every server must have a unique `url`. * **url** (string): url of the tang server. * **thumbprint** (string): thumbprint of a trusted signing key. - * **_tpm2_** (bool): whether or not to use a tpm2 device. - * **_threshold_** (int): sets the minimum number of pieces required to decrypt the device. Default is 1. + * **_tpm2_** (boolean): whether or not to use a tpm2 device. + * **_threshold_** (integer): sets the minimum number of pieces required to decrypt the device. Default is 1. * **_custom_** (object): overrides the clevis configuration. The `pin` & `config` will be passed directly to `clevis luks bind`. If specified, all other clevis options must be omitted. * **pin** (string): the clevis pin. * **config** (string): the clevis configuration JSON. - * **_needsNetwork_** (bool): whether or not the device requires networking. + * **_needsNetwork_** (boolean): whether or not the device requires networking. * **_systemd_** (object): describes the desired state of the systemd units. * **_units_** (list of objects): the list of systemd units. Every unit must have a unique `name`. * **name** (string): the name of the unit. This must be suffixed with a valid unit type (e.g. "thing.service"). @@ -168,17 +168,14 @@ The Ignition configuration is a JSON document conforming to the following specif * **_noUserGroup_** (boolean): whether or not to create a group with the same name as the user. This only has an effect if the account doesn't exist yet. * **_noLogInit_** (boolean): whether or not to add the user to the lastlog and faillog databases. This only has an effect if the account doesn't exist yet. * **_shell_** (string): the login shell of the new account. - * **_shouldExist_** (boolean) whether or not the user with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified user. - * **_system_** (bool): whether or not this account should be a system account. This only has an effect if the account doesn't exist yet. + * **_shouldExist_** (boolean): whether or not the user with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified user. + * **_system_** (boolean): whether or not this account should be a system account. This only has an effect if the account doesn't exist yet. * **_groups_** (list of objects): the list of groups to be added. All groups must have a unique `name`. * **name** (string): the name of the group. * **_gid_** (integer): the group ID of the new group. * **_passwordHash_** (string): the encrypted password of the new group. - * **_shouldExist_** (boolean) whether or not the group with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified group. - * **_system_** (bool): whether or not the group should be a system group. This only has an effect if the group doesn't exist yet. + * **_shouldExist_** (boolean): whether or not the group with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified group. + * **_system_** (boolean): whether or not the group should be a system group. This only has an effect if the group doesn't exist yet. * **_kernelArguments_** (object): describes the desired kernel arguments. * **_shouldExist_** (list of strings): the list of kernel arguments that should exist. * **_shouldNotExist_** (list of strings): the list of kernel arguments that should not exist. - -[part-types]: http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs -[rfc2397]: https://tools.ietf.org/html/rfc2397 diff --git a/docs/configuration-v3_4.md b/docs/configuration-v3_4.md index dcb2c2a5e..72f3dcc46 100644 --- a/docs/configuration-v3_4.md +++ b/docs/configuration-v3_4.md @@ -10,9 +10,9 @@ The Ignition configuration is a JSON document conforming to the following specif * **ignition** (object): metadata about the configuration itself. * **version** (string): the semantic version number of the spec. The spec version must be compatible with the latest version (`3.4.0`). Compatibility requires the major versions to match and the spec version be less than or equal to the latest version. `-experimental` versions compare less than the final version with the same number, and previous experimental versions are not accepted. - * **_config_** (objects): options related to the configuration. + * **_config_** (object): options related to the configuration. * **_merge_** (list of objects): a list of the configs to be merged to the current config. - * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `arn`, `gs`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `arn`, `gs`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_compression_** (string): the type of compression used on the config (null or gzip). Compression cannot be used with S3. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. @@ -20,7 +20,7 @@ The Ignition configuration is a JSON document conforming to the following specif * **_verification_** (object): options related to the verification of the config. * **_hash_** (string): the hash of the config, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed config. * **_replace_** (object): the config that will replace the current. - * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `arn`, `gs`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `arn`, `gs`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_compression_** (string): the type of compression used on the config (null or gzip). Compression cannot be used with S3. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. @@ -28,12 +28,12 @@ The Ignition configuration is a JSON document conforming to the following specif * **_verification_** (object): options related to the verification of the config. * **_hash_** (string): the hash of the config, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed config. * **_timeouts_** (object): options relating to `http` timeouts when fetching files over `http` or `https`. - * **_httpResponseHeaders_** (integer) the time to wait (in seconds) for the server's response headers (but not the body) after making a request. 0 indicates no timeout. Default is 10 seconds. - * **_httpTotal_** (integer) the time limit (in seconds) for the operation (connection, request, and response), including retries. 0 indicates no timeout. Default is 0. + * **_httpResponseHeaders_** (integer): the time to wait (in seconds) for the server's response headers (but not the body) after making a request. 0 indicates no timeout. Default is 10 seconds. + * **_httpTotal_** (integer): the time limit (in seconds) for the operation (connection, request, and response), including retries. 0 indicates no timeout. Default is 0. * **_security_** (object): options relating to network security. * **_tls_** (object): options relating to TLS when fetching resources over `https`. * **_certificateAuthorities_** (list of objects): the list of additional certificate authorities (in addition to the system authorities) to be used for TLS verification when fetching over `https`. All certificate authorities must have a unique `source`. - * **source** (string): the URL of the certificate bundle (in PEM format). The bundle can contain multiple concatenated certificates. Supported schemes are `http`, `https`, `s3`, `arn`, `gs`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **source** (string): the URL of the certificate bundle (in PEM format). The bundle can contain multiple concatenated certificates. Supported schemes are `http`, `https`, `s3`, `arn`, `gs`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_compression_** (string): the type of compression used on the certificate (null or gzip). Compression cannot be used with S3. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. @@ -53,11 +53,11 @@ The Ignition configuration is a JSON document conforming to the following specif * **_number_** (integer): the partition number, which dictates its position in the partition table (one-indexed). If zero, use the next available partition slot. * **_sizeMiB_** (integer): the size of the partition (in mebibytes). If zero, the partition will be made as large as possible. * **_startMiB_** (integer): the start of the partition (in mebibytes). If zero, the partition will be positioned at the start of the largest block available. - * **_typeGuid_** (string): the GPT [partition type GUID][part-types]. If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data). + * **_typeGuid_** (string): the GPT [partition type GUID](http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs). If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data). * **_guid_** (string): the GPT unique partition GUID. - * **_wipePartitionEntry_** (boolean) if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead. - * **_shouldExist_** (boolean) whether or not the partition with the specified `number` should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on `wipePartitionEntry`. If false `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted. - * **_resize_** (boolean) whether or not the existing partition should be resized. If omitted, it defaults to false. If true, Ignition will resize an existing partition if it matches the config in all respects except the partition size. + * **_wipePartitionEntry_** (boolean): if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead. + * **_shouldExist_** (boolean): whether or not the partition with the specified `number` should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on `wipePartitionEntry`. If false `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted. + * **_resize_** (boolean): whether or not the existing partition should be resized. If omitted, it defaults to false. If true, Ignition will resize an existing partition if it matches the config in all respects except the partition size. * **_raid_** (list of objects): the list of RAID arrays to be configured. Every RAID array must have a unique `name`. * **name** (string): the name to use for the resulting md device. * **level** (string): the redundancy level of the array (e.g. linear, raid1, raid5, etc.). @@ -78,7 +78,7 @@ The Ignition configuration is a JSON document conforming to the following specif * **_overwrite_** (boolean): whether to delete preexisting nodes at the path. `contents.source` must be specified if `overwrite` is true. Defaults to false. * **_contents_** (object): options related to the contents of the file. * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the file contents. Supported schemes are `http`, `https`, `tftp`, `s3`, `arn`, `gs`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. If source is omitted and a regular file already exists at the path, Ignition will do nothing. If source is omitted and no file exists, an empty file will be created. + * **_source_** (string): the URL of the file contents. Supported schemes are `http`, `https`, `tftp`, `s3`, `arn`, `gs`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. If source is omitted and a regular file already exists at the path, Ignition will do nothing. If source is omitted and no file exists, an empty file will be created. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. * **_value_** (string): the header contents. @@ -86,7 +86,7 @@ The Ignition configuration is a JSON document conforming to the following specif * **_hash_** (string): the hash of the contents, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed contents. * **_append_** (list of objects): list of contents to be appended to the file. Follows the same stucture as `contents` * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `arn`, `gs`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `arn`, `gs`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. * **_value_** (string): the header contents. @@ -123,9 +123,9 @@ The Ignition configuration is a JSON document conforming to the following specif * **_luks_** (list of objects): the list of luks devices to be created. Every device must have a unique `name`. * **name** (string): the name of the luks device. * **device** (string): the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. - * **_keyFile_** (string): options related to the contents of the key file. + * **_keyFile_** (object): options related to the contents of the key file. * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `arn`, `gs`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `arn`, `gs`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. * **_value_** (string): the header contents. @@ -141,13 +141,13 @@ The Ignition configuration is a JSON document conforming to the following specif * **_tang_** (list of objects): describes a tang server. Every server must have a unique `url`. * **url** (string): url of the tang server. * **thumbprint** (string): thumbprint of a trusted signing key. - * **advertisement** (string): the advertisement JSON. If not specified, the advertisement is fetched from the tang server during provisioning. - * **_tpm2_** (bool): whether or not to use a tpm2 device. - * **_threshold_** (int): sets the minimum number of pieces required to decrypt the device. Default is 1. + * **_advertisement_** (string): the advertisement JSON. If not specified, the advertisement is fetched from the tang server during provisioning. + * **_tpm2_** (boolean): whether or not to use a tpm2 device. + * **_threshold_** (integer): sets the minimum number of pieces required to decrypt the device. Default is 1. * **_custom_** (object): overrides the clevis configuration. The `pin` & `config` will be passed directly to `clevis luks bind`. If specified, all other clevis options must be omitted. * **pin** (string): the clevis pin. * **config** (string): the clevis configuration JSON. - * **_needsNetwork_** (bool): whether or not the device requires networking. + * **_needsNetwork_** (boolean): whether or not the device requires networking. * **_systemd_** (object): describes the desired state of the systemd units. * **_units_** (list of objects): the list of systemd units. Every unit must have a unique `name`. * **name** (string): the name of the unit. This must be suffixed with a valid unit type (e.g. "thing.service"). @@ -171,17 +171,14 @@ The Ignition configuration is a JSON document conforming to the following specif * **_noUserGroup_** (boolean): whether or not to create a group with the same name as the user. This only has an effect if the account doesn't exist yet. * **_noLogInit_** (boolean): whether or not to add the user to the lastlog and faillog databases. This only has an effect if the account doesn't exist yet. * **_shell_** (string): the login shell of the new account. - * **_shouldExist_** (boolean) whether or not the user with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified user. - * **_system_** (bool): whether or not this account should be a system account. This only has an effect if the account doesn't exist yet. + * **_shouldExist_** (boolean): whether or not the user with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified user. + * **_system_** (boolean): whether or not this account should be a system account. This only has an effect if the account doesn't exist yet. * **_groups_** (list of objects): the list of groups to be added. All groups must have a unique `name`. * **name** (string): the name of the group. * **_gid_** (integer): the group ID of the new group. * **_passwordHash_** (string): the encrypted password of the new group. - * **_shouldExist_** (boolean) whether or not the group with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified group. - * **_system_** (bool): whether or not the group should be a system group. This only has an effect if the group doesn't exist yet. + * **_shouldExist_** (boolean): whether or not the group with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified group. + * **_system_** (boolean): whether or not the group should be a system group. This only has an effect if the group doesn't exist yet. * **_kernelArguments_** (object): describes the desired kernel arguments. * **_shouldExist_** (list of strings): the list of kernel arguments that should exist. * **_shouldNotExist_** (list of strings): the list of kernel arguments that should not exist. - -[part-types]: http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs -[rfc2397]: https://tools.ietf.org/html/rfc2397 diff --git a/docs/configuration-v3_5_experimental.md b/docs/configuration-v3_5_experimental.md index 83c416751..4bb745209 100644 --- a/docs/configuration-v3_5_experimental.md +++ b/docs/configuration-v3_5_experimental.md @@ -12,9 +12,9 @@ The Ignition configuration is a JSON document conforming to the following specif * **ignition** (object): metadata about the configuration itself. * **version** (string): the semantic version number of the spec. The spec version must be compatible with the latest version (`3.5.0-experimental`). Compatibility requires the major versions to match and the spec version be less than or equal to the latest version. `-experimental` versions compare less than the final version with the same number, and previous experimental versions are not accepted. - * **_config_** (objects): options related to the configuration. + * **_config_** (object): options related to the configuration. * **_merge_** (list of objects): a list of the configs to be merged to the current config. - * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `arn`, `gs`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `arn`, `gs`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_compression_** (string): the type of compression used on the config (null or gzip). Compression cannot be used with S3. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. @@ -22,7 +22,7 @@ The Ignition configuration is a JSON document conforming to the following specif * **_verification_** (object): options related to the verification of the config. * **_hash_** (string): the hash of the config, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed config. * **_replace_** (object): the config that will replace the current. - * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `arn`, `gs`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **source** (string): the URL of the config. Supported schemes are `http`, `https`, `s3`, `arn`, `gs`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_compression_** (string): the type of compression used on the config (null or gzip). Compression cannot be used with S3. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. @@ -30,12 +30,12 @@ The Ignition configuration is a JSON document conforming to the following specif * **_verification_** (object): options related to the verification of the config. * **_hash_** (string): the hash of the config, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed config. * **_timeouts_** (object): options relating to `http` timeouts when fetching files over `http` or `https`. - * **_httpResponseHeaders_** (integer) the time to wait (in seconds) for the server's response headers (but not the body) after making a request. 0 indicates no timeout. Default is 10 seconds. - * **_httpTotal_** (integer) the time limit (in seconds) for the operation (connection, request, and response), including retries. 0 indicates no timeout. Default is 0. + * **_httpResponseHeaders_** (integer): the time to wait (in seconds) for the server's response headers (but not the body) after making a request. 0 indicates no timeout. Default is 10 seconds. + * **_httpTotal_** (integer): the time limit (in seconds) for the operation (connection, request, and response), including retries. 0 indicates no timeout. Default is 0. * **_security_** (object): options relating to network security. * **_tls_** (object): options relating to TLS when fetching resources over `https`. * **_certificateAuthorities_** (list of objects): the list of additional certificate authorities (in addition to the system authorities) to be used for TLS verification when fetching over `https`. All certificate authorities must have a unique `source`. - * **source** (string): the URL of the certificate bundle (in PEM format). The bundle can contain multiple concatenated certificates. Supported schemes are `http`, `https`, `s3`, `arn`, `gs`, `tftp`, and [`data`][rfc2397]. Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **source** (string): the URL of the certificate bundle (in PEM format). The bundle can contain multiple concatenated certificates. Supported schemes are `http`, `https`, `s3`, `arn`, `gs`, `tftp`, and [`data`](https://tools.ietf.org/html/rfc2397). Note: When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_compression_** (string): the type of compression used on the certificate (null or gzip). Compression cannot be used with S3. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. @@ -55,11 +55,11 @@ The Ignition configuration is a JSON document conforming to the following specif * **_number_** (integer): the partition number, which dictates its position in the partition table (one-indexed). If zero, use the next available partition slot. * **_sizeMiB_** (integer): the size of the partition (in mebibytes). If zero, the partition will be made as large as possible. * **_startMiB_** (integer): the start of the partition (in mebibytes). If zero, the partition will be positioned at the start of the largest block available. - * **_typeGuid_** (string): the GPT [partition type GUID][part-types]. If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data). + * **_typeGuid_** (string): the GPT [partition type GUID](http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs). If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data). * **_guid_** (string): the GPT unique partition GUID. - * **_wipePartitionEntry_** (boolean) if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead. - * **_shouldExist_** (boolean) whether or not the partition with the specified `number` should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on `wipePartitionEntry`. If false `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted. - * **_resize_** (boolean) whether or not the existing partition should be resized. If omitted, it defaults to false. If true, Ignition will resize an existing partition if it matches the config in all respects except the partition size. + * **_wipePartitionEntry_** (boolean): if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead. + * **_shouldExist_** (boolean): whether or not the partition with the specified `number` should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on `wipePartitionEntry`. If false `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted. + * **_resize_** (boolean): whether or not the existing partition should be resized. If omitted, it defaults to false. If true, Ignition will resize an existing partition if it matches the config in all respects except the partition size. * **_raid_** (list of objects): the list of RAID arrays to be configured. Every RAID array must have a unique `name`. * **name** (string): the name to use for the resulting md device. * **level** (string): the redundancy level of the array (e.g. linear, raid1, raid5, etc.). @@ -80,7 +80,7 @@ The Ignition configuration is a JSON document conforming to the following specif * **_overwrite_** (boolean): whether to delete preexisting nodes at the path. `contents.source` must be specified if `overwrite` is true. Defaults to false. * **_contents_** (object): options related to the contents of the file. * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the file contents. Supported schemes are `http`, `https`, `tftp`, `s3`, `arn`, `gs`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. If source is omitted and a regular file already exists at the path, Ignition will do nothing. If source is omitted and no file exists, an empty file will be created. + * **_source_** (string): the URL of the file contents. Supported schemes are `http`, `https`, `tftp`, `s3`, `arn`, `gs`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. If source is omitted and a regular file already exists at the path, Ignition will do nothing. If source is omitted and no file exists, an empty file will be created. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. * **_value_** (string): the header contents. @@ -88,7 +88,7 @@ The Ignition configuration is a JSON document conforming to the following specif * **_hash_** (string): the hash of the contents, in the form `-` where type is either `sha512` or `sha256`. If `compression` is specified, the hash describes the decompressed contents. * **_append_** (list of objects): list of contents to be appended to the file. Follows the same stucture as `contents` * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `arn`, `gs`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `arn`, `gs`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. * **_value_** (string): the header contents. @@ -125,9 +125,9 @@ The Ignition configuration is a JSON document conforming to the following specif * **_luks_** (list of objects): the list of luks devices to be created. Every device must have a unique `name`. * **name** (string): the name of the luks device. * **device** (string): the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks. - * **_keyFile_** (string): options related to the contents of the key file. + * **_keyFile_** (object): options related to the contents of the key file. * **_compression_** (string): the type of compression used on the contents (null or gzip). Compression cannot be used with S3. - * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `arn`, `gs`, and [`data`][rfc2397]. When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. + * **_source_** (string): the URL of the contents to append. Supported schemes are `http`, `https`, `tftp`, `s3`, `arn`, `gs`, and [`data`](https://tools.ietf.org/html/rfc2397). When using `http`, it is advisable to use the verification option to ensure the contents haven't been modified. * **_httpHeaders_** (list of objects): a list of HTTP headers to be added to the request. Available for `http` and `https` source schemes only. * **name** (string): the header name. * **_value_** (string): the header contents. @@ -143,13 +143,13 @@ The Ignition configuration is a JSON document conforming to the following specif * **_tang_** (list of objects): describes a tang server. Every server must have a unique `url`. * **url** (string): url of the tang server. * **thumbprint** (string): thumbprint of a trusted signing key. - * **advertisement** (string): the advertisement JSON. If not specified, the advertisement is fetched from the tang server during provisioning. - * **_tpm2_** (bool): whether or not to use a tpm2 device. - * **_threshold_** (int): sets the minimum number of pieces required to decrypt the device. Default is 1. + * **_advertisement_** (string): the advertisement JSON. If not specified, the advertisement is fetched from the tang server during provisioning. + * **_tpm2_** (boolean): whether or not to use a tpm2 device. + * **_threshold_** (integer): sets the minimum number of pieces required to decrypt the device. Default is 1. * **_custom_** (object): overrides the clevis configuration. The `pin` & `config` will be passed directly to `clevis luks bind`. If specified, all other clevis options must be omitted. * **pin** (string): the clevis pin. * **config** (string): the clevis configuration JSON. - * **_needsNetwork_** (bool): whether or not the device requires networking. + * **_needsNetwork_** (boolean): whether or not the device requires networking. * **_systemd_** (object): describes the desired state of the systemd units. * **_units_** (list of objects): the list of systemd units. Every unit must have a unique `name`. * **name** (string): the name of the unit. This must be suffixed with a valid unit type (e.g. "thing.service"). @@ -173,17 +173,14 @@ The Ignition configuration is a JSON document conforming to the following specif * **_noUserGroup_** (boolean): whether or not to create a group with the same name as the user. This only has an effect if the account doesn't exist yet. * **_noLogInit_** (boolean): whether or not to add the user to the lastlog and faillog databases. This only has an effect if the account doesn't exist yet. * **_shell_** (string): the login shell of the new account. - * **_shouldExist_** (boolean) whether or not the user with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified user. - * **_system_** (bool): whether or not this account should be a system account. This only has an effect if the account doesn't exist yet. + * **_shouldExist_** (boolean): whether or not the user with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified user. + * **_system_** (boolean): whether or not this account should be a system account. This only has an effect if the account doesn't exist yet. * **_groups_** (list of objects): the list of groups to be added. All groups must have a unique `name`. * **name** (string): the name of the group. * **_gid_** (integer): the group ID of the new group. * **_passwordHash_** (string): the encrypted password of the new group. - * **_shouldExist_** (boolean) whether or not the group with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified group. - * **_system_** (bool): whether or not the group should be a system group. This only has an effect if the group doesn't exist yet. + * **_shouldExist_** (boolean): whether or not the group with the specified `name` should exist. If omitted, it defaults to true. If false, then Ignition will delete the specified group. + * **_system_** (boolean): whether or not the group should be a system group. This only has an effect if the group doesn't exist yet. * **_kernelArguments_** (object): describes the desired kernel arguments. * **_shouldExist_** (list of strings): the list of kernel arguments that should exist. * **_shouldNotExist_** (list of strings): the list of kernel arguments that should not exist. - -[part-types]: http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs -[rfc2397]: https://tools.ietf.org/html/rfc2397 diff --git a/docs/release-notes.md b/docs/release-notes.md index b269925d2..67d2ead42 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -18,6 +18,7 @@ nav_order: 9 ### Bug fixes - Document that `hash` fields describe decompressed data +- Correctly document Tang `advertisement` field as optional ### Test changes From f86b4106e9ff85c0c2a07fddca1f3d30a4e9cbe7 Mon Sep 17 00:00:00 2001 From: Benjamin Gilbert Date: Sat, 25 Mar 2023 15:40:22 -0400 Subject: [PATCH 6/6] internal/doc: remove previous experimental doc during stabilization --- .github/ISSUE_TEMPLATE/stabilize-checklist.md | 1 - internal/doc/main.go | 21 +++++++++++++++---- 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/stabilize-checklist.md b/.github/ISSUE_TEMPLATE/stabilize-checklist.md index edfc6ee39..8291e10a9 100644 --- a/.github/ISSUE_TEMPLATE/stabilize-checklist.md +++ b/.github/ISSUE_TEMPLATE/stabilize-checklist.md @@ -49,7 +49,6 @@ The changes that are required to achieve these effects are typically the followi ## Update docs - [ ] Update `internal/doc/main.go` to add the new stable spec and reference the new experimental spec in `generate()`. -- [ ] Remove `docs/configuration-vX_Y-experimental.md`. - [ ] Run `generate` to regenerate Go schemas and spec docs. - [ ] Add a section to `docs/migrating-configs.md`. - [ ] In `docs/specs.md`, update the list of stable and experimental spec versions (listing the latest stable release first) and update the table listing the Ignition release where a spec has been marked as stable. diff --git a/internal/doc/main.go b/internal/doc/main.go index c1ab0569f..98cc46a54 100644 --- a/internal/doc/main.go +++ b/internal/doc/main.go @@ -16,7 +16,9 @@ package main import ( _ "embed" + "errors" "fmt" + "io/fs" "os" "path/filepath" "text/template" @@ -59,12 +61,23 @@ func generate(dir string) error { for i, c := range configs { ver := semver.New(c.version) + // clean up any previous experimental spec doc, for use + // during spec stabilization + experimentalPath := filepath.Join(dir, fmt.Sprintf("configuration-v%d_%d_experimental.md", ver.Major, ver.Minor)) + if err := os.Remove(experimentalPath); err != nil && !errors.Is(err, fs.ErrNotExist) { + return err + } + // open file - prerelease := "" - if ver.PreRelease != "" { - prerelease = "_" + string(ver.PreRelease) + var path string + switch ver.PreRelease { + case "": + path = filepath.Join(dir, fmt.Sprintf("configuration-v%d_%d.md", ver.Major, ver.Minor)) + case "experimental": + path = experimentalPath + default: + panic(fmt.Errorf("unexpected prerelease: %v", ver.PreRelease)) } - path := filepath.Join(dir, fmt.Sprintf("configuration-v%d_%d%s.md", ver.Major, ver.Minor, prerelease)) f, err := os.OpenFile(path, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0644) if err != nil { return err