From e2e873644ec6939e2fd4a7c47b42058cf8fe30f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Sch=C3=BCller?= Date: Mon, 24 Jun 2024 18:35:36 +0200 Subject: [PATCH] user-guide/01-blueprint-reference: document bootc style blueprints --- docs/user-guide/01-blueprint-reference.md | 176 ++++++++++++++++++++-- src/components/Highlight.js | 10 ++ src/css/custom.css | 10 +- 3 files changed, 186 insertions(+), 10 deletions(-) diff --git a/docs/user-guide/01-blueprint-reference.md b/docs/user-guide/01-blueprint-reference.md index b3e7a762f1..8c8c986242 100644 --- a/docs/user-guide/01-blueprint-reference.md +++ b/docs/user-guide/01-blueprint-reference.md @@ -1,6 +1,6 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -import Highlight, { tabValues, tabValuesOnPremiseOnly, tabValuesHostedOnly } from '@site/src/components/Highlight'; +import Highlight, { tabValues, tabValuesOnPremiseOnly, tabValuesHostedOnly, tabValuesWithBootc } from '@site/src/components/Highlight'; import '@site/src/css/custom.css'; # Blueprint Reference @@ -14,6 +14,8 @@ describes customizations of an image the 🟤  Not all customizations are supported in the API but those existing, are highlighted here with a 🟤 hosted label. +Additionally, there is 🟣 bootc which is supposed to be used from within podman desktop. + > An important thing to note is that these customizations are not applicable to all image types. `osbuild-composer` currently has no good validation or warning system in place to tell you if a customization in your blueprint is not supported for the image type you're building. The customization may be silently dropped. A very basic blueprint with just the required attributes at the root looks like: @@ -35,6 +37,11 @@ version = "0.0.1" } ``` + +``` +ℹ️ Currently not supported +``` + Where: @@ -117,6 +124,11 @@ version = "*" } ``` + +``` +ℹ️ Currently not supported +``` + ## Content @@ -166,6 +178,11 @@ packages = [ } ``` + +``` +ℹ️ Currently not supported +``` + ### Groups 🔵 {#groups} @@ -197,6 +214,11 @@ groups = [ ℹ️ Currently not supported ``` + +``` +ℹ️ Currently not supported +``` + ### Containers 🔵 🟤 {#containers} @@ -255,6 +277,11 @@ containers = [ } ``` + +``` +ℹ️ Currently not supported +``` + To access protected container resources a `containers-auth.json(5)` file can be used, see [Container registry credentials](../on-premises/installation/container-auth). @@ -284,11 +311,16 @@ hostname = "baseimage" } ``` + +``` +ℹ️ Currently not supported +``` + This is optional and can be left out to use the default hostname. -### Kernel 🔵 🟤 {#kernel} +### Kernel 🔵 🟤 🟣 {#kernel} #### Kernel Command-Line Arguments @@ -296,7 +328,7 @@ An *optional* object that contains the following attributes: - `name` an *optional* string which kernel to use - `append` an *optional* string to append arguments to the bootloader kernel command line - + ```toml [customizations.kernel] @@ -316,6 +348,13 @@ append = "nosmt=force" } ``` + +```toml +[customizations.kernel] +# name - not yet supported +append = "nosmt=force" +``` + ### SSH Keys 🔵 🟤 {#ssh-keys} @@ -352,11 +391,16 @@ key = "PUBLIC SSH KEY" } ``` + +``` +ℹ️ Currently not supported +``` + The key will be added to the user's `authorized_keys` file in their home directory. -### Additional Users 🔵 {#additional-users} +### Additional Users 🔵 🟤 🟣 {#additional-users} An *optional* list of objects that contain the following attributes: @@ -377,7 +421,7 @@ An *optional* list of objects that contain the following attributes: Add a user to the image, and/or set their ssh key. All fields for this section are optional except for the name. The following is a complete example: - + ```toml [[customizations.user]] @@ -411,16 +455,25 @@ expiredate = 12345 } ``` + +``` +[[customizations.user]] +name = "alice" +password = "bob" +key = "ssh-rsa AAA ... user@email.com" +groups = ["wheel"] +``` + -### Additional groups 🔵 🟤 {#additional-groups} +### Additional groups 🔵 🟤 🟣 {#additional-groups} An *optional* list of objects that contain the following attributes: - `name` a **required** string that sets the name of the group. - `gid` a **required** integer that sets the id of the group. - + ```toml [[customizations.group]] @@ -441,6 +494,13 @@ gid = 1130 } ``` + +```toml +[[customizations.group]] +name = "widget" +gid = 1130 +``` + ### Timezone 🔵 🟤 {#timezone} @@ -473,6 +533,11 @@ ntpservers = ["0.north-america.pool.ntp.org", "1.north-america.pool.ntp.org"] } ``` + +``` +ℹ️ Currently not supported +``` + The values supported by timezone can be listed by running the command: @@ -512,6 +577,11 @@ keyboard = "us" } ``` + +``` +ℹ️ Currently not supported +``` + The values supported by languages can be listed by running can be listed by running the command: @@ -557,6 +627,11 @@ ports = ["22:tcp", "80:tcp", "imap:tcp", "53:tcp", "53:udp", "30000-32767:tcp", } ``` + +``` +ℹ️ Currently not supported +``` + Numeric ports, or their names from `/etc/services` can be used in the ports enabled/disabled lists. @@ -587,6 +662,11 @@ disabled = ["telnet"] } ``` + +``` +ℹ️ Currently not supported +``` + Remember that the `firewall.services` are different from the names in `/etc/services`. @@ -627,6 +707,11 @@ masked = ["rpcbind"] } ``` + +``` +ℹ️ Currently not supported +``` + This section can be used to control which services are enabled at boot time. Some image types already have services enabled or disabled in order for the image to work correctly, and cannot be overridden. For example, `ami` image type requires `sshd`, `chronyd`, and `cloud-init` services. Without them, the image will not boot. Blueprint services do not replace these services, but add them to the list of services already present in the templates, if any. @@ -676,6 +761,11 @@ ensure_parents = false } ``` + +``` +ℹ️ Currently not supported +``` + - `path` is the path to the directory to create. It must be an absolute path under `/etc`. This is the only required field. @@ -728,6 +818,11 @@ data = "Hello world!" } ``` + +``` +ℹ️ Currently not supported +``` + - `path` is the path to the file to create. It must be an absolute under `/etc`. This is the only required field. @@ -760,6 +855,11 @@ installation_device = "/dev/sda" } ``` + +``` +ℹ️ Currently not supported +``` + ### Ignition 🔵 🟤 {#ignition} @@ -790,6 +890,11 @@ config = "eyJpZ25pdGlvbiI6eyJ2ZXJzaW9uIjoiMy4zLjAifSwicGFzc3dkIjp7InVzZXJzIjpbey } ``` + +``` +ℹ️ Currently not supported +``` + Add a `base64` encoded Ignition configuration in the `config` field. This Ignition configuration will be included in the `edge-simplified-installer` image. @@ -816,6 +921,11 @@ url = "http://some-server/configuration.ig" } ``` + +``` +ℹ️ Currently not supported +``` + Add a URL pointing to the Ignition configuration that will be fetched during the first boot in the `url` field. Available for both `edge-simplified-installer` and `edge-raw-image`. @@ -851,6 +961,11 @@ di_mfg_string_type_mac_iface = "enp2s0" } ``` + +``` +ℹ️ Currently not supported +``` + ### Repositories 🔵 🟤 {#repositories} @@ -891,6 +1006,11 @@ enabled=true } ``` + +``` +ℹ️ Currently not supported +``` + Since no filename is specified, the repo will be saved to `/etc/yum.repos.d/example.repo`. @@ -944,13 +1064,18 @@ partitioning_mode = "lvm" } ``` + +``` +ℹ️ Currently not supported +``` + -### Filesystems 🔵 🟤 {#filesystems} +### Filesystems 🔵 🟤 🟣 {#filesystems} The blueprints can be extended to provide filesytem support. Currently the `mountpoint` and minimum partition `minsize` can be set. On `RHEL-8`, custom mountpoints are supported only since version `8.5`. For older `RHEL` versions, only the root mountpoint, `/`, is supported, the size argument being an alias for the image size. - + ```toml [[customizations.filesystem]] @@ -971,6 +1096,14 @@ minsize = 2147483648 } ``` + +```toml +# only '/' and '/boot' supported here +[[customizations.filesystem]] +mountpoint = "/boot" +minsize = 2147483648 +``` + Filesystem customizations are currently **not** supported for the following image types: @@ -1053,6 +1186,11 @@ profile_id = "xccdf_org.ssgproject.content_profile_cis" } ``` + +``` +ℹ️ Currently not supported +``` + #### OpenSCAP Tailoring @@ -1083,6 +1221,11 @@ unselected = [ "grub2_password" ] ℹ️ Currently not supported ``` + +``` +ℹ️ Currently not supported +``` + #### FIPS 🔵 🟤 {#fips} @@ -1109,6 +1252,11 @@ fips = true } ``` + +``` +ℹ️ Currently not supported +``` + ### Architecture 🟤 {#architecture} @@ -1131,6 +1279,11 @@ On premises, we don't support multi-arch builds. The architecture of the image i } ``` + +``` +ℹ️ Currently not supported +``` + ### Installer 🔵 🟤 {#installer} @@ -1156,6 +1309,11 @@ sudo-nopasswd = ["user", "%wheel"] } ``` + +``` +ℹ️ Currently not supported +``` + - `unattended`: creates a kickstart file that makes the installation fully automatic. This includes setting the following options by default: diff --git a/src/components/Highlight.js b/src/components/Highlight.js index 51ae7d7273..6a1fd793c9 100644 --- a/src/components/Highlight.js +++ b/src/components/Highlight.js @@ -4,18 +4,28 @@ import React from 'react'; export const tabValues = [ { label: '🔵 on premises', value: 'on-premises', attributes: { className: 'highlight tab on-premises' } }, { label: '🟤 hosted', value: 'hosted', attributes: { className: 'highlight tab hosted' } }, + { label: '⚪ bootc', value: 'bootc', attributes: { className: 'highlight tab disabled' } }, ]; export const tabValuesOnPremiseOnly = [ { label: '🔵 on premises', value: 'on-premises', attributes: { className: 'highlight tab on-premises' } }, { label: '⚪ hosted', value: 'hosted', attributes: { className: 'highlight tab disabled' } }, + { label: '⚪ bootc', value: 'bootc', attributes: { className: 'highlight tab disabled' } }, ]; export const tabValuesHostedOnly = [ { label: '⚪ on premises', value: 'on-premises', attributes: { className: 'highlight tab disabled' } }, { label: '🟤 hosted', value: 'hosted', attributes: { className: 'highlight tab hosted' } }, + { label: '⚪ bootc', value: 'bootc', attributes: { className: 'highlight tab disabled' } }, ]; +export const tabValuesWithBootc = [ + { label: '🔵 on premises', value: 'on-premises', attributes: { className: 'highlight tab on-premises' } }, + { label: '🟤 hosted', value: 'hosted', attributes: { className: 'highlight tab hosted' } }, + { label: '🟣 bootc', value: 'bootc', attributes: { className: 'highlight tab bootc' } }, +]; + + //colorVars - see css/custom.css export default function Highlight({children, colorVar}) { diff --git a/src/css/custom.css b/src/css/custom.css index c4643017bc..feae002972 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -16,6 +16,7 @@ --ifm-code-font-size: 95%; --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1); --on-premises-color: SteelBlue; + --bootc-color: MediumPurple; --hosted-color: SandyBrown; } @@ -30,6 +31,7 @@ --ifm-color-primary-lightest: #4fddbf; --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3); --on-premises-color: SteelBlue; + --bootc-color: MediumPurple; --hosted-color: SandyBrown; } @@ -43,11 +45,13 @@ .highlight.box.on-premises { border: 1px solid var(--on-premises-color); - } .highlight.box.hosted { border: 1px solid var(--hosted-color); } +.highlight.box.bootc { + border: 1px solid var(--bootc-color); +} .highlight.tab.disabled { color: #bbb; @@ -67,3 +71,7 @@ border-bottom: none; background-color: #eee; } +.highlight.tab.bootc.tabs__item--active { + border-bottom: 3px solid var(--bootc-color); + background-color: #f0ebfa; +} \ No newline at end of file