Restructure config docs (#44)

* more guided UX when generating and filling in config
Signed-off-by: Fabian Kammel <fk@edgeless.systems>

cli/internal/cmd/configgenerate.go

@@ -65,6 +65,9 @@ func configGenerate(cmd *cobra.Command, fileHandler file.Handler, provider cloud
 	cmd.Println("Please fill in your CSP specific configuration before proceeding.")
 	cmd.Println("You can find the list of supported virtual machine types by executing:")
 	cmd.Println("\tconstellation config instance-types")
+	cmd.Println("Fore more information refer to our documentation:")
+	cmd.Println("\thttps://constellation-docs.edgeless.systems/constellation/getting-started/first-steps#create-a-cluster")
+
 	return nil
 }
 

docs/docs/getting-started/first-steps.md

@@ -9,10 +9,6 @@ The following steps will guide you through the process of creating a cluster and
     <tabs>
     <tabItem value="azure" label="Azure" default>
 
-    On Azure you also need a *user-assigned managed identity* with the [correct permissions](install.md?id=authorization).
-
-    Then execute:
-
     ```bash
     constellation config generate azure
     ```
@@ -27,11 +23,109 @@ The following steps will guide you through the process of creating a cluster and
     </tabItem>
     </tabs>
 
-    This creates the file `constellation-conf.yaml` in your current working directory. Edit this file to set your cloud subscription IDs and optionally customize further options of your Constellation cluster. All configuration options are documented in this file.
+    This creates the file `constellation-conf.yaml` in your current working directory.
 
-    For more details, see the [reference section](../reference/config.md#required-customizations).
+2.  Fill in your cloud provider specific information:
 
-2. Download the measurements for your configured image.
+    <tabs>
+    <tabItem value="azure-cli" label="Azure (CLI)" default>
+
+    For a quick start it's recommended to use our `az` script to automatically create all required resources:
+
+    ```bash
+    RESOURCE_GROUP=constellation # enter name of resource group here
+    LOCATION=westus # enter location of resources here
+    SUBSCRIPTION_ID=$(az account show --query id --out tsv)
+    SERVICE_PRINCIPLE_NAME=constell
+    az group create --name "${RESOURCE_GROUP}" --location "${LOCATION}"
+    az group create --name "${RESOURCE_GROUP}-identity" --location "${LOCATION}"
+    az ad sp create-for-rbac -n "${SERVICE_PRINCIPLE_NAME}" --role Owner --scopes "/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${RESOURCE_GROUP}" | tee azureServiceAccountKey.json
+    az identity create -g "${RESOURCE_GROUP}-identity" -n "${SERVICE_PRINCIPLE_NAME}"
+    identityID=$(az identity show -n "${SERVICE_PRINCIPLE_NAME}" -g "${RESOURCE_GROUP}-identity" --query principalId --out tsv)
+    az role assignment create --assignee-principal-type ServicePrincipal --assignee-object-id "${identityID}" --role 'Virtual Machine Contributor' --scope "/subscriptions/${SUBSCRIPTION_ID}"
+    az role assignment create --assignee-principal-type ServicePrincipal --assignee-object-id "${identityID}" --role 'Application Insights Component Contributor' --scope "/subscriptions/${SUBSCRIPTION_ID}"
+    echo "subscription: ${SUBSCRIPTION_ID}"
+    echo "tenant: $(az account show --query tenantId -o tsv)"
+    echo "location: ${LOCATION}"
+    echo "resourceGroup: ${RESOURCE_GROUP}"
+    echo "userAssignedIdentity: $(az identity show -n "${SERVICE_PRINCIPLE_NAME}" -g "${RESOURCE_GROUP}-identity" --query id --out tsv)"
+    echo "appClientID: $(jq -r '.appId' azureServiceAccountKey.json)"
+    echo "clientSecretValue: $(jq -r '.password' azureServiceAccountKey.json)"
+    ```
+
+    Fill in the printed out values to your configuration file.
+
+    </tabItem>
+    <tabItem value="azure-portal" label="Azure (Portal)" default>
+
+    * **subscription**: Is the UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`.
+
+        You can view your subscription UUID via `az account show` and read the `id` field. For more information refer to [Azure's documentation](https://docs.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id#find-your-azure-subscription).
+
+    * **tenant**: Is the UUID of your Azure tenant, e.g., `3400e5a2-8fe2-492a-886c-38cb66170f25`.
+
+        You can view your tenant UUID via `az account show` and read the `tenant` field. For more information refer to [Azure's documentation](https://docs.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id#find-your-azure-ad-tenant).
+
+    * **location**: Is the Azure datacenter location you want to deploy your cluster in, e.g., `westus`. Notice that CVMs are currently only supported in a few regions, check [Azure's products available by region](https://azure.microsoft.com/en-us/global-infrastructure/services/?products=virtual-machines&regions=all). Currently these are supported:
+
+        * `westus`
+        * `eastus`
+        * `northeurope`
+        * `westeurope`
+
+    * **resourceGroup**: [Create a new resource group in Azure](https://portal.azure.com/#create/Microsoft.ResourceGroup), to deploy your Constellation cluster into. Afterwards set the configuration field to the name of the created resource group, e.g., `constellation`.
+
+    * **userAssignedIdentity**: [Create a new managed identity in Azure](https://portal.azure.com/#create/Microsoft.ManagedIdentity). Notice that the identity should be created in a different resource group as all resources within the cluster resource group will be deleted on cluster termination.
+
+        After creation, add two role assignments to the identity, for the roles `Virtual Machine Contributor` and `Application Insights Component Contributor`. The `scope` of both should refer to the previously created resource group.
+
+        Set the configuration value to the full ID of the created identity, e.g., `/subscriptions/8b8bd01f-efd9-4113-9bd1-c82137c32da7/resourcegroups/constellation-identity/providers/Microsoft.ManagedIdentity/userAssignedIdentities/constellation-identity`.
+
+        The user-assigned identity is used by instances of the cluster to access other cloud resources.
+
+        For more information about managed identities refer to [Azure's documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities).
+
+    * **appClientID**: [Create a new app registration in Azure](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/CreateApplicationBlade/quickStartType~/null/isMSAApp~/false).
+
+        As `Supported account types` choose `Accounts in this organizational directory only`, and leave the `Redirect URI` empty.
+
+        In the cluster resource group, go to `Access Control (IAM)`, and set the created app registration as `Owner`.
+
+        Set the configuration value to the `Application (client) ID`, e.g., `86ec31dd-532b-4a8c-a055-dd23f25fb12f`.
+
+    * **clientSecretValue**: In our previously created app registration, go to `Certificates & secrets` and create a new `Client secret`.
+
+        Set the configuration value to the secret value.
+
+    </tabItem>
+    <tabItem value="gcp" label="GCP" default>
+
+    * **project**: Is the ID of your GCP project, e.g., `constellation-129857`.
+
+        You will find it on the [welcome screen of your GCP project](https://console.cloud.google.com/welcome). For more information refer to [Google's documentation](https://support.google.com/googleapi/answer/7014113).
+
+    * **region**: Is the GCP region you want to deploy your cluster in, e.g., `us-west-1`.
+
+        You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available).
+
+    * **zone**: Is the GCP zone you want to deploy your cluster in, e.g., `us-west-1a`.
+
+        You can find a [list of all zones in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available).
+
+    * **serviceAccountKeyPath**: To configure this, you need to create a GCP [service account](https://cloud.google.com/iam/docs/service-accounts) with the following permissions:
+
+        - `Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1)`
+        - `Compute Network Admin (roles/compute.networkAdmin)`
+        - `Compute Security Admin (roles/compute.securityAdmin)`
+        - `Compute Storage Admin (roles/compute.storageAdmin)`
+        - `Service Account User (roles/iam.serviceAccountUser)`
+
+        Afterwards, create and download a new `JSON` key for this service account. Place the downloaded file in your Constellation workspace, and set the config parameter to the filename, e.g., `constellation-129857-15343dba46cb.json`.
+
+    </tabItem>
+    </tabs>
+
+3. Download the measurements for your configured image.
 
     ```bash
     constellation config fetch-measurements
@@ -41,7 +135,7 @@ The following steps will guide you through the process of creating a cluster and
 
     For more details, see the [verification section](../workflows/verify.md).
 
-3. Create the cluster with one control-plane node and two worker nodes. `constellation create` uses options set in `constellation-conf.yaml` automatically.
+4. Create the cluster with one control-plane node and two worker nodes. `constellation create` uses options set in `constellation-conf.yaml` automatically.
 
     <tabs>
     <tabItem value="azure" label="Azure" default>
@@ -67,7 +161,7 @@ The following steps will guide you through the process of creating a cluster and
     Your Constellation cluster was created successfully.
     ```
 
-4. Initialize the cluster
+5. Initialize the cluster
 
     ```bash
     constellation init
@@ -89,7 +183,7 @@ The following steps will guide you through the process of creating a cluster and
     Keep `constellation-mastersecret.json` somewhere safe.
     This will allow you to [recover your cluster](../workflows/recovery.md) in case of a disaster.
 
-5. Configure kubectl
+6. Configure kubectl
 
     ```bash
     export KUBECONFIG="$PWD/constellation-admin.conf"
@@ -125,3 +219,12 @@ $ constellation terminate
 Terminating ...
 Your Constellation cluster was terminated successfully.
 ```
+
+In case you have used `az` CLI to create your environment, make sure to clean up afterwards:
+
+```bash
+APPID=$(jq -r '.appId' azureServiceAccountKey.json)
+az ad sp delete --id "${APPID}"
+az group delete -g "${RESOURCE_GROUP}-identity" --yes --no-wait
+az group delete -g "${RESOURCE_GROUP}" --yes --no-wait
+```

docs/docs/getting-started/install.md

@@ -15,7 +15,7 @@ Before we start, make sure the following requirements are fulfilled:
 
 ## Install the Constellation CLI
 
-The Constellation CLI can be downloaded from our [release page](https://github.com/edgelesssys/constellation/releases). Therefore, navigate to a release and download the file `constellation`. Move the downloaded file to a directory in your `PATH` (default: `/usr/local/bin`) and make it executable by entering `chmod s+x constellation` in your terminal.
+The Constellation CLI can be downloaded from our [release page](https://github.com/edgelesssys/constellation/releases). Therefore, navigate to a release and download the `constellation` binary for your operating system and architecture. Move the downloaded file to a directory in your `PATH` (default: `/usr/local/bin`) and make it executable by entering `chmod u+x constellation` in your terminal.
 
 Running `constellation` should then give you:
 
@@ -38,7 +38,7 @@ The Constellation CLI supports autocompletion for various shells. To set it up,
 For extra security, make sure to verify your CLI. Therefore, install [cosign](https://github.com/sigstore/cosign). Then, head to our [release page](https://github.com/edgelesssys/constellation/releases) again and, from the same release as before, download the following files:
 
 - `cosign.pub` (Edgeless System's cosign public key)
-- `constellation.sig` (the CLI's signature)
+- `constellation-*.sig` (the CLI's signature)
 
 You can then verify your CLI before launching a cluster using the paths to the public key, signature, and CLI executable:
 
@@ -124,23 +124,6 @@ Your user account needs the following permissions to set up a Constellation clus
 - `Contributor`
 - `User Access Administrator`
 
-Additionally, you need to [create a user-assigned managed identity](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities) with the following roles:
-
-- `Virtual Machine Contributor`
-- `Application Insights Component Contributor`
-
-The user-assigned identity is used by the instances of the cluster to access other cloud resources.
-
-You also need an empty resource group per cluster. Notice that the user-assigned identity has to be created in a
-different resource group as all resources within the cluster resource group will be deleted on cluster termination.
-
-Last, you need to [create an Active Directory app registration](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#register-an-application) (you don't need to add a redirect URI).
-As supported account types choose 'Accounts in this organizational directory only'. Then [create a client secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#option-2-create-a-new-application-secret), which will be used by Kubernetes.
-On the cluster resource group, [add the app registration](https://docs.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal?tabs=current#step-2-open-the-add-role-assignment-page)
-with role `Owner`.
-
-User-assigned identity, cluster resource group, app registration client ID and client secret value need to be set in the `constellation-conf.yaml` configuration file.
-
 </tabItem>
 <tabItem value="gcp" label="GCP" default>
 
@@ -150,20 +133,6 @@ Your user account needs the following permissions to set up a Constellation:
 
 Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access).
 
-Additionally, you need a service account with the following permissions:
-
-- `Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1)`
-- `Compute Network Admin (roles/compute.networkAdmin)`
-- `Compute Security Admin (roles/compute.securityAdmin)`
-- `Compute Storage Admin (roles/compute.storageAdmin)`
-- `Service Account User (roles/iam.serviceAccountUser)`
-
-The key for this service account is passed to the CLI and used by Kubernetes to authenticate with the cloud.
-You can configure the path to the key in the `constellation-conf.yaml` configuration file.
-
-GCP instances come with a [default service account](https://cloud.google.com/iam/docs/service-accounts#default) attached
-that's used by the instances to access the cloud resources of the cluster. You don't need to configure it.
-
 </tabItem>
 </tabs>
 

docs/docs/reference/config.md

@@ -50,7 +50,7 @@ provider:
         measurements:
             11: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
             12: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
-        userAssignedIdentity: "" # Authorize spawned VMs to access Azure API. See: https://docs.edgeless.systems/constellation/getting-started/install#authorization
+        userAssignedIdentity: "" # Authorize spawned VMs to access Azure API.
 kubernetesVersion: "1.24" # Kubernetes version installed in the cluster.
 
 # # Egress firewall rules for node network.
@@ -67,17 +67,3 @@ kubernetesVersion: "1.24" # Kubernetes version installed in the cluster.
 #     - username: Alice # Username of new SSH user.
 #       publicKey: ssh-rsa AAAAB3NzaC...5QXHKW1rufgtJeSeJ8= alice@domain.com # Public key of new SSH user.
 ```
-
-## Required customizations
-
-Most options of a generated configuration can be kept at their default values. However, you must edit some cloud provider options.
-
-### Azure
-
-Set the `subscription` and `tenant` IDs of your subscription.
-
-Set the `userAssignedIdentity` that you [created for Constellation](../getting-started/install.md#azure).
-
-### GCP
-
-Set the `project` that you want to use for your Constellation cluster.

docs/versioned_docs/version-1.5/reference/config.md

@@ -50,7 +50,7 @@ provider:
         measurements:
             11: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
             12: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
-        userAssignedIdentity: "" # Authorize spawned VMs to access Azure API. See: https://docs.edgeless.systems/constellation/getting-started/install#authorization
+        userAssignedIdentity: "" # Authorize spawned VMs to access Azure API.
 kubernetesVersion: "1.24" # Kubernetes version installed in the cluster.
 
 # # Egress firewall rules for node network.

internal/config/config.go

@@ -153,12 +153,12 @@ type AzureConfig struct {
 	//   Type of a node's state disk. The type influences boot time and I/O performance. See: https://docs.microsoft.com/en-us/azure/virtual-machines/disks-types#disk-type-comparison
 	StateDiskType string `yaml:"stateDiskType" validate:"oneof=Premium_LRS Premium_ZRS Standard_LRS StandardSSD_LRS StandardSSD_ZRS"`
 	// description: |
-	//   Authorize spawned VMs to access Azure API. See: https://docs.edgeless.systems/constellation/getting-started/install#authorization
-	UserAssignedIdentity string `yaml:"userAssignedIdentity" validate:"required"`
-	// description: |
 	//   Resource group to use.
 	ResourceGroup string `yaml:"resourceGroup" validate:"required"`
 	// description: |
+	//   Authorize spawned VMs to access Azure API.
+	UserAssignedIdentity string `yaml:"userAssignedIdentity" validate:"required"`
+	// description: |
 	//    Application client ID of the Active Directory app registration.
 	AppClientID string `yaml:"appClientID" validate:"required"`
 	// description: |
@@ -282,7 +282,7 @@ func Default() *Config {
 				Image:                 DefaultImageGCP,
 				InstanceType:          "n2d-standard-4",
 				StateDiskType:         "pd-ssd",
-				ServiceAccountKeyPath: "serviceAccountKey.json",
+				ServiceAccountKeyPath: "",
 				Measurements:          copyPCRMap(gcpPCRs),
 				EnforcedMeasurements:  []uint32{0, 8, 9, 11, 12},
 			},

internal/config/config_doc.go

@@ -230,16 +230,16 @@ func init() {
 	AzureConfigDoc.Fields[5].Note = ""
 	AzureConfigDoc.Fields[5].Description = "Type of a node's state disk. The type influences boot time and I/O performance. See: https://docs.microsoft.com/en-us/azure/virtual-machines/disks-types#disk-type-comparison"
 	AzureConfigDoc.Fields[5].Comments[encoder.LineComment] = "Type of a node's state disk. The type influences boot time and I/O performance. See: https://docs.microsoft.com/en-us/azure/virtual-machines/disks-types#disk-type-comparison"
-	AzureConfigDoc.Fields[6].Name = "userAssignedIdentity"
+	AzureConfigDoc.Fields[6].Name = "resourceGroup"
 	AzureConfigDoc.Fields[6].Type = "string"
 	AzureConfigDoc.Fields[6].Note = ""
-	AzureConfigDoc.Fields[6].Description = "Authorize spawned VMs to access Azure API. See: https://docs.edgeless.systems/constellation/getting-started/install#authorization"
+	AzureConfigDoc.Fields[6].Description = "Resource group to use."
-	AzureConfigDoc.Fields[6].Comments[encoder.LineComment] = "Authorize spawned VMs to access Azure API. See: https://docs.edgeless.systems/constellation/getting-started/install#authorization"
+	AzureConfigDoc.Fields[6].Comments[encoder.LineComment] = "Resource group to use."
-	AzureConfigDoc.Fields[7].Name = "resourceGroup"
+	AzureConfigDoc.Fields[7].Name = "userAssignedIdentity"
 	AzureConfigDoc.Fields[7].Type = "string"
 	AzureConfigDoc.Fields[7].Note = ""
-	AzureConfigDoc.Fields[7].Description = "Resource group to use."
+	AzureConfigDoc.Fields[7].Description = "Authorize spawned VMs to access Azure API."
-	AzureConfigDoc.Fields[7].Comments[encoder.LineComment] = "Resource group to use."
+	AzureConfigDoc.Fields[7].Comments[encoder.LineComment] = "Authorize spawned VMs to access Azure API."
 	AzureConfigDoc.Fields[8].Name = "appClientID"
 	AzureConfigDoc.Fields[8].Type = "string"
 	AzureConfigDoc.Fields[8].Note = ""