YAML Layering

Kubes Layering in it’s full form allows you to keep your resource definitions DRY and create different environments with the same code.

Project Structure

Here’s an example structure, so we can understand how layering works.

.kubes/resources/
├── base
│   ├── all.yaml
│   └── deployment.yaml
├── clock
│   └── deployment.yaml
└── web
    ├── all.yaml
    ├── deployment
    │   ├── dev.yaml
    │   └── prod.yaml
    ├── deployment.yaml
    └── service.yaml

Layering Basics

To explain the layering, here’s the general processing order that Kubes takes.

  1. Pre Layers: The .kubes/resources/base folder is treated as a base layer. It gets processed as pre-layers by Kubes.
  2. Main Layer: Then Kubes will process your .kubes/resources/ROLE definitions.
  3. Post Layers: Lastly, Kubes processes any post-layers in the .kubes/resources/ROLE/KIND folders.

Notes

  • Both YAML and DSL forms support layering. They can be mixed together.
  • In the Main Layer you can define single or multiple resource definitions.

Full Layering

Here’s a table showing the the full layering.

Type Folder/Pattern Example
pre base/all.yaml base/all.yaml
pre base/all/ENV.yaml base/all/dev.yaml
pre base/KIND.yaml base/deployment.yaml
pre base/KIND/base.yaml base/deployment/base.yaml
pre base/KIND/ENV.yaml base/deployment/dev.yaml
pre ROLE/all.yaml web/all.yaml
main ROLE/KIND.yaml web/deployment.yaml
post ROLE/KIND/base.yaml web/deployment/base.yaml
post ROLE/KIND/ENV.yaml web/deployment/dev.yaml
post ROLE/KIND/APP.yaml web/deployment/app1.yaml
post ROLE/KIND/APP/base.yaml web/deployment/app1/base.yaml
post ROLE/KIND/APP/ENV.yaml web/deployment/app1/dev.yaml

Real-World Uses

  1. With Kubes layering you can define common fields in base/all.yaml. Examples: namespace, labels, annotations. If you have additional common base-level fields, but are specific to a Kind. Then you can defined them in base/KIND.yaml. Example: base/deployment.yaml
  2. Then you can define the core of your resource definition in the ROLE/KIND.yaml. Example: web/deployment.yaml
  3. Finally, you can provide environment-specific overrides in the ROLE/KIND/ENV.yaml. Example: web/deployment/dev.yaml.

Here’s a concrete example of layering with the deployment resource kind:

.kubes/resources/base/all.yaml
.kubes/resources/base/deployment.yaml
.kubes/resources/web/deployment.yaml
.kubes/resources/web/deployment/dev.yaml

All of these files get layered and merged together to produce a resulting deployment.yaml

.kubes/output/web/deployment.yaml