Add some docs for build --cw, commit --cw, and mkcw

Add docs for the new --cw option recognized by both `commit` and `build`, and the new `mkcw` command. Signed-off-by: Nalin Dahyabhai <[email protected]>
containers · Sep 7, 2023 · 4f3abf9 · 4f3abf9
1 parent e89fac6
commit 4f3abf9
Show file tree

Hide file tree

Showing 4 changed files with 192 additions and 0 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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.                                                           |