diff --git a/docs/Makefile b/docs/Makefile index 80418449a478..1d742cb2140f 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -70,7 +70,8 @@ container-serve: ## Boot the development server using container. Run `make conta --bind 0.0.0.0 \ --destination /tmp/hugo \ --cleanDestinationDir \ - --baseURL http://0.0.0.0 + --baseURL http://0.0.0.0 \ + --enableGitInfo=false container-server: container-serve diff --git a/docs/content/en/docs/getting-started/baremetal/bare-spec.md b/docs/content/en/docs/getting-started/baremetal/bare-spec.md index f55f93bd6fa9..507b34100f05 100644 --- a/docs/content/en/docs/getting-started/baremetal/bare-spec.md +++ b/docs/content/en/docs/getting-started/baremetal/bare-spec.md @@ -362,30 +362,19 @@ More information in the [Host OS Configuration]({{< relref "../optional/hostOSCo ## Advanced Bare Metal cluster configuration -When you generate a Bare Metal cluster configuration, the `TinkerbellTemplateConfig` is kept internally and not shown in the generated configuration file. -`TinkerbellTemplateConfig` settings define the actions done to install each node, such as get installation media, configure networking, add users, and otherwise configure the node. +When you generate a Bare Metal cluster configuration, by default, the `TinkerbellTemplateConfig` is not shown in the generated configuration file. The `TinkerbellTemplateConfig` defines the actions to provision each node, such as getting installation media, configuring networking, adding users, and otherwise configuring the node. Internally, EKS Anywhere generates a default `TinkerbellTemplateConfig` based on the operating system family you choose. The default `TinkerbellTemplateConfig` is sufficient for most use cases. -Advanced users can override the default values set for `TinkerbellTemplateConfig`. -They can also add their own [Tinkerbell actions](https://docs.tinkerbell.org/actions/action-architecture/) to make personalized modifications to EKS Anywhere nodes. +If your use case necessitates that the operating system have additional configuration, you can add a `TinkerbellTemplateConfig` to your cluster configuration file with your own customizations. To do this, start with the default `TinkerbellTemplateConfig` generated by EKS Anywhere and modify it as needed. To generate the default `TinkerbellTemplateConfig`, use the following command: -A default `TinkerbellTemplateConfig` can be generated from cluster config template using eksctl: ```bash eksctl anywhere generate tinkerbelltemplateconfig -f eksa-mgmt-cluster.yaml ``` -The following shows three `TinkerbellTemplateConfig` examples that you can add to your cluster configuration file to override the values that EKS Anywhere sets: one for Ubuntu, one for RHEL and one for Bottlerocket. -Most actions used differ for different operating systems. +Now you can add your own Actions for configuring nodes. We highly recommend that you do not modify the first and the last Actions in the default `TinkerbellTemplateConfig`. The first Action streams the OS image to the disk, and the last Action reboots the node. See the upstream Tinkerbell documentation for more information on [Templates](https://tinkerbell.org/docs/concepts/templates/) and [Actions](https://tinkerbell.org/docs/concepts/templates/#actions). ->**_NOTE:_** For the `stream-image` action, `DEST_DISK` points to the device representing the entire hard disk (for example, `/dev/sda`). -For all the write actions, `DEST_DISK` must be set to point to the root partition. -For RHEL 8 and RHEL 9, `DEST_DISK` points to partition 1 (for example, `/dev/sda1`). -For Ubuntu, `DEST_DISK` points to partition 2 (for example, `/dev/sda2`), with the first partition being the EFI partition. -For the Bottlerocket image, which has 12 partitions, `DEST_DISK` points to partition 12 (for example, `/dev/sda12`). -Note that these partition index values may vary depending on how user built their OS image, user can always override these partitions using `TinkerbellTemplateConfig`. -Device names will be different for different disk types. -> +The following shows the default `TinkerbellTemplateConfig` generated by `eksctl anywhere generate tinkerbelltemplateconfig`. -### Ubuntu TinkerbellTemplateConfig example +### Ubuntu ```yaml --- @@ -402,76 +391,74 @@ spec: - actions: - environment: COMPRESSED: "true" - DEST_DISK: /dev/sda - IMG_URL: https://my-file-server/ubuntu-v1.23.7-eks-a-12-amd64.gz - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/image2disk:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 - name: stream-image - timeout: 360 + DEST_DISK: '{{ index .Hardware.Disks 0 }}' + IMG_URL: https://my-file-server/ubuntu-2204-kube-v1.30.gz + image: 127.0.0.1/embedded/image2disk + name: stream image to disk + timeout: 600 - environment: - DEST_DISK: /dev/sda2 + DEST_DISK: '{{ formatPartition ( index .Hardware.Disks 0 ) 2 }}' DEST_PATH: /etc/netplan/config.yaml - STATIC_NETPLAN: true DIRMODE: "0755" FS_TYPE: ext4 GID: "0" MODE: "0644" + STATIC_NETPLAN: "true" UID: "0" - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/writefile:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 - name: write-netplan + image: 127.0.0.1/embedded/writefile + name: write netplan config + pid: host timeout: 90 - environment: - CONTENTS: | - datasource: - Ec2: - metadata_urls: [, ] - strict_id: false - manage_etc_hosts: localhost - warnings: - dsid_missing_source: off - DEST_DISK: /dev/sda2 - DEST_PATH: /etc/cloud/cloud.cfg.d/10_tinkerbell.cfg + CONTENTS: 'network: {config: disabled}' + DEST_DISK: '{{ formatPartition ( index .Hardware.Disks 0 ) 2 }}' + DEST_PATH: /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg DIRMODE: "0700" FS_TYPE: ext4 GID: "0" MODE: "0600" UID: "0" - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/writefile:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 - name: add-tink-cloud-init-config + image: 127.0.0.1/embedded/writefile + name: disable cloud-init network capabilities timeout: 90 - environment: CONTENTS: | - network: - config: disabled - DEST_DISK: /dev/sda2 - DEST_PATH: /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg + datasource: + Ec2: + metadata_urls: [http://:50061,http://:50061] + strict_id: false + manage_etc_hosts: localhost + warnings: + dsid_missing_source: off + DEST_DISK: '{{ formatPartition ( index .Hardware.Disks 0 ) 2 }}' + DEST_PATH: /etc/cloud/cloud.cfg.d/10_tinkerbell.cfg DIRMODE: "0700" FS_TYPE: ext4 GID: "0" MODE: "0600" UID: "0" - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/writefile:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 - name: disable-cloud-init-network-capabilities + image: 127.0.0.1/embedded/writefile + name: add cloud-init config timeout: 90 - environment: CONTENTS: | datasource: Ec2 - DEST_DISK: /dev/sda2 + DEST_DISK: '{{ formatPartition ( index .Hardware.Disks 0 ) 2 }}' DEST_PATH: /etc/cloud/ds-identify.cfg DIRMODE: "0700" FS_TYPE: ext4 GID: "0" MODE: "0600" UID: "0" - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/writefile:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 - name: add-tink-cloud-init-ds-config + image: 127.0.0.1/embedded/writefile + name: add cloud-init ds config timeout: 90 - - environment: - BLOCK_DEVICE: /dev/sda2 - FS_TYPE: ext4 - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/kexec:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 - name: kexec-image + - image: 127.0.0.1/embedded/reboot + name: reboot pid: host timeout: 90 + volumes: + - /worker:/worker name: my-cluster-name volumes: - /dev:/dev @@ -481,7 +468,7 @@ spec: version: "0.1" ``` -### RHEL TinkerbellTemplateConfig example +### Red Hat Enterprise Linux ```yaml --- @@ -499,55 +486,53 @@ spec: - environment: COMPRESSED: "true" DEST_DISK: '{{ index .Hardware.Disks 0 }}' - IMG_URL: https://my-file-server/rhel-9-uefi-amd64.gz - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/image2disk:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 - name: stream-image - timeout: 360 + IMG_URL: https://my-file-server/rhel-9-kube-v1.30.0.gz + image: 127.0.0.1/embedded/image2disk + name: stream image to disk + timeout: 600 - environment: DEST_DISK: '{{ formatPartition ( index .Hardware.Disks 0 ) 1 }}' DEST_PATH: /etc/netplan/config.yaml - STATIC_NETPLAN: true DIRMODE: "0755" FS_TYPE: ext4 GID: "0" MODE: "0644" + STATIC_NETPLAN: "true" UID: "0" - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/writefile:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 - name: write-netplan + image: 127.0.0.1/embedded/writefile + name: write netplan config pid: host timeout: 90 - environment: - CONTENTS: | - datasource: - Ec2: - metadata_urls: [:50061, :50061] - strict_id: false - manage_etc_hosts: localhost - warnings: - dsid_missing_source: off + CONTENTS: 'network: {config: disabled}' DEST_DISK: '{{ formatPartition ( index .Hardware.Disks 0 ) 1 }}' - DEST_PATH: /etc/cloud/cloud.cfg.d/10_tinkerbell.cfg + DEST_PATH: /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg DIRMODE: "0700" FS_TYPE: ext4 GID: "0" MODE: "0600" UID: "0" - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/writefile:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 - name: add-tink-cloud-init-config + image: 127.0.0.1/embedded/writefile + name: disable cloud-init network capabilities timeout: 90 - environment: CONTENTS: | - network: - config: disabled + datasource: + Ec2: + metadata_urls: ['http://:50061','http://:50061'] + strict_id: false + manage_etc_hosts: localhost + warnings: + dsid_missing_source: off DEST_DISK: '{{ formatPartition ( index .Hardware.Disks 0 ) 1 }}' - DEST_PATH: /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg + DEST_PATH: /etc/cloud/cloud.cfg.d/10_tinkerbell.cfg DIRMODE: "0700" FS_TYPE: ext4 GID: "0" MODE: "0600" UID: "0" - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/writefile:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 - name: disable-cloud-init-network-capabilities + image: 127.0.0.1/embedded/writefile + name: add cloud-init config timeout: 90 - environment: CONTENTS: | @@ -559,15 +544,15 @@ spec: GID: "0" MODE: "0600" UID: "0" - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/writefile:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 - name: add-tink-cloud-init-ds-config + image: 127.0.0.1/embedded/writefile + name: add cloud-init ds config timeout: 90 - - name: "reboot-image" - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/reboot:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 + - image: 127.0.0.1/embedded/reboot + name: reboot pid: host timeout: 90 volumes: - - /worker:/worker + - /worker:/worker name: my-cluster-name volumes: - /dev:/dev @@ -577,294 +562,149 @@ spec: version: "0.1" ``` -### Bottlerocket TinkerbellTemplateConfig example +## TinkerbellTemplateConfig fields -Pay special attention to the `BOOTCONFIG_CONTENTS` environment section below if you wish to set up console redirection for the kernel and systemd. -If you are only using a direct attached monitor as your primary display device, no additional configuration is needed here. -However, if you need all boot output to be shown via a server's serial console for example, extra configuration should be provided inside `BOOTCONFIG_CONTENTS`. +Each Action has its own set of environment variables that are used to configure the Action. EKS Anywhere embeds a set of images into HookOS. This means that when these images are used in an Action they will not be pulled from any external registry. No external network communication is needed to use them. These Actions are prefixed with `127.0.0.1/embedded`. -An empty `kernel {}` key is provided below in the example; inside this key is where you will specify your console devices. -You may specify multiple comma delimited console devices in quotes to a console key as such: `console = "tty0", "ttyS0,115200n8"`. -The order of the devices is significant; systemd will output to the last device specified. -The console key belongs inside the kernel key like so: -``` -kernel { - console = "tty0", "ttyS0,115200n8" -} -``` +>**_NOTE:_** +Actions are user-defined and can include any container image that is available to HookOS. You can create your own Action images if the embedded Action images do not meet your requirements. +> + +The following describes the embedded Action images that are available in HookOS and their configuration options. + +### cexec + +`127.0.0.1/embedded/cexec` + +The `cexec` Action executes either within a chroot environment or within the HookOS filesystem. The primary use case is to provision files and an Operating System to disk, and then execute something that resides within that filesystem. + +All options can be set either via environment variables or CLI flags. +CLI flags take precedence over environment variables, which take precedence over default values. + +| Env variable | Flag | Type | Default Value | Required | Description | +|--------------|------|------|---------------|----------|-------------| +| `BLOCK_DEVICE` | `--block-device` | string | "" | yes | The block device to mount. | +| `FS_TYPE` | `--fs-type` | string | "" | yes | The filesystem type of the block device. | +| `CHROOT` | `--chroot` | string | "" | no | If set to `y` (or a non empty string), the Action will execute the given command within a chroot environment. This option is DEPRECATED. Future versions will always chroot. | +| `CMD_LINE` | `--cmd-line` | string | "" | yes | The command to execute. | +| `DEFAULT_INTERPRETER` | `--default-interpreter` | string | "" | no | The default interpreter to use when executing commands. This is useful when you need to execute multiple commands. | +| `UPDATE_RESOLV_CONF` | `--update-resolv-conf` | boolean | false | no | If set to `true`, the cexec Action will update the `/etc/resolv.conf` file within the chroot environment with the `/etc/resolv.conf` from the host. | +| `JSON_OUTPUT` | `--json-output` | boolean | true | no | If set to `true`, the cexec Action will log output in JSON format. This defaults to `true`. If set to `false`, the cexec Action will log output in plain text format. | -The above example will send all kernel output to both consoles, and systemd output to `ttyS0`. -Additional information about serial console setup can be found in the [Linux kernel documentation](https://www.kernel.org/doc/html/latest/admin-guide/serial-console.html). +Any environment variables you set on the Action will be available to the command you execute. +For example, if you set `DEBIAN_FRONTEND: noninteractive` as an environment variable (`DEBIAN_FRONTEND=noninteractive`), it will be available to the command you execute. + +### writefile + +`127.0.0.1/embedded/writefile` + +The `writefile` Action will mount a block device and write a file to a destination path on its filesystem. + +| Env variable | Type | Required | Description | +|--------------|------|----------|-------------| +| `DEST_DISK` | string | yes | The block device to mount. | +| `FS_TYPE` | string | yes | The filesystem type of the block device. | +| `DEST_PATH` | string | yes | The path to write the file to. | +| `CONTENTS` | string | yes | The contents of the file to write. | +| `UID` | string | yes | The user ID to set on the file. | +| `GID` | string | yes | The group ID to set on the file. | +| `MODE` | string | yes | The permission bits to set on the file. | +| `DIRMODE` | string | yes | The permission bits to set on the directory. | + +The follow field must be set on the Action. ```yaml ---- -apiVersion: anywhere.eks.amazonaws.com/v1alpha1 -kind: TinkerbellTemplateConfig -metadata: - name: my-cluster-name -spec: - template: - global_timeout: 6000 - id: "" - name: my-cluster-name - tasks: - - actions: - - environment: - COMPRESSED: "true" - DEST_DISK: /dev/sda - IMG_URL: https://anywhere-assets.eks.amazonaws.com/releases/bundles/11/artifacts/raw/1-22/bottlerocket-v1.22.10-eks-d-1-22-8-eks-a-11-amd64.img.gz - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/image2disk:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 - name: stream-image - timeout: 360 - - environment: - # An example console declaration that will send all kernel output to both consoles, and systemd output to ttyS0. - # kernel { - # console = "tty0", "ttyS0,115200n8" - # } - BOOTCONFIG_CONTENTS: | - kernel {} - DEST_DISK: /dev/sda12 - DEST_PATH: /bootconfig.data - DIRMODE: "0700" - FS_TYPE: ext4 - GID: "0" - MODE: "0644" - UID: "0" - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/writefile:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 - name: write-bootconfig - timeout: 90 - - environment: - CONTENTS: | - # Version is required, it will change as we support - # additional settings - version = 1 - # "eno1" is the interface name - # Users may turn on dhcp4 and dhcp6 via boolean - [eno1] - dhcp4 = true - # Define this interface as the "primary" interface - # for the system. This IP is what kubelet will use - # as the node IP. If none of the interfaces has - # "primary" set, we choose the first interface in - # the file - primary = true - DEST_DISK: /dev/sda12 - DEST_PATH: /net.toml - DIRMODE: "0700" - FS_TYPE: ext4 - GID: "0" - MODE: "0644" - UID: "0" - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/writefile:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 - name: write-netconfig - timeout: 90 - - environment: - HEGEL_URLS: http://:50061 - DEST_DISK: /dev/sda12 - DEST_PATH: /user-data.toml - DIRMODE: "0700" - FS_TYPE: ext4 - GID: "0" - MODE: "0644" - UID: "0" - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/writefile:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 - name: write-user-data - timeout: 90 - - name: "reboot" - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/reboot:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 - timeout: 90 - volumes: - - /worker:/worker - name: my-cluster-name - volumes: - - /dev:/dev - - /dev/console:/dev/console - - /lib/firmware:/lib/firmware:ro - worker: '{{.device_1}}' - version: "0.1" +pid: host ``` -## TinkerbellTemplateConfig Fields - -The values in the `TinkerbellTemplateConfig` fields are created from the contents of the CSV file used to generate a configuration. -The template contains actions that are performed on a Bare Metal machine when it first boots up to be provisioned. -For advanced users, you can add these fields to your cluster configuration file if you have special needs to do so. - -While there are fields that apply to all provisioned operating systems, actions are specific to each operating system. -Examples below describe actions for Ubuntu and Bottlerocket operating systems. - -### template.global_timeout - -Sets the timeout value for completing the configuration. Set to 6000 (100 minutes) by default. - -### template.id - -Not set by default. - -### template.tasks - -Within the TinkerbellTemplateConfig `template` under `tasks` is a set of actions. -The following descriptions cover the actions shown in the example templates for Ubuntu and Bottlerocket: - -### template.tasks.actions.name.stream-image (Ubuntu and Bottlerocket) -The `stream-image` action streams the selected image to the machine you are provisioning. It identifies: - -* environment.COMPRESSED: When set to `true`, Tinkerbell expects `IMG_URL` to be a compressed image, which Tinkerbell will uncompress when it writes the contents to disk. -* environment.DEST_DISK: The hard disk on which the operating system is deployed. The default is the first SCSI disk (/dev/sda), but can be changed for other disk types. -* environment.IMG_URL: The operating system tarball (ubuntu or other) to stream to the machine you are configuring. -* image: Container image needed to perform the steps needed by this action. -* timeout: Sets the amount of time (in seconds) that Tinkerbell has to stream the image, uncompress it, and write it to disk before timing out. Consider increasing this limit from the default 600 to a higher limit if this action is timing out. - -## Ubuntu-specific actions - -### template.tasks.actions.name.write-netplan (Ubuntu) -The `write-netplan` action writes Ubuntu network configuration information to the machine (see [Netplan](https://netplan.io/)) for details. It identifies: - -* environment.CONTENTS.network.version: Identifies the network version. -* environment.CONTENTS.network.renderer: Defines the service to manage networking. By default, the `networkd` systemd service is used. -* environment.CONTENTS.network.ethernets: Network interface to external network (eno1, by default) and whether or not to use dhcp4 (true, by default). -* environment.DEST_DISK: Destination block storage device partition where the operating system is copied. By default, /dev/sda2 is used (sda1 is the EFI partition). -* environment.DEST_PATH: File where the networking configuration is written (/etc/netplan/config.yaml, by default). -* environment.DIRMODE: Linux directory permissions bits to use when creating directories (0755, by default) -* environment.FS_TYPE: Type of filesystem on the partition (ext4, by default). -* environment.GID: The Linux group ID to set on file. Set to 0 (root group) by default. -* environment.MODE: The Linux permission bits to set on file (0644, by default). -* environment.UID: The Linux user ID to set on file. Set to 0 (root user) by default. -* image: Container image used to perform the steps needed by this action. -* timeout: Time needed to complete the action, in seconds. - -### template.tasks.actions.add-tink-cloud-init-config (Ubuntu) -The `add-tink-cloud-init-config` action configures cloud-init features to further configure the operating system. See [cloud-init Documentation](https://cloudinit.readthedocs.io/en/latest/) for details. It identifies: - -* environment.CONTENTS.datasource: Identifies Ec2 (Ec2.metadata_urls) as the data source and sets `Ec2.strict_id: false` to prevent cloud-init from producing warnings about this datasource. -* environment.CONTENTS.system_info: Creates the `tink` user and gives it administrative group privileges (wheel, adm) and passwordless sudo privileges, and set the default shell (/bin/bash). -* environment.CONTENTS.manage_etc_hosts: Updates the system's `/etc/hosts` file with the hostname. Set to `localhost` by default. -* environment.CONTENTS.warnings: Sets dsid_missing_source to `off`. -* environment.DEST_DISK: Destination block storage device partition where the operating system is located (`/dev/sda2`, by default). -* environment.DEST_PATH: Location of the cloud-init configuration file on disk (`/etc/cloud/cloud.cfg.d/10_tinkerbell.cfg`, by default) -* environment.DIRMODE: Linux directory permissions bits to use when creating directories (0700, by default) -* environment.FS_TYPE: Type of filesystem on the partition (ext4, by default). -* environment.GID: The Linux group ID to set on file. Set to 0 (root group) by default. -* environment.MODE: The Linux permission bits to set on file (0600, by default). -* environment.UID: The Linux user ID to set on file. Set to 0 (root user) by default. -* image: Container image used to perform the steps needed by this action. -* timeout: Time needed to complete the action, in seconds. - -### template.tasks.actions.add-tink-cloud-init-ds-config (Ubuntu) -The `add-tink-cloud-init-ds-config` action configures cloud-init data store features. This identifies the location of your metadata source once the machine is up and running. It identifies: - -* environment.CONTENTS.datasource: Sets the datasource. Uses Ec2, by default. -* environment.DEST_DISK: Destination block storage device partition where the operating system is located (/dev/sda2, by default). -* environment.DEST_PATH: Location of the data store identity configuration file on disk (/etc/cloud/ds-identify.cfg, by default) -* environment.DIRMODE: Linux directory permissions bits to use when creating directories (0700, by default) -* environment.FS_TYPE: Type of filesystem on the partition (ext4, by default). -* environment.GID: The Linux group ID to set on file. Set to 0 (root group) by default. -* environment.MODE: The Linux permission bits to set on file (0600, by default). -* environment.UID: The Linux user ID to set on file. Set to 0 (root user) by default. -* image: Container image used to perform the steps needed by this action. -* timeout: Time needed to complete the action, in seconds. - -### template.tasks.actions.kexec-image (Ubuntu) -The `kexec-image` action performs provisioning activities on the machine, then allows kexec to pivot the kernel to use the system installed on disk. This action identifies: - -* environment.BLOCK_DEVICE: Disk partition on which the operating system is installed (/dev/sda2, by default) -* environment.FS_TYPE: Type of filesystem on the partition (ext4, by default). -* image: Container image used to perform the steps needed by this action. -* pid: Process ID. Set to host, by default. -* timeout: Time needed to complete the action, in seconds. -* volumes: Identifies mount points that need to be remounted to point to locations in the installed system. - -There are known issues related to drivers with some hardware that may make it necessary to replace the kexec-image action with a full reboot. -If you require a full reboot, you can change the kexec-image setting as follows: + +### image2disk + +`127.0.0.1/embedded/image2disk` + +The `image2disk` Action will stream either a compressed or not compressed remote image (raw) to a block device. + +| Env variable | Type | Default Value | Required | Description | +|--------------|------|---------------|----------|-------------| +| IMG_URL | string | "" | yes | URL of the image to be streamed. | +| DEST_DISK | string | "" | yes | Block device to which the image is written. | +| COMPRESSED | bool | false | no | Decompress the image before writing it to the disk. | +| RETRY_ENABLED | bool | false | no | Retry the Action, using exponential backoff, for the duration specified in `RETRY_DURATION_MINUTES` before failing. | +| RETRY_DURATION_MINUTES | int | 10 | no | Duration for which the Action will retry before failing. | +| PROGRESS_INTERVAL_SECONDS | int | 3 | no | Interval at which the progress of the image transfer will be logged. | +| TEXT_LOGGING | bool | false | no | Output from the Action will be logged in a more human friendly text format, JSON format is used by default. | + +### oci2disk + +`127.0.0.1/embedded/oci2disk` + +The `oci2disk` Action provides the capability of streaming a raw (compressed) disk image from an OCI compliant-registry to a local block device. + +| Env variable | Type | Default Value | Required | Description | +|--------------|------|---------------|----------|-------------| +| IMG_URL | string | "" | yes | URL of the image to be streamed. | +| DEST_DISK | string | "" | yes | Block device to which the image is written. | +| COMPRESSED | bool | false | no | Decompress the image before writing it to the disk. | + +### kexec + + `127.0.0.1/embedded/kexec` + +The `kexec` Action makes use of the [Linux kexec function](https://en.wikipedia.org/wiki/Kexec) to boot directly into a kernel. + +| Env variable | Type | Default Value | Required | Description | +|--------------|------|---------------|----------|-------------| +| BLOCK_DEVICE | string | "" | yes | The block device to mount. | +| FS_TYPE | string | "" | yes | The filesystem type of the block device. | +| KERNEL_PATH | string | "" | no | The path to the kernel to boot. When not supplied the kernel path will discovered from `/boot/grub/grub.cfg` on the `BLOCK_DEVICE`. | +| INITRD_PATH | string | "" | yes | The path to the initial ramdisk to boot. | +| CMD_LINE | string | "" | no | The command line to pass to the kernel. When not supplied, the kernel cmdline parameters will discovered from `/boot/grub/grub.cfg` on the `BLOCK_DEVICE`. | + +>**_NOTE:_** +There are known issues related to drivers with some hardware that may make it necessary to replace the `kexec` Action image with the `reboot` Action image. +> + +### reboot + +`127.0.0.1/embedded/reboot` + +The `reboot` Action will reboot the machine. + +The follow fields must be set on the Action. ```yaml -actions: -- name: "reboot" - image: public.ecr.aws/l0g8r8j6/tinkerbell/hub/reboot-action:latest - timeout: 90 - volumes: +pid: host +volumes: - /worker:/worker ``` -## Bottlerocket-specific actions - -### template.tasks.actions.write-bootconfig (Bottlerocket) -The write-bootconfig action identifies the location on the machine to put content needed to boot the system from disk. - -* environment.BOOTCONFIG_CONTENTS.kernel: Add kernel parameters that are passed to the kernel when the system boots. -* environment.DEST_DISK: Identifies the block storage device that holds the boot partition. -* environment.DEST_PATH: Identifies the file holding boot configuration data (`/bootconfig.data` in this example). -* environment.DIRMODE: The Linux permissions assigned to the boot directory. -* environment.FS_TYPE: The filesystem type associated with the boot partition. -* environment.GID: The group ID associated with files and directories created on the boot partition. -* environment.MODE: The Linux permissions assigned to files in the boot partition. -* environment.UID: The user ID associated with files and directories created on the boot partition. UID 0 is the root user. -* image: Container image used to perform the steps needed by this action. -* timeout: Time needed to complete the action, in seconds. - -### template.tasks.actions.write-netconfig (Bottlerocket) -The write-netconfig action configures networking for the system. - -* environment.CONTENTS: Add network values, including: `version = 1` (version number), `[eno1]` (external network interface), `dhcp4 = true` (turns on dhcp4), and `primary = true` (identifies this interface as the primary interface used by kubelet). -* environment.DEST_DISK: Identifies the block storage device that holds the network configuration information. -* environment.DEST_PATH: Identifies the file holding network configuration data (`/net.toml` in this example). -* environment.DIRMODE: The Linux permissions assigned to the directory holding network configuration settings. -* environment.FS_TYPE: The filesystem type associated with the partition holding network configuration settings. -* environment.GID: The group ID associated with files and directories created on the partition. GID 0 is the root group. -* environment.MODE: The Linux permissions assigned to files in the partition. -* environment.UID: The user ID associated with files and directories created on the partition. UID 0 is the root user. -* image: Container image used to perform the steps needed by this action. - -### template.tasks.actions.write-user-data (Bottlerocket) -The write-user-data action configures the Tinkerbell Hegel service, which provides the metadata store for Tinkerbell. - -* environment.HEGEL_URLS: The IP address and port number of the Tinkerbell [Hegel](https://docs.tinkerbell.org/services/hegel/) service. -* environment.DEST_DISK: Identifies the block storage device that holds the network configuration information. -* environment.DEST_PATH: Identifies the file holding network configuration data (`/net.toml` in this example). -* environment.DIRMODE: The Linux permissions assigned to the directory holding network configuration settings. -* environment.FS_TYPE: The filesystem type associated with the partition holding network configuration settings. -* environment.GID: The group ID associated with files and directories created on the partition. GID 0 is the root group. -* environment.MODE: The Linux permissions assigned to files in the partition. -* environment.UID: The user ID associated with files and directories created on the partition. UID 0 is the root user. -* image: Container image used to perform the steps needed by this action. -* timeout: Time needed to complete the action, in seconds. - -### template.tasks.actions.reboot (Bottlerocket) -The reboot action defines how the system restarts to bring up the installed system. - -* image: Container image used to perform the steps needed by this action. -* timeout: Time needed to complete the action, in seconds. -* volumes: The volume (directory) to mount into the container from the installed system. -### version - -Matches the current version of the Tinkerbell template. - ## Custom Tinkerbell action examples -By creating your own custom Tinkerbell actions, you can add to or modify the installed operating system so those changes take effect when the installed system first starts (from a reboot or pivot). -The following example shows how to add a .deb package (`openssl`) to an Ubuntu installation: + +The following example shows how to add a .deb package (`openssl`) to a Red Hat Enterprise Linux installation: ```yaml - - environment: - BLOCK_DEVICE: /dev/sda1 - CHROOT: "y" - CMD_LINE: apt -y update && apt -y install openssl - DEFAULT_INTERPRETER: /bin/sh -c - FS_TYPE: ext4 - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/cexec:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 - name: install-openssl - timeout: 90 +- environment: + BLOCK_DEVICE: '{{ formatPartition ( index .Hardware.Disks 0 ) 1 }}' # /dev/sda1 + CHROOT: "y" + CMD_LINE: apt -y update && apt -y install openssl + DEFAULT_INTERPRETER: /bin/sh -c + FS_TYPE: ext4 + image: 127.0.0.1/embedded/cexec + name: install openssl + timeout: 90 ``` -The following shows an example of adding a new user (`tinkerbell`) to an installed Ubuntu system: + +The following shows an example of adding a new user (`tinkerbell`) to an Ubuntu installation: ```yaml - - environment: - BLOCK_DEVICE: # E.g. /dev/sda1 - FS_TYPE: ext4 - CHROOT: y - DEFAULT_INTERPRETER: "/bin/sh -c" - CMD_LINE: "useradd --password $(openssl passwd -1 tinkerbell) --shell /bin/bash --create-home --groups sudo tinkerbell" - image: public.ecr.aws/eks-anywhere/tinkerbell/hub/cexec:6c0f0d437bde2c836d90b000312c8b25fa1b65e1-eks-a-15 - name: "create-user" - timeout: 90 +- environment: + BLOCK_DEVICE: '{{ formatPartition ( index .Hardware.Disks 0 ) 2 }}' # /dev/sda2 + FS_TYPE: ext4 + CHROOT: y + DEFAULT_INTERPRETER: "/bin/sh -c" + CMD_LINE: "useradd --password $(openssl passwd -1 tinkerbell) --shell /bin/bash --create-home --groups sudo tinkerbell" + image: 127.0.0.1/embedded/cexec + name: create a user + timeout: 90 ``` Look for more examples as they are added to the [Tinkerbell examples](https://github.com/aws/eks-anywhere/tree/main/examples/tinkerbell) page.