20_folder-structure.md

Folder Structure

This document will describe how we create the directory structure inside the project folder and what files we will handle directly and what file the end user can use for adding its customizations.
At the first level inside the root directory, the user will find:

• The configuration file config.yaml
• The vendors folder, containing the Kustomize bases for modules and add-ons
• The clusters folder, including the Kustomize files used for creating the various resources divided by clusters and groups

Vendors

The vendors folder will include two main subfolders: modules and addons.
The two folders will contains the modules and add-ons specified inside the configuration file; if a module or add-on is imported multiple time with the same version only one copy is saved, but if different versions are specified you will find a folder for every version.

For example:

./project-name
├── config.yaml
├── clusters
|   └── [...]
└── vendors
    ├── modules
    |   ├── <module-category>
    |   |   └── <module-name-1>-<valid semver>
    |   |       ├── <flavor-name1>
    |   |       |   ├── [...]
    |   |       |   └── kustomization.yaml
    |   |       └── <flavor-name2>
    |   |           ├── [...]
    |   |           └── kustomization.yaml
    |   └── <module-category>
    |       └── <module-name-2>-<valid semver>
    |           ├── <flavor-name1>
    |           |   ├── [...]
    |           |   └── kustomization.yaml
    |           └── <flavor-name2>
    |               ├── [...]
    |               └── kustomization.yaml
    └── add-ons
        └── <addon-category>
            ├── <addon-name1>-v1.0.0
            |   ├── [...]
            |   └── kustomization.yaml
            └── <addon-name1>-v1.2.0
                ├── [...]
                └── kustomization.yaml

Clusters

The structure of the folder clusters depends on the cluster configuration provided by the user.
For every cluster it will be created a folder structure like <group-name>/<cluster-name>/bases. In this strucure inside the bases folder a kustomization.yaml file will be created and regenarated every time the sync command is launched and will contain the orderd import of the modules and add-ons selected for that cluster. Since this file is automatically generated the user cannot modify it directly because every manual change will not be kept.

The customization for that cluster can be added to the main kustomization.yaml file that can be found inside the <group-name>/<cluster-name> folder. In the directory the user can add all the additional resources or patches that it needs and organaze them as he may seem fit.

Additionally to the clusters folders a all-groups folder will be created containing the bases and custom-resources folders. As the cluster folder, the file contained in the bases folder is generated automatically and all additional resources that the user may want to add to all the clusters must be added to the custom-resources folder and its kustomization.yaml file. In this folder the user cannot setup patches for allowing customization of the bases by the single clusters.

Here an example of the folders structures:

./project-name
├── config.yaml
├── vendors
|   └── [...]
└── clusters
    ├── all-groups
    |   ├── bases
    |   |   └── kustomization.yaml
    |   ├── custom-resources
    |   |   └── kustomization.yaml
    |   └── kustomization.yaml
    ├── group-1
    |   ├── cluster-1
    |   |   ├── bases
    |   |   |   └── kustomization.yaml
    |   |   ├── custom-resources
    |   |   |   ├── traefik
    |   |   |   |   └── patch.yaml
    |   |   |   ├── calico
    |   |   |   |   └── patch.yaml
    |   |   |   └── kustomization.yaml
    |   |   └── kustomization.yaml
    |   └── cluster-2
    |       ├── bases
    |       |   └── kustomization.yaml
    |       ├── custom-resources
    |       |   ├── cilium
    |       |   |   └── patch-3.yaml
    |       |   └── kustomization.yaml
    |       └── kustomization.yaml
    └── group-2
        └── [...]

It is critical for the kustomization.yaml files to be well-formed and consistent with the directory structure and for the user to not add changes to the file that will be regenerated automatically.