Ref/readme (#375)

Co-authored-by: Thomas Tendyck <51411342+thomasten@users.noreply.github.com>
Co-authored-by: Simon Röckinghausen <s2401r@gmail.com>
This commit is contained in:
Moritz Eckert 2022-08-19 14:54:11 +02:00 committed by GitHub
parent 5216de0803
commit 38c1b9003c
5 changed files with 380 additions and 72 deletions

128
CODE_OF_CONDUCT.md Normal file
View File

@ -0,0 +1,128 @@
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
* Focusing on what is best not just for us as individuals, but for the
overall community
Examples of unacceptable behavior include:
* The use of sexualized language or imagery, and sexual attention or
advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email
address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
contact@edgeless.systems.
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series
of actions.
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
the community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.0, available at
<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
Community Impact Guidelines were inspired by [Mozilla's code of conduct
enforcement ladder](https://github.com/mozilla/diversity).
[homepage]: https://www.contributor-covenant.org
For answers to common questions about this code of conduct, see the FAQ at
<https://www.contributor-covenant.org/faq>. Translations are available at
<https://www.contributor-covenant.org/translations>.

View File

@ -1,15 +1,119 @@
## Testing ## First steps
Run all unit tests locally with Thank you for getting involved! Before you start, please familiarize yourself with the [documentation](https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692).
```sh Please follow our [Code of Conduct](CODE_OF_CONDUCT.md) when interacting with this project.
cd build
cmake .. If you want to support our development:
ctest
``` * Add a GitHub Star to the project
* Share our projects on social media
* Join the [Confidential Computing Discord](https://discord.gg/rH8QTH56JN)
Constellation is licensed under the [TODO](LICENSE). When contributing, you also need to agree to our [Contributor License Agreement](https://cla-assistant.io/edgelesssys/constellation).
## Development guidelines
Adhere to the style and best practices described in [Effective Go](https://golang.org/doc/effective_go.html). Read [Common Review Comments](https://github.com/golang/go/wiki/CodeReviewComments) for further information.
## Pull request process
Submissions should remain focused in scope and avoid containing unrelated commits.
For pull requests, we employ the following workflow:
1. Fork the repository to your own GitHub account
2. Create a branch locally with a descriptive name
3. Commit changes to the branch
4. Write your code according to our development guidelines
5. Push changes to your fork
6. Clean up your commit history
7. Open a PR in our repository and summarize the changes in the description
## Reporting issues and bugs, asking questions
This project uses the GitHub issue tracker. Please check the existing issues before submitting to avoid duplicates.
To report a security issue, contact security@edgeless.systems.
Your bug report should cover the following points:
* A quick summary and/or background of the issue
* Steps to reproduce (be specific, e.g., provide sample code)
* What you expected would happen
* What actually happens
* Further notes:
* Thoughts on possible causes
* Tested workarounds or fixes
## Major changes and feature requests
You should discuss larger changes and feature requests with the maintainers. Please open an issue describing your plans.
[Run CI e2e tests](/.github/docs/README.md) [Run CI e2e tests](/.github/docs/README.md)
## Repository Layout
Core components:
* [access_manager](access_manager): Contains the access-manager pod used to persist SSH users based on a K8s ConfigMap
* [cli](cli): The CLI is used to manage a Constellation cluster
* [bootstrapper](bootstrapper): The bootstrapper is a node agent whose most important task is to bootstrap a node
* [image](image): Build files for the Constellation disk image
* [kms](kms): Constellation's key management client and server
* [mount](mount): Package used by CSI plugins to create and mount encrypted block devices
* [state](state): Contains the disk-mapper that maps the encrypted node data disk during boot
Development components:
* [3rdparty](3rdparty): Contains the third party dependencies used by Constellation
* [conformance](conformance): Kubernetes conformance tests
* [debugd](debugd): Debug daemon and client
* [hack](hack): Development tools
* [proto](proto): Proto files generator
* [terraform](terraform): Infrastructure management using terraform (instead of `constellation create/destroy`)
* [libvirt](terraform/libvirt): Deploy local cluster using terraform, libvirt and QEMU
* [test](test): Integration test
Additional repositories:
* [constellation-docs](https://github.com/edgelesssys/constellation-docs): End-user documentation
* [constellation-fedora-coreos-config](https://github.com/edgelesssys/constellation-fedora-coreos-config): CoreOS build configuration with changes for Constellation
* [edg-azuredisk-csi-driver](https://github.com/edgelesssys/edg-azuredisk-csi-driver): Azure CSI driver with encryption on node
* [edg-gcp-compute-persistent-disk-csi-driver](https://github.com/edgelesssys/edg-gcp-compute-persistent-disk-csi-driver): GCP CSI driver with encryption on node
## Build
Prerequisites:
* [Go 1.18](https://go.dev/doc/install)
* [Docker](https://docs.docker.com/engine/install/)
* Packages on Ubuntu:
```sh
sudo apt install build-essential cmake libssl-dev pkg-config libcryptsetup12 libcryptsetup-dev
```
* Packages on Fedora:
```sh
sudo dnf install @development-tools pkg-config cmake openssl-devel cryptsetup-libs cryptsetup-devel
```
```sh
mkdir build
cd build
cmake ..
make -j`nproc`
```
## Testing
You can run all integration and unitttests like this:
```sh
ctest -j `nproc`
```
### Debug Images ### Debug Images
> :warning: These images are not safe to use in production environments. :warning: > :warning: These images are not safe to use in production environments. :warning:
@ -18,6 +122,25 @@ As described in [debugd](/debugd/README.md), it is possible to use a CoreOS imag
To enable the upload, an additional **unsecured** port (4000) is opened which accepts any binary to be run on target machine. **Make sure that this machine is not exposed to the internet.** To enable the upload, an additional **unsecured** port (4000) is opened which accepts any binary to be run on target machine. **Make sure that this machine is not exposed to the internet.**
## Cloud credentials
Using the CLI requires the user to make authorized API calls to the CSP API. See the [docs](https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692/#/getting-started/install?id=cloud-credentials) for configuration.
## Deploying a locally compiled bootstrapper binary
By default, `constellation create ...` will spawn cloud provider instances with a pre-baked bootstrapper binary.
For testing, you can use the constellation debug daemon (debugd) to upload your local bootstrapper binary to running instances and to obtain SSH access.
[Follow this introduction on how to install and setup `cdbg`](debugd/README.md)
## Development Guides
* [Upgrading Kubernetes](/docs/upgrade-kubernetes.md)
* [Manual local image testing](/docs/local-image-testing.md)
## Deployment Guides
* [Onboarding Customers](/docs/onboarding-customers.md)
## Linting ## Linting
This projects uses [golangci-lint](https://golangci-lint.run/) for linting. This projects uses [golangci-lint](https://golangci-lint.run/) for linting.
@ -40,9 +163,9 @@ As this project contains nested Go modules, it is recommended to create a local
go 1.18 go 1.18
use ( use (
. .
./hack ./hack
./operators/constellation-node-operator ./operators/constellation-node-operator
) )
``` ```

181
README.md
View File

@ -1,88 +1,145 @@
# Constellation <p align="center">
<b>⭐ Star us on GitHub — it motivates us a lot!</b>
</p>
This is the main repository of Constellation. ![](docs/constellation-header.png)
![E2ETestAzure](https://github.com/edgelesssys/constellation/actions/workflows/e2e-test-azure.yml/badge.svg?branch=main) <h1 align="center">Welcome to Constellation!</h1>
![E2ETestGCP](https://github.com/edgelesssys/constellation/actions/workflows/e2e-test-gcp.yml/badge.svg?branch=main)
[![Go Report Card](https://goreportcard.com/badge/github.com/edgelesssys/constellation)](https://goreportcard.com/report/github.com/edgelesssys/constellation)
[![Discord Chat](https://img.shields.io/badge/chat-on%20Discord-blue)](https://discord.gg/rH8QTH56JN)
Core components: <p align="center">
<a href="https://www.edgeless.systems/products/constellation/">Constellation</a> is the first Confidential Kubernetes platform. It leverages <a href="https://www.edgeless.systems/resources/confidential-computing/">confidential computing</a> to isolate entire Kubernetes clusters and all workloads from the rest of the cloud infrastructure.
</p>
* [access_manager](access_manager): Contains the access-manager pod used to persist SSH users based on a K8s ConfigMap <p align="center">
* [cli](cli): The CLI is used to manage a Constellation cluster <a href="https://github.com/edgelesssys/constellation/blob/master/LICENSE"><img src="https://img.shields.io/github/license/edgelesssys/constellation" alt="Constellation License"></a>
* [bootstrapper](bootstrapper): The bootstrapper is a node agent whose most important task is to bootstrap a node <a href="https://github.com/edgelesssys/constellation/actions/workflows/e2e-test-azure.yml/badge.svg?branch=main"><img src="https://github.com/edgelesssys/constellation/actions/workflows/e2e-test-azure.yml/badge.svg?branch=main" alt="E2E Test Azure"></a>
* [image](image): Build files for the Constellation disk image <a href="https://github.com/edgelesssys/constellation/actions/workflows/e2e-test-gcp.yml/badge.svg?branch=main"><img src="https://github.com/edgelesssys/constellation/actions/workflows/e2e-test-gcp.yml/badge.svg?branch=main" alt="E2E Test GCP"></a>
* [kms](kms): Constellation's key management client and server <a href="https://goreportcard.com/report/github.com/edgelesssys/constellation"><img src="https://goreportcard.com/badge/github.com/edgelesssys/constellation" alt="Go Report"></a>
* [mount](mount): Package used by CSI plugins to create and mount encrypted block devices <a href="https://discord.gg/rH8QTH56JN"><img src="https://img.shields.io/badge/chat-on%20Discord-blue" alt="Discord"></a>
* [state](state): Contains the disk-mapper that maps the encrypted node data disk during boot <a href="https://twitter.com/EdgelessSystems"><img src="https://img.shields.io/twitter/follow/EdgelessSystems?label=Follow" alt="Twitter"></a>
</p>
Development components: ## Table of contents
- [Table of contents](#table-of-contents)
- [✨ What is Constellation?](#-what-is-constellation)
- [🛠 Features](#-features)
- [🚀 Getting started](#-getting-started)
- [📖 Documentation](#-documentation)
- [👥 Community](#-community)
- [🤝 Contributing](#-contributing)
- [🗺 Roadmap](#-roadmap)
- [❓ Support & Enterprise Support](#-support--enterprise-support)
- [📃 License](#-license)
* [3rdparty](3rdparty): Contains the third party dependencies used by Constellation
* [conformance](conformance): Kubernetes conformance tests
* [debugd](debugd): Debug daemon and client
* [hack](hack): Development tools
* [proto](proto): Proto files generator
* [terraform](terraform): Infrastructure management using terraform (instead of `constellation create/destroy`)
* [libvirt](terraform/libvirt): Deploy local cluster using terraform, libvirt and QEMU
* [test](test): Integration test
Additional repositories: ## ✨ What is Constellation?
* [constellation-docs](https://github.com/edgelesssys/constellation-docs): End-user documentation From the inside, it's a fully featured, [certified] Kubernetes engine. From the outside, it's an end to end isolated, always encrypted stronghold. A Confidential Cloud in the public cloud.
* [constellation-fedora-coreos-config](https://github.com/edgelesssys/constellation-fedora-coreos-config): CoreOS build configuration with changes for Constellation Constellation is open source and enterprise-ready, tailored for unleashing the power of confidential computing for all your workloads at scale.
* [edg-azuredisk-csi-driver](https://github.com/edgelesssys/edg-azuredisk-csi-driver): Azure CSI driver with encryption on node
* [edg-gcp-compute-persistent-disk-csi-driver](https://github.com/edgelesssys/edg-gcp-compute-persistent-disk-csi-driver): GCP CSI driver with encryption on node
## Build ![Overview](docs/product-overview.png)
Prerequisites: For a brief introduction to the Confidential Kubernetes concept, read the [introduction][confidential-kubernetes].
For more elaborate overviews of Constellation, see the [architecture] documentation.
* [Go 1.18](https://go.dev/doc/install)
* [Docker](https://docs.docker.com/engine/install/)
* Packages on Ubuntu:
```sh ## 🛠 Features
sudo apt install build-essential cmake libssl-dev pkg-config libcryptsetup12 libcryptsetup-dev
```
* Packages on Fedora: * The only cloud-agnostic Confidential Kubernetes platform
* [Verifiable][cluster-attestation] integrity and confidentiality of the entire Kubernetes cluster
* High-available, enterprise-ready Kubernetes engine
* Memory runtime encryption of all Kubernetes nodes
* [Transparent network encryption][network-encryption] for the entire cluster node to node traffic. Provided by [Cilium], application independent, no sidecar required
* [Persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) encryption for block storage. [Encrypted in the confidential Kubernetes context][storage-encryption], keys and plaintext data never leave the cluster. No trust in the cloud storage backend required
* [Key management][key-management] for transparent network and storage encryption
* [Confidential computing-optimized][images], fully measured, and integrity-protected node OS
* Kubernetes node attestation based on confidential computing. Nodes are [verified][node-attestation] on their integrity and identity with a hardware-based remote attestation procedure before joining the cluster
* Dynamic cluster autoscaling
* [Supply chain protection][supply-chain] with [sigstore](https://www.sigstore.dev/)
```sh ## 🚀 Getting started
sudo dnf install @development-tools pkg-config cmake openssl-devel cryptsetup-libs cryptsetup-devel
```
```sh Sounds great, how can I try this?
mkdir build
cd build
cmake ..
make -j`nproc`
```
## Testing Constellation can be deployed in minutes to your favorite infrastructure provider:
You can run all integration and unitttests like this: :wrench: [Install][install]
```sh :lock: [Deploy][deploy]
ctest -j `nproc`
```
## Cloud credentials :white_check_mark: [Profit][examples]
Using the CLI requires the user to make authorized API calls to the CSP API. See the [docs](https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692/#/getting-started/install?id=cloud-credentials) for configuration. ## 📖 Documentation
## Deploying a locally compiled bootstrapper binary * [Concept][confidential-kubernetes]
* [Threat model][threat-model]
* [Architecture][architecture]
* [Installing the CLI][install]
* [Creating a Constelltion cluster][deploy]
By default, `constellation create ...` will spawn cloud provider instances with a pre-baked bootstrapper binary. ## 👥 Community
For testing, you can use the constellation debug daemon (debugd) to upload your local bootstrapper binary to running instances and to obtain SSH access.
[Follow this introduction on how to install and setup `cdbg`](debugd/README.md)
## Development Guides * Got a question? Please get in touch via [Discord][discord] or file an [issue][github-issues].
* If you see an error message or run into an issue, please make sure to create a [bug report][github-issues].
* Get the latest news and announcements on [Twitter][twitter], [LinkedIn][linkedin] or sign up for our monthly [newsletter][newsletter].
* Visit our [blog](https://blog.edgeless.systems/) for technical deep-dives and tutorials.
* [Upgrading Kubernetes](/docs/upgrade-kubernetes.md) ## 🤝 Contributing
* [Manual local image testing](/docs/local-image-testing.md)
## Deployment Guides * Read [`CONTRIBUTING.md`](CONTRIBUTING.md) for information on issue reporting, code guidelines, and how to work in this repository.
* Pull requests are welcome! You need to agree to our [Contributor License Agreement][cla-assistant].
* This project and everyone participating in it are governed by the [Code of Conduct](/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
* To report a security issue, write to security@edgeless.systems.
## 🗺 Roadmap
Constellation maintains a [public roadmap][TODO]. It gives a a high-level view of the main priorities for the project, the maturity of different features, and how to influence the project direction.
## ❓ Support & Enterprise Support
If you require a cluster with more than 8 vCPUs or need other services such as enterprise support: [Contact us][contact] or find more information on the [Constellation product page][constellation-product].
## 📃 License
<!-- refs -->
[architecture]: https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692/#/architecture/overview
[certified]: https://www.cncf.io/certification/software-conformance/
[Cilium]: https://cilium.io/
[cla-assistant]: https://cla-assistant.io/edgelesssys/constellation
[cluster-attestation]: https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692/#/architecture/attestation?id=cluster-attestation
[community-license]: https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e2742739869/getting-started/license
[confidential-computing]: https://www.edgeless.systems/resources/confidential-computing/
[confidential-kubernetes]: https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692/#/getting-started/confidential-kubernetes
[Constellation]: https://www.edgeless.systems/products/constellation/
[constellation-product]: https://www.edgeless.systems/products/constellation/
[contact]: https://www.edgeless.systems/contact/
[deploy]: https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692/#/workflows/create
[discord]: https://discord.gg/rH8QTH56JN
[discord-badge]: https://img.shields.io/badge/chat-on%20Discord-blue
[documentation]: https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692
[e2eTestAzure]: https://github.com/edgelesssys/constellation/actions/workflows/e2e-test-azure.yml/badge.svg?branch=main
[e2eTestGCP]: https://github.com/edgelesssys/constellation/actions/workflows/e2e-test-gcp.yml/badge.svg?branch=main
[examples]: https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692/#/getting-started/examples
[getting-started]: https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692/#/getting-started/install
[github-issues]: https://github.com/edgelesssys/constellation/issues/new/choose
[go-report-card]: https://goreportcard.com/report/github.com/edgelesssys/constellation
[go-report-card-badge]: https://goreportcard.com/badge/github.com/edgelesssys/constellation
[images]: https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692/#/architecture/images?id=constellation-images
[install]: https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692/#/getting-started/install
[join-service]: https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692/#/architecture/components?id=joinservice
[key-management]: https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692/#/architecture/keys?id=constellation-managed-key-management
[license]: https://github.com/edgelesssys/constellation/blob/master/LICENSE
[license-badge]: https://img.shields.io/github/license/edgelesssys/constellation
[linkedin]: https://www.linkedin.com/company/edgeless-systems/
[network-encryption]: https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692/#/architecture/keys?id=network-encryption
[newsletter]: https://www.edgeless.systems/#newsletter-signup
[node-attestation]: https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692/#/architecture/attestation?id=node-attestation
[storage-encryption]: https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692/#/architecture/keys?id=storage-encryption
[supply-chain]: https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692/#/architecture/attestation?id=chain-of-trust
[troubleshooting]: https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692/#/workflows/troubleshooting
[threat-model]: https://constellation-docs.edgeless.systems/6c320851-bdd2-41d5-bf10-e27427398692/#/getting-started/threat-model
[twitter]: https://twitter.com/EdgelessSystems
* [Onboarding Customers](/docs/onboarding-customers.md)

Binary file not shown.

After

Width:  |  Height:  |  Size: 45 KiB

BIN
docs/product-overview.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 275 KiB