mirror of
https://github.com/kata-containers/kata-containers.git
synced 2025-08-27 03:59:01 +00:00
Merge pull request #10315 from BbolroC/update-ibm-se-doc
doc: Update how-to-run-kata-containers-with-SE-VMs.md
This commit is contained in:
commit
03cd02a006
@ -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]
|
||||
|
@ -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}"
|
||||
|
@ -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" ] ||
|
||||
|
Loading…
Reference in New Issue
Block a user