Beaver
____
| __ ) ___ __ ___ _____ _ __
| _ \ / _ \/ _` \ \ / / _ \ '__|
| |_) | __/ (_| |\ V / __/ |
|____/ \___|\__,_| \_/ \___|_|
Description
beaver is a tool to build your k8s templates in a descriptive way.
Features
- template engine:
- patch engine:
- multi environment variables
- sha256 sum for any compiled resource can be used as variable
- inheritance between
beaverproject - each built resource is output inside it's own file
Usage
beaver build <path/to/beaver/project>see beaver build --help for more options.
Beaver project
A beaver project consists of a folder with a beaver config file, either beaver.yaml or beaver.yml.
Beaver config file
# Default namespace used for this project
namespace: default
# an inherited beaver project - which can also inherit another beaver project
inherit: ../../base # path is relative to this beaver config file
inherits:
- ../../base1
- ../../base2
# your project charts
charts:
postgres: # your chart local name
type: helm # can be either helm or ytt
path: ../.vendor/helm/postgresql # path to your chart - relative to this file
name: pgsql # overwrite **helm** application name
# Keyword `namespace` only available for Helm charts
namespace: my-namespace # Set namespace only for the current chart(Optional)
# beaver variables that can be used inside your charts value files
# They are two methods
# First method :
variables:
- name: tag # give your variable a name
value: v1.2.3 # and a value
# Second method :
variables:
tag: v1.2.3
my_dict1:
my_key1: value1
my_dict2:
my_key2: value2
my_list:
- elem1
- elem2
# You can also use inherit to overlay variables
# in project/base1/beaver.yaml :
variables:
my_dict:
key1: value1
key2: value2
# If you want to redefine all dict
# in project/base2/beaver.yaml :
inherit: ../base1
variables:
my_dict:
newKey1: value3
# Or if you want to redifine part of dict
inherit: ../base1
variables:
my_dict.key1: value3
# result of dict :
variables:
my_dict:
key1:value3
key2: value1
# generate beaver variables from compiled resource file sha256
sha:
- key: configmap_demo # use to generate beaver variable name
resource: ConfigMap.v1.demo.yaml # compiled resource filename
# create some resources using `kubectl create`
create:
- type: configmap # resource kind as passed to kubectl create
name: xbus-pipelines # resource name
args: # kubectl create arguments
- flag: --from-file
value: pipelinesValue files
Value files filename use the following format:
<chart_local_name>.[yaml,yml]you can provide a value file for your chart using its local name, and beaver
will pass this file to your template engine.
If you have a value file with the same name inside an inherited project then
beaver will also pass this one, but prior to your project file. This ensures
that your current values overwrite inherited values.
example:
# folder structure
.
├── base
│ ├── beaver.yml
│ └── postgres.yml
└── environments
└── demo
├── beaver.yml
└── postgres.yaml# base/beaver.yml
charts:
postgres:
type: postgres
path: ../.vendor/postgresql# environments/demo/beaver.yml
inherit: ../../base
namespace: demoIn the example above beaver will automaticaly pass base/postgres.yml and then
environments/demo/postgres.yaml to helm using .vendor/postgresql as chart
folder.
Beaver variables
beaver variables can be used inside your value files, and only inside value
files, using the following syntax:
<[variable_name]>example:
# base/beaver.yaml
variables:
- name: pg_tag
value: 14.4-alpine
charts:
postgres:
type: postgres
path: ../.vendor/postgresql# base/postgres.yml
image:
tag: <[pg_tag]>beaver variables are merged during inheritance, example:
# base/beaver.yaml
variables:
- name: pg_tag
value: 14.4-alpine# environments/demo/beaver.yaml
inherit: ../../base
variables:
- name: pg_tag
value: 13.7-alpinehere pg_tag value will be 13.7-alpine if you run
beaver build environments/demo.
Output files
beaver output files have the following format:
<kind>.<apiVersion>.<metadata.name>.yamlall apiVersion slashes (/) are replaced by underscores (_).
This convention will help you reviewing merge requests.
By default beaver will store those files inside ${PWD}/build/<namespace>, you
can use -o or --output to specify an output directory.
sha256 sum variables
Use generated sha256 sum in your chart value files with the following syntax:
<[sha.key]>For example:
# base/beaver.yaml
sha:
- key: configmap_demo
resource: ConfigMap.v1.demo.yamlWill generate a sha256 hex sum for ConfigMap.v1.demo.yaml compiled file.
Then you can use it in your value file using:
# base/postgres.yml
label:
configmapSha: <[sha.configmap_demo]>Patch using YTT overlay
You can patch all your compiled resources using
ytt overlays by providing
ytt.yaml or ytt.yml files or a ytt folder inside your beaver project(s).
You can use beaver variables inside ytt files (outside of ytt folder), because
beaver considers those as value files.
Create resources using kubectl create
example:
# base/beaver.yaml
# create some resources using `kubectl create`
create:
- type: configmap # resource kind as passed to kubectl create
name: xbus-pipelines # resource name
args: # kubectl create arguments
- flag: --from-file
value: pipelinesIn the current context we have a pipelines folder inside base folder with
some files inside it.
beaver will run the following command inside base folder:
kubectl create configmap xbus-pipelines --from-file pipelinesKustomize
To use kustomize create a kustomize folder inside your beaver project and
use kustomize as usual.
A special beaver variable is available in your kustomization.yaml file:
<[beaver.build]> which exposes your beaver build temp directory, so you can
kustomize your previous builds (helm, ytt, etc.).
example:
# folder structure
.
└── base
├── beaver.yml
└── kustomize
└── kustomization.yamlresources: # was previously named `bases`
- <[beaver.build]>
# now kustomize as usual.
patches:
- myPatch.yaml