DSL 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.rb
│   └── deployment.rb
├── clock
│   └── deployment.rb
└── web
    ├── all.rb
    ├── deployment
    │   ├── dev.rb
    │   └── prod.rb
    ├── deployment.rb
    └── service.rb

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.rb base/all.rb
pre base/all/ENV.rb base/all/dev.rb
pre base/KIND.rb base/deployment.rb
pre base/KIND/base.rb base/deployment/base.rb
pre base/KIND/ENV.rb base/deployment/dev.rb
pre ROLE/all.rb web/all.rb
main ROLE/KIND.rb web/deployment.rb
post ROLE/KIND/base.rb web/deployment/base.rb
post ROLE/KIND/ENV.rb web/deployment/dev.rb
post ROLE/KIND/APP.rb web/deployment/app1.rb
post ROLE/KIND/APP/base.rb web/deployment/app1/base.rb
post ROLE/KIND/APP/ENV.rb web/deployment/app1/dev.rb

Real-World Uses

  1. With Kubes layering you can define common fields in base/all.rb. 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.rb. Example: base/deployment.rb
  2. Then you can define the core of your resource definition in the ROLE/KIND.rb. Example: web/deployment.rb
  3. Finally, you can provide environment-specific overrides in the ROLE/KIND/ENV.rb. Example: web/deployment/dev.rb.

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

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

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

.kubes/output/web/deployment.rb