diff --git a/docs/buildah-build.1.md b/docs/buildah-build.1.md index 8507439d0e7..511eeee9a99 100644 --- a/docs/buildah-build.1.md +++ b/docs/buildah-build.1.md @@ -288,6 +288,62 @@ The [username[:password]] to use to authenticate with the registry if required. If one or both values are not supplied, a command line prompt will appear and the value can be entered. The password is entered without echo. +**--cw** *options* + +Produce an image suitable for use as a confidential workload running in a +trusted execution environment (TEE) using krun (i.e., *crun* built with the +libkrun feature enabled and invoked as *krun*). Instead of the conventional +contents, the root filesystem of the image will contain an encrypted disk image +and configuration information for krun. + +The value for *options* is a comma-separated list of key=value pairs, supplying +configuration information which is needed for producing the additional data +which will be included in the container image. + +Recognized _keys_ are: + +*attestation_url*: The location of a key broker / attestation server. +If a value is specified, the new image's workload ID, along with the passphrase +used to encrypt the disk image, will be registered with the server, and the +server's location will be stored in the container image. +At run-time, krun is expected to contact the server to retrieve the passphrase +using the workload ID, which is also stored in the container image. +If no value is specified, a *passphrase* value *must* be specified. + +*cpus*: The number of virtual CPUs which the image expects to be run with at +run-time. If not specified, a default value will be supplied. + +*firmware_library*: The location of the libkrunfw-sev shared library. If not +specified, `buildah` checks for its presence in a number of hard-coded +locations. + +*memory*: The amount of memory which the image expects to be run with at +run-time, as a number of megabytes. If not specified, a default value will be +supplied. + +*passphrase*: The passphrase to use to encrypt the disk image which will be +included in the container image. +If no value is specified, but an *attestation_url* value is specified, a +randomly-generated passphrase will be used. +The authors recommend setting an *attestation_url* but not a *passphrase*. + +*slop*: Extra space to allocate for the disk image compared to the size of the +container image's contents, expressed either as a percentage (..%) or a size +value (bytes, or larger units if suffixes like KB or MB are present), or a sum +of two or more such specifications. If not specified, `buildah` guesses that +25% more space than the contents will be enough, but this option is provided in +case its guess is wrong. + +*type*: The type of trusted execution environment (TEE) which the image should +be marked for use with. Accepted values are "SEV" (AMD Secure Encrypted +Virtualization - Encrypted State) and "SNP" (AMD Secure Encrypted +Virtualization - Secure Nested Paging). If not specified, defaults to "SNP". + +*workload_id*: A workload identifier which will be recorded in the container +image, to be used at run-time for retrieving the passphrase which was used to +encrypt the disk image. If not specified, a semi-random value will be derived +from the base image's image ID. + **--decryption-key** *key[:passphrase]* The [key[:passphrase]] to be used for decryption of images. Key can point to keys and/or certificates. Decryption will be tried with all keys. If the key is protected by a passphrase, it is required to be passed in the argument and omitted otherwise. diff --git a/docs/buildah-commit.1.md b/docs/buildah-commit.1.md index 2e5a4aa6260..72f8aa9d39e 100644 --- a/docs/buildah-commit.1.md +++ b/docs/buildah-commit.1.md @@ -39,6 +39,63 @@ The [username[:password]] to use to authenticate with the registry if required. If one or both values are not supplied, a command line prompt will appear and the value can be entered. The password is entered without echo. +**--cw** *options* + +Produce an image suitable for use as a confidential workload running in a +trusted execution environment (TEE) using krun (i.e., *crun* built with the +libkrun feature enabled and invoked as *krun*). Instead of the conventional +contents, the root filesystem of the image will contain an encrypted disk image +and configuration information for krun. + +The value for *options* is a comma-separated list of key=value pairs, supplying +configuration information which is needed for producing the additional data +which will be included in the container image. + +Recognized _keys_ are: + +*attestation_url*: The location of a key broker / attestation server. +If a value is specified, the new image's workload ID, along with the passphrase +used to encrypt the disk image, will be registered with the server, and the +server's location will be stored in the container image. +At run-time, krun is expected to contact the server to retrieve the passphrase +using the workload ID, which is also stored in the container image. +If no value is specified, a *passphrase* value *must* be specified. + +*cpus*: The number of virtual CPUs which the image expects to be run with at +run-time. If not specified, a default value will be supplied. + +*firmware_library*: The location of the libkrunfw-sev shared library. If not +specified, `buildah` checks for its presence in a number of hard-coded +locations. + +*memory*: The amount of memory which the image expects to be run with at +run-time, as a number of megabytes. If not specified, a default value will be +supplied. + +*passphrase*: The passphrase to use to encrypt the disk image which will be +included in the container image. +If no value is specified, but an *attestation_url* value is specified, a +randomly-generated passphrase will be used. +The authors recommend setting an *attestation_url* but not a *passphrase*. + +*slop*: Extra space to allocate for the disk image compared to the size of the +container image's contents, expressed either as a percentage (..%) or a size +value (bytes, or larger units if suffixes like KB or MB are present), or a sum +of two or more such specifications separated by "+". If not specified, +`buildah` guesses that 25% more space than the contents will be enough, but +this option is provided in case its guess is wrong. If the specified or +computed size is less than 10 megabytes, it will be increased to 10 megabytes. + +*type*: The type of trusted execution environment (TEE) which the image should +be marked for use with. Accepted values are "SEV" (AMD Secure Encrypted +Virtualization - Encrypted State) and "SNP" (AMD Secure Encrypted +Virtualization - Secure Nested Paging). If not specified, defaults to "SNP". + +*workload_id*: A workload identifier which will be recorded in the container +image, to be used at run-time for retrieving the passphrase which was used to +encrypt the disk image. If not specified, a semi-random value will be derived +from the base image's image ID. + **--disable-compression**, **-D** Don't compress filesystem layers when building the image unless it is required diff --git a/docs/buildah-mkcw.1.md b/docs/buildah-mkcw.1.md new file mode 100644 index 00000000000..2733327451c --- /dev/null +++ b/docs/buildah-mkcw.1.md @@ -0,0 +1,78 @@ +# buildah-mkcw "1" "July 2023" "buildah" + +## NAME +buildah\-mkcw - Convert a conventional container image into a confidential workload image. + +## SYNOPSIS +**buildah mkcw** [*options*] *source* *destination* + +## DESCRIPTION +Converts the contents of a container image into a new container image which is +suitable for use in a trusted execution environment (TEE), typically run using +krun (i.e., crun built with the libkrun feature enabled and invoked as *krun*). +Instead of the conventional contents, the root filesystem of the created image +will contain an encrypted disk image and configuration information for krun. + +## source +A container image, stored locally or in a registry + +## destination +A container image, stored locally or in a registry + +## OPTIONS + +**--attestation-url**, **-u** *url* +The location of a key broker / attestation server. +If a value is specified, the new image's workload ID, along with the passphrase +used to encrypt the disk image, will be registered with the server, and the +server's location will be stored in the container image. +At run-time, krun is expected to contact the server to retrieve the passphrase +using the workload ID, which is also stored in the container image. +If no value is specified, a *passphrase* value *must* be specified. + +**--base-image**, **-b** *image* +An alternate image to use as the base for the output image. By default, +the *scratch* non-image is used. + +**--cpus**, **-c** *number* +The number of virtual CPUs which the image expects to be run with at run-time. +If not specified, a default value will be supplied. + +**--firmware-library**, **-f** *file* +The location of the libkrunfw-sev shared library. If not specified, `buildah` +checks for its presence in a number of hard-coded locations. + +**--memory**, **-m** *number* +The amount of memory which the image expects to be run with at run-time, as a +number of megabytes. If not specified, a default value will be supplied. + +**--passphrase**, **-p** *text* +The passphrase to use to encrypt the disk image which will be included in the +container image. +If no value is specified, but an *--attestation-url* value is specified, a +randomly-generated passphrase will be used. +The authors recommend setting an *--attestation-url* but not a *--passphrase*. + +**--slop**, **-s** *{percentage%|sizeKB|sizeMB|sizeGB}* +Extra space to allocate for the disk image compared to the size of the +container image's contents, expressed either as a percentage (..%) or a size +value (bytes, or larger units if suffixes like KB or MB are present), or a sum +of two or more such specifications. If not specified, `buildah` guesses that +25% more space than the contents will be enough, but this option is provided in +case its guess is wrong. If the specified or computed size is less than 10 +megabytes, it will be increased to 10 megabytes. + +**--type**, **-t** {SEV|SNP} +The type of trusted execution environment (TEE) which the image should be +marked for use with. Accepted values are "SEV" (AMD Secure Encrypted +Virtualization - Encrypted State) and "SNP" (AMD Secure Encrypted +Virtualization - Secure Nested Paging). If not specified, defaults to "SNP". + +**--workload-id**, **-w** *id* +A workload identifier which will be recorded in the container image, to be used +at run-time for retrieving the passphrase which was used to encrypt the disk +image. If not specified, a semi-random value will be derived from the base +image's image ID. + +## SEE ALSO +buildah(1) diff --git a/docs/buildah.1.md b/docs/buildah.1.md index 3ca62b7c14e..1f8bbc5f14e 100644 --- a/docs/buildah.1.md +++ b/docs/buildah.1.md @@ -158,6 +158,7 @@ Buildah can set up environment variables from the env entry in the [engine] tabl | login | [buildah-login(1)](buildah-login.1.md) | Login to a container registry. | | logout | [buildah-logout(1)](buildah-logout.1.md) | Logout of a container registry | | manifest | [buildah-manifest(1)](buildah-manifest.1.md) | Create and manipulate manifest lists and image indexes. | +| mkcw | [buildah-mkcw(1)](buildah-mkcw.1.md) | Convert a conventional container image into a confidential workload image. | mount | [buildah-mount(1)](buildah-mount.1.md) | Mount the working container's root filesystem. | | prune | [buildah-prune(1)](buildah-prune.1.md) | Cleanup intermediate images as well as build and mount cache. | | pull | [buildah-pull(1)](buildah-pull.1.md) | Pull an image from the specified location. |