github/kata-containers
1
0
Fork 1
mirror of https://github.com/kata-containers/kata-containers.git synced 2025-08-31 16:36:38 +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
parent fc5a631791 8d609e47fb
commit 03cd02a006
3 changed files with 53 additions and 38 deletions
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
$ cd $GOPATH/src/github.com/kata-containers/kata-containers
$ sudo -E PATH=$PATH make kernel-confidential-tarball
$ sudo -E PATH=$PATH make rootfs-initrd-confidential-tarball
$ make rootfs-initrd-confidential-tarball
$ 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-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
./opt/kata/share/kata-containers/kata-containers-initrd-confidential.img
./opt/kata/share/kata-containers/kata-ubuntu-20.04-confidential.initrd
$ 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
$ 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
@@ -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
$ tool_version=v2.25.0
$ tool_version=v2.34.0
$ git clone -b $tool_version https://github.com/ibm-s390-linux/s390-tools.git
$ pushd s390-tools/genprotimg && make && sudo make install && popd
$ 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
subsequently decrypted using a corresponding private key during the VM bootstrap process.
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.
To ensure security, it is essential to verify the authenticity and integrity of the host key document
belonging to an authentic IBM machine. To achieve this, please additionally obtain the following
certificates from the Resource Link:
To ensure security, it is essential to verify the authenticity and integrity of the host
key document belonging to an authentic IBM machine. To achieve this, please additionally
obtain the following files from the Resource Link:
- IBM Z signing key certificate
- IBM Z host key certificate revocation list
- `DigiCert` intermediate CA certificate
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`
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`
- 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:
@@ -154,7 +156,7 @@ you can construct a secure image using the following procedure:
$ # Change a directory to the project root
$ cd $GOPATH/src/github.com/kata-containers/kata-containers
$ 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
$ echo "panic=1 scsi_mod.scan=none swiotlb=262144 agent.log=debug" > parmfile
$ genprotimg --host-key-document=${host_key_document} \
@@ -173,11 +175,12 @@ In production, the image construction should incorporate the verification
in the following manner:
```
$ signcert=$HOME/certificates/ibm-z-host-key-signing-gen2.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} \
--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,
@@ -186,20 +189,20 @@ can be easily accomplished by issuing the following make target:
```
$ cd $GOPATH/src/github.com/kata-containers/kata-containers
$ mkdir hkd_dir && cp $host_key_document hkd_dir
$ sudo -E PATH=$PATH HKD_PATH=hkd_dir SE_KERNEL_PARAMS="agent.log=debug" \
make boot-image-se-tarball
$ HKD_PATH=hkd_dir SE_KERNEL_PARAMS="agent.log=debug" make boot-image-se-tarball
$ ls 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.
In production, you could build an image by running the same command, but with two
additional environment variables for key verification:
In production, you could build an image by running the same command, but with the
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 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`:
@@ -213,8 +216,9 @@ CROSS_BUILD=true TARGET_ARCH=s390x ARCH=s390x
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')
$ 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
$ diff ${runtime_config_path}.old ${runtime_config_path}
16,17c16,17
@@ -258,6 +262,13 @@ $ sudo $hypervisor_command -machine confidential-guest-support=pv0 \
$ # 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
has been successfully loaded, and a Virtual Machine (VM) initiated by the kata runtime
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
(i.e., `kata-deploy`) for confidential containers. For the remaining instructions,
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.
@@ -327,12 +338,10 @@ $ cd $GOPATH/src/github.com/kata-containers/kata-containers
$ host_key_document=$HOME/host-key-document/HKD-0000-0000000.crt
$ mkdir hkd_dir && cp $host_key_document hkd_dir
$ # 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" \
make boot-image-se-tarball
$ sudo -E PATH=$PATH make qemu-tarball
$ sudo -E PATH=$PATH make virtiofsd-tarball
$ # shim-v2 should be built after kernel due to dependency
$ sudo -E PATH=$PATH make shim-v2-tarball
$ HKD_PATH=hkd_dir SE_KERNEL_PARAMS="agent.log=debug" make boot-image-se-tarball
$ make qemu-tarball
$ make virtiofsd-tarball
$ make shim-v2-tarball
$ mkdir kata-artifacts
$ build_dir=$(readlink -f build)
$ cp -r $build_dir/*.tar.xz kata-artifacts
@@ -340,6 +349,7 @@ $ ls -1 kata-artifacts
kata-static-agent.tar.xz
kata-static-boot-image-se.tar.xz
kata-static-coco-guest-components.tar.xz
kata-static-kernel-confidential-modules.tar.xz
kata-static-kernel-confidential.tar.xz
kata-static-pause-image.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
```
In production, the environment variables `SIGNING_KEY_CERT_PATH` and
`INTERMEDIATE_CA_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`)
without the Secure Execution functionality, please run the following command
before running `kata-deploy-merge-builds.sh`:
In production, the environment variables `SIGNING_KEY_CERT_PATH`, `INTERMEDIATE_CA_CERT_PATH`
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`) without the Secure Execution functionality, please run the following
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,
@@ -371,7 +381,7 @@ Build and push a payload image with the name `localhost:5000/build-kata-deploy`
`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 ...
Pushing the image localhost:5000/build-kata-deploy:latest to the registry
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.
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
HOST_KEY_CRL_PATH: a path for the host key CRL
DEBUG : If set, display debug information.
EOF
exit "${1:-0}"

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

@@ -27,12 +27,16 @@ build_secure_image() {
install_dest_dir="${3:-}"
key_verify_option="--no-verify" # no verification for CI testing purposes
if [ -n "${SIGNING_KEY_CERT_PATH:-}" ] && [ -n "${INTERMEDIATE_CA_CERT_PATH:-}" ]; then
if [ -e "${SIGNING_KEY_CERT_PATH}" ] && [ -e "${INTERMEDIATE_CA_CERT_PATH}" ]; then
key_verify_option="--cert=${SIGNING_KEY_CERT_PATH} --cert=${INTERMEDIATE_CA_CERT_PATH}"
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}" ] && [ -e "${HOST_KEY_CRL_PATH}" ]; then
key_verify_option="--cert=${SIGNING_KEY_CERT_PATH} --cert=${INTERMEDIATE_CA_CERT_PATH} --crl=${HOST_KEY_CRL_PATH}"
else
die "Specified certificate(s) not found"
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
if [ ! -f "${install_src_dir}/vmlinuz-confidential.container" ] ||