Git-Mirrors/constellation
1
0
Fork 0
mirror of https://github.com/edgelesssys/constellation.git synced 2025-05-02 06:16:08 -04:00
Code Issues Projects Releases Packages Wiki Activity

Release docs for v2.1 (#222)

Browse source
This commit is contained in:
Paul Meyer 2022-10-07 12:14:55 +02:00 • committed by GitHub
parent 7f96b82288
commit fd63ca1251
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
53 changed files with 6173 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

6
docs/versioned_docs/version-2.1/getting-started/examples.md Normal file
View file

@ -0,0 +1,6 @@
# Examples
After you [installed the CLI](install.md) and [created your first cluster](first-steps.md), you're ready to deploy applications. Why not start with one of the following examples?
* [Emojivoto](examples/emojivoto.md): a simple but fun web application
* [Online Boutique](examples/online-boutique.md): an e-commerce demo application by Google consisting of 11 separate microservices
* [Horizontal Pod Autoscaling](examples/horizontal-scaling.md): an example demonstrating Constellation's autoscaling capabilities

22
docs/versioned_docs/version-2.1/getting-started/examples/emojivoto.md Normal file
View file

@ -0,0 +1,22 @@
# Emojivoto
[Emojivoto](https://github.com/BuoyantIO/emojivoto) is a simple and fun application that's well suited to test the basic functionality of your cluster.
<!-- vale off -->
<img src={require("../../_media/example-emojivoto.jpg").default} alt="emojivoto - Web UI" width="552"/>
<!-- vale on -->
1. Deploy the application:
```bash
kubectl apply -k github.com/BuoyantIO/emojivoto/kustomize/deployment
```
2. Wait until it becomes available:
```bash
kubectl wait --for=condition=available --timeout=60s -n emojivoto --all deployments
```
3. Forward the web service to your machine:
```bash
kubectl -n emojivoto port-forward svc/web-svc 8080:80
```
4. Visit [http://localhost:8080](http://localhost:8080)

98
docs/versioned_docs/version-2.1/getting-started/examples/horizontal-scaling.md Normal file
View file

@ -0,0 +1,98 @@
# Horizontal Pod Autoscaling
This example demonstrates Constellation's autoscaling capabilities. It's based on the Kubernetes [HorizontalPodAutoscaler Walkthrough](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/). During the following steps, Constellation will spawn new VMs on demand, verify them, add them to the cluster, and delete them again when the load has settled down.
## Requirements
The cluster needs to be initialized with Kubernetes 1.23 or later. In addition, [autoscaling must be enabled](../../workflows/scale.md) to enable Constellation to assign new nodes dynamically.
Just for this example specifically, the cluster should have as few worker nodes in the beginning as possible. Start with a small cluster with only *one* low-powered node for the control-plane node and *one* low-powered worker node.
:::info
We tested the example using instances of types `Standard_DC4as_v5` on Azure and `n2d-standard-4` on GCP.
:::
## Setup
1. Install the Kubernetes Metrics Server:
```bash
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
```
2. Deploy the HPA example server that's supposed to be scaled under load.
This manifest is similar to the one from the Kubernetes HPA walkthrough, but with increased CPU limits and requests to facilitate the triggering of node scaling events.
```bash
cat <<EOF | kubectl apply -f -
apiVersion: apps/v1
kind: Deployment
metadata:
name: php-apache
spec:
selector:
matchLabels:
run: php-apache
replicas: 1
template:
metadata:
labels:
run: php-apache
spec:
containers:
- name: php-apache
image: registry.k8s.io/hpa-example
ports:
- containerPort: 80
resources:
limits:
cpu: 900m
requests:
cpu: 600m
---
apiVersion: v1
kind: Service
metadata:
name: php-apache
labels:
run: php-apache
spec:
ports:
- port: 80
selector:
run: php-apache
EOF
```
3. Create a HorizontalPodAutoscaler.
Set an average CPU usage across all Pods of 20% to see one additional worker node being created later. Note that the CPU usage isn't related to the host CPU usage, but rather to the requested CPU capacities (20% of 600 milli-cores CPU across all Pods). See the [original tutorial](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/#create-horizontal-pod-autoscaler) for more information on the HPA configuration.
```bash
kubectl autoscale deployment php-apache --cpu-percent=20 --min=1 --max=10
```
4. Create a Pod that generates load on the server:
```bash
kubectl run -i --tty load-generator --rm --image=busybox:1.28 --restart=Never -- /bin/sh -c "while true; do wget -q -O- http://php-apache; done"
```
5. Wait a few minutes until new nodes are added to the cluster. You can [monitor](#monitoring) the state of the HorizontalPodAutoscaler, the list of nodes, and the behavior of the autoscaler.
6. To stop the load generator, press CTRL+C and run:
```bash
kubectl delete pod load-generator
```
7. The cluster-autoscaler checks every few minutes if nodes are underutilized. It will taint such candidates for removal and wait additional 10 minutes before the nodes are eventually removed and deallocated. The whole process can take about 20 minutes.
## Monitoring
:::tip
For better observability, run the listed commands in different tabs in your terminal.
:::
You can watch the status of the HorizontalPodAutoscaler with the current CPU usage, the target CPU limit, and the number of replicas created with:
```bash
kubectl get hpa php-apache --watch
```
From time to time compare the list of nodes to check the behavior of the autoscaler:
```bash
kubectl get nodes
```
For deeper insights, see the logs of the autoscaler Pod, which contains more details about the scaling decision process:
```bash
kubectl logs -f deployment/constellation-cluster-autoscaler -n kube-system
```

29
docs/versioned_docs/version-2.1/getting-started/examples/online-boutique.md Normal file
View file

@ -0,0 +1,29 @@
# Online Boutique
[Online Boutique](https://github.com/GoogleCloudPlatform/microservices-demo) is an e-commerce demo application by Google consisting of 11 separate microservices. In this demo, Constellation automatically sets up a load balancer on your CSP, making it easy to expose services from your confidential cluster.
<!-- vale off -->
<img src={require("../../_media/example-online-boutique.jpg").default} alt="Online Boutique - Web UI" width="662"/>
<!-- vale on -->
1. Create a namespace:
```bash
kubectl create ns boutique
```
2. Deploy the application:
```bash
kubectl apply -n boutique -f https://github.com/GoogleCloudPlatform/microservices-demo/raw/main/release/kubernetes-manifests.yaml
```
3. Wait for all services to become available:
```bash
kubectl wait --for=condition=available --timeout=300s -n boutique --all deployments
```
4. Get the frontend's external IP address:
```shell-session
$ kubectl get service frontend-external -n boutique | awk '{print $4}'
EXTERNAL-IP
<your-ip>
```
(`<your-ip>` is a placeholder for the IP assigned by your CSP.)
5. Enter the IP from the result in your browser to browse the online shop.

285
docs/versioned_docs/version-2.1/getting-started/first-steps.md Normal file
View file

@ -0,0 +1,285 @@
# First steps
The following steps guide you through the process of creating a cluster and deploying a sample app. This example assumes that you have successfully [installed and set up Constellation](install.md),
and have access to a cloud subscription.
:::tip
If you don't have a cloud subscription, check out [mini Constellation](mini-constellation.md), which lets you set up a local Constellation cluster using virtualization.
:::
## Create a cluster
1. Create the configuration file for your selected cloud provider.
<tabs groupId="csp">
<tabItem value="azure" label="Azure">
```bash
constellation config generate azure
```
</tabItem>
<tabItem value="gcp" label="GCP">
```bash
constellation config generate gcp
```
</tabItem>
</tabs>
This creates the file `constellation-conf.yaml` in your current working directory.
2. Fill in your cloud provider specific information.
<tabs groupId="csp">
<tabItem value="azure" label="Azure (CLI)">
You need several resources for the cluster. You can use the following `az` script to create them:
```bash
RESOURCE_GROUP=constellation # enter name of new resource group for your cluster here
LOCATION=westus # enter location of resources here
SUBSCRIPTION_ID=$(az account show --query id --out tsv)
SERVICE_PRINCIPAL_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_PRINCIPAL_NAME}" --role Owner --scopes "/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${RESOURCE_GROUP}" | tee azureServiceAccountKey.json
az identity create -g "${RESOURCE_GROUP}-identity" -n "${SERVICE_PRINCIPAL_NAME}"
identityID=$(az identity show -n "${SERVICE_PRINCIPAL_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}
tenant: $(az account show --query tenantId -o tsv)
location: ${LOCATION}
resourceGroup: ${RESOURCE_GROUP}
userAssignedIdentity: $(az identity show -n "${SERVICE_PRINCIPAL_NAME}" -g "${RESOURCE_GROUP}-identity" --query id --out tsv)
appClientID: $(jq -r '.appId' azureServiceAccountKey.json)
clientSecretValue: $(jq -r '.password' azureServiceAccountKey.json)"
```
Fill the values produced by the script into your configuration file.
By default, Constellation uses `Standard_DC4as_v5` CVMs (4 vCPUs, 16 GB RAM) to create your cluster. Optionally, you can switch to a different VM type by modifying **instanceType** in the configuration file. For CVMs, any VM type with a minimum of 4 vCPUs from the [DCasv5 & DCadsv5](https://docs.microsoft.com/en-us/azure/virtual-machines/dcasv5-dcadsv5-series) or [ECasv5 & ECadsv5](https://docs.microsoft.com/en-us/azure/virtual-machines/ecasv5-ecadsv5-series) families is supported.
Run `constellation config instance-types` to get the list of all supported options.
</tabItem>
<tabItem value="azure-portal" label="Azure (Portal)">
* **subscription**: 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**: 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**: The Azure datacenter location you want to deploy your cluster in, e.g., `westus`. 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). These are:
* `westus`
* `eastus`
* `northeurope`
* `westeurope`
* **resourceGroup**: [Create a new resource group in Azure](https://portal.azure.com/#create/Microsoft.ResourceGroup) for your Constellation cluster. Set this configuration field to the name of the created resource group.
* **userAssignedIdentity**: [Create a new managed identity in Azure](https://portal.azure.com/#create/Microsoft.ManagedIdentity). You should create the identity in a different resource group as all resources within the cluster resource group will be deleted on cluster termination.
Add two role assignments to the identity: `Virtual Machine Contributor` and `Application Insights Component Contributor`. The `scope` of both should refer to the previously created cluster 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`. You can get it by opening the `JSON View` from the `Overview` section of the 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).
Set `Supported account types` to `Accounts in this organizational directory only` and leave the `Redirect URI` empty.
Set the configuration value to the `Application (client) ID`, e.g., `86ec31dd-532b-4a8c-a055-dd23f25fb12f`.
In the cluster resource group, go to `Access Control (IAM)` and set the created app registration as `Owner`.
* **clientSecretValue**: In the previously created app registration, go to `Certificates & secrets` and create a new `Client secret`.
Set the configuration value to the secret value.
* **instanceType**: The VM type you want to use for your Constellation nodes.
For CVMs, any type with a minimum of 4 vCPUs from the [DCasv5 & DCadsv5](https://docs.microsoft.com/en-us/azure/virtual-machines/dcasv5-dcadsv5-series) or [ECasv5 & ECadsv5](https://docs.microsoft.com/en-us/azure/virtual-machines/ecasv5-ecadsv5-series) families is supported. It defaults to `Standard_DC4as_v5` (4 vCPUs, 16 GB RAM).
Run `constellation config instance-types` to get the list of all supported options.
</tabItem>
<tabItem value="gcp" label="GCP (CLI)">
You need a service account for the cluster. You can use the following `gcloud` script to create it:
```bash
SERVICE_ACCOUNT_ID=constell # enter name of service account here
PROJECT_ID= # enter project id here
SERVICE_ACCOUNT_EMAIL=${SERVICE_ACCOUNT_ID}@${PROJECT_ID}.iam.gserviceaccount.com
gcloud iam service-accounts create "${SERVICE_ACCOUNT_ID}" --description="Service account used inside Constellation" --display-name="Constellation service account" --project="${PROJECT_ID}"
gcloud projects add-iam-policy-binding "${PROJECT_ID}" --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" --role='roles/compute.instanceAdmin.v1'
gcloud projects add-iam-policy-binding "${PROJECT_ID}" --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" --role='roles/compute.networkAdmin'
gcloud projects add-iam-policy-binding "${PROJECT_ID}" --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" --role='roles/compute.securityAdmin'
gcloud projects add-iam-policy-binding "${PROJECT_ID}" --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" --role='roles/compute.storageAdmin'
gcloud projects add-iam-policy-binding "${PROJECT_ID}" --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" --role='roles/iam.serviceAccountUser'
gcloud iam service-accounts keys create gcpServiceAccountKey.json --iam-account="${SERVICE_ACCOUNT_EMAIL}"
echo "project: ${PROJECT_ID}
serviceAccountKeyPath: $(realpath gcpServiceAccountKey.json)"
```
Fill the values produced by the script into your configuration file.
By default, Constellation uses `n2d-standard-4` VMs (4 vCPUs, 16 GB RAM) to create your cluster. Optionally, you can switch to a different VM type by modifying **instanceType** in the configuration file. Supported are all machines from the N2D family. Refer to [N2D machine series](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) or run `constellation config instance-types` to get the list of all supported options.
</tabItem>
<tabItem value="gcp-console" label="GCP (Console)">
* **project**: The ID of your GCP project, e.g., `constellation-129857`.
You can 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**: The GCP region you want to deploy your cluster in, e.g., `us-west1`.
You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available).
* **zone**: The GCP zone you want to deploy your cluster in, e.g., `us-west1-a`.
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)`
Afterward, 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`.
* **instanceType**: The VM type you want to use for your Constellation nodes.
Supported are all machines from the N2D family. It defaults to `n2d-standard-4` (4 vCPUs, 16 GB RAM), but you can use any other VMs from the same family. Refer to [N2D machine series](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) or run `constellation config instance-types` to get the list of all supported options.
</tabItem>
</tabs>
:::info
In case you don't have access to CVMs on Azure, you may use less secure [trusted launch VMs](../workflows/trusted-launch.md) instead. For this, set **confidentialVM** to `false` in the configuration file.
:::
3. Download the trusted measurements for your configured image.
```bash
constellation config fetch-measurements
```
For details, see the [verification section](../workflows/verify-cluster.md).
4. Create the cluster with one control-plane node and two worker nodes. `constellation create` uses options set in `constellation-conf.yaml`.
:::tip
On Azure, you may need to wait 15+ minutes at this point for role assignments to propagate.
:::
```bash
constellation create --control-plane-nodes 1 --worker-nodes 2 -y
```
This should give the following output:
```shell-session
$ constellation create ...
Your Constellation cluster was created successfully.
```
5. Initialize the cluster
```bash
constellation init
```
This should give the following output:
```shell-session
$ constellation init
Your Constellation master secret was successfully written to ./constellation-mastersecret.json
Initializing cluster ...
Your Constellation cluster was successfully initialized.
Constellation cluster identifier g6iMP5wRU1b7mpOz2WEISlIYSfdAhB0oNaOg6XEwKFY=
Kubernetes configuration constellation-admin.conf
You can now connect to your cluster by executing:
export KUBECONFIG="$PWD/constellation-admin.conf"
```
The cluster's identifier will be different in your output.
Keep `constellation-mastersecret.json` somewhere safe.
This will allow you to [recover your cluster](../workflows/recovery.md) in case of a disaster.
:::info
Depending on your CSP and region, `constellation init` may take 10+ minutes to complete.
:::
6. Configure kubectl
```bash
export KUBECONFIG="$PWD/constellation-admin.conf"
```
## Deploy a sample application
1. Deploy the [emojivoto app](https://github.com/BuoyantIO/emojivoto)
```bash
kubectl apply -k github.com/BuoyantIO/emojivoto/kustomize/deployment
```
2. Expose the frontend service locally
```bash
kubectl wait --for=condition=available --timeout=60s -n emojivoto --all deployments
kubectl -n emojivoto port-forward svc/web-svc 8080:80 &
curl http://localhost:8080
kill %1
```
## Terminate your cluster
```bash
constellation terminate
```
This should give the following output:
```shell-session
$ constellation terminate
Terminating ...
Your Constellation cluster was terminated successfully.
```
:::tip
On Azure, if you have used the `az` script, you can keep the prerequisite resources and reuse them for a new cluster.
Or you can delete them:
```bash
RESOURCE_GROUP=constellation # name of your cluster resource group
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
```
:::

192
docs/versioned_docs/version-2.1/getting-started/install.md Normal file
View file

@ -0,0 +1,192 @@
# Installation and setup
Constellation runs entirely in your cloud environment and can be controlled via a dedicated command-line interface (CLI).
The following guides you through the steps of installing the CLI on your machine, verifying it, and connecting it to your cloud service provider (CSP).
## Prerequisites
Make sure the following requirements are met:
- Your machine is running Linux or macOS
- You have admin rights on your machine
- [kubectl](https://kubernetes.io/docs/tasks/tools/) is installed
- Your CSP is Microsoft Azure or Google Cloud Platform (GCP)
## Install the Constellation CLI
The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases).
Install it with the following commands:
<tabs>
<tabItem value="linux-amd64" label="Linux (amd64)">
1. Download the CLI:
```bash
curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/constellation-linux-amd64
```
2. [Verify the signature](../workflows/verify-cli.md) (optional)
3. Install the CLI to your PATH:
```bash
sudo install constellation-linux-amd64 /usr/local/bin/constellation
```
</tabItem>
<tabItem value="linux-arm64" label="Linux (arm64)">
1. Download the CLI:
```bash
curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/constellation-linux-arm64
```
2. [Verify the signature](../workflows/verify-cli.md) (optional)
3. Install the CLI to your PATH:
```bash
sudo install constellation-linux-arm64 /usr/local/bin/constellation
```
</tabItem>
<tabItem value="darwin-arm64" label="macOS (Apple Silicon)">
1. Download the CLI:
```bash
curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/constellation-darwin-arm64
```
2. [Verify the signature](../workflows/verify-cli.md) (optional)
3. Install the CLI to your PATH:
```bash
sudo install constellation-darwin-arm64 /usr/local/bin/constellation
```
</tabItem>
<tabItem value="darwin-amd64" label="macOS (Intel)">
1. Download the CLI:
```bash
curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/constellation-darwin-amd64
```
2. [Verify the signature](../workflows/verify-cli.md) (optional)
3. Install the CLI to your PATH:
```bash
sudo install constellation-darwin-amd64 /usr/local/bin/constellation
```
</tabItem>
</tabs>
:::tip
The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps.
:::
## Set up cloud credentials
The CLI makes authenticated calls to the CSP API. Therefore, you need to set up Constellation with the credentials for your CSP.
:::tip
If you don't have a cloud subscription, you can try [mini Constellation](mini-constellation.md), which lets you set up a local Constellation cluster using virtualization.
:::
### Required permissions
<tabs groupId="csp">
<tabItem value="azure" label="Azure">
You need the following permissions for your user account:
- `Contributor` (to create cloud resources)
- `User Access Administrator` (to create a service account)
If you don't have these permissions with scope *subscription*, ask your administrator to [create the service account and a resource group for your Constellation cluster](first-steps.md).
Your user account needs the `Contributor` permission scoped to this resource group.
</tabItem>
<tabItem value="gcp" label="GCP">
Create a new project for Constellation or use an existing one.
Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it.
You need the following permissions on this project:
- `compute.*` (or the subset defined by `roles/compute.instanceAdmin.v1`)
- `iam.serviceAccountUser`
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).
</tabItem>
</tabs>
### Authentication
You need to authenticate with your CSP. The following lists the required steps for *testing* and *production* environments.
:::note
The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps.
:::
<tabs groupId="csp">
<tabItem value="azure" label="Azure">
**Testing**
Simply open the [Azure Cloud Shell](https://docs.microsoft.com/en-us/azure/cloud-shell/overview).
**Production**
Use the latest version of the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/) on a trusted machine:
```bash
az login
```
Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli).
</tabItem>
<tabItem value="gcp" label="GCP">
**Testing**
You can use the [Google Cloud Shell](https://cloud.google.com/shell). Make sure your [session is authorized](https://cloud.google.com/shell/docs/auth). For example, execute `gsutil` and accept the authorization prompt.
**Production**
Use one of the following options on a trusted machine:
- Use the [`gcloud` CLI](https://cloud.google.com/sdk/gcloud)
```bash
gcloud auth application-default login
```
This will ask you to log-in to your Google account and create your credentials.
The Constellation CLI will automatically load these credentials when needed.
- Set up a service account and pass the credentials manually
Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials.
</tabItem>
</tabs>
## Next steps
You are now ready to [deploy your first confidential Kubernetes cluster and application](first-steps.md).

155
docs/versioned_docs/version-2.1/getting-started/mini-constellation.md Normal file
View file

@ -0,0 +1,155 @@
# Mini Constellation
With `constellation mini`, users can deploy and test Constellation locally without the need for a cloud subscription.
The command uses virtualization to create a local cluster with one control-plane and one worker node.
:::info
Since mini Constellation is running on your local system, please note that common cloud features, such as load-balancing,
attaching persistent storage, or autoscaling, are unavailable.
:::
## Prerequisites
* [Constellation CLI](./install.md#install-the-constellation-cli)
* A x86-64 CPU with at least 4 cores
* Recommended are 6 cores or more
* Hardware virtualization enabled in the BIOS/UEFI (often referred to as Intel VT-x or AMD-V/SVM)
* At least 4 GB RAM
* Recommend are 6 GB or more
* 20 GB of free disk space
* a Linux operating system
* [KVM kernel module](https://www.linux-kvm.org/page/Main_Page) enabled
* [Docker](https://docs.docker.com/engine/install/)
* [xsltproc](https://gitlab.gnome.org/GNOME/libxslt/-/wikis/home)
* Install on Ubuntu:
```bash
sudo apt install xsltproc
```
* Install on Fedora
```bash
sudo dnf install xsltproc
```
* (Optional) [`virsh`](https://www.libvirt.org/manpages/virsh.html) to observe and access your nodes
## Create your cluster
Setting up your mini Constellation cluster is as easy as running the following command:
```bash
constellation mini up
```
This will configure your current directory as the working directory for Constellation.
All `constellation` commands concerning this cluster need to be issued from this directory.
The command will create your cluster and initialize it. Depending on your system, this may take up to 10 minutes.
The output should look like the following:
```shell
$ constellation mini up
Downloading image to ./constellation.qcow2
Done.
Creating cluster in QEMU ...
Cluster successfully created.
Connect to the VMs by executing:
virsh -c qemu+tcp://localhost:16599/system
Your Constellation master secret was successfully written to ./constellation-mastersecret.json
Initializing cluster ...
Your Constellation cluster was successfully initialized.
Constellation cluster identifier hmrRaTJEKHk6zlM6wcTCGxZ+7HAA16ec4T9CmKs12uQ=
Kubernetes configuration constellation-admin.conf
You can now connect to your cluster by executing:
export KUBECONFIG="$PWD/constellation-admin.conf"
```
You can now configure `kubectl` to connect to your local Constellation cluster:
```bash
export KUBECONFIG="$PWD/constellation-admin.conf"
```
It may take a couple of minutes for all cluster resources to be available.
You can check on the state of your cluster by running the following:
```bash
kubectl get nodes
```
If your cluster is running as expected the output should look like the following:
```shell
$ kubectl get nodes
NAME STATUS ROLES AGE VERSION
control-plane-0 Ready control-plane,master 2m59s v1.23.9
worker-0 Ready <none> 32s v1.23.9
```
## Deploy a sample application
1. Deploy the [emojivoto app](https://github.com/BuoyantIO/emojivoto)
```bash
kubectl apply -k github.com/BuoyantIO/emojivoto/kustomize/deployment
```
2. Expose the frontend service locally
```bash
kubectl wait --for=condition=available --timeout=60s -n emojivoto --all deployments
kubectl -n emojivoto port-forward svc/web-svc 8080:80 &
curl http://localhost:8080
kill %1
```
## Terminate your cluster
Once you are done, you can clean up the created resources using the following command:
```shell
constellation mini down
```
This will destroy your cluster and clean up the your working directory.
The VM image and cluster configuration file (`constellation-conf.yaml`) will be left behind and may be reused to create new clusters.
## Troubleshooting
### VMs have no internet access
`iptables` rules may prevent your VMs form properly accessing the internet.
Make sure your rules are'nt dropping forwarded packages.
List your rules:
```shell
sudo iptables -S
```
The output may look similar to the following:
```shell
-P INPUT ACCEPT
-P FORWARD DROP
-P OUTPUT ACCEPT
-N DOCKER
-N DOCKER-ISOLATION-STAGE-1
-N DOCKER-ISOLATION-STAGE-2
-N DOCKER-USER
```
If your `FORWARD` chain is set to `DROP`, you will need to update your rules:
```shell
sudo iptables -P FORWARD ACCEPT
```