README
¶
Always Encrypted Kubernetes
Constellation is a Kubernetes engine that aims to provide the best possible data security. It wraps your K8s cluster into a single confidential context that is shielded from the underlying cloud infrastructure. Everything inside is always encrypted, including at runtime in memory. For this, Constellation leverages confidential computing (see the whitepaper) and more specifically Confidential VMs.
Goals
From a security perspective, Constellation is designed to keep all data always encrypted and to prevent access from the infrastructure layer (i.e., remove the infrastructure from the TCB). This includes access from datacenter employees, privileged cloud admins, and attackers coming through the infrastructure (e.g., malicious co-tenants escalating their privileges).
From a DevOps perspective, Constellation is designed to work just like what you would expect from a modern K8s engine.
Use cases
Encrypting your K8s is good for:
- Increasing the overall security of your clusters
- Increasing the trustworthiness of your SaaS offerings
- Moving sensitive workloads from on-prem to the cloud
- Meeting regulatory requirements
Features
🔒 Everything always encrypted
- Runtime encryption: All nodes run inside AMD SEV-based Confidential VMs (CVMs). Support for Intel TDX will be added in the future.
- Transparent encryption of network and storage: All pod-to-pod traffic and all writes to persistent storage are automatically encrypted
- Transparent key management: All cryptographic keys are managed within the confidential context
🔍 Everything verifiable
- "Whole cluster" attestation based on the remote-attestation feature of CVMs
- Confidential computing-optimized node images; fully measured and integrity-protected
- Supply chain protection with sigstore and SLSA Level 3.
🚀 Performance and scale
- High availability with multi-master architecture and stacked etcd topology
- Dynamic cluster autoscaling with verification and secure bootstrapping of new nodes
- Competitive performance (see K-Bench comparison with AKS and GKE)
🧩 Easy to use and integrate
- Constellation is a CNCF-certified Kubernetes. It's aligned to Kubernetes' version support policy and will likely work with your existing workloads and tools.
- Support for Azure, GCP, and AWS.
- Support for local installations with MiniConstellation.
Getting started
If you're already familiar with Kubernetes, it's easy to get started with Constellation:
- 📦 Install the CLI
- ⌨️ Create a Constellation cluster in the cloud or locally
- 🏎️ Run your app
Live demos
We're running public instances of popular software on Constellation:
- Rocket.Chat: https://rocket.edgeless.systems/ (blog post)
- GitLab: https://gitlab.edgeless.systems/ (blog post)
These instances run on CVMs in Azure and Constellation keeps them end-to-end confidential.
Documentation
To learn more, see the documentation. You may want to start with one of the following sections.
- Confidential Kubernetes (Constellation vs. AKS/GKE + CVMs)
- Security benefits
- Architecture
Support
- If something doesn't work, make sure to use the latest release and check out the known issues.
- Please file an issue to get help or report a bug.
- Join the Discord to have a chat on confidential computing and Constellation.
- Visit our blog for technical deep-dives and tutorials and follow us on Twitter for news.
- Edgeless Systems also offers Enterprise Support.
Contributing
Refer to CONTRIBUTING.md on how to contribute. The most important points:
- Pull requests are welcome! You need to agree to our Contributor License Agreement.
- Please follow the Code of Conduct.
Warning Please report any security issue via a private GitHub vulnerability report or write to security@edgeless.systems.
License
The Constellation source code is licensed under the GNU Affero General Public License v3.0. Edgeless Systems provides pre-built and signed binaries and images for Constellation. You may use these free of charge to create and run services for internal consumption, evaluation purposes, or non-commercial use. You can find more information in the license section of the docs.
Directories
¶
| Path | Synopsis |
|---|---|
|
bootstrapper
|
|
|
internal/certificate
Package certificate provides functions to create a certificate request and matching private key.
|
Package certificate provides functions to create a certificate request and matching private key. |
|
internal/clean
Package clean provides functionality to stop a list of services gracefully and synchronously.
|
Package clean provides functionality to stop a list of services gracefully and synchronously. |
|
internal/diskencryption
Package diskencryption handles interaction with a node's state disk.
|
Package diskencryption handles interaction with a node's state disk. |
|
internal/helm
Package helm is used to install Constellation microservices and other services during cluster initialization.
|
Package helm is used to install Constellation microservices and other services during cluster initialization. |
|
internal/journald
Package journald provides functions to read and collect journald logs.
|
Package journald provides functions to read and collect journald logs. |
|
internal/kubernetes
Package kubernetes provides functionality to bootstrap a Kubernetes cluster, or join an exiting one.
|
Package kubernetes provides functionality to bootstrap a Kubernetes cluster, or join an exiting one. |
|
internal/kubernetes/k8sapi
Package k8sapi is used to interact with the Kubernetes API to create or update required resources.
|
Package k8sapi is used to interact with the Kubernetes API to create or update required resources. |
|
internal/kubernetes/k8sapi/resources
Package resources contains Kubernetes configs and policies for Constellation.
|
Package resources contains Kubernetes configs and policies for Constellation. |
|
internal/kubernetes/kubewaiter
Package kubewaiter is used to wait for the Kubernetes API to be available.
|
Package kubewaiter is used to wait for the Kubernetes API to be available. |
|
internal/logging
Package logging provides an interface for logging information to a non-confidential destination
|
Package logging provides an interface for logging information to a non-confidential destination |
|
internal/nodelock
Package nodelock handles locking operations on the node.
|
Package nodelock handles locking operations on the node. |
|
cmd
Package cmd is the entrypoint of the Constellation CLI.
|
Package cmd is the entrypoint of the Constellation CLI. |
|
internal/cloudcmd
Package cloudcmd provides executable command for the CLI.
|
Package cloudcmd provides executable command for the CLI. |
|
internal/cmd
Package cmd provides the Constellation CLI.
|
Package cmd provides the Constellation CLI. |
|
internal/helm
Package helm provides a higher level interface to the Helm GO SDK.
|
Package helm provides a higher level interface to the Helm GO SDK. |
|
internal/iamid
Package iamid contains the output information of IAM resource creation.
|
Package iamid contains the output information of IAM resource creation. |
|
internal/image
Package image provides helping wrappers around a versionsapi fetcher.
|
Package image provides helping wrappers around a versionsapi fetcher. |
|
internal/kubernetes
Package kubernetes provides functions to interact with a live cluster to the CLI.
|
Package kubernetes provides functions to interact with a live cluster to the CLI. |
|
internal/libvirt
Package libvirt is used to start and stop containerized libvirt instances.
|
Package libvirt is used to start and stop containerized libvirt instances. |
|
internal/terraform
Package terraform handles creation/destruction of a Constellation cluster using Terraform.
|
Package terraform handles creation/destruction of a Constellation cluster using Terraform. |
|
csi
|
|
|
cryptmapper
Package cryptmapper provides a wrapper around libcryptsetup to manage dm-crypt volumes for CSI drivers.
|
Package cryptmapper provides a wrapper around libcryptsetup to manage dm-crypt volumes for CSI drivers. |
|
debugd
|
|
|
internal/cdbg/cmd
Package cmd contains the cdbg CLI.
|
Package cmd contains the cdbg CLI. |
|
internal/debugd
Package debugd contains internal packages for the debugd.
|
Package debugd contains internal packages for the debugd. |
|
internal/debugd/deploy
Package deploy implements deployment of binaries and services to a Constellation instance.
|
Package deploy implements deployment of binaries and services to a Constellation instance. |
|
internal/debugd/info
Package info implements the info map that is used to distribute key–value pair between debugd instances.
|
Package info implements the info map that is used to distribute key–value pair between debugd instances. |
|
internal/debugd/logcollector
Package logcollector uses podman to deploy logstash and filebeat containers in order to collect logs centrally for debugging purposes.
|
Package logcollector uses podman to deploy logstash and filebeat containers in order to collect logs centrally for debugging purposes. |
|
internal/debugd/metadata
Package metadata schedules the discovery of other debugd instances to exchange settings and binaries.
|
Package metadata schedules the discovery of other debugd instances to exchange settings and binaries. |
|
internal/debugd/metadata/cloudprovider
Package cloudprovider implements a metadata service for cloud providers.
|
Package cloudprovider implements a metadata service for cloud providers. |
|
internal/debugd/metadata/fallback
Package fallback implements a fake metadata backend.
|
Package fallback implements a fake metadata backend. |
|
internal/debugd/server
Package server implements the gRPC endpoint of Constellation's debugd.
|
Package server implements the gRPC endpoint of Constellation's debugd. |
|
internal/filetransfer
Package filetransfer implements the exchange of files between cdgb <-> debugd and between debugd <-> debugd pairs.
|
Package filetransfer implements the exchange of files between cdgb <-> debugd and between debugd <-> debugd pairs. |
|
internal/filetransfer/streamer
Package streamer implements streaming of files over gRPC.
|
Package streamer implements streaming of files over gRPC. |
|
disk-mapper
|
|
|
internal/mapper
Package mapper uses libcryptsetup to format and map crypt devices.
|
Package mapper uses libcryptsetup to format and map crypt devices. |
|
internal/recoveryserver
Package recoveryserver implements the gRPC endpoints for recovering a restarting node.
|
Package recoveryserver implements the gRPC endpoints for recovering a restarting node. |
|
internal/rejoinclient
Package rejoinclient handles the automatic rejoining of a restarting node.
|
Package rejoinclient handles the automatic rejoining of a restarting node. |
|
internal/setup
Package setup handles setting up rejoinclient and recoveryserver for the disk-mapper.
|
Package setup handles setting up rejoinclient and recoveryserver for the disk-mapper. |
|
internal/systemd
Package systemd configures systemd units for encrypted volumes.
|
Package systemd configures systemd units for encrypted volumes. |
|
End-to-end tests which are executed from our GitHub action pipelines.
|
End-to-end tests which are executed from our GitHub action pipelines. |
|
internal/kubectl
Provides functionality to easily interact with the K8s API, which can be used from any e2e test.
|
Provides functionality to easily interact with the K8s API, which can be used from any e2e test. |
|
internal/upgrade
Package upgrade tests that the CLI's upgrade apply command works as expected and the operators eventually upgrade all nodes inside the cluster.
|
Package upgrade tests that the CLI's upgrade apply command works as expected and the operators eventually upgrade all nodes inside the cluster. |
|
internal
|
|
|
atls
aTLS provides config generation functions to bootstrap attested TLS connections.
|
aTLS provides config generation functions to bootstrap attested TLS connections. |
|
attestation
This package deals with the low level attestation and verification logic of Constellation nodes.
|
This package deals with the low level attestation and verification logic of Constellation nodes. |
|
attestation/idkeydigest
Package idkeydigest contains policies and type definitions for checking the ID Key Digest value in SEV-SNP attestation.
|
Package idkeydigest contains policies and type definitions for checking the ID Key Digest value in SEV-SNP attestation. |
|
attestation/simulator
TPM2 simulator used for unit tests.
|
TPM2 simulator used for unit tests. |
|
cloud/aws
Implements interaction with the AWS API.
|
Implements interaction with the AWS API. |
|
cloud/azure
Implements interaction with the Azure API.
|
Implements interaction with the Azure API. |
|
cloud/azureshared
Package gcpshared contains code to parse and define data types relevant for Microsoft Azure.
|
Package gcpshared contains code to parse and define data types relevant for Microsoft Azure. |
|
cloud/gcp
Implements interaction with the GCP API.
|
Implements interaction with the GCP API. |
|
cloud/gcpshared
Package gcpshared contains code to parse and define data types relevant for Google Cloud Platform.
|
Package gcpshared contains code to parse and define data types relevant for Google Cloud Platform. |
|
cloud/qemu
This package provides an interface to fake a CSP API for QEMU instances.
|
This package provides an interface to fake a CSP API for QEMU instances. |
|
compatibility
Package compatibility offers helper functions for comparing and filtering versions.
|
Package compatibility offers helper functions for comparing and filtering versions. |
|
config
Definitions for Constellation's user config file.
|
Definitions for Constellation's user config file. |
|
constants
Package constants contains the constants used by Constellation.
|
Package constants contains the constants used by Constellation. |
|
crypto
Package crypto provides functions to for cryptography and random numbers.
|
Package crypto provides functions to for cryptography and random numbers. |
|
crypto/testvector
Package testvector provides test vectors for key derivation and crypto functions.
|
Package testvector provides test vectors for key derivation and crypto functions. |
|
cryptsetup
Package cryptsetup contains CGO bindings for cryptsetup.
|
Package cryptsetup contains CGO bindings for cryptsetup. |
|
deploy/helm
Package helm provides types and functions shared across services.
|
Package helm provides types and functions shared across services. |
|
file
Package file provides functions that combine file handling, JSON marshaling and file system abstraction.
|
Package file provides functions that combine file handling, JSON marshaling and file system abstraction. |
|
grpc/atlscredentials
Package atlscredentials handles creation of TLS credentials for attested TLS (ATLS).
|
Package atlscredentials handles creation of TLS credentials for attested TLS (ATLS). |
|
grpc/dialer
Package dialer provides a grpc dialer that can be used to create grpc client connections with different levels of ATLS encryption / verification.
|
Package dialer provides a grpc dialer that can be used to create grpc client connections with different levels of ATLS encryption / verification. |
|
grpc/grpclog
grpclog provides a logging utilities for gRPC.
|
grpclog provides a logging utilities for gRPC. |
|
grpc/retry
Package retry provides functions to check if a gRPC error is retryable.
|
Package retry provides functions to check if a gRPC error is retryable. |
|
grpc/testdialer
Package testdialer provides a fake dialer for testing.
|
Package testdialer provides a fake dialer for testing. |
|
installer
Package installer provides functionality to install binary components of supported kubernetes versions.
|
Package installer provides functionality to install binary components of supported kubernetes versions. |
|
kms/config
Package config provides configuration constants for the KeyService.
|
Package config provides configuration constants for the KeyService. |
|
kms/kms
Package kms provides an abstract interface for Key Management Services.
|
Package kms provides an abstract interface for Key Management Services. |
|
kms/kms/aws
Package aws implements a KMS backend for AWS KMS.
|
Package aws implements a KMS backend for AWS KMS. |
|
kms/kms/azure
Package azure implements KMS backends for Azure Key Vault and Azure managed HSM.
|
Package azure implements KMS backends for Azure Key Vault and Azure managed HSM. |
|
kms/kms/cluster
Package cluster implements a KMS backend for in cluster key management.
|
Package cluster implements a KMS backend for in cluster key management. |
|
kms/kms/gcp
Package gcp implements a KMS backend for Google Cloud KMS.
|
Package gcp implements a KMS backend for Google Cloud KMS. |
|
kms/kms/internal
Package internal implements the CloudKMS interface using go-kms-wrapping.
|
Package internal implements the CloudKMS interface using go-kms-wrapping. |
|
kms/setup
Package setup provides functions to create a KMS and key store from a given URI.
|
Package setup provides functions to create a KMS and key store from a given URI. |
|
kms/storage
Package storage implements storage backends for DEKs.
|
Package storage implements storage backends for DEKs. |
|
kms/storage/awss3
Package awss3 implements a storage backend for the KMS using AWS S3: https://aws.amazon.com/s3/
|
Package awss3 implements a storage backend for the KMS using AWS S3: https://aws.amazon.com/s3/ |
|
kms/storage/azureblob
Package azureblob implements a storage backend for the KMS using Azure Blob Storage.
|
Package azureblob implements a storage backend for the KMS using Azure Blob Storage. |
|
kms/storage/gcs
Package gcs implements a storage backend for the KMS using Google Cloud Storage (GCS).
|
Package gcs implements a storage backend for the KMS using Google Cloud Storage (GCS). |
|
kms/storage/memfs
Package memfs implements a storage backend for the KMS that stores keys in memory only.
|
Package memfs implements a storage backend for the KMS that stores keys in memory only. |
|
kms/uri
Package uri provides URIs and parsing logic for KMS and storage URIs.
|
Package uri provides URIs and parsing logic for KMS and storage URIs. |
|
kubernetes
Package kubernetes provides data types and custom marshalers for Kubernetes API objects.
|
Package kubernetes provides data types and custom marshalers for Kubernetes API objects. |
|
kubernetes/kubectl
Package kubectl provides a kubectl-like interface for Kubernetes.
|
Package kubectl provides a kubectl-like interface for Kubernetes. |
|
license
Package license provides functions to check a user's Constellation license.
|
Package license provides functions to check a user's Constellation license. |
|
logger
Package logger provides logging functionality for Constellation services.
|
Package logger provides logging functionality for Constellation services. |
|
nodestate
Package nodestate is used to persist the state of a Constellation node to disk.
|
Package nodestate is used to persist the state of a Constellation node to disk. |
|
retry
Package retry provides a simple interface for retrying operations.
|
Package retry provides a simple interface for retrying operations. |
|
semver
Package semver provides functionality to parse and process semantic versions, as they are used in multiple components of Constellation.
|
Package semver provides functionality to parse and process semantic versions, as they are used in multiple components of Constellation. |
|
sigstore
Package sigstore is used to verify Constellation components using sigstore, cosign and rekor.
|
Package sigstore is used to verify Constellation components using sigstore, cosign and rekor. |
|
variant
Package variant defines Attestation variants for different CSPs.
|
Package variant defines Attestation variants for different CSPs. |
|
versions
Package versions defines the supported versions of Constellation components.
|
Package versions defines the supported versions of Constellation components. |
|
versionsapi/cli
This package provides a CLI tool to interact with the Constellation versions API.
|
This package provides a CLI tool to interact with the Constellation versions API. |
|
versionsapi/client
Package client provides a client for the versions API.
|
Package client provides a client for the versions API. |
|
versionsapi/fetcher
Package fetcher implements a client for the versions API.
|
Package fetcher implements a client for the versions API. |
|
watcher
Package watcher implements a file watcher to update an object on file changes.
|
Package watcher implements a file watcher to update an object on file changes. |
|
joinservice
|
|
|
internal/kms
Package kms handles communication with Constellation's key service to request data encryption keys for new or rejoining nodes.
|
Package kms handles communication with Constellation's key service to request data encryption keys for new or rejoining nodes. |
|
internal/kubeadm
Package kubeadm handles joining of new nodes by creating Kubernetes Join Tokens.
|
Package kubeadm handles joining of new nodes by creating Kubernetes Join Tokens. |
|
internal/kubernetes
Package kubernetes interacts with the Kubernetes API to update an fetch objects related to joining nodes.
|
Package kubernetes interacts with the Kubernetes API to update an fetch objects related to joining nodes. |
|
internal/kubernetesca
kubernetesca implements a certificate authority that uses the Kubernetes root CA to sign certificates.
|
kubernetesca implements a certificate authority that uses the Kubernetes root CA to sign certificates. |
|
internal/server
Package server implements the gRPC endpoint of Constellation's node join service.
|
Package server implements the gRPC endpoint of Constellation's node join service. |
|
keyservice
|
|
|
internal/server
Package server implements an API to manage encryption keys.
|
Package server implements an API to manage encryption keys. |
|
measurement-reader
|
|
|
internal/sorted
Type definition for sorted measurements.
|
Type definition for sorted measurements. |
|
internal/tpm
Package tpm reads measurements from a TPM.
|
Package tpm reads measurements from a TPM. |
|
upgrade-agent
|
|
|
internal/server
Package server implements the gRPC server for the upgrade agent.
|
Package server implements the gRPC server for the upgrade agent. |
|
verify
|
|
|
server
Package server implements the gRPC and REST endpoints for retrieving attestation statements.
|
Package server implements the gRPC and REST endpoints for retrieving attestation statements. |
Click to show internal directories.
Click to hide internal directories.