diff --git a/docs/versioned_docs/version-1.2/_media/cert-chain.svg b/docs/versioned_docs/version-1.2/_media/cert-chain.svg
new file mode 100644
index 00000000..3f9325d5
--- /dev/null
+++ b/docs/versioned_docs/version-1.2/_media/cert-chain.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/docs/versioned_docs/version-1.2/_media/enc-state-distributed.svg b/docs/versioned_docs/version-1.2/_media/enc-state-distributed.svg
new file mode 100644
index 00000000..646659e4
--- /dev/null
+++ b/docs/versioned_docs/version-1.2/_media/enc-state-distributed.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/docs/versioned_docs/version-1.2/_media/enc-state-single.svg b/docs/versioned_docs/version-1.2/_media/enc-state-single.svg
new file mode 100644
index 00000000..50df40aa
--- /dev/null
+++ b/docs/versioned_docs/version-1.2/_media/enc-state-single.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/docs/versioned_docs/version-1.2/_media/security_architecture.svg b/docs/versioned_docs/version-1.2/_media/security_architecture.svg
new file mode 100644
index 00000000..21970277
--- /dev/null
+++ b/docs/versioned_docs/version-1.2/_media/security_architecture.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/docs/versioned_docs/version-1.2/getting-started/concepts.md b/docs/versioned_docs/version-1.2/architecture/concepts.md
similarity index 100%
rename from docs/versioned_docs/version-1.2/getting-started/concepts.md
rename to docs/versioned_docs/version-1.2/architecture/concepts.md
diff --git a/docs/versioned_docs/version-1.2/getting-started/coordinator.md b/docs/versioned_docs/version-1.2/architecture/coordinator.md
similarity index 76%
rename from docs/versioned_docs/version-1.2/getting-started/coordinator.md
rename to docs/versioned_docs/version-1.2/architecture/coordinator.md
index cb4a7e5e..16a54f0d 100644
--- a/docs/versioned_docs/version-1.2/getting-started/coordinator.md
+++ b/docs/versioned_docs/version-1.2/architecture/coordinator.md
@@ -1,6 +1,14 @@
# Coordinator
The Coordinator is MarbleRun's control plane.
+Conceptually, it operates as trusted controller in your confidential deployment.
+It securely holds the deployment's state, including the [manifest](../features/manifest.md) and the defined [secrets](../features/secrets-management.md).
+Based on the manifest, the Coordinator uses [remote attestation](../features/attestation.md) to authenticate the application's enclaves.
+
+
+
+## API and Configuration
+
It communicates with the Marble's data plane through gRPC and provides an HTTP REST interface on the client-side.
The Coordinator can be configured with several environment variables:
diff --git a/docs/versioned_docs/version-1.2/architecture/marbles.md b/docs/versioned_docs/version-1.2/architecture/marbles.md
new file mode 100644
index 00000000..d34f04ec
--- /dev/null
+++ b/docs/versioned_docs/version-1.2/architecture/marbles.md
@@ -0,0 +1,6 @@
+# Marbles
+
+Marbles are MarbleRun's data planes and run your application code in secure enclaves.
+Marbles communicate with the Coordinator via gRPC over TLS.
+MarbleRun [supports multiple enclave runtimes](../features/runtimes.md) as the data plane.
+See the [Add a Service](../workflows/add-service.md) section on how to build and configure an enclave as Marble.
diff --git a/docs/versioned_docs/version-1.2/architecture/security.md b/docs/versioned_docs/version-1.2/architecture/security.md
new file mode 100644
index 00000000..214f6fa6
--- /dev/null
+++ b/docs/versioned_docs/version-1.2/architecture/security.md
@@ -0,0 +1,111 @@
+# Key management and cryptographic primitives
+
+MarbleRun protects and isolates your deployments and workloads. To that end, cryptography is the foundation that ensures the confidentiality and integrity of all components.
+Evaluating the security of MarbleRun requires a precise understanding of the cryptographic primitives and keys used.
+The following gives an overview of the architecture and explains the technical details.
+
+## High-level architecture
+
+The [Coordinator](coordinator.md) and the [Marbles](marbles.md) run inside SGX Enclaves. See [Intel's documentation](https://www.intel.com/content/www/us/en/developer/tools/software-guard-extensions/overview.html) on the architecture details and cryptographic primitives of SGX.
+
+MarbleRun uses cryptography for the following tasks.
+
+* Authentication and authorization
+* Establishment of a public key infrastructure (PKI) for MarbleRun
+* Encryption of network traffic via mutual TLS between enclaves
+* Encrypting persistent state
+
+The following diagram gives an overview of the architecture and the components.
+
+
+
+## Authentication and authorization
+
+MarbleRun uses the SGX [remote attestation](../features/attestation.md) capability to authenticate the Coordinator and the Marble enclaves.
+For authorization, the [manifest](../features/manifest.md) defines the Marble's access to secrets and keys after successful attestation.
+Furthermore, MarbleRun's [RBAC](../workflows/define-manifest.md#roles) attaches [users'](../workflows/define-manifest.md#users) identities to roles in the manifest.
+Each role is associated with a set of operations the user can perform in the deployment.
+Users are authenticated by the Coordinator using an RSA or ECDSA public key defined in the manifest.
+
+## Public key infrastructure and certificate authority
+
+The Coordinator establishes a public key infrastructure (PKI) for MarbleRun and acts as the certificate authority (CA).
+The goal of the PKI is to make authentication of confidential applications based on remote attestation accessible and usable.
+The Coordinator provides an [API](../reference/coordinator.md) for retrieving an SGX attestation statement that embeds its *Root CA Certificate* in the user-defined body.
+By verifying the statement, clients can verify the certificate's authenticity and, thereby, the MarbleRun CA.
+See the [attested TLS](#attested-tls-atls) section for details behind that concept.
+All MarbleRun clients and Marbles can then use the attested *Root CA Certificate* for authenticating TLS connections.
+This is further illustrated conceptually in the [attestation](../features/attestation.md) section. The following focuses on the cryptographic primitives.
+The Coordinator generates a root X.509 certificate and corresponding asymmetric key pair during initialization.
+The [Elliptic Curve Digital Signature Algorithm (ECDSA)](https://www.secg.org/sec1-v2.pdf#page=49) is used with curve [P256](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf#page=111).
+The *Root CA Certificate* has no expiry date and lives as long as the MarbleRun deployment.
+
+Alongside the *Root CA Certificate*, the Coordinator generates an X.509 *Intermediate Certificate* and corresponding asymmetric key pair, again using ECDSA with P256.
+The *Intermediate Certificate* is signed by the Coordinator's *Root CA Certificate* and rotated with every manifest update.
+When you push an update to the manifest (for example, bump up the *SecurityVersion* of a Marble), the *Intermediate Certificate* will change.
+Marble instances of the new version won't authenticate with instances of the old version and vice versa.
+Hence, no data flow is happening between different *SecurityVersions* of your application.
+However, the *Root CA Certificate* doesn't change. So you can still verify the Coordinator and your application from the outside and ensure it's the same instance you might have interacted with.
+Applications interacting with the MarbleRun deployment should use the intermediate certificate as CA to make manifest updates observable:
+If the manifest changes, connections to the deployment will fail.
+The application user can then review the changes and install the new intermediate certificate to approve them.
+If such observability isn't required, the application can use the root certificate as CA.
+In that case, the application will continue to work even if the manifest changes.
+
+The Coordinator creates a second certificate with the same key material as the *Intermediate Certificate* called the *Marble Root Certificate*.
+In that sense, they're siblings containing the same public key.
+However, while the *Intermediate Certificate* is signed by the *Root Certificate*, the *Marble Root Certificate* is self-signed using its private key.
+The goal here is to implement a [cross-signed certificate chain](https://www.ssltrust.com.au/blog/understanding-certificate-cross-signing).
+In that way, the Marbles see the *Marble Root Certificate* as a self-signed root certificate. Hence, they're dealing with a terminating certificate chain without knowing about the Coordinator's *Root CA Certificate*.
+The "outside world" sees an intermediate certificate signed by the Coordinator's *Root CA Certificate*.
+The Coordinator generates a unique leaf *Marble Certificate* and corresponding key pair using ECDSA with P256 for every Marble.
+The *Marble Root Certificate* signs the *Marble Certificate*.
+The *Marble Certificate* is provisioned to the Marble's enclave via the secure channel established during the [attestation procedure](../features/attestation.md).
+Depending on the Marble's runtime, the certificate can be used [manually](../workflows/add-service.md#make-your-service-use-the-provided-tls-credentials) or [automatically](../features/transparent-TLS.md) to establish mutually authenticated TLS connections.
+
+
+
+
+## Attested TLS (aTLS)
+
+In a confidential computing environment, attested TLS (aTLS) can establish secure connections between two parties using the remote attestation features of the confidential computing components.
+With aTLS, the party to be authenticated binds its TLS certificate to an attestation statement.
+For example, it embeds the certificate's public key into the attestation statement.
+Instead of relying on a certificate authority, aTLS uses this attestation statement to establish trust in the certificate.
+The protocol can be used by clients to verify a server certificate, by a server to verify a client certificate, or for mutual verification (mutual aTLS).
+
+
+## Encryption of state
+
+The Coordinator holds MarbleRun's state, which consists of the [manifest](../features/manifest.md), the [managed secrets](../features/secrets-management.md), and the [certificates for its CA](../features/attestation.md).
+The state is stored encrypted in persistent storage. For this, MarbleRun uses [AES128-GCM](https://www.rfc-editor.org/rfc/rfc5116#section-5.1) and a generated 16-byte data encryption key (DEK).
+The DEK is also sealed to persistent storage to recover the state in case of a restart autonomously.
+[SGX sealing](https://www.intel.com/content/www/us/en/developer/articles/technical/introduction-to-intel-sgx-sealing.html) is used for that purpose.
+The Coordinator encrypts the DEK with a key encryption key (KEK).
+MarbleRun uses the SGX sealing key called `Product key` as its KEK, which is bound to its `Product ID` and the enclave's author `MRSIGNER` identity.
+In other words, a fresh and benign enclave instance of the same identity can recover that key.
+Hence, if the Coordinator is restarted on the same CPU, it can obtain the same KEK from the CPU, decrypt the DEK, and recover its state.
+
+
+
+If the Coordinator is restarted on a different CPU, it won't be able to obtain the same SGX sealing key from the CPU.
+To address this, MarbleRun provides a [recovery feature](../features/recovery.md#recovery).
+The manifest allows for specifying a designated Recovery Key. The Recovery Key is a RSA public key. Upon startup, the Coordinator encrypts the DEK with this public key and returns it to the user.
+In case of a recovery event, the user decrypts the DEK locally and [uploads it to the Coordinator](../workflows/recover-coordinator.md).
+The Coordinator will decrypt the state with the DEK and proceed with operations.
+
+For [multi-party use cases](../features/recovery.md#multi-party-recovery), MarbleRun allows splitting the Recovery Key between parties.
+Every recovery party is defined in the manifest with its own public RSA key.
+The Coordinator generates a share of the recovery secret for every party and encrypts it with the corresponding RSA key.
+During a recovery event, every party will upload their share of the secret, which are all XORed together by the Coordinator to receive the combined key for decrypting the DEK.
+
+
+### Distributed Coordinator
+
+The [distributed Coordinator](../features/recovery.md#distributed-coordinator) works similarly. However, all Coordinators share the same state stored encrypted in the Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) called *marble-state*.
+In contrast to the single instance, the KEK is generated at start-up by the first instance.
+The existing Coordinators authenticate every new Coordinator instance via remote attestation, and the KEK is subsequently shared via the secure and attested TLS connection.
+Every Coordinator instance uses its own SGX Product (Sealing) Key to seal the KEK into a Kubernetes [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) structure called "KEK."
+
+
+
diff --git a/docs/versioned_docs/version-1.2/building-services/ego.md b/docs/versioned_docs/version-1.2/building-marbles/ego.md
similarity index 100%
rename from docs/versioned_docs/version-1.2/building-services/ego.md
rename to docs/versioned_docs/version-1.2/building-marbles/ego.md
diff --git a/docs/versioned_docs/version-1.2/building-services/gramine.md b/docs/versioned_docs/version-1.2/building-marbles/gramine.md
similarity index 100%
rename from docs/versioned_docs/version-1.2/building-services/gramine.md
rename to docs/versioned_docs/version-1.2/building-marbles/gramine.md
diff --git a/docs/versioned_docs/version-1.2/building-services/occlum.md b/docs/versioned_docs/version-1.2/building-marbles/occlum.md
similarity index 80%
rename from docs/versioned_docs/version-1.2/building-services/occlum.md
rename to docs/versioned_docs/version-1.2/building-marbles/occlum.md
index f0c3ec7d..d35bfe91 100644
--- a/docs/versioned_docs/version-1.2/building-services/occlum.md
+++ b/docs/versioned_docs/version-1.2/building-marbles/occlum.md
@@ -2,18 +2,18 @@
Running an Occlum app with MarbleRun requires some changes to its manifest.
## Requirements
-Set up an environment to create Occlum images. For an easy start, we recommend that you use either the official [Occlum Docker image](https://hub.docker.com/r/occlum/occlum) or use [our provided Dockerfile](https://github.com/edgelesssys/marblerun/blob/master/samples/occlum-hello/Dockerfile). For a working DCAP remote attestation environment, we recommend [our cloud deployment guide](../deployment/cloud.md).
+Set up an environment to create Occlum images. For an easy start, we recommend using either the official [Occlum Docker image](https://hub.docker.com/r/occlum/occlum) or [our provided Dockerfile](https://github.com/edgelesssys/marblerun/blob/master/samples/occlum-hello/Dockerfile). For a working DCAP remote attestation environment, we recommend [our platform deployment guide](../deployment/platforms/platforms.md).
-To build your service, you can start with [Occlum's Introduction](https://github.com/occlum/occlum#introduction) to get your application up and running, and then come back here to adapt it for use with MarbleRun.
+To build your service, you can start with [Occlum's Introduction](https://github.com/occlum/occlum#introduction) to get your application up and running and then come back here to adapt it for use with MarbleRun.
## Configuration
### Premain executable
-Add our pre-built [premain-libos](https://github.com/edgelesssys/marblerun/releases/latest/download/premain-libos) executable to your Occlum image, e.g., by copying it to `image/bin/premain-libos`. By default, Occlum restricts executable files to the `/bin` directory. If you placed the `premain-libos` binary to a different path, you need to adjust this setting accordingly.
+Add our pre-built [premain-libos](https://github.com/edgelesssys/marblerun/releases/latest/download/premain-libos) executable to your Occlum image, e.g., by copying it to `image/bin/premain-libos`. By default, Occlum restricts executable files to the `/bin` directory. If you placed the `premain-libos` binary at a different path, you must adjust this setting accordingly.
Finally, define the original entry point for your Occlum instance as the first `Argv` parameter for your Marble in MarbleRun's `manifest.json`. See [Defining a manifest](../workflows/define-manifest.md) for more information on how to define the `Argv` parameters. This lets MarbleRun launch your application after it succeeded in authenticating with the Coordinator and provides entrypoint pinning similar to the one offered in `Occlum.json`.
### Environment variables
-The Marble needs to retrieve the MarbleRun specific configuration parameters via environment variables, as [described under Step 3 in "Adding a service."](../workflows/add-service.md)
+The Marble needs to retrieve the MarbleRun-specific configuration parameters via environment variables, as [described under Step 3 in "Adding a service."](../workflows/add-service.md)
To pass environment variables to the enclave, Occlum requires them to be specified in the `env` section in `Occlum.json`.
@@ -41,9 +41,9 @@ For example, consider this configuration:
This will allow you to embed the expected default values during build time. It also lets the user/host system change them during run time when a non-default Coordinator configuration is used.
### Resource limits
-The premain process is written in Go. The enclave needs to have enough resources for the Go runtime, plus additional memory to launch your application.
+The premain process is written in Go. The enclave must have enough resources for the Go runtime and additional memory to launch your application.
-We recommend starting with the following values which should work fine for light-weight to medium memory demanding applications:
+We recommend starting with the following values, which should work fine for light-weight to medium memory-demanding applications:
```javascript
"user_space_size": "2048MB",
"default_mmap_size": "900MB"
@@ -68,7 +68,7 @@ left: `SGX_QL_SUCCESS`,
right: `SGX_QL_NETWORK_ERROR`: fail to launch QE', src/util/sgx/dcap/quote_generator.rs:22:13
```
-You might need to check the DCAP configuration on your system. Note that when using the Docker image, the local Intel DCAP configuration needs to be correctly set from **inside the container.**
+You might need to check the DCAP configuration on your system. Note that when using the Docker image, the local Intel DCAP configuration must be correctly set **inside the container.**
If you use an Azure Confidential Computing machine, you can use our [provided Dockerfile](https://github.com/edgelesssys/marblerun/blob/master/samples/occlum-hello/Dockerfile). It patches the official Occlum image to use the Azure DCAP client, which handles the configuration automatically.
diff --git a/docs/versioned_docs/version-1.2/deployment/cloud.md b/docs/versioned_docs/version-1.2/deployment/cloud.md
deleted file mode 100644
index 03d0f8d4..00000000
--- a/docs/versioned_docs/version-1.2/deployment/cloud.md
+++ /dev/null
@@ -1,86 +0,0 @@
-# Cloud deployment
-
-This guide walks you through setting up MarbleRun on different CSP offerings individually.
-
-## Azure confidential computing VMs
-
-[Azure confidential computing services](https://azure.microsoft.com/en-us/solutions/confidential-compute/) provide access to VMs with Intel SGX enabled in [DCsv2 VM instances](https://docs.microsoft.com/en-us/azure/virtual-machines/dcv2-series).
-The description below uses a VM running Ubuntu 18.04.
-
-### Prerequisites
-
-* [Update and install EGo](https://github.com/edgelesssys/ego#install)
-* [Update and install the Azure DCAP client](https://docs.microsoft.com/en-us/azure/confidential-computing/quick-create-portal#3-install-the-intel-and-open-enclave-packages-and-dependencies)
-
-### Deploy MarbleRun
-
-You can run MarbleRun standalone on your Azure DCsv2 VM, see our [standalone guide](../deployment/standalone.md).
-Alternatively, you can install a Kubernetes cluster, probably the simplest option would be [minikube](https://minikube.sigs.k8s.io/docs/start/), see our [Kubernetes guide](../deployment/kubernetes.md) on how to install MarbleRun in minikube.
-
-## Alibaba Cloud Elastic Compute Service
-
-With 7th generation [security-enhanced ECS instances](https://www.alibabacloud.com/help/doc-detail/207734.htm) users can try out and use Intel SGX on Alibaba Cloud.
-Currently, security-enhanced instances are only available as part of an invitational preview.
-
-The description below uses a VM running Ubuntu 18.04.
-
-### Prerequisites
-
-1. Install Intel DCAP Quote Provider Library
-
- Add the Intel SGX APT repository:
- ```bash
- wget -qO - https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo apt-key add -
- echo 'deb [arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu bionic main' | sudo tee /etc/apt/sources.list.d/intel-sgx.list
- ```
-
- Download and install the QPL:
- ```bash
- sudo apt update
- sudo apt install libsgx-dcap-default-qpl
- ```
-
-1. Set configuration for Alibaba Cloud SGX remote attestation service
-
- Alibaba Cloud provides a PCCS for remote attestation, deployed on a per-region basis. For optimal stability it's recommended to access the service in your instance's region.
- The configuration is set in `/etc/sgx_default_qcnl.conf`.
-
- * If your instance is assigned a public IP address, change the configuration to the following, where `[Region-ID]` is the ID of your instance's region:
- ```
- PCCS_URL=https://sgx-dcap-server.[Region-ID].aliyuncs.com/sgx/certification/v3/
- USE_SECURE_CERT=TRUE
- ```
-
- * If your instance is in a virtual private cloud and has only internal IP addresses, change the configuration to the following, where `[Region-ID]` is the ID of your instance's region:
- ```
- PCCS_URL=https://sgx-dcap-server-vpc.[Region-ID].aliyuncs.com/sgx/certification/v3/
- USE_SECURE_CERT=TRUE
- ```
-
- :::note
-
- Currently, the Alibaba Cloud SGX remote attestation service is only supported within [mainland China regions](https://www.alibabacloud.com/help/doc-detail/40654.htm#concept-2459516)
-
- :::
-
-1. [Update and install EGo](https://github.com/edgelesssys/ego#install)
-
-### Deploy MarbleRun
-
-You can run MarbleRun standalone on your Alibaba Cloud ECS VM, see our [standalone guide](../deployment/standalone.md).
-Alternatively, you can install a Kubernetes cluster, probably the simplest option would be [minikube](https://minikube.sigs.k8s.io/docs/start/), see our [Kubernetes guide](../deployment/kubernetes.md) on how to install MarbleRun in minikube.
-
-## Azure Kubernetes Services (AKS)
-
-Azure Kubernetes Service (AKS) offers a popular deployment technique relying on
-Azure's cloud resources. AKS hosts Kubernetes pods in Azure confidential compute
-VMs and exposes the underlying confidential compute hardware.
-
-### Prerequisites
-
-Follow the instructions on the [AKS Confidential Computing Quick Start guide](https://docs.microsoft.com/en-us/azure/confidential-computing/confidential-enclave-nodes-aks-get-started)
-to provision an AKS cluster with Intel SGX enabled worker nodes.
-
-### Deploy MarbleRun
-
-See our [Kubernetes guide](../deployment/kubernetes.md) on how to install MarbleRun in your AKS cluster.
diff --git a/docs/versioned_docs/version-1.2/deployment/kubernetes.md b/docs/versioned_docs/version-1.2/deployment/kubernetes.md
index cf8e867b..7c9660d0 100644
--- a/docs/versioned_docs/version-1.2/deployment/kubernetes.md
+++ b/docs/versioned_docs/version-1.2/deployment/kubernetes.md
@@ -19,7 +19,7 @@ The SGX device plugin can either be deployed manually or as a DaemonSet in the c
:::info
-If you are using a CC-enlightened, managed Kubernetes cluster, you will usually already have an SGX device plugin installed.
+If you are using a confidential computing-enlightened, managed Kubernetes cluster, you will usually already have an SGX device plugin installed.
For example, creating a confidential computing cluster on AKS has a pre-configured SGX device plugin.
:::
@@ -81,7 +81,7 @@ Intel SGX supports two modes for obtaining remote attestation quotes:
* In-process: The software generating the quote is part of the enclave application
* Out-of-process: The software generating the quote isn't part of the actual enclave application. This requires the Intel SGX Architectural Enclave Service Manager (AESM) to run on the system
-While Marbles built with [Ego](../building-services/ego.md) perform in-process attestation, other frameworks, such as [Gramine](../building-services/gramine.md), use out-of-process attestation.
+While Marbles built with [Ego](../building-marbles/ego.md) perform in-process attestation, other frameworks, such as [Gramine](../building-marbles/gramine.md), use out-of-process attestation.
If your confidential application uses out-of-process attestation, you will need to expose the AESM device to your container.
You can follow [the AKS guide](https://docs.microsoft.com/en-us/azure/confidential-computing/confidential-nodes-aks-addon) to make your deployments able to use AESM for quote generation. Note, that in this case, your Kubernetes nodes need the AESM service installed. See the [Intel installation guide](https://download.01.org/intel-sgx/sgx-linux/2.12/docs/Intel_SGX_Installation_Guide_Linux_2.12_Open_Source.pdf) for more information.
diff --git a/docs/versioned_docs/version-1.2/deployment/platforms/alibaba.md b/docs/versioned_docs/version-1.2/deployment/platforms/alibaba.md
new file mode 100644
index 00000000..43960785
--- /dev/null
+++ b/docs/versioned_docs/version-1.2/deployment/platforms/alibaba.md
@@ -0,0 +1,66 @@
+# Alibaba Cloud MarbleRun deployment
+
+## Alibaba Cloud Container Service for Kubernetes (ACK)
+
+Alibaba Cloud Container Service for Kubernetes (ACK) offers a popular deployment technique relying on Alibaba's cloud resources.
+[ACK hosts Kubernetes pods in SGX-capable Alibaba VMs](https://www.alibabacloud.com/help/en/ack/ack-managed-and-ack-dedicated/user-guide/tee-based-confidential-computing) and exposes the underlying SGX hardware.
+
+### Prerequisites
+* Follow the instructions on the [ACK Confidential Computing Quick Start guide](https://www.alibabacloud.com/help/en/ack/ack-managed-and-ack-dedicated/user-guide/create-an-ack-managed-cluster-for-confidential-computing) to provision an ACK cluster with Intel SGX-enabled worker nodes.
+
+### Deploy MarbleRun
+
+See the [Kubernetes guide](../kubernetes.md) on installing MarbleRun in your ACK cluster.
+
+
+## Alibaba Cloud Elastic Compute Service
+With 7th-generation [security-enhanced ECS instances](https://www.alibabacloud.com/help/en/ecs/user-guide/overview-25), users can use Intel SGX on Alibaba Cloud.
+You can follow the guide for creating a [g7t, c7t, or r7t](https://www.alibabacloud.com/help/en/elastic-compute-service/latest/create-security-enhanced-instances) instance.
+
+The description below uses a VM running Ubuntu 18.04.
+
+### Prerequisites
+
+1. Install Intel DCAP Quote Provider Library
+
+ Add the Intel SGX APT repository:
+ ```bash
+ wget -qO - https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo apt-key add -
+ echo 'deb [arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu bionic main' | sudo tee /etc/apt/sources.list.d/intel-sgx.list
+ ```
+
+ Download and install the QPL:
+ ```bash
+ sudo apt update
+ sudo apt install libsgx-dcap-default-qpl
+ ```
+
+1. Set configuration for Alibaba Cloud SGX remote attestation service
+
+ Alibaba Cloud provides a PCCS for remote attestation deployed per region. For optimal stability, accessing the service in your instance's region is recommended.
+ The configuration is set in `/etc/sgx_default_qcnl.conf`.
+
+ * If your instance is assigned a public IP address, change the configuration to the following, where `[Region-ID]` is the ID of your instance's region:
+ ```
+ PCCS_URL=https://sgx-dcap-server.[Region-ID].aliyuncs.com/sgx/certification/v3/
+ USE_SECURE_CERT=TRUE
+ ```
+
+ * If your instance is in a virtual private cloud and has only internal IP addresses, change the configuration to the following, where `[Region-ID]` is the ID of your instance's region:
+ ```
+ PCCS_URL=https://sgx-dcap-server-vpc.[Region-ID].aliyuncs.com/sgx/certification/v3/
+ USE_SECURE_CERT=TRUE
+ ```
+
+ :::note
+
+ Currently, the Alibaba Cloud SGX remote attestation service is only supported within [mainland China regions, Singapore, and Indonesia](https://www.alibabacloud.com/help/en/elastic-compute-service/latest/build-an-sgx-encrypted-computing-environment)
+
+ :::
+
+1. [Update and install EGo](https://github.com/edgelesssys/ego#install)
+
+### Deploy MarbleRun
+
+You can run MarbleRun standalone on your Alibaba Cloud ECS VM. See the [standalone guide](../standalone.md).
+Alternatively, you can install a Kubernetes cluster. Probably the simplest option would be [minikube](https://minikube.sigs.k8s.io/docs/start/). See the [Kubernetes guide](../kubernetes.md) on how to install MarbleRun in minikube.
diff --git a/docs/versioned_docs/version-1.2/deployment/platforms/azure.md b/docs/versioned_docs/version-1.2/deployment/platforms/azure.md
new file mode 100644
index 00000000..dd8984ae
--- /dev/null
+++ b/docs/versioned_docs/version-1.2/deployment/platforms/azure.md
@@ -0,0 +1,29 @@
+# Azure MarbleRun deployment
+
+## Azure Kubernetes Services (AKS)
+
+Azure Kubernetes Service (AKS) offers a popular deployment technique relying on
+Azure's cloud resources. AKS hosts Kubernetes pods in SGX-capabale Azure VMs and exposes the underlying SGX hardware.
+
+### Prerequisites
+
+* Follow the instructions on the [AKS Confidential Computing Quick Start guide](https://docs.microsoft.com/en-us/azure/confidential-computing/confidential-enclave-nodes-aks-get-started) to provision an AKS cluster with Intel SGX enabled worker nodes.
+
+### Deploy MarbleRun
+
+See our [Kubernetes guide](../kubernetes.md) on how to install MarbleRun in your AKS cluster.
+
+## Azure confidential computing VMs
+
+[Azure confidential computing services](https://learn.microsoft.com/en-us/azure/confidential-computing/virtual-machine-solutions-sgx) provide access to VMs with Intel SGX enabled.
+You can follow their [quickstart](https://learn.microsoft.com/en-us/azure/confidential-computing/quick-create-portal) to create a [DCsv2](https://docs.microsoft.com/en-us/azure/virtual-machines/dcv2-series) (Coffee Lake) or [DCsv3](https://learn.microsoft.com/en-us/azure/virtual-machines/dcv3-series) (Ice Lake) VM.
+
+### Prerequisites
+
+* [Update and install EGo](https://github.com/edgelesssys/ego#install)
+* [Update and install the Azure DCAP client](https://learn.microsoft.com/en-us/azure/confidential-computing/quick-create-portal#install-azure-dcap-client)
+
+### Deploy MarbleRun
+
+You can run MarbleRun standalone on your Azure DCsv2/3 VM, see our [standalone guide](../standalone.md).
+Alternatively, you can install a Kubernetes cluster, probably the simplest option would be [minikube](https://minikube.sigs.k8s.io/docs/start/), see our [Kubernetes guide](../kubernetes.md) on how to install MarbleRun in minikube.
diff --git a/docs/versioned_docs/version-1.2/deployment/on-prem.md b/docs/versioned_docs/version-1.2/deployment/platforms/on-prem.md
similarity index 75%
rename from docs/versioned_docs/version-1.2/deployment/on-prem.md
rename to docs/versioned_docs/version-1.2/deployment/platforms/on-prem.md
index 91026d44..1b3b0f2a 100644
--- a/docs/versioned_docs/version-1.2/deployment/on-prem.md
+++ b/docs/versioned_docs/version-1.2/deployment/platforms/on-prem.md
@@ -11,17 +11,16 @@ This guide walks you through setting up MarbleRun for your on-premises deploymen
To deploy MarbleRun with Intel SGX, the machine or VM has to support Intel SGX.
Particularly, MarbleRun requires support for the SGX Data Center Attestation Primitives (DCAP).
You can verify [if your CPU supports DCAP](https://www.intel.com/content/www/us/en/support/articles/000057420/software/intel-security-products.html).
-
-For more information read this article on [detecting Intel Software Guard Extensions](https://software.intel.com/content/www/us/en/develop/articles/properly-detecting-intel-software-guard-extensions-in-your-applications.html) in your applications.
+For more information, read this article on [detecting Intel Software Guard Extensions](https://software.intel.com/content/www/us/en/develop/articles/properly-detecting-intel-software-guard-extensions-in-your-applications.html) in your applications.
#### BIOS
BIOS support is required for Intel SGX to provide the capability to enable and configure the Intel SGX feature in the system.
-Currently, most of the SGX capable systems have SGX disabled by default in the BIOS. This default setting might change but for now, you need to manually enable it if it's not already enabled.
+Currently, most of the SGX-capable systems have SGX disabled by default in the BIOS. This default setting might change, but for now, you need to manually enable it if it's not already enabled.
#### Updates
-As with any modern technology, Intel SGX has been affected by security vulnerabilities. Intel addresses these vulnerabilities by updating the microcode of CPUs, changing the hardware of new CPUs, and updating the system software. Each microcode update that patches an SGX vulnerability requires a BIOS update. During remote attestation, it's checked that the microcode of the CPU which is deployed by the BIOS is up to date. The microcode and platform enclaves are commonly called the platform `Trusted Computing Base (TCB)`.
+As with any modern technology, Intel SGX has been affected by security vulnerabilities. Intel addresses these vulnerabilities by updating the microcode of CPUs, changing the hardware of new CPUs, and updating the system software. Each microcode update that patches an SGX vulnerability requires a BIOS update. During remote attestation, it's checked that the microcode of the CPU, which is deployed by the BIOS, is up to date. The microcode and platform enclaves are commonly called the platform `Trusted Computing Base (TCB)`.
If your BIOS/firmware is outdated, you will see errors as `Platform TCB (2) is not up-to-date (oe_result_t=OE_TCB_LEVEL_INVALID)` during remote attestation procedures.
@@ -39,19 +38,19 @@ Most of the popular hypervisors support SGX:
#### Driver
You need to install the [DCAP SGX Driver](https://download.01.org/intel-sgx/sgx-dcap/1.11/linux/docs/Intel_SGX_SW_Installation_Guide_for_Linux.pdf).
-Azure provides the instructions on [how to install this driver](https://docs.microsoft.com/en-us/azure/confidential-computing/quick-create-portal#2-install-the-intel-sgx-dcap-driver) that you can use for your on-premises machines.
+Azure provides instructions on [how to install this driver](https://docs.microsoft.com/en-us/azure/confidential-computing/quick-create-portal#2-install-the-intel-sgx-dcap-driver) that you can use for your on-premises machines.
### SGX Data Center Attestation Primitives (DCAP)
-DCAP is the new attestation mechanism for SGX [replacing EPID](https://software.intel.com/content/www/us/en/develop/blogs/an-update-on-3rd-party-attestation.html).
+DCAP is the new attestation mechanism for SGX, [replacing EPID](https://software.intel.com/content/www/us/en/develop/blogs/an-update-on-3rd-party-attestation.html).
You can find an overview of DCAP in the [official Intel docs](https://download.01.org/intel-sgx/sgx-dcap/1.11/linux/docs/DCAP_ECDSA_Orientation.pdf).
MarbleRun only supports DCAP and requires DCAP libraries installed and configured on your system.
-From the perspective of MarbleRun and your workloads DCAP is accessed with a [Quote Generation Library (QGL)](https://github.com/intel/SGXDataCenterAttestationPrimitives/blob/master/QuoteGeneration/README.md) and a [Quote Verification Library (QVL)](https://github.com/intel/SGXDataCenterAttestationPrimitives/blob/master/QuoteVerification/README.md) for generating and verifying quotes respectively.
+From the perspective of MarbleRun and your workloads, DCAP is accessed with a [Quote Generation Library (QGL)](https://github.com/intel/SGXDataCenterAttestationPrimitives/blob/master/QuoteGeneration/README.md) and a [Quote Verification Library (QVL)](https://github.com/intel/SGXDataCenterAttestationPrimitives/blob/master/QuoteVerification/README.md) for generating and verifying quotes respectively.
The QGL and QVL libraries need to be configured to talk to a [Provisioning Certificate Caching Service (PCCS)](https://download.01.org/intel-sgx/sgx-dcap/1.11/linux/docs/DCAP_ECDSA_Orientation.pdf).
You currently have two options regarding PCCS for your on-premises machines and clusters:
-1. Use a public PCCS service by configuring your QGL and QVL to point to the public endpoints. Currently, Azure and Alibaba Cloud provide such a service, but require using infrastructure by these providers to make full use of the service.
+1. Use a public PCCS service by configuring your QGL and QVL to point to the public endpoints. Currently, Azure and Alibaba Cloud provide such a service but require using infrastructure by these providers to make full use of the service.
1. Run your own PCCS and expose it to your machine or cluster. See [Intel's demo reference implementation](https://github.com/intel/SGXDataCenterAttestationPrimitives/blob/master/QuoteGeneration/pccs/README.md) and [design guide](https://download.01.org/intel-sgx/latest/dcap-latest/linux/docs/SGX_DCAP_Caching_Service_Design_Guide.pdf) for more information.
@@ -90,4 +89,4 @@ Similarly, the [EGo image](https://github.com/orgs/edgelesssys/packages?repo_nam
You have made sure your hardware supports SGX, updated all firmware, installed the SGX driver, and configured DCAP on all your machines and VMs?
Great! Now it's time to install MarbleRun and get going.
-You can either [use MarbleRun in standalone mode](../deployment/standalone.md) or [install it in your Kubernetes cluster](../deployment/kubernetes.md).
+You can either [use MarbleRun in standalone mode](../standalone.md) or [install it in your Kubernetes cluster](../kubernetes.md).
diff --git a/docs/versioned_docs/version-1.2/deployment/platforms/platforms.md b/docs/versioned_docs/version-1.2/deployment/platforms/platforms.md
new file mode 100644
index 00000000..4e74677d
--- /dev/null
+++ b/docs/versioned_docs/version-1.2/deployment/platforms/platforms.md
@@ -0,0 +1,16 @@
+# Supported platforms
+
+MarbleRun supports all platforms where Intel SGX and the [Data Center Attestation Primitives (DCAP)](https://download.01.org/intel-sgx/latest/dcap-latest/linux/docs/DCAP_ECDSA_Orientation.pdf) are available.
+
+The following gives you an updated list of supported platforms:
+
+
+| Platform | Service | DCAP |
+|---------------|------------|-------------------|
+| Azure | VMs | Managed |
+| | AKS | Managed |
+| Alibaba Cloud | VMs | Managed |
+| | ACK | Managed |
+| Equinix | Bare-Metal | Customer-operated |
+| IBM Cloud | Bare-Metal | Customer-operated |
+| On-premises | * | Customer-operated |
diff --git a/docs/versioned_docs/version-1.2/deployment/standalone.md b/docs/versioned_docs/version-1.2/deployment/standalone.md
index 09d19b6b..25725b81 100644
--- a/docs/versioned_docs/version-1.2/deployment/standalone.md
+++ b/docs/versioned_docs/version-1.2/deployment/standalone.md
@@ -38,7 +38,7 @@ See the [how to add a service](../workflows/add-service.md) documentation for mo
### Run your workloads
You first need to build your workloads together with our Marble data plane.
-See our guides for building [EGo](../building-services/ego.md), [Gramine](../building-services/gramine.md), and [Occlum](../building-services/occlum.md) workloads.
+See our guides for building [EGo](../building-marbles/ego.md), [Gramine](../building-marbles/gramine.md), and [Occlum](../building-marbles/occlum.md) workloads.
You can then run your Marble as follows:
diff --git a/docs/versioned_docs/version-1.2/features/attestation.md b/docs/versioned_docs/version-1.2/features/attestation.md
index 76191cf2..73f52a6f 100644
--- a/docs/versioned_docs/version-1.2/features/attestation.md
+++ b/docs/versioned_docs/version-1.2/features/attestation.md
@@ -8,7 +8,7 @@ However, MarbleRun works with any DCAP service complying with the SGX specificat
Initially, the MarbleRun Coordinator is deployed to the cluster.
The Coordinator generates an X.509 certificate chain with a root and intermediate certificate authority (CA).
-It generates a remote attestation quote which contains the hash of the root certificate (as `report_data`) as well as a hardware measurement of its enclave (`MRENCLAVE` of the report).
+It generates a remote attestation quote that contains the hash of the root certificate (as `report_data`) as well as a hardware measurement of its enclave (`MRENCLAVE` of the report).
The admin receives the quote and verifies the Coordinator's integrity via the measurement. Next, they verify that the quote contains the root certificate’s hash. This ensures that the certificate was indeed generated by this Coordinator and wasn't manipulated during transport.
@@ -22,7 +22,7 @@ The [manifest](../workflows/define-manifest.md) describes which Marbles (service
The Coordinator enforces the manifest and only admits the desired Marbles to the cluster.
Each Marble registers itself with a quote via gRPC to the Coordinator. This quote is tied to the TLS session of the gRPC call. It contains the Marble's measurements. The Coordinator compares them to the manifest to ensure the Marble's identity and integrity.
The [Marble's TLS credentials](../features/secrets-management.md) are generated by the Coordinator and signed with the intermediate certificate.
-The Coordinator's certificate chain as well as the freshly generated Marble certificate are then delivered to the Marble.
+The Coordinator's certificate chain and the freshly generated Marble certificate are then delivered to the Marble.
@@ -35,17 +35,17 @@ If a client wants to connect to a Marble, the Coordinator acts as a trusted CA t
-When the Coordinator receives an update to the manifest, e.g. a Marble is updated to a newer security version, a new intermediate certificate is generated. The communication between Marbles relies on the intermediate certificate as root of trust. This ensures that Marbles which were deployed before the update can't communicate with Marbles that have the newer security version.
+When the Coordinator receives an update to the manifest, e.g., a Marble is updated to a newer security version, a new intermediate certificate is generated. The communication between Marbles relies on the intermediate certificate as the root of trust. This ensures that Marbles which were deployed before the update can't communicate with Marbles that have the newer security version.
## Cluster attestation
-The Coordinator issues one concise remote-attestation statement for your whole distributed app.
+The Coordinator issues one concise remote attestation statement for your whole distributed app.
The Coordinator's build-time measurement is distributed to the relying party (this must be done by the admin or operator).
The relying party requests the Coordinator's quote and certificate chain.
The quote contains the hash of the Coordinator's root CA certificate, which is verified against the received certificate chain.
The quote also contains the Coordinator's measurement, which is verified against the build-time measurement.
The relying party then requests the manifest from the Coordinator and ensures it contains the expected Marbles and their expected measurements.
-The steps required on the client-side are described in our [verification hands-on](../workflows/verification.md).
+The steps required on the client side are described in the [verification hands-on](../workflows/verification.md).
diff --git a/docs/versioned_docs/version-1.2/features/kubernetes-integration.md b/docs/versioned_docs/version-1.2/features/kubernetes-integration.md
index b070957a..4a52db4a 100644
--- a/docs/versioned_docs/version-1.2/features/kubernetes-integration.md
+++ b/docs/versioned_docs/version-1.2/features/kubernetes-integration.md
@@ -1,14 +1,13 @@
# Kubernetes integration
-MarbleRun provides its data-plane configuration through Kubernetes resource definitions. For this, like regular service meshes, MarbleRun uses Kubernetes' [admission controllers](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook).
+MarbleRun provides its data-plane configuration through Kubernetes resource definitions. Like regular service meshes, MarbleRun uses Kubernetes' [admission controllers](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook).
MarbleRun optionally injects [tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) and [resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) for its SGX device plugin. See the [Kubernetes deployment](../deployment/kubernetes.md#sgx-device-plugin-on-kubernetes) section for more information.
You can enable auto-injection of the data-plane configuration using Pod labels.
## The `marbletype` label
-
-In MarbleRun, Marbles (i.e, secure enclaves) are defined in the [manifest](../workflows/define-manifest.md). You need to reference Marbles in your Kubernetes resource description as follows using the `marblerun/marbletype` label:
+In MarbleRun, Marbles (i.e., secure enclaves) are defined in the [manifest](../workflows/define-manifest.md). You need to reference Marbles in your Kubernetes resource description as follows using the `marblerun/marbletype` label:
```javascript
{
@@ -30,21 +29,20 @@ metadata:
marblerun/marbletype: voting-svc
```
-We use this label to map Kubernetes Pods to MarbleRun Marbles.
+The label is used to map Kubernetes Pods to MarbleRun Marbles.
When you deploy your application with the `marblerun/marbletype` label, the Pod's creation is intercepted by MarbleRun.
-It will then inject environment variables and SGX resources into the containers of the Pod based on the value of the label.
-If the `marblerun/marbletype` label is missing, the Pod's injection is skipped.
+It will then inject environment variables and SGX resources into the Pod containers based on the label's value.
+The Pod's injection is skipped if the `marblerun/marbletype` label is missing.
## The `marblecontainer` label
-
-By default MarbleRun will inject environment variables and resource requests into all containers of the Pod.
+By default, MarbleRun will inject environment variables and resource requests into all containers of the Pod.
You can use the `marblerun/marblecontainer=` label to limit injection to the specified container.
-This is useful if your configuration uses multiple containers in the same Pod, e.g. a sidecar proxy, and you wish to prevent non enclave containers taking up resources.
+This is useful if your configuration uses multiple containers in the same Pod, e.g., a sidecar proxy, and you wish to prevent non-enclave containers from taking up resources.
## The `resource-injection` label
-To prevent MarbleRun from injecting SGX resource request, you can set the label `marblerun/resource-injection=disabled`.
-Use this if you want to set your own SGX resource requests, or if you need to start a Marble in simulation mode without any SGX resources.
+To prevent MarbleRun from injecting SGX resource requests, you can set the label `marblerun/resource-injection=disabled`.
+Use this if you want to set your own SGX resource requests or if you need to start a Marble in simulation mode without any SGX resources.
## Injected environment variables
@@ -52,7 +50,7 @@ The webhook will inject the following environment variables into each container
* `EDG_MARBLE_TYPE`: The value of the `marblerun/marbletype` label
* `EDG_MARBLE_COORDINATOR_ADDR`: The address of the MarbleRun Coordinator running on the cluster
-* `EDG_MARBLE_DNS_NAMES`: DNS names of the pod derived from `marbletype` and namespace: `marbletype, marbletype.namespace, marbletype.namespace.svc.cluster.local`
+* `EDG_MARBLE_DNS_NAMES`: DNS names of the pod are derived from `marbletype` and namespace: `marbletype, marbletype.namespace, marbletype.namespace.svc.cluster.local`
* `EDG_MARBLE_UUID_FILE`: The mounted UUID of the Marble
-If an environment variable is already set before the webhook handles the creation request, the variable won't be overwritten and the custom value is used instead.
+If an environment variable is already set before the webhook handles the creation request, the variable won't be overwritten, and the custom value is used instead.
diff --git a/docs/versioned_docs/version-1.2/features/manifest.md b/docs/versioned_docs/version-1.2/features/manifest.md
index 0f4bdb63..82d96389 100644
--- a/docs/versioned_docs/version-1.2/features/manifest.md
+++ b/docs/versioned_docs/version-1.2/features/manifest.md
@@ -1,7 +1,7 @@
# Manifest and deployment updates
The manifest is a JSON document that defines the essential properties of your deployment: allowed software packages, secrets, access control, update policy, etc.
-Particularly, the manifest contains all information required by the [Coordinator](../getting-started/coordinator.md) to verify the confidentiality and integrity of a newly spawned [Marble](../getting-started/marbles.md).
+Particularly, the manifest contains all information required by the [Coordinator](../architecture/coordinator.md) to verify the confidentiality and integrity of a newly spawned [Marble](../architecture/marbles.md).
On successful verification, the Coordinator provisions the Marble with configuration and secrets.
As a cluster owner, you can define in the manifest how rigid you want your deployment to be.
diff --git a/docs/versioned_docs/version-1.2/features/recovery.md b/docs/versioned_docs/version-1.2/features/recovery.md
index b718af6e..9611694c 100644
--- a/docs/versioned_docs/version-1.2/features/recovery.md
+++ b/docs/versioned_docs/version-1.2/features/recovery.md
@@ -1,14 +1,14 @@
# State and recovery
-Persistent storage for confidential applications in the cloud requires a bit of attention.
+Persistent storage for confidential applications in the cloud requires attention.
If an application should be able to restart without manual intervention, it needs a way to automatically and securely obtain a secret to decrypt its state.
The SGX programming model considers a single, local application running on a specific CPU.
-In this case, the application can use the SGX seal key as its root secret.
+The application can use the SGX seal key as its root secret.
However, this binds the application and its state to the physical machine because seal keys are unique to a single CPU.
-In sum, this means that the usual SGX programming model isn't suited for virtual environments or distributed applications.
+In sum, the usual SGX programming model isn't suited for virtual environments or distributed applications.
-With MarbleRun, the Coordinator [manages the Marbles' secrets](../features/secrets-management.md) and Marbles obtain them securely on start.
+With MarbleRun, the Coordinator [manages the Marbles' secrets](../features/secrets-management.md), and Marbles obtain them securely on start.
Thus, Marbles can be distributed and rescheduled on arbitrary machines.
This narrows the challenge of persistent storage down to the Coordinator itself.
@@ -17,7 +17,7 @@ This narrows the challenge of persistent storage down to the Coordinator itself.
The straightforward way to run MarbleRun is with a single Coordinator.
In this case, the state is encrypted with the SGX seal key and stored on disk.
When pinned to a single host, the Coordinator can unseal its state automatically.
-However, when the Coordinator is moved to another physical host, a [manual step](#recovery) is required to recover the Coordinator's state.
+However, a [manual step](#recovery) is required to recover the Coordinator's state when the Coordinator is moved to another physical host.
### Distributed Coordinator
@@ -32,7 +32,6 @@ In this mode of operation, manual recovery is only required when
* all Coordinator instances are stopped at the same time, and
* all new instances are scheduled on new physical hosts.
-
In other words, if at least one instance is scheduled on a host where a previous instance was running, the state can be recovered automatically.
## Recovery
@@ -41,7 +40,7 @@ The manifest allows for specifying a designated *Recovery Key*. The Recovery Key
:::caution
-The owner of the Recovery Key can access the raw state of the Coordinator.
+The Recovery Key's owner can access the Coordinator's raw state.
:::
diff --git a/docs/versioned_docs/version-1.2/features/runtimes.md b/docs/versioned_docs/version-1.2/features/runtimes.md
index 6f06eb92..1fe7b0ca 100644
--- a/docs/versioned_docs/version-1.2/features/runtimes.md
+++ b/docs/versioned_docs/version-1.2/features/runtimes.md
@@ -3,18 +3,18 @@
MarbleRun strives to be runtime-agnostic. Currently, supported runtimes are described below. More will follow in the future.
## EGo
-[EGo](https://github.com/edgelesssys/ego) is the preferred way for writing confidential Go applications from scratch as well as porting existing ones. Usage is similar to conventional Go programming. Start [building your service with EGo](../building-services/ego.md) to use it with MarbleRun.
+[EGo](https://github.com/edgelesssys/ego) is the preferred way for writing confidential Go applications from scratch as well as porting existing ones. Usage is similar to conventional Go programming. Start [building your service with EGo](../building-marbles/ego.md) to use it with MarbleRun.
## Edgeless RT
-With [Edgeless RT](https://github.com/edgelesssys/edgelessrt) you can create confidential C++ applications with a low TCB. Please follow the build instructions provided [in our C++ sample](https://github.com/edgelesssys/marblerun/blob/master/samples/helloc%2B%2B) to use it with MarbleRun.
+With [Edgeless RT](https://github.com/edgelesssys/edgelessrt), you can create confidential C++ applications with a low TCB. Please follow the build instructions provided [in the C++ sample](https://github.com/edgelesssys/marblerun/blob/master/samples/helloc%2B%2B) to use it with MarbleRun.
## Gramine
[Gramine](https://gramineproject.io/) is a popular choice for wrapping unmodified applications into enclaves.
This approach, commonly known as "lift and shift," facilitates the process of bringing existing applications into the confidential space.
Gramine further adds support for dynamically linked libraries and multi-process applications in SGX.
-[Running a Gramine app](../building-services/gramine.md) with MarbleRun requires minor changes to its manifest.
+[Running a Gramine app](../building-marbles/gramine.md) with MarbleRun requires minor changes to its manifest.
## Occlum
-[Occlum](https://github.com/occlum/occlum) is another popular solution which allows wrapping existing applications with minimal to no changes inside an enclave. It requires you to at best recompile existing applications with the provided toolchains with support for common languages such as C, C++, Go, Java, and Rust.
-Its core is written in the memory-safe programming language Rust and it provides a separated environment under which your application is running. This provides a safe yet powerful way to build your applications.
-[Running an Occlum app](../building-services/occlum.md) with MarbleRun requires minor changes to its manifest.
+[Occlum](https://github.com/occlum/occlum) is another popular solution that allows wrapping existing applications with minimal to no changes inside an enclave. It requires you to, at best, recompile existing applications with the provided toolchains with support for common languages such as C, C++, Go, Java, and Rust.
+Its core is written in the memory-safe programming language Rust, and it provides a separated environment under which your application is running. This provides a safe yet powerful way to build your applications.
+[Running an Occlum app](../building-marbles/occlum.md) with MarbleRun requires minor changes to its manifest.
diff --git a/docs/versioned_docs/version-1.2/features/transparent-TLS.md b/docs/versioned_docs/version-1.2/features/transparent-TLS.md
index 07f2b993..0ed9e71e 100644
--- a/docs/versioned_docs/version-1.2/features/transparent-TLS.md
+++ b/docs/versioned_docs/version-1.2/features/transparent-TLS.md
@@ -4,7 +4,7 @@ Authenticated and encrypted connections between services are essential for the s
Transparent TLS (TTLS) can wrap any connection in TLS on the MarbleRun layer. MarbleRun adds secure communication to your cluster even if your application doesn't support the required TLS features. Just define the desired [connections in the manifest](../workflows/define-manifest.md#tls).
-TTLS is currently available with [EGo Marbles](../building-services/ego.md). Other [runtimes](../features/runtimes.md) will be supported in future.
+TTLS is currently available with [EGo Marbles](../building-marbles/ego.md). Other [runtimes](../features/runtimes.md) will be supported in future.
## Authentication and credentials
By default the Marble's credentials are automatically configured. Connections between two Marbles are mutually authenticated.
diff --git a/docs/versioned_docs/version-1.2/examples.md b/docs/versioned_docs/version-1.2/getting-started/examples.md
similarity index 100%
rename from docs/versioned_docs/version-1.2/examples.md
rename to docs/versioned_docs/version-1.2/getting-started/examples.md
diff --git a/docs/versioned_docs/version-1.2/getting-started/installation.md b/docs/versioned_docs/version-1.2/getting-started/installation.md
new file mode 100644
index 00000000..7640d34a
--- /dev/null
+++ b/docs/versioned_docs/version-1.2/getting-started/installation.md
@@ -0,0 +1,61 @@
+# Installation and setup
+
+In this guide, you will install MarbleRun into your Kubernetes cluster and deploy a sample confidential application to demonstrate the capabilities of MarbleRun.
+
+Installing MarbleRun is easy. First, you will install the CLI (command-line interface) onto your local machine. Using this CLI, you’ll then install the control plane onto your Kubernetes cluster.
+Finally, you will add your services and set up a corresponding manifest.
+
+## Prerequisites
+
+Make sure the following requirements are met:
+
+* Your machine is running Ubuntu 20.04 on an x86 (AMD64) CPU
+* You have access to a Kubernetes cluster and kubectl installed and configured
+
+Probably the easiest way to get started is to run Kubernetes on your local machine using [minikube](https://minikube.sigs.k8s.io/docs/start/). Please check our [prerequisites](../deployment/kubernetes.md#prerequisites) if you want to set up an SGX-enabled cluster. Another easy way is to use [Azure Kubernetes Service (AKS)](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal), which offers SGX-enabled nodes.
+
+You can validate your setup by running the following:
+
+```bash
+kubectl version --short
+```
+
+You should see an output with both a Client Version and a Server Version component.
+Now your cluster is ready and we’ll install the MarbleRun CLI.
+
+## Install the MarbleRun CLI
+
+If this is your first time running MarbleRun, you will need to download the MarbleRun command-line interface (CLI) onto your local machine. The CLI will allow you to interact with your MarbleRun deployment.
+
+To install the CLI, run the following:
+
+
+
+
+```bash
+wget -P ~/.local/bin https://github.com/edgelesssys/marblerun/releases/latest/download/marblerun
+chmod +x ~/.local/bin/marblerun
+```
+
+
+
+
+```bash
+sudo wget -O /usr/local/bin/marblerun https://github.com/edgelesssys/marblerun/releases/latest/download/marblerun
+sudo chmod +x /usr/local/bin/marblerun
+```
+
+
+
+
+Once installed, verify the CLI is running correctly with the following:
+
+```bash
+marblerun
+```
+
+You can use the CLI to check if your cluster is configured to run SGX workloads:
+
+```bash
+marblerun precheck
+```
diff --git a/docs/versioned_docs/version-1.2/getting-started/marbles.md b/docs/versioned_docs/version-1.2/getting-started/marbles.md
deleted file mode 100644
index 85aa7cd5..00000000
--- a/docs/versioned_docs/version-1.2/getting-started/marbles.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Marbles
-
-Marbles are MarbleRun's data planes and run your application code in secure enclaves within otherwise regular Docker containers. Marbles communicate with the Coordinator via gRPC over TLS. See the [Add a Service](../workflows/add-service.md) section on how to build and configure a Marble.
diff --git a/docs/versioned_docs/version-1.2/getting-started/quickstart-sgx.md b/docs/versioned_docs/version-1.2/getting-started/quickstart-sgx.md
deleted file mode 100644
index da29f01d..00000000
--- a/docs/versioned_docs/version-1.2/getting-started/quickstart-sgx.md
+++ /dev/null
@@ -1,112 +0,0 @@
-# Quickstart SGX
-
-## Step 1: Install the control plane onto your cluster
-
-Install MarbleRun's *Coordinator* control plane by running:
-
-```bash
-marblerun install
-```
-
-The `marblerun install` command generates a Kubernetes manifest with all the necessary control plane resources.
-This includes a deployment for the Coordinator and for MarbleRun's [admission controller.](../features/kubernetes-integration.md)
-
-Wait for the control plane to finish installing:
-
-```bash
-marblerun check
-```
-
-This command will wait until all components of MarbleRun are ready to be used or return an error after a timeout period is reached.
-
-Port forward the Coordinator's Client API:
-
-```bash
-kubectl -n marblerun port-forward svc/coordinator-client-api 4433:4433 --address localhost >/dev/null &
-export MARBLERUN=localhost:4433
-```
-
-## Step 2: Verify the Coordinator
-
-After installing the Coordinator we need to verify its integrity.
-For this, we utilize SGX remote attestation and obtain the Coordinator's root certificate.
-
-Verify the quote and get the Coordinator's root certificate
-
-```bash
-marblerun certificate root $MARBLERUN -o marblerun.crt
-```
-
-The CLI will obtain the Coordinator's remote attestation quote and verify it against the configuration on our [release page](https://github.com/edgelesssys/marblerun/releases/latest/download/coordinator-era.json).
-The SGX quote proves the integrity of the Coordinator pod.
-The CLI returns a certificate and stores it as `marblerun.crt` in your current directory.
-The certificate is bound to the quote and can be used for future verification.
-It can also be used as a root of trust for [authenticating your confidential applications](../features/attestation.md).
-
-## Step 3: Deploy the demo application
-
-To get a feel for how MarbleRun would work for one of your services, you can install a demo application.
-The emojivoto application is a standalone Kubernetes application that uses a mix of gRPC and HTTP calls to allow the users to vote on their favorite emojis.
-Created as a demo application for the popular [Linkerd](https://linkerd.io) service mesh, we've made a confidential variant that uses a confidential service mesh for all gRPC and HTTP connections.
-Clone the [demo application's repository](https://github.com/edgelesssys/emojivoto.git) from GitHub by running:
-
-```bash
-git clone https://github.com/edgelesssys/emojivoto.git && cd emojivoto
-```
-
-### Step 3.1: Configure MarbleRun
-
-MarbleRun guarantees that the topology of your distributed app adheres to a manifest specified in simple JSON.
-MarbleRun verifies the integrity of services, bootstraps them, and sets up encrypted connections between them.
-The emojivoto demo already comes with a [manifest](https://github.com/edgelesssys/emojivoto/blob/main/tools/manifest.json), which you can deploy onto MarbleRun by running:
-
-```bash
-marblerun manifest set tools/manifest.json $MARBLERUN
-```
-
-You can check that the state of MarbleRun changed and is now ready to authenticate your services by running:
-
-```bash
-marblerun status $MARBLERUN
-```
-
-### Step 3.2: Deploy emojivoto
-
-Finally, install the demo application onto your cluster.
-Please make sure you have [Helm](https://helm.sh/docs/intro/install/) ("the package manager for Kubernetes") installed at least at Version v3.2.0.
-Install emojivoto into the emojivoto namespace by running:
-
-```bash
-helm install -f ./kubernetes/sgx_values.yaml emojivoto ./kubernetes --create-namespace -n emojivoto
-```
-
-## Step 4: Watch it run
-
-You can now check the MarbleRun log and see the services being authenticated by the Coordinator.
-
-```bash
-kubectl -n marblerun logs -f -l edgeless.systems/control-plane-component=coordinator
-```
-
-Port forward the front-end web service to access it on your local machine by running:
-
-```bash
-kubectl -n emojivoto port-forward svc/web-svc 8443:443 --address 0.0.0.0
-```
-
-Now visit [https://localhost:8443](https://localhost:8443).
-You'll be presented with a certificate warning because your browser by default doesn't trust certificates signed by MarbleRun.
-You can ignore this error for now and proceed to the website.\
-Voila! Your emoji votes have never been safer!
-
-## That’s it 👏
-
-Congratulations, you’re now a MarbleRun user! Here are some suggested next steps:
-
-* Explore how [MarbleRun takes care of your secrets](../features/secrets-management.md)
-* [Add your own service](../workflows/add-service.md) to MarbleRun
-* Learn more about [MarbleRun’s architecture](../getting-started/concepts.md)
-* Chat with us on [Discord](https://discord.gg/rH8QTH56JN)
-* Try out the full demo on [GitHub](https://github.com/edgelesssys/emojivoto)
-
-Welcome to the MarbleRun community!
diff --git a/docs/versioned_docs/version-1.2/getting-started/quickstart-simulation.md b/docs/versioned_docs/version-1.2/getting-started/quickstart-simulation.md
deleted file mode 100644
index ba8aec50..00000000
--- a/docs/versioned_docs/version-1.2/getting-started/quickstart-simulation.md
+++ /dev/null
@@ -1,99 +0,0 @@
-# Quickstart simulation mode
-
-## Step 1: Install the control plane onto your cluster
-
-Install MarbleRun's *Coordinator* control plane by running:
-
-```bash
-marblerun install --simulation
-```
-
-The `marblerun install` command generates a Kubernetes manifest with all the necessary control plane resources.
-This includes a deployment for the Coordinator and for MarbleRun's [admission controller.](../features/kubernetes-integration.md)
-The simulation flag tells MarbleRun that real SGX hardware might not be present and the SGX-layer should be emulated.
-
-Wait for the control plane to finish installing:
-
-```bash
-marblerun check
-```
-
-This command will wait until all components of MarbleRun are ready to be used or return an error after a timeout period is reached.
-
-Port forward the Coordinator's Client API:
-
-```bash
-kubectl -n marblerun port-forward svc/coordinator-client-api 4433:4433 --address localhost >/dev/null &
-export MARBLERUN=localhost:4433
-```
-
-## Step 2: Deploy the demo application
-
-To get a feel for how MarbleRun would work for one of your services, you can install a demo application.
-The emojivoto application is a standalone Kubernetes application that uses a mix of gRPC and HTTP calls to allow the users to vote on their favorite emojis.
-Created as a demo application for the popular [Linkerd](https://linkerd.io) service mesh, we've made a confidential variant that uses a confidential service mesh for all gRPC and HTTP connections.
-Clone the [demo application's repository]( https://github.com/edgelesssys/emojivoto.git) from GitHub by running:
-
-```bash
-git clone https://github.com/edgelesssys/emojivoto.git && cd emojivoto
-```
-
-### Step 2.1: Configure MarbleRun
-
-MarbleRun guarantees that the topology of your distributed app adheres to a manifest specified in simple JSON.
-MarbleRun verifies the integrity of services, bootstraps them, and sets up encrypted connections between them.
-The emojivoto demo already comes with a [manifest](https://github.com/edgelesssys/emojivoto/blob/main/tools/manifest.json), which you can deploy onto MarbleRun by running:
-
-```bash
-marblerun manifest set tools/manifest.json $MARBLERUN --insecure
-```
-
-Normally, the CLI will verify the Coordinators SGX quote every time it connects to the Coordinators REST interface.
-Since we run MarbleRun in simulation mode, and therefore don't actually generate a quote, we use the `--insecure` flag to skip this verification.
-
-You can check that the state of MarbleRun changed and is now ready to authenticate your services by running:
-
-```bash
-marblerun status $MARBLERUN --insecure
-```
-
-### Step 2.2: Deploy emojivoto
-
-Finally, install the demo application onto your cluster.
-Please make sure you have [Helm](https://helm.sh/docs/intro/install/) ("the package manager for Kubernetes") installed at least at Version v3.2.0.
-Install emojivoto into the emojivoto namespace by running:
-
-```bash
-helm install -f ./kubernetes/nosgx_values.yaml emojivoto ./kubernetes --create-namespace -n emojivoto
-```
-
-## Step 3: Watch it run
-
-You can now check the MarbleRun log and see the services being authenticated by the Coordinator.
-
-```bash
-kubectl -n marblerun logs -f -l edgeless.systems/control-plane-component=coordinator
-```
-
-Port forward the front-end web service to access it on your local machine by running:
-
-```bash
-kubectl -n emojivoto port-forward svc/web-svc 8443:443 --address 0.0.0.0
-```
-
-Now visit [https://localhost:8443](https://localhost:8443).
-You'll be presented with a certificate warning because your browser by default doesn't trust certificates signed by MarbleRun.
-You can ignore this error for now and proceed to the website.\
-Voila! Your emoji votes have never been safer!
-
-## That’s it 👏
-
-Congratulations, you’re now a MarbleRun user! Here are some suggested next steps:
-
-* Explore how [MarbleRun takes care of your secrets](../features/secrets-management.md)
-* [Add your own service](../workflows/add-service.md) to MarbleRun
-* Learn more about [MarbleRun’s architecture](../getting-started/concepts.md)
-* Chat with us on [Discord](https://discord.gg/rH8QTH56JN)
-* Try out the full demo on [GitHub](https://github.com/edgelesssys/emojivoto)
-
-Welcome to the MarbleRun community!
diff --git a/docs/versioned_docs/version-1.2/getting-started/quickstart.md b/docs/versioned_docs/version-1.2/getting-started/quickstart.md
index a0e3adbd..9b6c6bb3 100644
--- a/docs/versioned_docs/version-1.2/getting-started/quickstart.md
+++ b/docs/versioned_docs/version-1.2/getting-started/quickstart.md
@@ -1,66 +1,190 @@
-# Quickstart
+# First steps with MarbleRun
-In this guide, you will install MarbleRun into your Kubernetes cluster and deploy a sample confidential application to demonstrate the capabilities of MarbleRun.
+The following steps guide you through the process of deploying MarbleRun in your cluster and deploying a sample app. This example assumes that you have successfully [installed MarbleRun](./installation.md), and have access to a Kubernetes cluster.
-Installing MarbleRun is easy. First, you will install the CLI (command-line interface) onto your local machine. Using this CLI, you’ll then install the control plane onto your Kubernetes cluster.
-Finally, you will add your own services and set up a corresponding manifest.
+A working SGX DCAP environment is required for MarbleRun. For ease of exploring and testing, we provide a simulation mode with `--simulation` that runs without SGX hardware.
+Depending on your setup, you may follow the quickstart for SGX-enabled clusters. Alternatively, if your setup doesn't support SGX, you can follow the quickstart in simulation mode by selecting the respective tabs.
-:::tip
+## Step 1: Install the control plane onto your cluster
-A working SGX DCAP environment is required for MarbleRun to work. For the ease of exploring and testing we provide a simulation mode with `--simulation` that runs without SGX hardware.
-Depending on your setup you may follow the [quickstart for SGX-enabled clusters](../getting-started/quickstart-sgx.md). Alternatively, if your setup doesn't support SGX, you can follow the [quickstart in simulation mode](../getting-started/quickstart-simulation.md).
+Install MarbleRun's *Coordinator* control plane by running:
-:::
+
+
-## Step 0: Setup
+```bash
+marblerun install
+```
+
+The `marblerun install` command generates a Kubernetes manifest with all the necessary control plane resources.
+This includes a deployment for the Coordinator and for MarbleRun's [admission controller.](../features/kubernetes-integration.md)
+
+
+
+
+```bash
+marblerun install --simulation
+```
+
+The `marblerun install` command generates a Kubernetes manifest with all the necessary control plane resources.
+This includes a deployment for the Coordinator and for MarbleRun's [admission controller.](../features/kubernetes-integration.md)
+The simulation flag tells MarbleRun that real SGX hardware might not be present and the SGX layer should be emulated.
+
+
+
+
+
+
+Wait for the control plane to finish installing:
+
+```bash
+marblerun check
+```
+
+This command will wait until all components of MarbleRun are ready to be used or return an error after a timeout period is reached.
+
+Port forward the Coordinator's Client API:
+
+```bash
+kubectl -n marblerun port-forward svc/coordinator-client-api 4433:4433 --address localhost >/dev/null &
+export MARBLERUN=localhost:4433
+```
+
+## Step 2: Verify the Coordinator
+
+After installing the Coordinator, we need to verify its integrity.
+For this, we utilize SGX remote attestation and obtain the Coordinator's root certificate.
+
+Verify the quote and get the Coordinator's root certificate
+
+
+
+
+```bash
+marblerun certificate root $MARBLERUN -o marblerun.crt
+```
+
+
+
+
+```bash
+marblerun certificate root $MARBLERUN -o marblerun.crt --insecure
+```
+The insecure flag tells MarbleRun that real SGX hardware might not be present and the quote verification should be omitted.
-First, ensure you have access to a Kubernetes cluster and kubectl installed and configured. Probably the easiest way to get started is to run Kubernetes on your local machine using [minikube](https://minikube.sigs.k8s.io/docs/start/). Please check our [prerequisites](../deployment/kubernetes.md#prerequisites) if you want to setup an SGX-enabled cluster. Another easy way is to use [Azure Kubernetes Service (AKS)](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal), which offers SGX-enabled nodes.
+
+
+
+The CLI will obtain the Coordinator's remote attestation quote and verify it against the configuration on our [release page](https://github.com/edgelesssys/marblerun/releases/latest/download/coordinator-era.json).
+The SGX quote proves the integrity of the Coordinator pod.
+The CLI returns a certificate and stores it as `marblerun.crt` in your current directory.
+The certificate is bound to the quote and can be used for future verification.
+It can also be used as a root of trust for [authenticating your confidential applications](../features/attestation.md).
+
+## Step 3: Deploy the demo application
+
+To get a feel for how MarbleRun would work for one of your services, you can install a demo application.
+The emojivoto application is a standalone Kubernetes application that uses a mix of gRPC and HTTP calls to allow users to vote on their favorite emojis.
+Created as a demo application for the popular [Linkerd](https://linkerd.io) service mesh, we've made a confidential variant that uses a confidential service mesh for all gRPC and HTTP connections.
+Clone the [demo application's repository](https://github.com/edgelesssys/emojivoto.git) from GitHub by running the following:
+
+```bash
+git clone https://github.com/edgelesssys/emojivoto.git && cd emojivoto
+```
+
+### Step 3.1: Configure MarbleRun
-You can validate your setup by running:
+MarbleRun guarantees that the topology of your distributed app adheres to a manifest specified in simple JSON.
+MarbleRun verifies the integrity of services, bootstraps them, and sets up encrypted connections between them.
+The emojivoto demo already comes with a [manifest](https://github.com/edgelesssys/emojivoto/blob/main/tools/manifest.json), which you can deploy onto MarbleRun by running the following:
+
+
+
```bash
-kubectl version --short
+marblerun manifest set tools/manifest.json $MARBLERUN
```
-You should see an output with both a Client Version and Server Version component.
-Now your cluster is ready and we’ll install the MarbleRun CLI.
+
+
-## Step 0.5: Install the CLI
+```bash
+marblerun manifest set tools/manifest.json $MARBLERUN --insecure
+```
+
+
+
-If this is your first time running MarbleRun, you will need to download the MarbleRun command-line interface (CLI) onto your local machine. The CLI will allow you to interact with your MarbleRun deployment.
-To install the CLI, run:
+You can check that the state of MarbleRun has changed and is now ready to authenticate your services by running:
-
-
+
+
```bash
-wget -P ~/.local/bin https://github.com/edgelesssys/marblerun/releases/latest/download/marblerun
-chmod +x ~/.local/bin/marblerun
+marblerun status $MARBLERUN
```
-
+
```bash
-sudo wget -O /usr/local/bin/marblerun https://github.com/edgelesssys/marblerun/releases/latest/download/marblerun
-sudo chmod +x /usr/local/bin/marblerun
+marblerun status $MARBLERUN --insecure
```
-Once installed, verify the CLI is running correctly with:
+### Step 3.2: Deploy emojivoto
+
+Finally, install the demo application onto your cluster.
+Please make sure you have [Helm](https://helm.sh/docs/intro/install/) ("the package manager for Kubernetes") installed at least at Version v3.2.0.
+Install emojivoto into the emojivoto namespace by running:
+
+
+
```bash
-marblerun
+helm install -f ./kubernetes/sgx_values.yaml emojivoto ./kubernetes --create-namespace -n emojivoto
```
-You can use the CLI to check if your cluster is configured to run SGX workloads:
+
+
+
+```bash
+helm install -f ./kubernetes/nosgx_values.yaml emojivoto ./kubernetes --create-namespace -n emojivoto
+```
+
+
+
+
+## Step 4: Watch it run
+
+You can now check the MarbleRun log and see the services being authenticated by the Coordinator.
```bash
-marblerun precheck
+kubectl -n marblerun logs -f -l edgeless.systems/control-plane-component=coordinator
```
-If your cluster supports SGX, you can follow the [quickstart for clusters with SGX support.](../getting-started/quickstart-sgx.md)
-Otherwise, please follow the [quickstart in simulation mode.](../getting-started/quickstart-simulation.md)
+Port forward the front-end web service to access it on your local machine by running:
+
+```bash
+kubectl -n emojivoto port-forward svc/web-svc 8443:443 --address 0.0.0.0
+```
+
+Now visit [https://localhost:8443](https://localhost:8443).
+You'll be presented with a certificate warning because your browser, by default, doesn't trust certificates signed by MarbleRun.
+You can ignore this error for now and proceed to the website.\
+Voila! Your emoji votes have never been safer!
+
+## That’s it 👏
+
+Congratulations, you’re now a MarbleRun user! Here are some suggested next steps:
+
+* Explore how [MarbleRun takes care of your secrets](../features/secrets-management.md)
+* [Add your own service](../workflows/add-service.md) to MarbleRun
+* Learn more about [MarbleRun’s architecture](../architecture/concepts.md)
+* Chat with us on [Discord](https://discord.gg/rH8QTH56JN)
+* Try out the full demo on [GitHub](https://github.com/edgelesssys/emojivoto)
+
+Welcome to the MarbleRun community!
diff --git a/docs/versioned_docs/version-1.2/intro.md b/docs/versioned_docs/version-1.2/intro.md
index 91e2b791..85094883 100644
--- a/docs/versioned_docs/version-1.2/intro.md
+++ b/docs/versioned_docs/version-1.2/intro.md
@@ -4,32 +4,42 @@ slug: /
# Welcome to MarbleRun
-MarbleRun is a framework for creating distributed confidential computing apps.
+MarbleRun is a framework for deploying distributed confidential computing applications.
+MarbleRun acts as a confidential operator for your deployment. Think of a trusted party in the control plane.
-Build your confidential microservices with [EGo, Gramine, or another runtime](features/runtimes.md), distribute them with Kubernetes on an SGX-enabled cluster, and let MarbleRun take care of the rest. Deploy end-to-end secure and verifiable AI pipelines or crunch on sensitive big data in the cloud. Confidential computing at scale has never been easier.
+Build your confidential microservices with [EGo, Gramine, or similar runtimes](./features/runtimes.md), orchestrate them with Kubernetes on an SGX-enabled cluster, and let MarbleRun take care of the rest.
+Deploy end-to-end secure and verifiable AI pipelines or crunch on sensitive big data in the cloud. Confidential computing at scale has never been easier.
-MarbleRun guarantees that the topology of your distributed app adheres to a manifest specified in simple JSON. MarbleRun verifies the integrity of services, bootstraps them, and sets up encrypted connections between them. If a node fails, MarbleRun will seamlessly substitute it with respect to the rules defined in the manifest.
+MarbleRun simplifies the process by handling much of the groundwork.
+It ensures that your app's topology adheres to your specified manifest.
+It verifies the identity and integrity of all your services, bootstraps them, and establishes secure, encrypted communication channels.
+As your app needs to scale, MarbleRun manages the addition of new instances, ensuring their secure verification.
-To keep things simple, MarbleRun issues one concise remote-attestation statement for your whole distributed app. This can be used by anyone to verify the integrity of your distributed app.
+MarbleRun provides comprehensive access and privilege management through its role-based access control (RBAC) feature. You can use this to enforce security policies such as four-eyes principles and other verification procedures in your operations.
+
+To keep things simple, MarbleRun offers a single remote attestation statement for your entire app. Anyone can use this to verify the integrity of your distributed app, making it easier to assure stakeholders of your app's security.
## Key features
🔒 Authentication and integrity verification of microservices based on the manifest
-🔑 Secrets management for microservices
+🔑 Secrets management for confidential microservices
📃 Provisioning of certificates, configurations, and parameters
-🔬 Remote attestation of the entire cluster
+🔬 Remote attestation of the entire deployment
+
+
+👥 Role-based access control (RBAC), verifiable updates, and multi-stakeholder support
## Overview
Logically, MarbleRun consists of two parts, the control plane called *Coordinator* and the data plane called *Marbles*.
-The Coordinator needs to be deployed once in your cluster and the Marble layer needs to be integrated with each service.
+The Coordinator needs to be deployed once in your cluster, and the Marble layer needs to be integrated with each service.
MarbleRun is configured with a simple JSON document called the *manifest*.
-It specifies the topology of the distributed app, the infrastructure properties, and provides configuration parameters for each service.
+It specifies the distributed app's topology and infrastructure properties and provides configuration parameters for each service.
diff --git a/docs/versioned_docs/version-1.2/workflows/add-service.md b/docs/versioned_docs/version-1.2/workflows/add-service.md
index 222b6bb8..79c0e2d0 100644
--- a/docs/versioned_docs/version-1.2/workflows/add-service.md
+++ b/docs/versioned_docs/version-1.2/workflows/add-service.md
@@ -5,18 +5,18 @@ Adding a service to your application requires three steps, which are described i
## **Step 1:** Get your service ready for MarbleRun
To get your service ready for MarbleRun, you need to rebuild it with one of the supported [runtimes](../features/runtimes.md):
-* [EGo](../building-services/ego.md)
+* [EGo](../building-marbles/ego.md)
* [Edgeless RT](https://github.com/edgelesssys/marblerun/blob/master/samples/helloc%2B%2B)
-* [Gramine](../building-services/gramine.md)
-* [Occlum](../building-services/occlum.md)
+* [Gramine](../building-marbles/gramine.md)
+* [Occlum](../building-marbles/occlum.md)
### Make your service use the provided TLS credentials
Skip this step, when using EGo with [TTLS](../features/transparent-TLS.md).
-Quick refresher: MarbleRun's Coordinator issues TLS credentials for each verified Marble (i.e., a service running in a secure enclave) as is described in our [secrets management chapter](../features/secrets-management.md).
+Quick refresher: MarbleRun's Coordinator issues TLS credentials for each verified Marble (i.e., a service running in a secure enclave) as is described in the [secrets management chapter](../features/secrets-management.md).
-The TLS X.509 certificate and the corresponding private key can be securely passed to a service through files, environment variables, or command line arguments. This is defined in the manifest as is described in our [writing a manifest hands-on](../workflows/define-manifest.md#marbles).
+The TLS X.509 certificate and the corresponding private key can be securely passed to a service through files, environment variables, or command line arguments. This is defined in the manifest as is described in the [writing a manifest hands-on](../workflows/define-manifest.md#marbles).
Make sure that your service reads the credentials from one of these sources, e.g., the file `/tmp/mycert.cert` or the environment variable `MY_PRIVATE_KEY`, and uses them for internal and external connections. If you're lucky, your service already does this and you don't need to change a thing in the code.
@@ -26,7 +26,7 @@ Now that your service is ready, you need to make two types of entries in the man
### **Step 2.1:** Define the enclave software package
-As is described in more detail in our [writing a manifest hands-on](../workflows/define-manifest.md#packages), the manifest contains a section `Packages`, in which allowed enclave software packages are defined.
+As is described in more detail in the [writing a manifest hands-on](../workflows/define-manifest.md#packages), the manifest contains a section `Packages`, in which allowed enclave software packages are defined.
#### EGo / EdgelessRT
To add an entry for your EGo / EdgelessRT service, run the `oesign` tool on the enclave file you built in the previous step as follows. (`oesign` is installed with [Edgeless RT](https://github.com/edgelesssys/edgelessrt).)
@@ -96,7 +96,7 @@ Use `UniqueID` (i.e., `MRENCLAVE` in Intel SGX speak) or the triplet of `SignerI
### **Step 2.2:** Define the parameters
-Now you can define with which parameters (i.e., files, environment variables, and command line arguments) your service is allowed to run. This is done in the `Marbles` section of the manifest as is described in our [writing a manifest hands-on](../workflows/define-manifest.md#marbles). When using EGo, define all TTLS connections as described in the [manifest hands-on](../workflows/define-manifest.md#tls).
+Now you can define with which parameters (i.e., files, environment variables, and command line arguments) your service is allowed to run. This is done in the `Marbles` section of the manifest as is described in the [writing a manifest hands-on](../workflows/define-manifest.md#marbles). When using EGo, define all TTLS connections as described in the [manifest hands-on](../workflows/define-manifest.md#tls).
Otherwise, as discussed in [Step #1](#make-your-service-use-the-provided-tls-credentials), make sure that the TLS credentials for your service (i.e., `MarbleRun.MarbleCert.Cert` and `MarbleRun.MarbleCert.Private`) are injected such that your service finds them at runtime.
@@ -117,7 +117,7 @@ For EGo (`ego marblerun`), Gramine (`gramine-sgx`), and Occlum (`occlum run`) us
The environment variables have the following purposes.
-* `EDG_MARBLE_COORDINATOR_ADDR` is the network address of the Coordinator's API for Marbles. When you deploy the Coordinator using our Helm repository as is described in our [deploying MarbleRun hands-on](../deployment/kubernetes.md), the default address is `coordinator-mesh-api.marblerun:2001`.
+* `EDG_MARBLE_COORDINATOR_ADDR` is the network address of the Coordinator's API for Marbles. When you deploy the Coordinator using the Helm repository as is described in the [deploying MarbleRun hands-on](../deployment/kubernetes.md), the default address is `coordinator-mesh-api.marblerun:2001`.
* `EDG_MARBLE_TYPE` needs to reference one entry from your manifest's `Marbles` section.
@@ -164,4 +164,4 @@ spec:
value: "$PWD/uuid"
```
-Refer to our [emojivoto](https://github.com/edgelesssys/emojivoto) app for complete Helm chart examples.
+Refer to the [emojivoto](https://github.com/edgelesssys/emojivoto) app for complete Helm chart examples.
diff --git a/docs/versioned_docs/version-1.2/workflows/verification.md b/docs/versioned_docs/version-1.2/workflows/verification.md
index 991b9aa8..103fbb8b 100644
--- a/docs/versioned_docs/version-1.2/workflows/verification.md
+++ b/docs/versioned_docs/version-1.2/workflows/verification.md
@@ -57,7 +57,7 @@ To verify the coordinator, `era` requires the Coordinator's UniqueID (or MRENCLA
In production, the expected values in `coordinator-era.json` would be generated when building the Coordinator and distributed to your clients. When you build MarbleRun from source, you can find the file in your build directory.
For testing with a pre-built release, there's a Coordinator image at `ghcr.io/edgelesssys/marblerun/coordinator`.
-You can pull the corresponding `coordinator-era.json` file from our release page:
+You can pull the corresponding `coordinator-era.json` file from the release page:
```bash
wget https://github.com/edgelesssys/marblerun/releases/latest/download/coordinator-era.json
diff --git a/docs/versioned_sidebars/version-1.2-sidebars.json b/docs/versioned_sidebars/version-1.2-sidebars.json
index f6f0a808..3eb9e1c3 100644
--- a/docs/versioned_sidebars/version-1.2-sidebars.json
+++ b/docs/versioned_sidebars/version-1.2-sidebars.json
@@ -14,33 +14,18 @@
"items": [
{
"type": "doc",
- "label": "Quickstart",
- "id": "getting-started/quickstart"
- },
- {
- "type": "doc",
- "label": "Quickstart SGX",
- "id": "getting-started/quickstart-sgx"
- },
- {
- "type": "doc",
- "label": "Quickstart Simulation",
- "id": "getting-started/quickstart-simulation"
- },
- {
- "type": "doc",
- "label": "Concepts",
- "id": "getting-started/concepts"
+ "label": "Installation",
+ "id": "getting-started/installation"
},
{
"type": "doc",
- "label": "Coordinator",
- "id": "getting-started/coordinator"
+ "label": "First steps",
+ "id": "getting-started/quickstart"
},
{
"type": "doc",
- "label": "Marbles",
- "id": "getting-started/marbles"
+ "label": "Examples",
+ "id": "getting-started/examples"
}
]
},
@@ -95,16 +80,6 @@
"type": "generated-index"
},
"items": [
- {
- "type": "doc",
- "label": "Cloud",
- "id": "deployment/cloud"
- },
- {
- "type": "doc",
- "label": "On-premises",
- "id": "deployment/on-prem"
- },
{
"type": "doc",
"label": "Kubernetes",
@@ -114,6 +89,31 @@
"type": "doc",
"label": "Standalone",
"id": "deployment/standalone"
+ },
+ {
+ "type": "category",
+ "label": "Platforms",
+ "link": {
+ "type": "doc",
+ "id": "deployment/platforms/platforms"
+ },
+ "items": [
+ {
+ "type": "doc",
+ "label": "Azure",
+ "id": "deployment/platforms/azure"
+ },
+ {
+ "type": "doc",
+ "label": "Alibaba Cloud",
+ "id": "deployment/platforms/alibaba"
+ },
+ {
+ "type": "doc",
+ "label": "On-premises",
+ "id": "deployment/platforms/on-prem"
+ }
+ ]
}
]
},
@@ -173,7 +173,36 @@
},
{
"type": "category",
- "label": "Building services",
+ "label": "Architecture",
+ "link": {
+ "type": "generated-index"
+ },
+ "items": [
+ {
+ "type": "doc",
+ "label": "Concepts",
+ "id": "architecture/concepts"
+ },
+ {
+ "type": "doc",
+ "label": "Coordinator",
+ "id": "architecture/coordinator"
+ },
+ {
+ "type": "doc",
+ "label": "Marbles",
+ "id": "architecture/marbles"
+ },
+ {
+ "type": "doc",
+ "label": "Keys and cryptography",
+ "id": "architecture/security"
+ }
+ ]
+ },
+ {
+ "type": "category",
+ "label": "Building Marbles",
"link": {
"type": "generated-index"
},
@@ -181,25 +210,20 @@
{
"type": "doc",
"label": "EGo",
- "id": "building-services/ego"
+ "id": "building-marbles/ego"
},
{
"type": "doc",
"label": "Gramine",
- "id": "building-services/gramine"
+ "id": "building-marbles/gramine"
},
{
"type": "doc",
"label": "Occlum",
- "id": "building-services/occlum"
+ "id": "building-marbles/occlum"
}
]
},
- {
- "type": "doc",
- "label": "Examples",
- "id": "examples"
- },
{
"type": "category",
"label": "Reference",