github/kata-containers
1
0
Fork 1
mirror of https://github.com/kata-containers/kata-containers.git synced 2025-08-27 12:08:58 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #10315 from BbolroC/update-ibm-se-doc

Browse Source 
doc: Update how-to-run-kata-containers-with-SE-VMs.md
This commit is contained in:
Hyounggyu Choi 2024-09-16 15:12:18 +02:00 committed by GitHub
commit 03cd02a006
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 53 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
docs/how-to/how-to-run-kata-containers-with-SE-VMs.md
View File

@ -88,19 +88,19 @@ However, if any of these components are absent, they must be built from the
``` ```
$ # Assume that the project is cloned at $GOPATH/src/github.com/kata-containers $ # Assume that the project is cloned at $GOPATH/src/github.com/kata-containers
$ cd $GOPATH/src/github.com/kata-containers/kata-containers $ cd $GOPATH/src/github.com/kata-containers/kata-containers
$ sudo -E PATH=$PATH make kernel-confidential-tarball $ make rootfs-initrd-confidential-tarball
$ sudo -E PATH=$PATH make rootfs-initrd-confidential-tarball
$ tar -tf build/kata-static-kernel-confidential.tar.xz | grep vmlinuz $ tar -tf build/kata-static-kernel-confidential.tar.xz | grep vmlinuz
./opt/kata/share/kata-containers/vmlinuz-confidential.container ./opt/kata/share/kata-containers/vmlinuz-confidential.container
./opt/kata/share/kata-containers/vmlinuz-6.1.62-121-confidential ./opt/kata/share/kata-containers/vmlinuz-6.7-136-confidential
$ kernel_version=6.7-136
$ tar -tf build/kata-static-rootfs-initrd-confidential.tar.xz | grep initrd $ tar -tf build/kata-static-rootfs-initrd-confidential.tar.xz | grep initrd
./opt/kata/share/kata-containers/kata-containers-initrd-confidential.img ./opt/kata/share/kata-containers/kata-containers-initrd-confidential.img
./opt/kata/share/kata-containers/kata-ubuntu-20.04-confidential.initrd ./opt/kata/share/kata-containers/kata-ubuntu-20.04-confidential.initrd
$ mkdir artifacts $ mkdir artifacts
$ tar -xvf build/kata-static-kernel-confidential.tar.xz -C artifacts ./opt/kata/share/kata-containers/vmlinuz-6.1.62-121-confidential $ tar -xvf build/kata-static-kernel-confidential.tar.xz -C artifacts ./opt/kata/share/kata-containers/vmlinuz-${kernel_version}-confidential
$ tar -xvf build/kata-static-rootfs-initrd-confidential.tar.xz -C artifacts ./opt/kata/share/kata-containers/kata-ubuntu-20.04-confidential.initrd $ tar -xvf build/kata-static-rootfs-initrd-confidential.tar.xz -C artifacts ./opt/kata/share/kata-containers/kata-ubuntu-20.04-confidential.initrd
$ ls artifacts/opt/kata/share/kata-containers/ $ ls artifacts/opt/kata/share/kata-containers/
kata-ubuntu-20.04-confidential.initrd vmlinuz-6.1.62-121-confidential kata-ubuntu-20.04-confidential.initrd vmlinuz-${kernel_version}-confidential
``` ```
3. Secure Image Generation Tool 3. Secure Image Generation Tool
@ -114,7 +114,7 @@ Here is an example of a native build from the source:
``` ```
$ sudo apt-get install gcc libglib2.0-dev libssl-dev libcurl4-openssl-dev $ sudo apt-get install gcc libglib2.0-dev libssl-dev libcurl4-openssl-dev
$ tool_version=v2.25.0 $ tool_version=v2.34.0
$ git clone -b $tool_version https://github.com/ibm-s390-linux/s390-tools.git $ git clone -b $tool_version https://github.com/ibm-s390-linux/s390-tools.git
$ pushd s390-tools/genprotimg && make && sudo make install && popd $ pushd s390-tools/genprotimg && make && sudo make install && popd
$ rm -rf s390-tools $ rm -rf s390-tools
@ -125,14 +125,15 @@ $ rm -rf s390-tools
A host key document is a public key employed for encrypting a secure image, which is A host key document is a public key employed for encrypting a secure image, which is
subsequently decrypted using a corresponding private key during the VM bootstrap process. subsequently decrypted using a corresponding private key during the VM bootstrap process.
You can obtain the host key document either through IBM's designated You can obtain the host key document either through IBM's designated
[Resource Link](http://www.ibm.com/servers/resourcelink) or by requesting it from the [Resource Link](http://www.ibm.com/servers/resourcelink)(you need to log in to access it) or by requesting it from the
cloud provider responsible for the IBM Z and LinuxONE instances where your workloads are intended to run. cloud provider responsible for the IBM Z and LinuxONE instances where your workloads are intended to run.
To ensure security, it is essential to verify the authenticity and integrity of the host key document To ensure security, it is essential to verify the authenticity and integrity of the host
belonging to an authentic IBM machine. To achieve this, please additionally obtain the following key document belonging to an authentic IBM machine. To achieve this, please additionally
certificates from the Resource Link: obtain the following files from the Resource Link:
- IBM Z signing key certificate - IBM Z signing key certificate
- IBM Z host key certificate revocation list
- `DigiCert` intermediate CA certificate - `DigiCert` intermediate CA certificate
These files will be used for verification during secure image construction in the next section. These files will be used for verification during secure image construction in the next section.
@ -143,10 +144,11 @@ Assuming you have placed a host key document at `$HOME/host-key-document`:
- Host key document as `HKD-0000-0000000.crt` - Host key document as `HKD-0000-0000000.crt`
and two certificates at `$HOME/certificates`: and two certificates and one revocation list at `$HOME/certificates`:
- IBM Z signing-key certificate as `ibm-z-host-key-signing-gen2.crt`
- `DigiCert` intermediate CA certificate as `DigiCertCA.crt` - `DigiCert` intermediate CA certificate as `DigiCertCA.crt`
- IBM Z signing-key certificate as `ibm-z-host-key-signing.crt` - IBM Z host key certificate revocation list as `ibm-z-host-key-gen2.crl`
you can construct a secure image using the following procedure: you can construct a secure image using the following procedure:
@ -154,7 +156,7 @@ you can construct a secure image using the following procedure:
$ # Change a directory to the project root $ # Change a directory to the project root
$ cd $GOPATH/src/github.com/kata-containers/kata-containers $ cd $GOPATH/src/github.com/kata-containers/kata-containers
$ host_key_document=$HOME/host-key-document/HKD-0000-0000000.crt $ host_key_document=$HOME/host-key-document/HKD-0000-0000000.crt
$ kernel_image=artifacts/opt/kata/share/kata-containers/vmlinuz-6.1.62-121-confidential $ kernel_image=artifacts/opt/kata/share/kata-containers/vmlinuz-${kernel_version}-confidential
$ initrd_image=artifacts/opt/kata/share/kata-containers/kata-ubuntu-20.04-confidential.initrd $ initrd_image=artifacts/opt/kata/share/kata-containers/kata-ubuntu-20.04-confidential.initrd
$ echo "panic=1 scsi_mod.scan=none swiotlb=262144 agent.log=debug" > parmfile $ echo "panic=1 scsi_mod.scan=none swiotlb=262144 agent.log=debug" > parmfile
$ genprotimg --host-key-document=${host_key_document} \ $ genprotimg --host-key-document=${host_key_document} \
@ -173,11 +175,12 @@ In production, the image construction should incorporate the verification
in the following manner: in the following manner:
``` ```
$ signcert=$HOME/certificates/ibm-z-host-key-signing-gen2.crt
$ cacert=$HOME/certificates/DigiCertCA.crt $ cacert=$HOME/certificates/DigiCertCA.crt
$ signcert=$HOME/certificates/ibm-z-host-key-signing.crt $ crl=$HOME/certificates/ibm-z-host-key-gen2.crl
$ genprotimg --host-key-document=${host_key_document} \ $ genprotimg --host-key-document=${host_key_document} \
--output=kata-containers-se.img --image=${kernel_image} --ramdisk=${initrd_image} \ --output=kata-containers-se.img --image=${kernel_image} --ramdisk=${initrd_image} \
--cert=${cacert} --cert=${signcert} --parmfile=parmfile --cert=${cacert} --cert=${signcert} --crl=${crl} --parmfile=parmfile
``` ```
The steps with no verification, including the dependencies for the kernel and initrd, The steps with no verification, including the dependencies for the kernel and initrd,
@ -186,20 +189,20 @@ can be easily accomplished by issuing the following make target:
``` ```
$ cd $GOPATH/src/github.com/kata-containers/kata-containers $ cd $GOPATH/src/github.com/kata-containers/kata-containers
$ mkdir hkd_dir && cp $host_key_document hkd_dir $ mkdir hkd_dir && cp $host_key_document hkd_dir
$ sudo -E PATH=$PATH HKD_PATH=hkd_dir SE_KERNEL_PARAMS="agent.log=debug" \ $ HKD_PATH=hkd_dir SE_KERNEL_PARAMS="agent.log=debug" make boot-image-se-tarball
make boot-image-se-tarball
$ ls build/kata-static-boot-image-se.tar.xz $ ls build/kata-static-boot-image-se.tar.xz
build/kata-static-boot-image-se.tar.xz build/kata-static-boot-image-se.tar.xz
``` ```
`SE_KERNEL_PARAMS` could be used to add any extra kernel parameters. If no additional kernel configuration is required, this can be omitted. `SE_KERNEL_PARAMS` could be used to add any extra kernel parameters. If no additional kernel configuration is required, this can be omitted.
In production, you could build an image by running the same command, but with two In production, you could build an image by running the same command, but with the
additional environment variables for key verification: following environment variables for key verification:
``` ```
$ export SIGNING_KEY_CERT_PATH=$HOME/certificates/ibm-z-host-key-signing.crt $ export SIGNING_KEY_CERT_PATH=$HOME/certificates/ibm-z-host-key-signing-gen2.crt
$ export INTERMEDIATE_CA_CERT_PATH=$HOME/certificates/DigiCertCA.crt $ export INTERMEDIATE_CA_CERT_PATH=$HOME/certificates/DigiCertCA.crt
$ export HOST_KEY_CRL_PATH=$HOME/certificates/ibm-z-host-key-gen2.crl
``` ```
To build an image on the `x86_64` platform, set the following environment variables together with the variables above before `make boot-image-se-tarball`: To build an image on the `x86_64` platform, set the following environment variables together with the variables above before `make boot-image-se-tarball`:
@ -213,8 +216,9 @@ CROSS_BUILD=true TARGET_ARCH=s390x ARCH=s390x
There still remains an opportunity to fine-tune the configuration file: There still remains an opportunity to fine-tune the configuration file:
``` ```
$ export PATH=$PATH:/opt/kata/bin
$ runtime_config_path=$(kata-runtime kata-env --json | jq -r '.Runtime.Config.Path') $ runtime_config_path=$(kata-runtime kata-env --json | jq -r '.Runtime.Config.Path')
$ cp ${runtime_config_path} ${runtime_config_path}.old $ sudo cp ${runtime_config_path} ${runtime_config_path}.old
$ # Make the following adjustment to the original config file $ # Make the following adjustment to the original config file
$ diff ${runtime_config_path}.old ${runtime_config_path} $ diff ${runtime_config_path}.old ${runtime_config_path}
16,17c16,17 16,17c16,17
@ -258,6 +262,13 @@ $ sudo $hypervisor_command -machine confidential-guest-support=pv0 \
$ # Press ctrl + a + x to exit $ # Press ctrl + a + x to exit
``` ```
Unless the host key document is legitimate, you will encounter the following error message:
```
qemu-system-s390x: KVM PV command 2 (KVM_PV_SET_SEC_PARMS) failed: header rc 108 rrc 5 IOCTL rc: -22
Protected boot has failed: 0xa02
```
If the hypervisor log does not indicate any errors, it provides assurance that the image If the hypervisor log does not indicate any errors, it provides assurance that the image
has been successfully loaded, and a Virtual Machine (VM) initiated by the kata runtime has been successfully loaded, and a Virtual Machine (VM) initiated by the kata runtime
will function properly. will function properly.
@ -318,7 +329,7 @@ binary artifacts such as kernel, shim-v2, and more.
This section will explain how to build a payload image This section will explain how to build a payload image
(i.e., `kata-deploy`) for confidential containers. For the remaining instructions, (i.e., `kata-deploy`) for confidential containers. For the remaining instructions,
please refer to the please refer to the
[documentation](https://github.com/confidential-containers/operator/blob/main/docs/how-to/INSTALL-CC-WITH-IBM-SE.md) [documentation](https://github.com/confidential-containers/confidential-containers/blob/main/guides/ibm-se.md)
for confidential containers. for confidential containers.
@ -327,12 +338,10 @@ $ cd $GOPATH/src/github.com/kata-containers/kata-containers
$ host_key_document=$HOME/host-key-document/HKD-0000-0000000.crt $ host_key_document=$HOME/host-key-document/HKD-0000-0000000.crt
$ mkdir hkd_dir && cp $host_key_document hkd_dir $ mkdir hkd_dir && cp $host_key_document hkd_dir
$ # kernel-confidential and rootfs-initrd-confidential are built automactially by the command below $ # kernel-confidential and rootfs-initrd-confidential are built automactially by the command below
$ sudo -E PATH=$PATH HKD_PATH=hkd_dir SE_KERNEL_PARAMS="agent.log=debug" \ $ HKD_PATH=hkd_dir SE_KERNEL_PARAMS="agent.log=debug" make boot-image-se-tarball
make boot-image-se-tarball $ make qemu-tarball
$ sudo -E PATH=$PATH make qemu-tarball $ make virtiofsd-tarball
$ sudo -E PATH=$PATH make virtiofsd-tarball $ make shim-v2-tarball
$ # shim-v2 should be built after kernel due to dependency
$ sudo -E PATH=$PATH make shim-v2-tarball
$ mkdir kata-artifacts $ mkdir kata-artifacts
$ build_dir=$(readlink -f build) $ build_dir=$(readlink -f build)
$ cp -r $build_dir/*.tar.xz kata-artifacts $ cp -r $build_dir/*.tar.xz kata-artifacts
@ -340,6 +349,7 @@ $ ls -1 kata-artifacts
kata-static-agent.tar.xz kata-static-agent.tar.xz
kata-static-boot-image-se.tar.xz kata-static-boot-image-se.tar.xz
kata-static-coco-guest-components.tar.xz kata-static-coco-guest-components.tar.xz
kata-static-kernel-confidential-modules.tar.xz
kata-static-kernel-confidential.tar.xz kata-static-kernel-confidential.tar.xz
kata-static-pause-image.tar.xz kata-static-pause-image.tar.xz
kata-static-qemu.tar.xz kata-static-qemu.tar.xz
@ -349,14 +359,14 @@ kata-static-virtiofsd.tar.xz
$ ./tools/packaging/kata-deploy/local-build/kata-deploy-merge-builds.sh kata-artifacts $ ./tools/packaging/kata-deploy/local-build/kata-deploy-merge-builds.sh kata-artifacts
``` ```
In production, the environment variables `SIGNING_KEY_CERT_PATH` and In production, the environment variables `SIGNING_KEY_CERT_PATH`, `INTERMEDIATE_CA_CERT_PATH`
`INTERMEDIATE_CA_CERT_PATH` should be exported like the manual configuration. and `SIGNING_KEY_CERT_PATH` should be exported like the manual configuration.
If a rootfs-image is required for other available runtime classes (e.g. `kata` and `kata-qemu`) If a rootfs-image is required for other available runtime classes (e.g. `kata` and
without the Secure Execution functionality, please run the following command `kata-qemu`) without the Secure Execution functionality, please run the following
before running `kata-deploy-merge-builds.sh`: command before running `kata-deploy-merge-builds.sh`:
``` ```
$ sudo -E PATH=$PATH make rootfs-image-tarball $ make rootfs-image-tarball
``` ```
At this point, you should have an archive file named `kata-static.tar.xz` at the project root, At this point, you should have an archive file named `kata-static.tar.xz` at the project root,
@ -371,7 +381,7 @@ Build and push a payload image with the name `localhost:5000/build-kata-deploy`
`latest` using the following: `latest` using the following:
``` ```
$ sudo -E PATH=$PATH ./tools/packaging/kata-deploy/local-build/kata-deploy-build-and-upload-payload.sh kata-static.tar.xz localhost:5000/build-kata-deploy latest $ ./tools/packaging/kata-deploy/local-build/kata-deploy-build-and-upload-payload.sh kata-static.tar.xz localhost:5000/build-kata-deploy latest
... logs ... ... logs ...
Pushing the image localhost:5000/build-kata-deploy:latest to the registry Pushing the image localhost:5000/build-kata-deploy:latest to the registry
The push refers to repository [localhost:5000/build-kata-deploy] The push refers to repository [localhost:5000/build-kata-deploy]

1
tools/packaging/guest-image/build_se_image.sh
View File

@ -37,6 +37,7 @@ Environment variables:
for information on how to retrieve and verify this document. for information on how to retrieve and verify this document.
SIGNING_KEY_CERT_PATH: a path for the IBM zSystem signing key certificate SIGNING_KEY_CERT_PATH: a path for the IBM zSystem signing key certificate
INTERMEDIATE_CA_CERT_PATH: a path for the intermediate CA certificate signed by the root CA INTERMEDIATE_CA_CERT_PATH: a path for the intermediate CA certificate signed by the root CA
HOST_KEY_CRL_PATH: a path for the host key CRL
DEBUG : If set, display debug information. DEBUG : If set, display debug information.
EOF EOF
exit "${1:-0}" exit "${1:-0}"

10
tools/packaging/guest-image/lib_se.sh
View File

@ -27,12 +27,16 @@ build_secure_image() {
install_dest_dir="${3:-}" install_dest_dir="${3:-}"
key_verify_option="--no-verify" # no verification for CI testing purposes key_verify_option="--no-verify" # no verification for CI testing purposes
if [ -n "${SIGNING_KEY_CERT_PATH:-}" ] && [ -n "${INTERMEDIATE_CA_CERT_PATH:-}" ]; then if [ -n "${SIGNING_KEY_CERT_PATH:-}" ] && [ -n "${INTERMEDIATE_CA_CERT_PATH:-}" ] && [ -n "${HOST_KEY_CRL_PATH:-}" ]; then
if [ -e "${SIGNING_KEY_CERT_PATH}" ] && [ -e "${INTERMEDIATE_CA_CERT_PATH}" ]; then if [ -e "${SIGNING_KEY_CERT_PATH}" ] && [ -e "${INTERMEDIATE_CA_CERT_PATH}" ] && [ -e "${HOST_KEY_CRL_PATH}" ]; then
key_verify_option="--cert=${SIGNING_KEY_CERT_PATH} --cert=${INTERMEDIATE_CA_CERT_PATH}" key_verify_option="--cert=${SIGNING_KEY_CERT_PATH} --cert=${INTERMEDIATE_CA_CERT_PATH} --crl=${HOST_KEY_CRL_PATH}"
else else
die "Specified certificate(s) not found" die "Specified certificate(s) not found"
fi fi
elif [ -n "${SIGNING_KEY_CERT_PATH}" ] || [ -n "${INTERMEDIATE_CA_CERT_PATH}" ] || [ -n "${HOST_KEY_CRL_PATH}" ]; then
die "All of SIGNING_KEY_CERT_PATH, INTERMEDIATE_CA_CERT_PATH, and HOST_KEY_CRL_PATH must be specified"
else
echo "No certificate specified. Using --no-verify option"
fi fi
if [ ! -f "${install_src_dir}/vmlinuz-confidential.container" ] || if [ ! -f "${install_src_dir}/vmlinuz-confidential.container" ] ||