# constellation-coordinator ## Prerequisites * Go 1.18 ### Ubuntu 20.04 ```sh sudo apt install build-essential cmake libssl-dev curl https://sh.rustup.rs -sSf | sh ``` ### Amazon Linux ```sh sudo yum install cmake3 gcc make curl https://sh.rustup.rs -sSf | sh ``` ## Build ```sh mkdir build cd build cmake .. make -j`nproc` ``` ## CMake build options: ### Release build This options leaves out debug symbols and turns on more compiler optimizations. ```sh cmake -DCMAKE_BUILD_TYPE=Release .. ``` ### Static build (coordinator as static binary, no dependencies on libc or other libraries) Install the musl-toolchain Ubuntu / Debian: ```sh sudo apt install -y musl-tools rustup target add x86_64-unknown-linux-musl ``` From source (Amazon-Linux): ```sh wget https://musl.libc.org/releases/musl-1.2.2.tar.gz tar xfz musl-1.2.2.tar.gz cd musl-1.2.2 ./configure make -j `nproc` sudo make install rustup target add x86_64-unknown-linux-musl ``` Add `musl-gcc` to your PATH: ```sh export PATH=$PATH:/usr/loca/musl/bin/ ``` Compile the coordinator ```sh cmake -DCOORDINATOR_STATIC_MUSL=ON .. ``` ## Cloud credentials Using the CLI or debug-CLI requires the user to make authorized API calls to the AWS or GCP API. ### Google Cloud Platform (GCP) If you are running from within a Google VM, and the VM is allowed to access the necessary APIs, no further configuration is needed. Otherwise you have a couple options: 1. Use the `gcloud` CLI tool ```shell gcloud auth application-default login ``` This will ask you to log into your Google account, and then create your credentials. The Constellation CLI will automatically load these credentials when needed. 2. 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. ### Amazon Web Services (AWS) To use the CLI with an Constellation cluster on AWS configure the following files: ```bash $ cat ~/.aws/credentials [default] aws_access_key_id = XXXXX aws_secret_access_key = XXXXX ``` ```bash $ cat ~/.aws/config [default] region = us-east-2 ``` ### Azure To use the CLI with an Constellation cluster on Azure execute: ```bash az login ``` ### Deploying a locally compiled coordinator binary By default, `constellation create ...` will spawn cloud provider instances with a pre-baked coordinator binary. For testing, you can use the constellation debug daemon (debugd) to upload your local coordinator binary to running instances and to obtain SSH access. [Follow this introduction on how to install and setup `cdbg`](#debugd-debug-daemon) # debug daemon (debugd) ## debugd Prerequisites * Go 1.18 ## Build debugd ``` mkdir -p build go build -o build/debugd debugd/debugd/cmd/debugd/debugd.go ``` ## Build & install cdbg The go install command for cdbg only works inside the checked out repository due to replace directives in the `go.mod` file. ``` git clone https://github.com/edgelesssys/constellation && cd constellation go install github.com/edgelesssys/constellation/debugd/cdbg ``` ## debugd & cdbg usage With `cdbg` installed in your path: 1. Run `constellation --dev-config /path/to/dev-config create […]` while specifying a cloud-provider image with the debugd already included. See [Configuration](#debugd-configuration) for a dev-config with a custom image and firewall rules to allow incoming connection on the debugd default port 4000. 2. Run `cdbg deploy --dev-config /path/to/dev-config` 3. Run `constellation init […]` as usual ### debugd GCP image For GCP, run the following command to get a list of all constellation images, sorted by their creation date: ``` gcloud compute images list --filter="name~'constellation-.+'" --sort-by=~creationTimestamp ``` Choose the newest debugd image with the naming scheme `constellation-coreos-debugd-`. ### debugd Azure Image For Azure, run the following command to get a list of all constellation debugd images, sorted by their creation date: ``` az sig image-version list --resource-group constellation-images --gallery-name Constellation --gallery-image-definition constellation-coreos-debugd --query "sort_by([], &publishingProfile.publishedDate)[].id" -o table ``` Choose the newest debugd image and copy the full URI. ## debugd Configuration You should first locate the newest debugd image for your cloud provider ([GCP](#debugd-gcp-image), [Azure](#debugd-azure-image)). This tool uses the dev-config file from `constellation-coordinator` and extends it with more fields. See this example on what the possible settings are and how to setup the constellation cli to use a cloud-provider image and firewall rules with support for debugd: ```json { "cdbg":{ "authorized_keys":[ { "user":"my-username", "pubkey":"ssh-rsa AAAAB…LJuM=" } ], "coordinator_path":"/path/to/coordinator", "systemd_units":[ { "name":"some-custom.service", "contents":"[Unit]\nDescription=…" } ] }, "provider": { "gcpconfig": { "image": "constellation-coreos-debugd-TIMESTAMP", "firewallinput": { "Ingress": [ { "Name": "coordinator", "Description": "Coordinator default port", "Protocol": "tcp", "Port": 9000 }, { "Name": "wireguard", "Description": "WireGuard default port", "Protocol": "udp", "Port": 51820 }, { "Name": "ssh", "Description": "SSH", "Protocol": "tcp", "Port": 22 }, { "Name": "debugd", "Description": "debugd default port", "Protocol": "tcp", "Port": 4000 } ] } }, "azureconfig": { "image": "/subscriptions/0d202bbb-4fa7-4af8-8125-58c269a05435/resourceGroups/CONSTELLATION-IMAGES/providers/Microsoft.Compute/galleries/Constellation/images/constellation-coreos-debugd/versions/0.0.TIMESTAMP", "networksecuritygroupinput": { "Ingress": [ { "Name": "coordinator", "Description": "Coordinator default port", "Protocol": "tcp", "IPRange": "0.0.0.0/0", "Port": 9000 }, { "Name": "wireguard", "Description": "WireGuard default port", "Protocol": "udp", "IPRange": "0.0.0.0/0", "Port": 51820 }, { "Name": "ssh", "Description": "SSH", "Protocol": "tcp", "IPRange": "0.0.0.0/0", "Port": 22 }, { "Name": "debugd", "Description": "debugd default port", "Protocol": "tcp", "IPRange": "0.0.0.0/0", "Port": 4000 } ] } } } } ``` # constellation-kms-client This library provides an interface for the key management services used with constellation. It's intendet for the Constellation CSI Plugins and the CLI. ## KMS The Cloud KMS is where we store our key encryption key (KEK). It should be initiated by the CLI and provided with a key release policy. The CSP Plugin can request to encrypt data encryption keys (DEK) with the DEK to safely store them on persistent memory. The [kms](pkg/kms) package interacts with the Cloud KMS APIs. Currently planned are KMS are: * AWS KMS * GCP CKM * Azure Key Vault ## Storage Storage is where the CSI Plugin stores the encrypted DEKs. Currently planned are: * AWS S3, SSP * GCP GCS * Azure Blob # constellation-images # constellation-mount-utils Wrapper for https://github.com/kubernetes/mount-utils ## Dependencies This package uses the C library [`libcryptsetup`](https://gitlab.com/cryptsetup/cryptsetup/) for device mapping. To install the required dependencies on Ubuntu run: ```shell sudo apt install libcryptsetup-dev ``` To install or upgrade `go.mod` dependencies from private repositories run: ``` GOPRIVATE=github.com/edgelesssys/constellation-coordinator go get github.com/edgelesssys/constellation-coordinator GOPRIVATE=github.com/edgelesssys/constellation-kms-client go get github.com/edgelesssys/constellation-kms-client ``` ## Testing A small test programm is available in `test/main.go`. To build the programm run: ```shell go build -o test/crypt ./test/ ``` Create a new crypt device for `/dev/sdX` and map it to `/dev/mapper/volume01`: ```shell sudo test/crypt -source /dev/sdX -target volume01 -v 4 ``` You can now interact with the mapped volume as if it was an unformatted device: ```shell sudo mkfs.ext4 /dev/mapper/volume01 sudo mount /dev/mapper/volume01 /mnt/volume01 ``` Close the mapped volume: ```shell sudo umount /mnt/volume01 sudo test/crypt -c -target volume01 -v 4 ```