-
-
Notifications
You must be signed in to change notification settings - Fork 200
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
## Docs and Tests * [ ] Tests added * [X] Updated documentation
- Loading branch information
Showing
5 changed files
with
139 additions
and
124 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| # :kapitan-logo: **Alternative Inventory Backends** | ||
|
|
||
| We provide pluggable backend alternatives for the Inventory: | ||
|
|
||
| * `reclass`(**default**): The original kapitan inventory (see [reclass](https://github.com/kapicorp/reclass)) | ||
| * `reclass-rs`: The Rust drop in replacement (see [reclass-rs](reclass-rs.md)) | ||
| * `omegaconf`: An alternative inventory solution based on [Omegaconf](https://github.com/omry/omegaconf) | ||
|
|
||
| You can switch the backend to by: | ||
|
|
||
| * (**recommended**) Define the backend in the [.kapitan config file](../commands/kapitan_dotfile.md). | ||
| * Passing the `--inventory-backend=backend` command line option when calling `kapitan`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,43 +1,69 @@ | ||
| ## Overview | ||
|
|
||
| <iframe width="560" height="315" src="https://www.youtube.com/embed/M81qU94FCLQ?si=SGlQG-gP2mmA1n9b" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe> | ||
| # :kapitan-logo: **What is the inventory?** | ||
|
|
||
| The **Inventory** is a core component of Kapitan: this section aims to explain how it works and how to best take advantage of it. | ||
|
|
||
| The **Inventory** is a hierarchical `YAML` based structure which you use to capture anything that you want to make available to **Kapitan**, so that it can be passed on to its templating engines. | ||
|
|
||
| The first concept to learn about the **Inventory** is the [**target**](#targets). A target is a file, found under the [`inventory/targets`](#targets) substructure, that tells Kapitan what you want to compile. It will usually map to something you want to do with **Kapitan**. | ||
| ``` | ||
| inventory/ | ||
| ├── classes/ | ||
| │ ├── common/ | ||
| │ │ └── base.yml # Foundational configurations | ||
| │ ├── components/ | ||
| │ │ └── web/ # Component-specific settings | ||
| │ └── environments/ | ||
| │ └── production.yml # Environment-specific configurations | ||
| └── targets/ | ||
| └── production/ | ||
| └── web.yml # Specific deployment configurations | ||
| ``` | ||
|
|
||
| The **Kapitan** inventory is divided between [**targets**](#targets) and [**classes**](#classes). | ||
|
|
||
| For instance, you might want to define a [**target**](#targets) for each environment that you want to deploy using **Kapitan**. | ||
| Both classes and targets are yaml file with the same structure | ||
|
|
||
| The **Inventory** lets you also define and reuse common configurations through YAML files that are referred to as [**classes**](#classes): by listing classes into [**target**](#targets), their content gets merged together and allows you to compose complex configurations without repetitions. | ||
| ```yaml | ||
| classes: | ||
| - common | ||
| - my.other.class | ||
|
|
||
| By combining [**target**](#targets) and [**classes**](#classes), the **Inventory** becomes the SSOT for your whole configuration, and learning how to use it will unleash the real power of **Kapitan**. | ||
| parameters: | ||
| key: value | ||
| key2: | ||
| subkey: value | ||
| ``` | ||
| [**Classes**](#classes) are found by default under the [`inventory/classes`](#classes) directory and define common settings and data that you define once and can be included in other files. This promotes consistency and reduces duplication. | ||
|
|
||
| !!! info | ||
| The **Kapitan** **Inventory** is based on an open source project called [reclass](https://github.com/kapicorp/reclass) and you can find the full documentation on our Github clone. However we discourage you to look directly at the reclass documentation before you learn more about **Kapitan**, because **Kapitan** uses a fork of reclass and greatly simplifies the reclass experience. | ||
| Classes are identified with a name that maps to the directory structure they are nested under. | ||
| In this example, the `kapicorp.common` class represented by the file `classes/kapicorp/common.yml` | ||
|
|
||
| !!! info | ||
| Kapitan allows users to switch the inventory backend to [reclass-rs](https://github.com/projectsyn/reclass-rs). You can switch the backend to reclass-rs by passing `--inventory-backend=reclass-rs` on the command line. Alternatively, you can define the backend in the [.kapitan config file](../commands/kapitan_dotfile.md). | ||
| ``` | ||
| # classes/kapicorp/common.yml | ||
| classes: | ||
| - common | ||
|
|
||
| See the [reclass-rs inventory backend](reclass-rs.md) documentation for more details. | ||
| parameters: | ||
| namespace: ${target_name} | ||
| base_docker_repository: quay.io/kapicorp | ||
| base_domain: kapicorp.com | ||
| ``` | ||
| !!! note | ||
| Kapitan enforces very little structure for the **Inventory**, so that you can adapt it to your specific needs: this might be overwhelming at the beginning: don’t worry, we will explain best practice and give guidelines soon. | ||
| [**Targets**](#targets) are found by default under the [`inventory/targets`](#targets) directory and represent the different environments or components you want to manage. Each target is a YAML file that defines a set of configurations. | ||
| By default, Kapitan will search for its **Inventory** under [`inventory/classes`](#classes) and [`inventory/targets`](#targets). | ||
| For example, you might have targets for **`production`**, **`staging`**, and **`development`** environments. | ||
| ``` | ||
| inventory/ | ||
| ├── classes | ||
| │ ├── applications | ||
| │ ├── components | ||
| │ ├── features | ||
| │ ├── kapitan | ||
| │ ├── projects | ||
| │ └── terraform | ||
| └── targets | ||
| ├── examples | ||
| ├── kapicorp | ||
| └── terraform | ||
| # targets/production.yml | ||
| classes: | ||
| - kapicorp.common | ||
| - components.web | ||
| - environments.production | ||
|
|
||
| parameters: | ||
| target_name: web | ||
| ``` | ||
| By combining [**target**](#targets) and [**classes**](#classes), the **Inventory** becomes the SSOT for your whole configuration, and learning how to use it will unleash the real power of **Kapitan**. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,111 +1,73 @@ | ||
|
|
||
| # Targets | ||
| # :kapitan-logo: **Targets** | ||
|
|
||
| ## Usage | ||
| In the world of Kapitan, a target represents a specific environment or deployment scenario where you want to apply your configurations. | ||
|
|
||
| A target is a file that lives under the [`inventory/targets`](#targets) subdirectory, and that tells **Kapitan** what you want it to do for you. | ||
| Think of it as a blueprint that defines all the necessary settings and parameters for a particular deployment. | ||
|
|
||
| **Kapitan** will recognise all YAML files in the [`inventory/targets`](#targets) subtree as targets. | ||
| For instance, you might have separate targets for **`production`**, **`staging`**, and **`development`** environments, each with its own unique configurations. | ||
|
|
||
| !!! note | ||
| Only use **`.yml`** as extension for **Inventory** files. `.yaml` will not be recognised as a valid **Inventory** file. | ||
| ## Defining targets | ||
| Targets are defined as YAML files within the `inventory/targets/` directory of your Kapitan project. Each target file typically includes: | ||
|
|
||
| What you do with a [**target**](#targets) is largely up to you and your setup. Common examples: | ||
| ``` | ||
| classes: | ||
| # A list of classes to inherit configurations from. | ||
| # This allows you to reuse common settings and avoid repetition | ||
| - | ||
| * **clusters**: Map each [**target**](#targets) to a cluster, capturing all configurations needed for a given cluster. For instance: `targets/clusters/production-cluster1.yml` | ||
| * **applications**: When using **Kapitan** to manage **Kubernetes** applications, you might define a [**target**](#targets) for everything that you would normally deploy in a single namespace, including all its resources, scripts, secrets and documentation. For instance: `targets/mysql.yml` | ||
| * **environments**: You might have want to define a different [**target**](#targets) for each environment you have, like `dev.yml`, `test.yml` and `prod.yml` | ||
| * **cloud projects**: When working with **Terraform**, it may be convenient to group [**target**](#targets) by cloud project. For instance: `targets/gcp/projects/engineering-prod.yml`. | ||
| * **single tenancy**: When deploying a single-tenancy application, you might combine the approaches above, and have a [**target**](#targets) `acme.yml` that is used to define both **Terraform** and **Kubernetes** resources for a given tenant, perhaps also with some **ArgoCD** or **Spinnaker** pipelines to go with it. | ||
| parameters: | ||
| # file parameters that override or extend the parameters inherited from previously loaded classes | ||
| ``` | ||
|
|
||
| Example: | ||
|
|
||
| !!! example | ||
| ```yaml | ||
| # inventory/targets/production/web.yml | ||
| classes: | ||
| - common | ||
| - components.nginx | ||
|
|
||
| If you have configured your kapitan repository like in [Quick Start](/kapitan_overview/#setup-your-repository) instructions, you can run the commands we give during the course of this documentation. | ||
| parameters: | ||
| environment: production | ||
| description: ${environment} environment | ||
| nginx: | ||
| replicas: 3 | ||
| namespace: ${environment} | ||
| ``` | ||
| !!! quote "" | ||
| In this example, the `production.web` target: | ||
|
|
||
| `kapitan compile` | ||
| * Inherits configurations from the common and components.nginx classes. | ||
| * Sets the `environment` parameter to **`production`**. | ||
| * Overrides (if defined) the `replicas` for the `nginx` component to `3`. | ||
| * Defines the namespace as **`production`** using variable interpolation. | ||
| * Creates a dynamic description based on the content of the environment variable. | ||
|
|
||
| ```shell | ||
| Compiled gke-pvm-killer (0.09s) | ||
| Compiled vault (0.18s) | ||
| Compiled pritunl (0.17s) | ||
| Compiled mysql (0.07s) | ||
| Compiled examples (0.25s) | ||
| Compiled postgres-proxy (0.06s) | ||
| Compiled echo-server (0.08s) | ||
| Compiled global (0.05s) | ||
| Compiled tutorial (0.09s) | ||
| Compiled guestbook-argocd (0.08s) | ||
| Compiled sock-shop (0.30s) | ||
| Compiled kapicorp-demo-march (0.04s) | ||
| Compiled kapicorp-project-123 (0.03s) | ||
| Compiled kapicorp-terraform-admin (0.08s) | ||
| Compiled tesoro (0.09s) | ||
| Compiled prod-sockshop (0.34s) | ||
| Compiled dev-sockshop (0.41s) | ||
| Compiled argocd (2.53s) | ||
| ``` | ||
| ## Compiling targets | ||
| When you run kapitan compile -t <target_name>, Kapitan: | ||
|
|
||
| When you run `kapitan compile`, you instruct **Kapitan** to generate for each given [**target**](#targets) a directory under `compiled` with the same name. Under this directory you will find all the files that have been generated by **Kapitan** for that target. | ||
| * Reads the target file: Kapitan parses the YAML file for the specified target. | ||
| * Merges configurations: It merges the parameters from the included classes with the target-specific parameters, giving priority to the target's values. | ||
| * Generates output in `compiled/target/path/targetname`: It uses this merged configuration data, along with the input types and generators, to create the final configuration files for the target environment. | ||
|
|
||
| !!! quote "" | ||
| When you run `kapitan` without the selector, it will run compile for all targets it discovers under the `inventory/targets` subdirectory. | ||
|
|
||
| `tree compiled/mysql/` | ||
| ## Target directory structure | ||
| Targets are not limited to living directly within the `inventory/targets` directory. | ||
|
|
||
| ```shell | ||
| compiled/mysql/ | ||
| ├── argocd | ||
| ├── docs | ||
| │ ├── mysql-readme.md | ||
| │ └── README.md | ||
| ├── manifests | ||
| │ ├── mysql-bundle.yml | ||
| │ ├── mysql-config.yml | ||
| │ ├── mysql-namespace.yml | ||
| │ └── mysql-secret.yml | ||
| ├── pre-deploy | ||
| ├── rabbitmq | ||
| ├── scripts | ||
| └── terraform | ||
| They can be organized into subdirectories to create a more structured and hierarchical inventory. This is particularly useful for managing large and complex projects. | ||
|
|
||
| 7 directories, 6 files | ||
| ``` | ||
| When targets are organized in subdirectories, Kapitan uses the full path from the `targets/` directory to create the target name. This name is then used to identify the target during compilation and in the generated output. | ||
|
|
||
| ## Definition | ||
| Example for target `clusters.production.my-cluster` | ||
|
|
||
| A typical [**target**](#targets) might look like this: | ||
| ```shell | ||
| inventory/ | ||
| └── targets/ | ||
| └── clusters/ | ||
| └── production/ | ||
| └── my-cluster.yml | ||
| ``` | ||
|
|
||
| !!! example "`inventory/targets/acme/dev.yaml`" | ||
|
|
||
| ```yaml | ||
| classes: | ||
| - common | ||
| - components.acme.frontend | ||
| - components.acme.backend | ||
|
|
||
| parameters: | ||
| target_name: dev | ||
| ``` | ||
|
|
||
| Note that it is made of 2 sections: | ||
|
|
||
| * `classes` is a list of class files you will want to import. | ||
| * `parameters` allows for local override of what is unique to this target. | ||
|
|
||
| !!! info | ||
|
|
||
| the `kapitan` key under the root `parameters` is reserved for kapitan usage. Some examples: | ||
|
|
||
| ```yaml | ||
| parameters: | ||
| kapitan: | ||
| compile: # input types configuration section | ||
| dependencies: # dependencies configuration section to download resources | ||
| secrets: # secret encryption/decryption configuration section | ||
| validate: # items which indicate which compiled output to validate | ||
| vars: # which are also passed down to input types as context | ||
| ``` | ||
|
|
||
| *[SSOT]: Single Source Of Truth | ||
| In this example, the `my-cluster.yml` target file is located within the `clusters/production/` subdirectory, and can be identified with `clusters.production.my-cluster`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters