Stefan Reimer
ac51a0774a
All checks were successful
ZeroDownTime/CloudBender/pipeline/head This commit looks good
110 lines
4.8 KiB
Markdown
110 lines
4.8 KiB
Markdown
#  CloudBender
|
|
|
|
# About
|
|
|
|
Toolset to deploy and maintain infrastructure in automated and trackable manner.
|
|
First class support for:
|
|
- [Pulumi](https://www.pulumi.com/docs/)
|
|
- [AWS CloudFormation](https://aws.amazon.com/cloudformation)
|
|
|
|
|
|
# Installation
|
|
The preferred way of running CloudBender is using the public container. This ensure all tools and dependencies are in sync and underwent some basic testing during the development and build phase.
|
|
|
|
As a fall back CloudBender and its dependencies can be installed locally see step *1b* below.
|
|
|
|
## 1a. Containerized
|
|
|
|
The command below tests the ability to run containers within containers on your local setup.
|
|
( This most likely only works on a recent Linux box/VM, which is capable of running rootless containers within containers.
|
|
Requires kernel >= 5.12, Cgroups V2, podman, ... )
|
|
|
|
```
|
|
podman run --rm -v .:/workspace -v $HOME/.aws/config:/workspace/.aws/config public.ecr.aws/zero-downtime/cloudbender:latest podman run -q --rm docker.io/busybox:latest echo "Rootless container inception works!"
|
|
```
|
|
|
|
if you get `Rootless container inception works!`, add an alias to your environment, eg:
|
|
|
|
```
|
|
alias cloudbender="podman run --rm -v .:/workspace -v $HOME/.aws/config:/home/cloudbender/.aws/config public.ecr.aws/zero-downtime/cloudbender:latest cloudbender"
|
|
```
|
|
and proceed with step 2)
|
|
|
|
## 1b. Local install
|
|
- `pip3 install -U cloudbender`
|
|
- `curl -fsSL https://get.pulumi.com | sh` (official [Docs](https://www.pulumi.com/docs/get-started/install/))
|
|
- either `podman` or `docker` depending on your platform
|
|
|
|
## 2. Test cli
|
|
To verify that all pieces are in place run:
|
|
```
|
|
cloudbender version
|
|
```
|
|
which should get you something like:
|
|
```
|
|
[2022-06-28 16:06:24] CloudBender: 0.13.5
|
|
[2022-06-28 16:06:24] Pulumi: v3.34.1
|
|
[2022-06-28 16:06:24] Podman/Docker: podman version 4.1.0
|
|
```
|
|
|
|
## CLI
|
|
|
|
```
|
|
Usage: cloudbender [OPTIONS] COMMAND [ARGS]...
|
|
|
|
Options:
|
|
--profile TEXT Use named AWS .config profile, overwrites any stack config
|
|
--dir TEXT Specify cloudbender project directory.
|
|
--debug Turn on debug logging.
|
|
--help Show this message and exit.
|
|
|
|
Commands:
|
|
assimilate Imports potentially existing resources into Pulumi...
|
|
clean Deletes all previously rendered files locally
|
|
create-change-set Creates a change set for an existing stack - CFN only
|
|
create-docs Parses all documentation fragments out of rendered...
|
|
delete Deletes stacks or stack groups
|
|
execute Executes custom Python function within an existing...
|
|
export Exports a Pulumi stack to repair state
|
|
get-config Get a config value, decrypted if secret
|
|
outputs Prints all stack outputs
|
|
preview Preview of Pulumi stack up operation
|
|
provision Creates or updates stacks or stack groups
|
|
refresh Refreshes Pulumi stack / Drift detection
|
|
render Renders template and its parameters - CFN only
|
|
set-config Sets a config value, encrypts with stack key if secret
|
|
sync Renders template and provisions it right away
|
|
validate Validates already rendered templates using cfn-lint...
|
|
version Displays own version and all dependencies
|
|
```
|
|
|
|
# Architecture
|
|
## State management
|
|
### Pulumi
|
|
The state for all Pulumi resources are stored on S3 in your account and in the same region as the resources being deployed.
|
|
No data is send to nor shared with the official Pulumi provided APIs.
|
|
|
|
CloudBender configures Pulumi with a local, temporary workspace on the fly. This incl. the injection of various common parameters like the AWS account ID and region etc.
|
|
|
|
### Cloudformation
|
|
All state is handled by AWS Cloudformation.
|
|
The required account and region are determined by CloudBender automatically from the configuration.
|
|
|
|
|
|
## Config management
|
|
- Within the config folder each directory represents either a stack group if it has sub-directories, or an actual Cloudformation stack in case it is a leaf folder.
|
|
- The actual configuration for each stack is hierachly merged. Lower level config files overwrite higher-level values. Complex data structures like dictionaries and arrays are deep merged.
|
|
|
|
## Secrets
|
|
|
|
### Pulumi
|
|
CloudBender supports the native Pulumi secret handling.
|
|
See [Pulumi Docs](https://www.pulumi.com/docs/intro/concepts/secrets/) for details.
|
|
|
|
### Cloudformation
|
|
CloudBender supports [SOPS](https://github.com/mozilla/sops) to encrypt values in any config file.
|
|
|
|
If a sops encrypted config file is detected by CloudBender, it will automatically try to decrypt the file. All required information to decrypt has to be present in the embedded sops config or set ahead of time via sops supported ENVIRONMENT variables.
|
|
|
|
SOPS support can be disabled by setting `DISABLE_SOPS` in order to reduce timeouts etc.
|