Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 63 additions & 3 deletions docs/usage/getting-started-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,23 @@ Kind can be used with `docker` or `podman`. Although, we set `podman` as default
export RUNTIME=docker
```

The `CONTAINER_CLI` env var will used for building and pushing. If you require a non-Podman engine for building and pushing images, you can override it with the `$CONTAINER_CLI` variable.
```console
export CONTAINER_CLI=docker
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Building should work fine on Podman -- did you find this to be necessary?

Copy link
Copy Markdown
Author

@SpaceFace02 SpaceFace02 May 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is a line in the guide saying:

Kind can be used with docker or podman. Although, we set podman as default, right now there are some networking issues, therefore, the suggested runtime to use is docker at the moment. The runtime can be configured with:

So I went ahead and set default of runtime and container_cli to docker.

If the aforementioned issue is resolved, I'll change it to podman/CRI agnostic.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah yes. CONTAINER_CLI is really just used for building and pushing, but this deserves clarification so let's maybe remove the paragraph but put this in its place:

If you require a non-Podman engine for building and pushing images, you can override it with the `$CONTAINER_CLI` variable.

Copy link
Copy Markdown
Author

@SpaceFace02 SpaceFace02 May 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

building and pushing can be either podman or docker, but for the runtime env variable? That has to be docker due to networking issues on podman?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Exactly, that's what the paragraph just above is about

```

In order to interact with the cluster, `kubectl` is required.
```console
dnf install -y kubectl
```

Our kind cluster configuration is available under the `kind` directory and it uses the script `scripts/create-cluster-kind.sh`. The cluster can be simply created by running:
Our kind cluster configuration is available under the `kind` directory and it uses the script `scripts/create-cluster-kind.sh`.
Make sure any previously installed cluster is deleted before attempting to install a new one:
```console
make cluster-down
```

The cluster can be simply created by running:
```console
make cluster-up
```
Expand Down Expand Up @@ -75,15 +86,27 @@ export TRUSTEE_ADDR=kbs-service.trusted-execution-clusters.svc.cluster.local
export AK_REGISTRATION_ADDR=attestation-key-register.trusted-execution-clusters.svc.cluster.local

```
This example works with KubeVirt when the KBS is reachable using the pod networking.
This example works with KubeVirt when the KBS is reachable using the pod networking.

Refer to the one-shot deploy shell script at the end of this guide for attesting a Kubevirt VM with plain vTPM based attestation, i.e (i.e. no real trusted execution environment).
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would remove the script from the guide and therefore this sentence


Finally, the operator can be installed with:
```console
make install
```

Wait for cluster to be ready:
```console
sleep 10m
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we really need to put a sleep in the doc?

```

Print cluster status
```console
kubectl -n trusted-execution-clusters get po,svc
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something we could add is a Ready Condition in the TEC CR and wait for it. @Jakob-Naucke WDYT?

```

Further customization of the project can be controlled with the following env variables:
+ NAMESPACE: sets the namespace where the operator will be deplyoed
+ NAMESPACE: sets the namespace where the operator will be deployed
+ PLATFORM: use during the installation to configure the platform where the operator will be deployed (`kind` or `openshift`)
+ INTEGRATION_TEST_THREADS: how many integration tests are run in parallel
+ REGISTRY: the registry used to publish the images
Expand Down Expand Up @@ -132,3 +155,40 @@ kubectl logs -n trusted-execution-clusters <trustee-deplyoment>
```

In the logs, trustee prints the content of the TPM PCR registers. They need to match with the reference values present in the configmap `trustee-data` under `reference-values.json`.

## One-shot deploy script: Installs KubeVirt, attests an example KubeVirt VM with plain TPM attestation (i.e. no real trusted execution environment)

Comment thread
SpaceFace02 marked this conversation as resolved.
```bash
#! /bin/bash
set -euo pipefail
set -v

# kind exports
export CONTAINER_CLI=docker
Comment thread
SpaceFace02 marked this conversation as resolved.
export RUNTIME=docker

# operator exports
export AK_REGISTRATION_ADDR=attestation-key-register.trusted-execution-clusters.svc.cluster.local
export TRUSTEE_ADDR=kbs-service.trusted-execution-clusters.svc.cluster.local
export REGISTRY=localhost:5000/trusted-cluster-operator

# clean and create new cluster
make cluster-down
make cluster-up
make install-kubevirt
Comment on lines +182 to +184
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what I don't quite like of this script is that it always tears down the cluster while the cluster installation is necessary only once. You can run multiple times make install if you make some changes. I would simply discard this script


# install operator
make push
make manifests
make install

# print cluster status
kubectl -n trusted-execution-clusters get po,svc

# wait for cluster to be ready
sleep 10m

# create Vm
examples/create-ignition-secret.sh examples/ignition-coreos.json coreos-ignition-secret
kubectl apply -f examples/vm-coreos-ign.yaml
```
2 changes: 2 additions & 0 deletions tests/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ Upon a successful test, the namespace is cleaned up, otherwise it is kept for in
The tests use [`virtctl`](https://kubevirt.io/user-guide/user_workloads/virtctl_client_tool/) in order to interact with
VM, like getting the serial console and verifying that the guest has correctly booted by ssh-ing into it.

Other dependencies: *openssl-devel, gcc-c++*

N.B KubeVirt requires the cluster to be run as a privileged container on the host in order to handle the devices. Therefore, for now, we have moved to Docker with kind in order to generate the cluster. In the future, we might be able to move to rootful podman.

Run the tests locally with kind:
Expand Down