diff --git a/docs/docs/features/manifest.md b/docs/docs/features/manifest.md index 82d96389..7c525d42 100644 --- a/docs/docs/features/manifest.md +++ b/docs/docs/features/manifest.md @@ -20,7 +20,7 @@ Choose this approach for deployments with a well-defined scope, but a possibly l ## Fully updatable deployment - + The manifest allows to [permit a user to update the full manifest](../workflows/define-manifest.md#roles). With such a deployment, this user usually needs to be a trusted party. diff --git a/docs/docs/features/recovery.md b/docs/docs/features/recovery.md index 9611694c..f4a096cc 100644 --- a/docs/docs/features/recovery.md +++ b/docs/docs/features/recovery.md @@ -21,7 +21,7 @@ However, a [manual step](#recovery) is required to recover the Coordinator's sta ### Distributed Coordinator - + When you use MarbleRun [with Kubernetes](../deployment/kubernetes.md), you can scale the Coordinator to multiple instances. The instances share a common state, encrypted and stored as a Kubernetes secret. @@ -46,7 +46,7 @@ The Recovery Key's owner can access the Coordinator's raw state. ### Multi-party recovery - + Depending on the use case, it may not be acceptable that the owner has full control over the cluster. MarbleRun supports splitting the Recovery Key between parties. diff --git a/docs/docs/getting-started/installation.md b/docs/docs/getting-started/installation.md index c9a2b0f7..94a60b2a 100644 --- a/docs/docs/getting-started/installation.md +++ b/docs/docs/getting-started/installation.md @@ -28,8 +28,8 @@ Now your cluster is ready and you can install the MarbleRun CLI. CLI executables for different platforms are available at [GitHub](https://github.com/edgelesssys/marblerun/releases). The CLI needs an SGX [quote provider](https://download.01.org/intel-sgx/latest/dcap-latest/linux/docs/DCAP_ECDSA_Orientation.pdf) to verify attestation reports. - - + + The AppImage runs on all x86-64 Linux distributions with glibc v2.29 or higher. It includes the quote provider. @@ -40,8 +40,8 @@ wget https://github.com/edgelesssys/marblerun/releases/latest/download/marblerun sudo install marblerun-x86_64.AppImage /usr/local/bin/marblerun ``` - - + + Install the CLI and the quote provider with the following commands: @@ -58,8 +58,8 @@ sudo apt update sudo apt install libsgx-dcap-default-qpl ``` - - + + Install the CLI and the quote provider with the following commands: @@ -75,8 +75,8 @@ sudo apt update sudo apt install libsgx-dcap-default-qpl ``` - - + + Once installed, verify the CLI is running correctly with the following: diff --git a/docs/docs/getting-started/quickstart.md b/docs/docs/getting-started/quickstart.md index ae4a43ec..d0a63b9a 100644 --- a/docs/docs/getting-started/quickstart.md +++ b/docs/docs/getting-started/quickstart.md @@ -9,8 +9,8 @@ Depending on your setup, you may follow the quickstart for SGX-enabled clusters. Install MarbleRun's *Coordinator* control plane by running: - - + + ```bash marblerun install @@ -19,8 +19,8 @@ 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 @@ -30,8 +30,8 @@ The `marblerun install` command generates a Kubernetes manifest with all the nec 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: @@ -55,15 +55,15 @@ For this, we utilize SGX remote attestation and obtain the Coordinator's root ce 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 @@ -71,8 +71,8 @@ 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. - - + + 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. @@ -97,41 +97,41 @@ MarbleRun guarantees that the topology of your distributed app adheres to a mani 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 marblerun manifest set tools/manifest.json $MARBLERUN ``` - - + + ```bash marblerun manifest set tools/manifest.json $MARBLERUN --insecure ``` - - + + You can check that the state of MarbleRun has changed and is now ready to authenticate your services by running: - - + + ```bash marblerun status $MARBLERUN ``` - - + + ```bash marblerun status $MARBLERUN --insecure ``` - - + + ### Step 3.2: Deploy emojivoto @@ -139,22 +139,22 @@ 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 ``` - - + + ```bash helm install -f ./kubernetes/nosgx_values.yaml emojivoto ./kubernetes --create-namespace -n emojivoto ``` - - + + ## Step 4: Watch it run diff --git a/docs/docs/workflows/define-manifest.md b/docs/docs/workflows/define-manifest.md index 4f000655..f598b074 100644 --- a/docs/docs/workflows/define-manifest.md +++ b/docs/docs/workflows/define-manifest.md @@ -417,7 +417,7 @@ awk 1 ORS='\\n' public_key.pem ### Multi-party recovery - + To enable [multi-party recovery](../features/recovery.md#multi-party-recovery), first ask the other parties to generate key pairs as described above and receive their public keys via an authenticated channel. diff --git a/docs/docs/workflows/recover-coordinator.md b/docs/docs/workflows/recover-coordinator.md index 749b5175..23da81b0 100644 --- a/docs/docs/workflows/recover-coordinator.md +++ b/docs/docs/workflows/recover-coordinator.md @@ -50,7 +50,7 @@ On success, the Coordinator applies the sealed state again. If the Coordinator c ## Multi-party recovery - + If you've [configured your MarbleRun deployment for multi-party recovery](define-manifest.md#multi-party-recovery), send each party the corresponding [recovery secret](set-manifest.md). Ask them to perform the steps above. Once all parties have uploaded their secrets, the Coordinator recovers the sealed state and continues its operations. diff --git a/docs/docs/workflows/update-manifest.md b/docs/docs/workflows/update-manifest.md index ec74bcab..a5aae876 100644 --- a/docs/docs/workflows/update-manifest.md +++ b/docs/docs/workflows/update-manifest.md @@ -48,7 +48,7 @@ Don't define other values except the `SecurityVersion` value for a package, as M ## Full update - + Some deployment scenarios require more flexibility regarding changes to the manifest. To this end, MarbleRun also allows uploading a full manifest. User-defined secrets and secrets of type `symmetric-key` are retained if their definition doesn't change. diff --git a/docs/src/theme/MDXComponents.js b/docs/src/theme/MDXComponents.js index 937ce109..a4857b8a 100644 --- a/docs/src/theme/MDXComponents.js +++ b/docs/src/theme/MDXComponents.js @@ -10,7 +10,7 @@ export default { ...MDXComponents, // Map the "highlight" tag to our component! // `Highlight` will receive all props that were passed to `highlight` in MDX - tabs: Tabs, - tabItem: TabItem, - enterpriseBanner: EnterpriseBanner, + Tabs, + TabItem, + EnterpriseBanner, }; diff --git a/docs/versioned_docs/version-1.1/features/manifest.md b/docs/versioned_docs/version-1.1/features/manifest.md index 0f4bdb63..9d92853b 100644 --- a/docs/versioned_docs/version-1.1/features/manifest.md +++ b/docs/versioned_docs/version-1.1/features/manifest.md @@ -20,7 +20,7 @@ Choose this approach for deployments with a well-defined scope, but a possibly l ## Fully updatable deployment - + The manifest allows to [permit a user to update the full manifest](../workflows/define-manifest.md#roles). With such a deployment, this user usually needs to be a trusted party. diff --git a/docs/versioned_docs/version-1.1/features/recovery.md b/docs/versioned_docs/version-1.1/features/recovery.md index b718af6e..7bbfeb92 100644 --- a/docs/versioned_docs/version-1.1/features/recovery.md +++ b/docs/versioned_docs/version-1.1/features/recovery.md @@ -21,7 +21,7 @@ However, when the Coordinator is moved to another physical host, a [manual step] ### Distributed Coordinator - + When you use MarbleRun [with Kubernetes](../deployment/kubernetes.md), you can scale the Coordinator to multiple instances. The instances share a common state, encrypted and stored as a Kubernetes secret. @@ -47,7 +47,7 @@ The owner of the Recovery Key can access the raw state of the Coordinator. ### Multi-party recovery - + Depending on the use case, it may not be acceptable that the owner has full control over the cluster. MarbleRun supports splitting the Recovery Key between parties. diff --git a/docs/versioned_docs/version-1.1/getting-started/quickstart.md b/docs/versioned_docs/version-1.1/getting-started/quickstart.md index a0e3adbd..80da2ea8 100644 --- a/docs/versioned_docs/version-1.1/getting-started/quickstart.md +++ b/docs/versioned_docs/version-1.1/getting-started/quickstart.md @@ -31,24 +31,24 @@ If this is your first time running MarbleRun, you will need to download the Marb To install the CLI, run: - - + + ```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: diff --git a/docs/versioned_docs/version-1.1/reference/cli.md b/docs/versioned_docs/version-1.1/reference/cli.md index 8c219f26..7079fe8a 100644 --- a/docs/versioned_docs/version-1.1/reference/cli.md +++ b/docs/versioned_docs/version-1.1/reference/cli.md @@ -7,24 +7,24 @@ This CLI allows you to install MarbleRun on your cluster and interacts with the To install the MarbleRun CLI on your machine you can use our pre-built binaries. - - + + ```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 ``` - - + + To build the MarbleRun CLI, [Edgeless RT](https://github.com/edgelesssys/edgelessrt) needs to be installed on your machine. @@ -33,16 +33,16 @@ git clone https://github.com/edgelesssys/marblerun && cd ./marblerun go build -buildvcs=false -o marblerun ./cli ``` - - + + ### Requirements The CLI requires an SGX quote verification library to verify quotes issued by the Coordinator. You have different options depending on the environment the Coordinator is deployed to: - - + + If the Coordinator is running on an Azure VM, the CLI relies on the [Azure DCAP Client](https://github.com/microsoft/Azure-DCAP-Client) to verify quotes. To install the dependency on Ubuntu 20.04 run: @@ -54,8 +54,8 @@ sudo apt update sudo apt install -y az-dcap-client ``` - - + + Intel provides the `libsgx-dcap-default-qpl` library to facilitate SGX quote verification. To install the dependency on Ubuntu 20.04 run: @@ -68,8 +68,8 @@ sudo apt install -y libsgx-dcap-default-qpl ``` Follow [Intel's documentation](https://github.com/intel/SGXDataCenterAttestationPrimitives/blob/master/QuoteGeneration/qpl/README.md#configuration) to configure access to the PCCS. - - + + ## Reference @@ -933,4 +933,3 @@ marblerun version [flags] --era-config string Path to remote attestation config file in json format, if none provided the newest configuration will be loaded from github -i, --insecure Set to skip quote verification, needed when running in simulation mode ``` - diff --git a/docs/versioned_docs/version-1.1/workflows/define-manifest.md b/docs/versioned_docs/version-1.1/workflows/define-manifest.md index 4f000655..f598b074 100644 --- a/docs/versioned_docs/version-1.1/workflows/define-manifest.md +++ b/docs/versioned_docs/version-1.1/workflows/define-manifest.md @@ -417,7 +417,7 @@ awk 1 ORS='\\n' public_key.pem ### Multi-party recovery - + To enable [multi-party recovery](../features/recovery.md#multi-party-recovery), first ask the other parties to generate key pairs as described above and receive their public keys via an authenticated channel. diff --git a/docs/versioned_docs/version-1.1/workflows/recover-coordinator.md b/docs/versioned_docs/version-1.1/workflows/recover-coordinator.md index 749b5175..23da81b0 100644 --- a/docs/versioned_docs/version-1.1/workflows/recover-coordinator.md +++ b/docs/versioned_docs/version-1.1/workflows/recover-coordinator.md @@ -50,7 +50,7 @@ On success, the Coordinator applies the sealed state again. If the Coordinator c ## Multi-party recovery - + If you've [configured your MarbleRun deployment for multi-party recovery](define-manifest.md#multi-party-recovery), send each party the corresponding [recovery secret](set-manifest.md). Ask them to perform the steps above. Once all parties have uploaded their secrets, the Coordinator recovers the sealed state and continues its operations. diff --git a/docs/versioned_docs/version-1.1/workflows/update-manifest.md b/docs/versioned_docs/version-1.1/workflows/update-manifest.md index ec74bcab..a5aae876 100644 --- a/docs/versioned_docs/version-1.1/workflows/update-manifest.md +++ b/docs/versioned_docs/version-1.1/workflows/update-manifest.md @@ -48,7 +48,7 @@ Don't define other values except the `SecurityVersion` value for a package, as M ## Full update - + Some deployment scenarios require more flexibility regarding changes to the manifest. To this end, MarbleRun also allows uploading a full manifest. User-defined secrets and secrets of type `symmetric-key` are retained if their definition doesn't change. diff --git a/docs/versioned_docs/version-1.2/features/manifest.md b/docs/versioned_docs/version-1.2/features/manifest.md index 82d96389..7c525d42 100644 --- a/docs/versioned_docs/version-1.2/features/manifest.md +++ b/docs/versioned_docs/version-1.2/features/manifest.md @@ -20,7 +20,7 @@ Choose this approach for deployments with a well-defined scope, but a possibly l ## Fully updatable deployment - + The manifest allows to [permit a user to update the full manifest](../workflows/define-manifest.md#roles). With such a deployment, this user usually needs to be a trusted party. diff --git a/docs/versioned_docs/version-1.2/features/recovery.md b/docs/versioned_docs/version-1.2/features/recovery.md index 9611694c..f4a096cc 100644 --- a/docs/versioned_docs/version-1.2/features/recovery.md +++ b/docs/versioned_docs/version-1.2/features/recovery.md @@ -21,7 +21,7 @@ However, a [manual step](#recovery) is required to recover the Coordinator's sta ### Distributed Coordinator - + When you use MarbleRun [with Kubernetes](../deployment/kubernetes.md), you can scale the Coordinator to multiple instances. The instances share a common state, encrypted and stored as a Kubernetes secret. @@ -46,7 +46,7 @@ The Recovery Key's owner can access the Coordinator's raw state. ### Multi-party recovery - + Depending on the use case, it may not be acceptable that the owner has full control over the cluster. MarbleRun supports splitting the Recovery Key between parties. diff --git a/docs/versioned_docs/version-1.2/getting-started/installation.md b/docs/versioned_docs/version-1.2/getting-started/installation.md index 7640d34a..df763a4e 100644 --- a/docs/versioned_docs/version-1.2/getting-started/installation.md +++ b/docs/versioned_docs/version-1.2/getting-started/installation.md @@ -29,24 +29,24 @@ If this is your first time running MarbleRun, you will need to download the Marb 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: 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 ae4a43ec..d0a63b9a 100644 --- a/docs/versioned_docs/version-1.2/getting-started/quickstart.md +++ b/docs/versioned_docs/version-1.2/getting-started/quickstart.md @@ -9,8 +9,8 @@ Depending on your setup, you may follow the quickstart for SGX-enabled clusters. Install MarbleRun's *Coordinator* control plane by running: - - + + ```bash marblerun install @@ -19,8 +19,8 @@ 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 @@ -30,8 +30,8 @@ The `marblerun install` command generates a Kubernetes manifest with all the nec 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: @@ -55,15 +55,15 @@ For this, we utilize SGX remote attestation and obtain the Coordinator's root ce 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 @@ -71,8 +71,8 @@ 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. - - + + 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. @@ -97,41 +97,41 @@ MarbleRun guarantees that the topology of your distributed app adheres to a mani 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 marblerun manifest set tools/manifest.json $MARBLERUN ``` - - + + ```bash marblerun manifest set tools/manifest.json $MARBLERUN --insecure ``` - - + + You can check that the state of MarbleRun has changed and is now ready to authenticate your services by running: - - + + ```bash marblerun status $MARBLERUN ``` - - + + ```bash marblerun status $MARBLERUN --insecure ``` - - + + ### Step 3.2: Deploy emojivoto @@ -139,22 +139,22 @@ 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 ``` - - + + ```bash helm install -f ./kubernetes/nosgx_values.yaml emojivoto ./kubernetes --create-namespace -n emojivoto ``` - - + + ## Step 4: Watch it run diff --git a/docs/versioned_docs/version-1.2/reference/cli.md b/docs/versioned_docs/version-1.2/reference/cli.md index 1081a446..33fbf561 100644 --- a/docs/versioned_docs/version-1.2/reference/cli.md +++ b/docs/versioned_docs/version-1.2/reference/cli.md @@ -7,24 +7,24 @@ This CLI allows you to install MarbleRun on your cluster and interacts with the To install the MarbleRun CLI on your machine you can use our pre-built binaries. - - + + ```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 ``` - - + + To build the MarbleRun CLI, [Edgeless RT](https://github.com/edgelesssys/edgelessrt) needs to be installed on your machine. @@ -33,16 +33,16 @@ git clone https://github.com/edgelesssys/marblerun && cd ./marblerun go build -buildvcs=false -o marblerun ./cli ``` - - + + ### Requirements The CLI requires an SGX quote verification library to verify quotes issued by the Coordinator. You have different options depending on the environment the Coordinator is deployed to: - - + + If the Coordinator is running on an Azure VM, the CLI relies on the [Azure DCAP Client](https://github.com/microsoft/Azure-DCAP-Client) to verify quotes. To install the dependency on Ubuntu 20.04 run: @@ -54,8 +54,8 @@ sudo apt update sudo apt install -y az-dcap-client ``` - - + + Intel provides the `libsgx-dcap-default-qpl` library to facilitate SGX quote verification. To install the dependency on Ubuntu 20.04 run: @@ -68,8 +68,8 @@ sudo apt install -y libsgx-dcap-default-qpl ``` Follow [Intel's documentation](https://github.com/intel/SGXDataCenterAttestationPrimitives/blob/master/QuoteGeneration/qpl/README.md#configuration) to configure access to the PCCS. - - + + ## Reference @@ -934,4 +934,3 @@ marblerun version [flags] --era-config string Path to remote attestation config file in json format, if none provided the newest configuration will be loaded from github -i, --insecure Set to skip quote verification, needed when running in simulation mode ``` - diff --git a/docs/versioned_docs/version-1.2/workflows/define-manifest.md b/docs/versioned_docs/version-1.2/workflows/define-manifest.md index 4f000655..f598b074 100644 --- a/docs/versioned_docs/version-1.2/workflows/define-manifest.md +++ b/docs/versioned_docs/version-1.2/workflows/define-manifest.md @@ -417,7 +417,7 @@ awk 1 ORS='\\n' public_key.pem ### Multi-party recovery - + To enable [multi-party recovery](../features/recovery.md#multi-party-recovery), first ask the other parties to generate key pairs as described above and receive their public keys via an authenticated channel. diff --git a/docs/versioned_docs/version-1.2/workflows/recover-coordinator.md b/docs/versioned_docs/version-1.2/workflows/recover-coordinator.md index 749b5175..23da81b0 100644 --- a/docs/versioned_docs/version-1.2/workflows/recover-coordinator.md +++ b/docs/versioned_docs/version-1.2/workflows/recover-coordinator.md @@ -50,7 +50,7 @@ On success, the Coordinator applies the sealed state again. If the Coordinator c ## Multi-party recovery - + If you've [configured your MarbleRun deployment for multi-party recovery](define-manifest.md#multi-party-recovery), send each party the corresponding [recovery secret](set-manifest.md). Ask them to perform the steps above. Once all parties have uploaded their secrets, the Coordinator recovers the sealed state and continues its operations. diff --git a/docs/versioned_docs/version-1.2/workflows/update-manifest.md b/docs/versioned_docs/version-1.2/workflows/update-manifest.md index ec74bcab..a5aae876 100644 --- a/docs/versioned_docs/version-1.2/workflows/update-manifest.md +++ b/docs/versioned_docs/version-1.2/workflows/update-manifest.md @@ -48,7 +48,7 @@ Don't define other values except the `SecurityVersion` value for a package, as M ## Full update - + Some deployment scenarios require more flexibility regarding changes to the manifest. To this end, MarbleRun also allows uploading a full manifest. User-defined secrets and secrets of type `symmetric-key` are retained if their definition doesn't change. diff --git a/docs/versioned_docs/version-1.3/features/manifest.md b/docs/versioned_docs/version-1.3/features/manifest.md index 82d96389..7c525d42 100644 --- a/docs/versioned_docs/version-1.3/features/manifest.md +++ b/docs/versioned_docs/version-1.3/features/manifest.md @@ -20,7 +20,7 @@ Choose this approach for deployments with a well-defined scope, but a possibly l ## Fully updatable deployment - + The manifest allows to [permit a user to update the full manifest](../workflows/define-manifest.md#roles). With such a deployment, this user usually needs to be a trusted party. diff --git a/docs/versioned_docs/version-1.3/features/recovery.md b/docs/versioned_docs/version-1.3/features/recovery.md index 9611694c..f4a096cc 100644 --- a/docs/versioned_docs/version-1.3/features/recovery.md +++ b/docs/versioned_docs/version-1.3/features/recovery.md @@ -21,7 +21,7 @@ However, a [manual step](#recovery) is required to recover the Coordinator's sta ### Distributed Coordinator - + When you use MarbleRun [with Kubernetes](../deployment/kubernetes.md), you can scale the Coordinator to multiple instances. The instances share a common state, encrypted and stored as a Kubernetes secret. @@ -46,7 +46,7 @@ The Recovery Key's owner can access the Coordinator's raw state. ### Multi-party recovery - + Depending on the use case, it may not be acceptable that the owner has full control over the cluster. MarbleRun supports splitting the Recovery Key between parties. diff --git a/docs/versioned_docs/version-1.3/getting-started/installation.md b/docs/versioned_docs/version-1.3/getting-started/installation.md index c9a2b0f7..94a60b2a 100644 --- a/docs/versioned_docs/version-1.3/getting-started/installation.md +++ b/docs/versioned_docs/version-1.3/getting-started/installation.md @@ -28,8 +28,8 @@ Now your cluster is ready and you can install the MarbleRun CLI. CLI executables for different platforms are available at [GitHub](https://github.com/edgelesssys/marblerun/releases). The CLI needs an SGX [quote provider](https://download.01.org/intel-sgx/latest/dcap-latest/linux/docs/DCAP_ECDSA_Orientation.pdf) to verify attestation reports. - - + + The AppImage runs on all x86-64 Linux distributions with glibc v2.29 or higher. It includes the quote provider. @@ -40,8 +40,8 @@ wget https://github.com/edgelesssys/marblerun/releases/latest/download/marblerun sudo install marblerun-x86_64.AppImage /usr/local/bin/marblerun ``` - - + + Install the CLI and the quote provider with the following commands: @@ -58,8 +58,8 @@ sudo apt update sudo apt install libsgx-dcap-default-qpl ``` - - + + Install the CLI and the quote provider with the following commands: @@ -75,8 +75,8 @@ sudo apt update sudo apt install libsgx-dcap-default-qpl ``` - - + + Once installed, verify the CLI is running correctly with the following: diff --git a/docs/versioned_docs/version-1.3/getting-started/quickstart.md b/docs/versioned_docs/version-1.3/getting-started/quickstart.md index ae4a43ec..d0a63b9a 100644 --- a/docs/versioned_docs/version-1.3/getting-started/quickstart.md +++ b/docs/versioned_docs/version-1.3/getting-started/quickstart.md @@ -9,8 +9,8 @@ Depending on your setup, you may follow the quickstart for SGX-enabled clusters. Install MarbleRun's *Coordinator* control plane by running: - - + + ```bash marblerun install @@ -19,8 +19,8 @@ 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 @@ -30,8 +30,8 @@ The `marblerun install` command generates a Kubernetes manifest with all the nec 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: @@ -55,15 +55,15 @@ For this, we utilize SGX remote attestation and obtain the Coordinator's root ce 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 @@ -71,8 +71,8 @@ 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. - - + + 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. @@ -97,41 +97,41 @@ MarbleRun guarantees that the topology of your distributed app adheres to a mani 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 marblerun manifest set tools/manifest.json $MARBLERUN ``` - - + + ```bash marblerun manifest set tools/manifest.json $MARBLERUN --insecure ``` - - + + You can check that the state of MarbleRun has changed and is now ready to authenticate your services by running: - - + + ```bash marblerun status $MARBLERUN ``` - - + + ```bash marblerun status $MARBLERUN --insecure ``` - - + + ### Step 3.2: Deploy emojivoto @@ -139,22 +139,22 @@ 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 ``` - - + + ```bash helm install -f ./kubernetes/nosgx_values.yaml emojivoto ./kubernetes --create-namespace -n emojivoto ``` - - + + ## Step 4: Watch it run diff --git a/docs/versioned_docs/version-1.3/workflows/define-manifest.md b/docs/versioned_docs/version-1.3/workflows/define-manifest.md index 4f000655..f598b074 100644 --- a/docs/versioned_docs/version-1.3/workflows/define-manifest.md +++ b/docs/versioned_docs/version-1.3/workflows/define-manifest.md @@ -417,7 +417,7 @@ awk 1 ORS='\\n' public_key.pem ### Multi-party recovery - + To enable [multi-party recovery](../features/recovery.md#multi-party-recovery), first ask the other parties to generate key pairs as described above and receive their public keys via an authenticated channel. diff --git a/docs/versioned_docs/version-1.3/workflows/recover-coordinator.md b/docs/versioned_docs/version-1.3/workflows/recover-coordinator.md index 749b5175..23da81b0 100644 --- a/docs/versioned_docs/version-1.3/workflows/recover-coordinator.md +++ b/docs/versioned_docs/version-1.3/workflows/recover-coordinator.md @@ -50,7 +50,7 @@ On success, the Coordinator applies the sealed state again. If the Coordinator c ## Multi-party recovery - + If you've [configured your MarbleRun deployment for multi-party recovery](define-manifest.md#multi-party-recovery), send each party the corresponding [recovery secret](set-manifest.md). Ask them to perform the steps above. Once all parties have uploaded their secrets, the Coordinator recovers the sealed state and continues its operations. diff --git a/docs/versioned_docs/version-1.3/workflows/update-manifest.md b/docs/versioned_docs/version-1.3/workflows/update-manifest.md index ec74bcab..a5aae876 100644 --- a/docs/versioned_docs/version-1.3/workflows/update-manifest.md +++ b/docs/versioned_docs/version-1.3/workflows/update-manifest.md @@ -48,7 +48,7 @@ Don't define other values except the `SecurityVersion` value for a package, as M ## Full update - + Some deployment scenarios require more flexibility regarding changes to the manifest. To this end, MarbleRun also allows uploading a full manifest. User-defined secrets and secrets of type `symmetric-key` are retained if their definition doesn't change.