diff --git a/docs/docs/deployment/kubernetes.md b/docs/docs/deployment/kubernetes.md index a71bd21e1..b1b8230aa 100644 --- a/docs/docs/deployment/kubernetes.md +++ b/docs/docs/deployment/kubernetes.md @@ -89,17 +89,44 @@ You can follow [the AKS guide](https://learn.microsoft.com/en-us/azure/confident Use MarbleRun's [CLI](../reference/cli.md) that facilitates the administrative tasks. You can install MarbleRun using the CLI as follows: -* For a cluster with SGX support: + - ```bash - marblerun install --domain=mycluster.uksouth.cloudapp.azure.com - ``` + -* For a cluster without SGX support: +```bash +marblerun install --distributed-deployment --domain=mycluster.uksouth.cloudapp.azure.com +``` + +The distributed deployment mode allows you to scale the MarbleRun Coordinator across different nodes on your cluster. +This ensures high availability of MarbleRun's control plane and is the recommended deployment mode for production use cases. + +See [the key management documentation](../architecture/security.md#distributed-coordinator) for more details on how distributed MarbleRun deployments manage their state. + + + + + +```bash +marblerun install --domain=mycluster.uksouth.cloudapp.azure.com +``` + +The standalone installation deploys a single MarbleRun Coordinator. +Please note that moving the Pod to a different node requires [manual recovery](../workflows/recover-coordinator.md). +Consider using a distributed deployment if availability, scaling, or automatic recovery are a concern. + + + + - ```bash - marblerun install --domain=mycluster.uksouth.cloudapp.azure.com --simulation - ``` +```bash +marblerun install --domain=mycluster.uksouth.cloudapp.azure.com --simulation +``` + +MarbleRun's simulation mode deploys a single Coordinator instance without the need for SGX support. +Since the Coordinator isn't actually running in an SGX enclave, this mode must only be used for evaluation and testing purposes. + + + This command will pull the latest Helm chart from [our repository](https:/helm.edgeless.systems) and manages the installation of said chart. @@ -132,30 +159,64 @@ Review the `values.yaml` file of the chart for a full list of available configur Update the hostname with your cluster's FQDN. -* For a cluster with SGX support: + - ```bash - helm install marblerun edgeless/marblerun \ - --create-namespace \ - -n marblerun \ - --set coordinator.hostname=mycluster.uksouth.cloudapp.azure.com \ - --set marbleInjector.start=true \ - --set marbleInjector.useCertManager=true - ``` + -* For a cluster without SGX support: +```bash +helm install marblerun edgeless/marblerun \ + --create-namespace \ + -n marblerun \ + --set coordinator.replicas=3 \ + --set coordinator.distributedDeployment=true \ + --set coordinator.hostname=mycluster.uksouth.cloudapp.azure.com \ + --set marbleInjector.start=true \ + --set marbleInjector.useCertManager=true +``` - ```bash - helm install marblerun edgeless/marblerun \ - --create-namespace \ - -n marblerun \ - --set coordinator.resources=null \ - --set coordinator.simulation=1 \ - --set tolerations=null \ - --set coordinator.hostname=mycluster.uksouth.cloudapp.azure.com \ - --set marbleInjector.start=true \ - --set marbleInjector.useCertManager=true - ``` +The distributed deployment mode allows you to scale the MarbleRun Coordinator across different nodes on your cluster. +This ensures high availability of MarbleRun's control plane and is the recommended deployment mode for production use cases. + +See [the key management documentation](../architecture/security.md#distributed-coordinator) for more details on how distributed MarbleRun deployments manage their state. + + + + + +```bash +helm install marblerun edgeless/marblerun \ + --create-namespace \ + -n marblerun \ + --set coordinator.hostname=mycluster.uksouth.cloudapp.azure.com \ + --set marbleInjector.start=true \ + --set marbleInjector.useCertManager=true +``` + +The standalone installation deploys a single MarbleRun Coordinator. +Please note that moving the Pod to a different node requires [manual recovery](../workflows/recover-coordinator.md). +Consider using a distributed deployment if availability, scaling, or automatic recovery are a concern. + + + + + +```bash +helm install marblerun edgeless/marblerun \ + --create-namespace \ + -n marblerun \ + --set coordinator.resources=null \ + --set coordinator.simulation=1 \ + --set tolerations=null \ + --set coordinator.hostname=mycluster.uksouth.cloudapp.azure.com \ + --set marbleInjector.start=true \ + --set marbleInjector.useCertManager=true +``` + +MarbleRun's simulation mode deploys a single Coordinator instance without the need for SGX support. +Since the Coordinator isn't actually running in an SGX enclave, this mode must only be used for evaluation and testing purposes. + + + By default `coordinator.hostname` is set to `localhost`. The domain is used as the CommonName in the Coordinator's TLS certificate. @@ -198,13 +259,27 @@ Otherwise, set the [necessary configuration](https://github.com/intel/SGXDataCen marblerun install --dcap-pccs-url --dcap-secure-cert ``` + or pass the path to a custom DCAP config file using `--dcap-qcnl-config-file`: + + ```bash + marblerun install --dcap-qcnl-config-file=/path/to/sgx_qcnl.conf + ``` + * Using Helm ```bash helm install marblerun edgeless/marblerun \ --create-namespace \ -n marblerun \ - --set coordinator.hostname=mycluster.uksouth.cloudapp.azure.com \ --set dcap.pccsUrl= \ --set dcap.useSecureCert= ``` + + or pass the path to a custom DCAP config to Helm: + + ```bash + helm install marblerun edgeless/marblerun \ + --create-namespace \ + -n marblerun \ + --set-file dcap.qcnlConfig=/path/to/sgx_qcnl.conf + ``` diff --git a/docs/docs/reference/coordinator.md b/docs/docs/reference/coordinator.md index 82d5c7cff..73b3bd562 100644 --- a/docs/docs/reference/coordinator.md +++ b/docs/docs/reference/coordinator.md @@ -163,7 +163,7 @@ Example request body: #### Returns -* `recoveryKeys` object +* `RecoverySecrets` object An optional field that will be present if the manifest contains `RecoveryKeys`. Key-value mapping of strings to strings, where the key matches each supplied key from `RecoveryKeys` in the manifest, @@ -175,7 +175,7 @@ Example response: { "status": "success", "data": { - "recoveryKeys": { + "RecoverySecrets": { "recoveryKey1": "ZW5jcnlwdGVkUmVjb3ZlcnlTZWNyZXQxCg==", "recoveryKey2": "ZW5jcnlwdGVkUmVjb3ZlcnlTZWNyZXQyCg==" } @@ -407,6 +407,45 @@ Example response: +## Retrieve Coordinator recovery public key + + + + +```http +GET /api/v2/recover/public-key +``` + +Retrieve a public key for encryption of recovery secrets. +Use the returned key to encrypt your decrypted recovery secret before sending it to a Coordinator for recovery. +See [the offline recovery secret signing workflow](../workflows/recover-coordinator.md#offline-recovery-secret-signing) for more details on how the endpoint is used. + +#### Returns + +* `algorithm` string + + Algorithm of the key, for example `RSA`. + Currently, only RSA is supported. + +* `ephemeralPublicKey` string + + DER encoded public key + +Example response: + +```JSON +{ + "status": "success", + "data": { + "algorithm": "RSA", + "ephemeralPublicKey": "MIICIjANBgkqhkiG9...EAAQ==" + } +} +``` + + + + ## Retrieve MarbleRun managed secrets @@ -907,6 +946,13 @@ Example request body: An array of user IDs that haven't yet acknowledged the update. +* `recoverySecrets` object + + An optional field that will be present if the manifest was successfully applied, + and the new manifest's `RecoveryKeys` differ from the previous one. + Key-value mapping of strings to strings, where the key matches each supplied key from `RecoveryKeys` in the new manifest, + and the value is the base64 encoded encrypted recovery secret. + Example response: ```json @@ -1015,6 +1061,13 @@ Example request body: An array of user IDs that haven't yet acknowledged the update. +* `recoverySecrets` object + + An optional field that will be present if the manifest was successfully applied, + and the new manifest's `RecoveryKeys` differ from the previous one. + Key-value mapping of strings to strings, where the key matches each supplied key from `RecoveryKeys` in the new manifest, + and the value is the base64 encoded encrypted recovery secret. + Example response: ```JSON diff --git a/docs/styles/config/vocabularies/edgeless/accept.txt b/docs/styles/config/vocabularies/edgeless/accept.txt index 0b671f639..0ae9d3664 100644 --- a/docs/styles/config/vocabularies/edgeless/accept.txt +++ b/docs/styles/config/vocabularies/edgeless/accept.txt @@ -8,6 +8,8 @@ collateral config CPU crypto +DCAP +DER Dockerfile emojivoto Env @@ -33,6 +35,7 @@ precheck premain Redis runtime +SGX subcommand Tensorflow toleration diff --git a/docs/versioned_docs/version-1.9/deployment/kubernetes.md b/docs/versioned_docs/version-1.9/deployment/kubernetes.md index a71bd21e1..b1b8230aa 100644 --- a/docs/versioned_docs/version-1.9/deployment/kubernetes.md +++ b/docs/versioned_docs/version-1.9/deployment/kubernetes.md @@ -89,17 +89,44 @@ You can follow [the AKS guide](https://learn.microsoft.com/en-us/azure/confident Use MarbleRun's [CLI](../reference/cli.md) that facilitates the administrative tasks. You can install MarbleRun using the CLI as follows: -* For a cluster with SGX support: + - ```bash - marblerun install --domain=mycluster.uksouth.cloudapp.azure.com - ``` + -* For a cluster without SGX support: +```bash +marblerun install --distributed-deployment --domain=mycluster.uksouth.cloudapp.azure.com +``` + +The distributed deployment mode allows you to scale the MarbleRun Coordinator across different nodes on your cluster. +This ensures high availability of MarbleRun's control plane and is the recommended deployment mode for production use cases. + +See [the key management documentation](../architecture/security.md#distributed-coordinator) for more details on how distributed MarbleRun deployments manage their state. + + + + + +```bash +marblerun install --domain=mycluster.uksouth.cloudapp.azure.com +``` + +The standalone installation deploys a single MarbleRun Coordinator. +Please note that moving the Pod to a different node requires [manual recovery](../workflows/recover-coordinator.md). +Consider using a distributed deployment if availability, scaling, or automatic recovery are a concern. + + + + - ```bash - marblerun install --domain=mycluster.uksouth.cloudapp.azure.com --simulation - ``` +```bash +marblerun install --domain=mycluster.uksouth.cloudapp.azure.com --simulation +``` + +MarbleRun's simulation mode deploys a single Coordinator instance without the need for SGX support. +Since the Coordinator isn't actually running in an SGX enclave, this mode must only be used for evaluation and testing purposes. + + + This command will pull the latest Helm chart from [our repository](https:/helm.edgeless.systems) and manages the installation of said chart. @@ -132,30 +159,64 @@ Review the `values.yaml` file of the chart for a full list of available configur Update the hostname with your cluster's FQDN. -* For a cluster with SGX support: + - ```bash - helm install marblerun edgeless/marblerun \ - --create-namespace \ - -n marblerun \ - --set coordinator.hostname=mycluster.uksouth.cloudapp.azure.com \ - --set marbleInjector.start=true \ - --set marbleInjector.useCertManager=true - ``` + -* For a cluster without SGX support: +```bash +helm install marblerun edgeless/marblerun \ + --create-namespace \ + -n marblerun \ + --set coordinator.replicas=3 \ + --set coordinator.distributedDeployment=true \ + --set coordinator.hostname=mycluster.uksouth.cloudapp.azure.com \ + --set marbleInjector.start=true \ + --set marbleInjector.useCertManager=true +``` - ```bash - helm install marblerun edgeless/marblerun \ - --create-namespace \ - -n marblerun \ - --set coordinator.resources=null \ - --set coordinator.simulation=1 \ - --set tolerations=null \ - --set coordinator.hostname=mycluster.uksouth.cloudapp.azure.com \ - --set marbleInjector.start=true \ - --set marbleInjector.useCertManager=true - ``` +The distributed deployment mode allows you to scale the MarbleRun Coordinator across different nodes on your cluster. +This ensures high availability of MarbleRun's control plane and is the recommended deployment mode for production use cases. + +See [the key management documentation](../architecture/security.md#distributed-coordinator) for more details on how distributed MarbleRun deployments manage their state. + + + + + +```bash +helm install marblerun edgeless/marblerun \ + --create-namespace \ + -n marblerun \ + --set coordinator.hostname=mycluster.uksouth.cloudapp.azure.com \ + --set marbleInjector.start=true \ + --set marbleInjector.useCertManager=true +``` + +The standalone installation deploys a single MarbleRun Coordinator. +Please note that moving the Pod to a different node requires [manual recovery](../workflows/recover-coordinator.md). +Consider using a distributed deployment if availability, scaling, or automatic recovery are a concern. + + + + + +```bash +helm install marblerun edgeless/marblerun \ + --create-namespace \ + -n marblerun \ + --set coordinator.resources=null \ + --set coordinator.simulation=1 \ + --set tolerations=null \ + --set coordinator.hostname=mycluster.uksouth.cloudapp.azure.com \ + --set marbleInjector.start=true \ + --set marbleInjector.useCertManager=true +``` + +MarbleRun's simulation mode deploys a single Coordinator instance without the need for SGX support. +Since the Coordinator isn't actually running in an SGX enclave, this mode must only be used for evaluation and testing purposes. + + + By default `coordinator.hostname` is set to `localhost`. The domain is used as the CommonName in the Coordinator's TLS certificate. @@ -198,13 +259,27 @@ Otherwise, set the [necessary configuration](https://github.com/intel/SGXDataCen marblerun install --dcap-pccs-url --dcap-secure-cert ``` + or pass the path to a custom DCAP config file using `--dcap-qcnl-config-file`: + + ```bash + marblerun install --dcap-qcnl-config-file=/path/to/sgx_qcnl.conf + ``` + * Using Helm ```bash helm install marblerun edgeless/marblerun \ --create-namespace \ -n marblerun \ - --set coordinator.hostname=mycluster.uksouth.cloudapp.azure.com \ --set dcap.pccsUrl= \ --set dcap.useSecureCert= ``` + + or pass the path to a custom DCAP config to Helm: + + ```bash + helm install marblerun edgeless/marblerun \ + --create-namespace \ + -n marblerun \ + --set-file dcap.qcnlConfig=/path/to/sgx_qcnl.conf + ``` diff --git a/docs/versioned_docs/version-1.9/reference/coordinator.md b/docs/versioned_docs/version-1.9/reference/coordinator.md index 82d5c7cff..73b3bd562 100644 --- a/docs/versioned_docs/version-1.9/reference/coordinator.md +++ b/docs/versioned_docs/version-1.9/reference/coordinator.md @@ -163,7 +163,7 @@ Example request body: #### Returns -* `recoveryKeys` object +* `RecoverySecrets` object An optional field that will be present if the manifest contains `RecoveryKeys`. Key-value mapping of strings to strings, where the key matches each supplied key from `RecoveryKeys` in the manifest, @@ -175,7 +175,7 @@ Example response: { "status": "success", "data": { - "recoveryKeys": { + "RecoverySecrets": { "recoveryKey1": "ZW5jcnlwdGVkUmVjb3ZlcnlTZWNyZXQxCg==", "recoveryKey2": "ZW5jcnlwdGVkUmVjb3ZlcnlTZWNyZXQyCg==" } @@ -407,6 +407,45 @@ Example response: +## Retrieve Coordinator recovery public key + + + + +```http +GET /api/v2/recover/public-key +``` + +Retrieve a public key for encryption of recovery secrets. +Use the returned key to encrypt your decrypted recovery secret before sending it to a Coordinator for recovery. +See [the offline recovery secret signing workflow](../workflows/recover-coordinator.md#offline-recovery-secret-signing) for more details on how the endpoint is used. + +#### Returns + +* `algorithm` string + + Algorithm of the key, for example `RSA`. + Currently, only RSA is supported. + +* `ephemeralPublicKey` string + + DER encoded public key + +Example response: + +```JSON +{ + "status": "success", + "data": { + "algorithm": "RSA", + "ephemeralPublicKey": "MIICIjANBgkqhkiG9...EAAQ==" + } +} +``` + + + + ## Retrieve MarbleRun managed secrets @@ -907,6 +946,13 @@ Example request body: An array of user IDs that haven't yet acknowledged the update. +* `recoverySecrets` object + + An optional field that will be present if the manifest was successfully applied, + and the new manifest's `RecoveryKeys` differ from the previous one. + Key-value mapping of strings to strings, where the key matches each supplied key from `RecoveryKeys` in the new manifest, + and the value is the base64 encoded encrypted recovery secret. + Example response: ```json @@ -1015,6 +1061,13 @@ Example request body: An array of user IDs that haven't yet acknowledged the update. +* `recoverySecrets` object + + An optional field that will be present if the manifest was successfully applied, + and the new manifest's `RecoveryKeys` differ from the previous one. + Key-value mapping of strings to strings, where the key matches each supplied key from `RecoveryKeys` in the new manifest, + and the value is the base64 encoded encrypted recovery secret. + Example response: ```JSON