First steps with 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, and have access to a Kubernetes cluster.

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.

Step 0: Clone the demo repository

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 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 from GitHub by running the following:

git clone https://github.com/edgelesssys/emojivoto.git && cd emojivoto

Step 1: Install the control plane onto your cluster

Install MarbleRun's Coordinator control plane by running:

With SGX

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.

In simulation mode

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. 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:

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:

kubectl -n marblerun port-forward svc/coordinator-client-api 4433:4433 --address localhost >/dev/null &
export MARBLERUN=localhost:4433

Step 2: 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, which you can deploy onto MarbleRun by running the following:

With SGX

marblerun manifest set tools/manifest.json $MARBLERUN

The CLI will obtain the Coordinator's remote attestation quote and verify it against the configuration on our release page. The SGX quote proves the integrity of the Coordinator pod. The CLI saves the TLS certificate of the Coordinator as coordinator-cert.pem in your config directory. The certificate is bound to the quote and is used by the CLI for future verification. It can also be used as a root of trust for authenticating your confidential applications.

info

By default the certificate is saved to $XDG_CONFIG_HOME/marblerun/coordinator-cert.pem, or $HOME/.config/marblerun/coordinator-cert.pem if $XDG_CONFIG_HOME isn't set. Subsequent CLI commands will try loading the certificate from that location. Use the --coordinator-cert flag to choose your own location to save or load the certificate.

In simulation mode

marblerun manifest set tools/manifest.json $MARBLERUN --insecure

The insecure flag tells MarbleRun that real SGX hardware might not be present and the quote verification should be omitted. Since this bypasses all security checks on the TLS connection to the Coordinator, you MUST NOT use it in production.

You can check that the state of MarbleRun has changed and is now ready to authenticate your services by running:

With SGX

marblerun status $MARBLERUN

In simulation mode

marblerun status $MARBLERUN --insecure

Step 3: Deploy the demo application

Finally, install the demo application onto your cluster. Please make sure you have Helm ("the package manager for Kubernetes") installed at least at Version v3.2.0. Install emojivoto into the emojivoto namespace by running:

With SGX

helm install -f ./kubernetes/sgx_values.yaml emojivoto ./kubernetes --create-namespace -n emojivoto

In simulation mode

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.

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:

kubectl -n emojivoto port-forward svc/web-svc 8443:443 --address 0.0.0.0

Now visit 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
• Add your own service to MarbleRun
• Learn more about MarbleRun’s architecture
• Chat with us on Discord
• Try out the full demo on GitHub

Welcome to the MarbleRun community!