From 2105b02191e36485fa7decedf8238d0e3a7602cb Mon Sep 17 00:00:00 2001
From: Paul Meyer <49727155+katexochen@users.noreply.github.com>
Date: Tue, 19 Dec 2023 12:12:48 +0100
Subject: [PATCH] readme: describe coordinator and initializer

Signed-off-by: Paul Meyer <49727155+katexochen@users.noreply.github.com>
---
 README.md | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 255823e2ee..3e6f34493f 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,28 @@ Nunki ([/ˈnʌŋki/](https://en.wikipedia.org/wiki/Sigma_Sagittarii)) runs confi
 on untrusted Kubernetes at scale.
 
 Nunki is based on the [Kata Containers](https://github.com/kata-containers/kata-containers) and
-[Confidential Containers](https://github.com/confidential-containers) projects. Confidential Containers are Kubernetes pods that are executed inside a confidential micro-VM and provide strong hardware-based isolation
-from the surrounding environment.
+[Confidential Containers](https://github.com/confidential-containers) projects. Confidential Containers are
+Kubernetes pods that are executed inside a confidential micro-VM and provide strong hardware-based isolation
+from the surrounding environment. This works with unmodified containers in a lift-and-shift approach.
+
+## The Nunki Coordinator
+
+The Nunki Coordinator is the central remote attestation component of a Nunki deployment. It's a certificate
+authority and issues certificates for workload pods running inside confidential containers. The Coordinator
+is configured with a *manifest*, a configuration file that holds the reference values of all other parts of
+a deployment. The Coordinator ensures that your app's topology adheres to your specified manifest. It verifies
+the identity and integrity of all your services and establishes secure, encrypted communication channels between
+the different parts of your deployment. As your app needs to scale, the Coordinator transparently verifies new
+instances and then provides them with mesh credentials.
+
+To verify your deployment, the remote attestation of the Coordinator and its manifest offers a single remote
+attestation statement for your entire deployment. Anyone can use this to verify the integrity of your distributed
+app, making it easier to assure stakeholders of your app's security.
+
+## The Nunki Initializer
+
+Nunki provides an Initializer that handles the remote attestation on the workload side transparently and
+fetches the workload certificate. The Initializer runs as init container before your workload is started.
 
 ## Contributing