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.

Structure

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

.kubes/resources/
├── base
│   ├── all.yaml
│   └── deployment.yaml
├── clock
│   └── deployment.yaml
└── web
    ├── 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. The .kubes/resources/base folder is treated as a base layer. It gets processed as pre-layers by Kubes.
  2. Then Kubes will process your .kubes/resources/ROLE definitions.
  3. Lastly, Kubes processes any post-layers in the .kubes/resources/ROLE/KIND folders.

Note, both YAML and DSL forms support layering.

Layering only combines resources definitions with the same form. For example, the DSL form base/all.rb will not be combined with YAML form web/deployment.yaml.

Full Layering

Here’s a table showing the the full layering.

Folder/Pattern Example
base/all.yaml base/all.yaml
base/all/ENV.yaml base/all/dev.yaml
base/KIND.yaml base/deployment.yaml
base/KIND/base.yaml base/deployment/base.yaml
base/KIND/ENV.yaml base/deployment/dev.yaml
ROLE/KIND.yaml web/deployment.yaml
ROLE/KIND/base.yaml web/deployment/base.yaml
ROLE/KIND/ENV.yaml web/deployment/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 an example of the structure:

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