diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c55984d98..c7b4a8c27 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -3,7 +3,6 @@ repos: rev: 22.10.0 hooks: - id: black - language_version: python3.8 - repo: https://github.com/igorshubovych/markdownlint-cli rev: v0.32.2 hooks: diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 000000000..3907abd1f --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,70 @@ +# :kapitan-logo: **Kapitan Overview** + +## Setup your repository + +!!! note + We are currently working on improving the experience to give you an even quicker experience with Kapitan + +### Quickstart + +[kapicorp/kapitan-reference](https://github.com/kapicorp/kapitan-reference) repository is meant to be a way to bootstrap your **Kapitan** setup to get you up and running. + +It is meant to help you make use of best practices and libraries that can make Kapitan the ultimate tool for all your configuration needs. + +``` +$ git clone git@github.com:kapicorp/kapitan-reference.git kapitan-templates +$ cd kapitan-templates + +$ ./kapitan compile +Compiled postgres-proxy (1.51s) +Compiled tesoro (1.70s) +Compiled echo-server (1.64s) +Compiled mysql (1.67s) +Compiled gke-pvm-killer (1.17s) +Compiled prod-sockshop (4.74s) +Compiled dev-sockshop (4.74s) +Compiled tutorial (1.68s) +Compiled global (0.76s) +Compiled examples (2.60s) +Compiled pritunl (2.03s) +Compiled sock-shop (4.36s) +``` + +### From Scratch (Advanced) + +!!! warning + + the `kapitan init` command leaves you with a bare configuration. Setting up Kapitan might require time. + + Please use the [**Quickstart**](#quickstart) setup if you want to get started quicker. + +If you want to start off with a clean **kapitan** project, you can run `kapitan init --directory ` to populate a new directory with the recommended kapitan folder structure. + +The bare minimum structure that makes use of kapitan features may look as follows: + +```text +. +├── components +│ ├── mycomponent.jsonnet +├── templates +├── ├── README.md +├── inventory +│ ├── classes +│ │ ├── common.yml +│ └── targets +│ ├── dev.yml +│ ├── staging.yml +│ └── prod.yml +├── refs +│ ├── targets +│ │ ├── prod +│ │ │ └── password +└───├── common + └── example-com-tls.key +``` + +* `components`: template files for kadet, jsonnet and helm +* `templates`: stores Jinja2 templates for scripts and documentation +* `inventory/targets`: target files +* `inventory/classes`: inventory classes to be inherited by targets +* `refs`: references files diff --git a/docs/inventory.md b/docs/inventory.md deleted file mode 100644 index c24d11c26..000000000 --- a/docs/inventory.md +++ /dev/null @@ -1,316 +0,0 @@ -# :kapitan-logo: **Inventory** - -## Overview - -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**. - -For instance, you might want to define a [**target**](#targets) for each environment that you want to deploy using **Kapitan**. - -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. - -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**. - -!!! 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. - -!!! 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. - -By default, Kapitan will search for its **Inventory** under [`inventory/classes`](#classes) and [`inventory/targets`](#targets). - -``` -inventory/ -├── classes -│ ├── applications -│ ├── components -│ ├── features -│ ├── kapitan -│ ├── projects -│ └── terraform -└── targets - ├── examples - ├── kapicorp - └── terraform -``` - -## Targets - -### Usage - -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. - - **Kapitan** will recognise all YAML files in the [`inventory/targets`](#targets) subtree as targets. - -!!! note - Only use **`.yml`** as extension for **Inventory** files. `.yaml` will not be recognised as a valid **Inventory** file. - -What you do with a [**target**](#targets) is largely up to you and your setup. Common examples: - -* **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. - - -!!! example - - 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. - - !!! quote "" - - `kapitan compile` - - ```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) - ``` - - 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. - - !!! quote "" - - `tree compiled/mysql/` - - ```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 - - 7 directories, 6 files - ``` - -### Definition - -A typical [**target**](#targets) might look like this: - -!!! 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 - ``` - - -## Classes - -### Usage - -The next thing you want to learn about the inventory are [**classes**](#classes). A class is a yaml file containing a fragment of yaml that we want to import and merge into the inventory. - -[**Classes**](#classes) are *fragments* of yaml: feature sets, commonalities between targets. [**Classes**](#classes) let you compose your [**Inventory**](/inventory/) from smaller bits, eliminating duplication and exposing all important parameters from a single, logically organised place. As the [**Inventory**](#inventory) lets you reference other parameters in the hierarchy, [**classes**](#classes) become places where you can define something that will then get referenced from another section of the inventory, allowing for composition. - -[**Classes**](#classes) are organised under the [`inventory/classes`](#classes) directory substructure. -They are organised hierarchically in subfolders, and the way they can be imported into a [**target**](#targets) or other [**classes**](#classes) depends on their location relative to the [`inventory/classes`](#classes) directory. - - -### Importing classes - -To import a class from within another file of the [**Inventory**](#inventory), you can follow these instructions: - -* take the file path relative to the `inventory/classes/` directory -* remove the `.yml` file extension -* replace `/` with `.` - -For example, this will import the class `inventory/classes/applications/sock-shop.yaml` - -```yaml -classes: -- applications.sock-shop -``` - -### Definition - -Let's take a look at the `common` class which appears in the example above: - -As explained, because the **`common.yaml`** is directly under the **`inventory/classes`** subdirectory, it can be imported directly into a target with: - -```yaml -classes: -- common -``` - -If we open the file, we find another familiar yaml fragment. - -!!! example "`inventory/classes/common.yml`" - - ```yaml - classes: - - kapitan.common - - parameters: - namespace: ${target_name} - target_name: ${_reclass_:name:short} - ``` - -Notice that this class includes an import definition for another class, `kapitan.common`. We've already learned this means that kapitan will import a file on disk called `inventory/classes/kapitan/common.yml` - -You can also see that in the `parameters` section we now encounter a new syntax which unlocks another powerful inventory feature: *parameters interpolation*! - -## Parameters Interpolation - -!!! note - - as a shorthand, when we encounter deep yaml structures like the following: - - ```yaml - parameters: - components: - nginx: - image: nginx:latest - ``` - - Usually when we want to talk about the `image` subkey, we normally use either of the following: - - * `parameters.components.nginx.image` - * `components.nginx.image` - - However, when used in parameter expansion, remember to: - - * replace the `.` with `:` - * omit the `parameters` initial key which is implied - * wrap it into the `${}` variable interpolation syntax - - The correct way to reference `parameters.nginx.image` then becomes `${components:nginx:image}`. - -The [**Inventory**](#inventory) allows you to refer to other values defined elsewhere in the structure, using parameter interpolation. - -Given the example: - -```yaml - -parameters: - cluster: - location: europe - - application: - location: ${cluster:location} - - namespace: ${target_name} - target_name: dev -``` - - - -Here we tell **Kapitan** that: - -* `namespace` should take the same value defined in `target_name` -* `target_name` should take the literal string `dev` -* `application.location` should take the same value as defined in `cluster.location` - -It is important to notice that the inventory can refer to values defined in other classes, as long as they are imported by the target. So for instance with the following example - -```yaml - -classes: - - project.production - - parameters: - application: - location: ${cluster.location} -``` - -Here in this case `application.location` refers to a value `location` which has been defined elsewhere, perhaps (but not necessarily) in the `project.production` class. - -Also notice that the class name (`project.production`) is not in any ways influencing the name or the structed of the yaml it imports into the file - -## Advanced Inventory Features - - -### Target labels - -Kapitan allows you to define labels in your inventory, which can then be used to group together targets with similar labels. - -For instance you could define the following: - -!!! example "" - - Defines a class to add the `customer` label to selected targets - - !!! example "`inventory/classes/type/customer_project.yml`" - ```yaml - parameters: - customer_name: ${target_name} # Defaults to the target_name - kapitan: - labels: - customer: ${customer_name} - ``` - - Apply the class to the target for customer `acme` - !!! example "`inventory/targets/customers/acme.yml`" - - ```yaml - classes: - ... - - type.customer_project - - parameters: - ... - ``` - - You can now selectively compile targets for customer `acme` using the following (see see [**Labels**](/website/commands/kapitan_compile/#using-labels) for more details ) - - !!! example "" - - ```shell - kapitan compile -l customer=acme - Compiled acme (0.06s) - Compiled acme-documentation (0.09s) - ``` - -*[SSOT]: Single Source Of Truth diff --git a/docs/pages/blog/2023-01-16.md b/docs/pages/blog/2023-01-16.md index 0277f910f..e24bed6ad 100644 --- a/docs/pages/blog/2023-01-16.md +++ b/docs/pages/blog/2023-01-16.md @@ -15,4 +15,4 @@ Head over our [release page](https://github.com/kapicorp/kapitan/releases/tag/v0 If you missed it, have a look at our latest blog post here [5 years of Kapitan](2022-12-04.md) -Please help us by visiting our [Sponsor Kapitan](../contribute/sponsor.md) page. \ No newline at end of file +Please help us by visiting our [Sponsor Kapitan](../contribute/sponsor.md) page. diff --git a/docs/external_dependencies.md b/docs/pages/external_dependencies.md similarity index 100% rename from docs/external_dependencies.md rename to docs/pages/external_dependencies.md diff --git a/docs/pages/input_types/introduction.md b/docs/pages/input_types/introduction.md index 2436f1af6..f42cd2e50 100644 --- a/docs/pages/input_types/introduction.md +++ b/docs/pages/input_types/introduction.md @@ -1,4 +1,4 @@ -# :kapitan-logo: **Input Types | Introduction** +# Introduction **Note:** make sure to read up on [inventory](/inventory.md) before moving on. diff --git a/docs/pages/inventory/advanced.md b/docs/pages/inventory/advanced.md new file mode 100644 index 000000000..ef70fdbab --- /dev/null +++ b/docs/pages/inventory/advanced.md @@ -0,0 +1,44 @@ +# Advanced Inventory Features + +## Target labels + +Kapitan allows you to define labels in your inventory, which can then be used to group together targets with similar labels. + +For instance you could define the following: + +!!! example "" + + Defines a class to add the `customer` label to selected targets + + !!! example "`inventory/classes/type/customer_project.yml`" + ```yaml + parameters: + customer_name: ${target_name} # Defaults to the target_name + kapitan: + labels: + customer: ${customer_name} + ``` + + Apply the class to the target for customer `acme` + !!! example "`inventory/targets/customers/acme.yml`" + + ```yaml + classes: + ... + - type.customer_project + + parameters: + ... + ``` + + You can now selectively compile targets for customer `acme` using the following (see see [**Labels**](/website/commands/kapitan_compile/#using-labels) for more details ) + + !!! example "" + + ```shell + kapitan compile -l customer=acme + Compiled acme (0.06s) + Compiled acme-documentation (0.09s) + ``` + + diff --git a/docs/pages/inventory/classes.md b/docs/pages/inventory/classes.md new file mode 100644 index 000000000..72a8c404b --- /dev/null +++ b/docs/pages/inventory/classes.md @@ -0,0 +1,55 @@ +# Classes + +## Usage + +The next thing you want to learn about the inventory are [**classes**](#classes). A class is a yaml file containing a fragment of yaml that we want to import and merge into the inventory. + +[**Classes**](#classes) are *fragments* of yaml: feature sets, commonalities between targets. [**Classes**](#classes) let you compose your [**Inventory**](/inventory/) from smaller bits, eliminating duplication and exposing all important parameters from a single, logically organised place. As the [**Inventory**](#inventory) lets you reference other parameters in the hierarchy, [**classes**](#classes) become places where you can define something that will then get referenced from another section of the inventory, allowing for composition. + +[**Classes**](#classes) are organised under the [`inventory/classes`](#classes) directory substructure. +They are organised hierarchically in subfolders, and the way they can be imported into a [**target**](#targets) or other [**classes**](#classes) depends on their location relative to the [`inventory/classes`](#classes) directory. + + +### Importing classes + +To import a class from within another file of the [**Inventory**](#inventory), you can follow these instructions: + +* take the file path relative to the `inventory/classes/` directory +* remove the `.yml` file extension +* replace `/` with `.` + +For example, this will import the class `inventory/classes/applications/sock-shop.yaml` + +```yaml +classes: +- applications.sock-shop +``` + +## Definition + +Let's take a look at the `common` class which appears in the example above: + +As explained, because the **`common.yaml`** is directly under the **`inventory/classes`** subdirectory, it can be imported directly into a target with: + +```yaml +classes: +- common +``` + +If we open the file, we find another familiar yaml fragment. + +!!! example "`inventory/classes/common.yml`" + + ```yaml + classes: + - kapitan.common + + parameters: + namespace: ${target_name} + target_name: ${_reclass_:name:short} + ``` + +Notice that this class includes an import definition for another class, `kapitan.common`. We've already learned this means that kapitan will import a file on disk called `inventory/classes/kapitan/common.yml` + +You can also see that in the `parameters` section we now encounter a new syntax which unlocks another powerful inventory feature: *parameters interpolation*! + diff --git a/docs/pages/inventory/introduction.md b/docs/pages/inventory/introduction.md new file mode 100644 index 000000000..608a33bb9 --- /dev/null +++ b/docs/pages/inventory/introduction.md @@ -0,0 +1,36 @@ +## Overview + +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**. + +For instance, you might want to define a [**target**](#targets) for each environment that you want to deploy using **Kapitan**. + +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. + +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**. + +!!! 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. + +!!! 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. + +By default, Kapitan will search for its **Inventory** under [`inventory/classes`](#classes) and [`inventory/targets`](#targets). + +``` +inventory/ +├── classes +│ ├── applications +│ ├── components +│ ├── features +│ ├── kapitan +│ ├── projects +│ └── terraform +└── targets + ├── examples + ├── kapicorp + └── terraform +``` diff --git a/docs/pages/inventory/parameters_interpolation.md b/docs/pages/inventory/parameters_interpolation.md new file mode 100644 index 000000000..04bc273b5 --- /dev/null +++ b/docs/pages/inventory/parameters_interpolation.md @@ -0,0 +1,67 @@ +# Parameters Interpolation + +!!! note + + as a shorthand, when we encounter deep yaml structures like the following: + + ```yaml + parameters: + components: + nginx: + image: nginx:latest + ``` + + Usually when we want to talk about the `image` subkey, we normally use either of the following: + + * `parameters.components.nginx.image` + * `components.nginx.image` + + However, when used in parameter expansion, remember to: + + * replace the `.` with `:` + * omit the `parameters` initial key which is implied + * wrap it into the `${}` variable interpolation syntax + + The correct way to reference `parameters.nginx.image` then becomes `${components:nginx:image}`. + +The [**Inventory**](#inventory) allows you to refer to other values defined elsewhere in the structure, using parameter interpolation. + +Given the example: + +```yaml + +parameters: + cluster: + location: europe + + application: + location: ${cluster:location} + + namespace: ${target_name} + target_name: dev +``` + + + +Here we tell **Kapitan** that: + +* `namespace` should take the same value defined in `target_name` +* `target_name` should take the literal string `dev` +* `application.location` should take the same value as defined in `cluster.location` + +It is important to notice that the inventory can refer to values defined in other classes, as long as they are imported by the target. So for instance with the following example + +```yaml + +classes: + - project.production + + parameters: + application: + location: ${cluster.location} +``` + +Here in this case `application.location` refers to a value `location` which has been defined elsewhere, perhaps (but not necessarily) in the `project.production` class. + +Also notice that the class name (`project.production`) is not in any ways influencing the name or the structed of the yaml it imports into the file + diff --git a/docs/pages/inventory/targets.md b/docs/pages/inventory/targets.md new file mode 100644 index 000000000..48da8a0f5 --- /dev/null +++ b/docs/pages/inventory/targets.md @@ -0,0 +1,111 @@ + +# Targets + +## Usage + +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. + + **Kapitan** will recognise all YAML files in the [`inventory/targets`](#targets) subtree as targets. + +!!! note + Only use **`.yml`** as extension for **Inventory** files. `.yaml` will not be recognised as a valid **Inventory** file. + +What you do with a [**target**](#targets) is largely up to you and your setup. Common examples: + +* **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. + + +!!! example + + 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. + + !!! quote "" + + `kapitan compile` + + ```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) + ``` + + 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. + + !!! quote "" + + `tree compiled/mysql/` + + ```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 + + 7 directories, 6 files + ``` + +## Definition + +A typical [**target**](#targets) might look like this: + +!!! 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 diff --git a/docs/kapitan_overview.md b/docs/pages/kapitan_overview.md similarity index 75% rename from docs/kapitan_overview.md rename to docs/pages/kapitan_overview.md index b1166e53d..86cff2692 100644 --- a/docs/kapitan_overview.md +++ b/docs/pages/kapitan_overview.md @@ -105,7 +105,7 @@ everything that matters in your setup, for instance you can define: After defining it, you can make this data available to the various templating engines [***Input types***](#input-types) offered by Kapitan, allowing you to reuse it. -Find more detaled explanation in the [inventory](inventory.md) section of the documentation. +Find more detaled explanation in the [inventory](inventory/introduction.md) section of the documentation. ### Input types @@ -195,75 +195,6 @@ Use Kapitan to securely generate and manage secrets with GPG, AWS KMS, gCloud KM Use [Tesoro](https://github.com/kapicorp/tesoro), our **Kubernetes Admission Controller**, to complete your integration with Kubernetes for secure secret decryption on-the-fly. -## Setup your repository - -!!! note - We are currently working on improving the experience to give you an even quicker experience with Kapitan - -### Quickstart - -[kapicorp/kapitan-reference](https://github.com/kapicorp/kapitan-reference) repository is meant to be a way to bootstrap your **Kapitan** setup to get you up and running. - -It is meant to help you make use of best practices and libraries that can make Kapitan the ultimate tool for all your configuration needs. - -``` -$ git clone git@github.com:kapicorp/kapitan-reference.git kapitan-templates -$ cd kapitan-templates - -$ ./kapitan compile -Compiled postgres-proxy (1.51s) -Compiled tesoro (1.70s) -Compiled echo-server (1.64s) -Compiled mysql (1.67s) -Compiled gke-pvm-killer (1.17s) -Compiled prod-sockshop (4.74s) -Compiled dev-sockshop (4.74s) -Compiled tutorial (1.68s) -Compiled global (0.76s) -Compiled examples (2.60s) -Compiled pritunl (2.03s) -Compiled sock-shop (4.36s) -``` - -### From Scratch (Advanced) - -!!! warning - - the `kapitan init` command leaves you with a bare configuration. Setting up Kapitan might require time. - - Please use the [**Quickstart**](#quickstart) setup if you want to get started quicker. - -If you want to start off with a clean **kapitan** project, you can run `kapitan init --directory ` to populate a new directory with the recommended kapitan folder structure. - -The bare minimum structure that makes use of kapitan features may look as follows: - -```text -. -├── components -│ ├── mycomponent.jsonnet -├── templates -├── ├── README.md -├── inventory -│ ├── classes -│ │ ├── common.yml -│ └── targets -│ ├── dev.yml -│ ├── staging.yml -│ └── prod.yml -├── refs -│ ├── targets -│ │ ├── prod -│ │ │ └── password -└───├── common - └── example-com-tls.key -``` - -* `components`: template files for kadet, jsonnet and helm -* `templates`: stores Jinja2 templates for scripts and documentation -* `inventory/targets`: target files -* `inventory/classes`: inventory classes to be inherited by targets -* `refs`: references files - ## Credits * [Jsonnet](https://github.com/google/jsonnet) diff --git a/docs/remote_repositories.md b/docs/pages/remote_repositories.md similarity index 100% rename from docs/remote_repositories.md rename to docs/pages/remote_repositories.md diff --git a/kapitan/inputs/kadet.py b/kapitan/inputs/kadet.py index f9b556434..ebd1c97c0 100644 --- a/kapitan/inputs/kadet.py +++ b/kapitan/inputs/kadet.py @@ -92,13 +92,21 @@ def compile_file(self, file_path, compile_path, ext_vars, **kwargs): ext_vars is not used in Kadet kwargs: output: default 'yaml', accepts 'json' +<<<<<<< HEAD prune_output: default False +======= + prune_input: default False +>>>>>>> dcd110c (Fix typo in kadet prune input handling) reveal: default False, set to reveal refs on compile target_name: default None, set to current target being compiled indent: default 2 """ output = kwargs.get("output", "yaml") +<<<<<<< HEAD prune_output = kwargs.get("prune_output", False) +======= + prune_input = kwargs.get("prune_input", False) +>>>>>>> dcd110c (Fix typo in kadet prune input handling) reveal = kwargs.get("reveal", False) target_name = kwargs.get("target_name", None) # inventory_path = kwargs.get("inventory_path", None) @@ -135,7 +143,11 @@ def compile_file(self, file_path, compile_path, ext_vars, **kwargs): raise CompileError(f"Could not load Kadet module: {spec.name[16:]}") output_obj = _to_dict(output_obj) +<<<<<<< HEAD if prune_output: +======= + if prune_input: +>>>>>>> dcd110c (Fix typo in kadet prune input handling) output_obj = prune_empty(output_obj) # Return None if output_obj has no output diff --git a/mkdocs.yml b/mkdocs.yml index 17dd9a493..220547733 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -18,8 +18,8 @@ theme: - announce.dismiss - content.code.annotate - content.tabs.link + - navigation.instant - navigation.indexes - - navigation.sections - navigation.tabs - navigation.tabs.sticky - navigation.top @@ -81,24 +81,18 @@ extra: use_directory_urls: true nav: - Home: README.md - - Getting started: - - Kapitan Overview: kapitan_overview.md - - Support: - - Ask for support: support.md - - Related Projects: related.md - - Contribute: - - Sponsor Us: pages/contribute/sponsor.md - - Talk about Kapitan: pages/contribute/talk.md - - Active contributions: - - Documentation: pages/contribute/documentation.md - - Kapitan Code: pages/contribute/code.md - - Blog: - - 2023: - - New Kapitan release: pages/blog/2023-01-16.md - - 2022: - - 5 years of Kapitan: pages/blog/2022-12-04.md + - Getting started: getting_started.md + + - Documentation: - - Inventory: inventory.md + - Overview: pages/kapitan_overview.md + - Inventory: + - Introduction: /inventory/introduction.md + - Targets: pages/inventory/targets.md + - Classes: pages/inventory/classes.md + - Parameters Interpolation: pages/inventory/parameters_interpolation.md + - Advanced: pages/inventory/advanced.md + - Input Types: - Introduction: pages/input_types/introduction.md - Kadet: pages/input_types/kadet.md @@ -110,19 +104,33 @@ nav: - Remove: pages/input_types/remove.md - References: references.md - Advanced Kapitan: - - Remote repositories: remote_repositories.md - - External dependencies: external_dependencies.md - - Proposals: proposals.md - - CLI reference: - - compile: pages/commands/kapitan_compile.md - - inventory: pages/commands/kapitan_inventory.md - - lint: pages/commands/kapitan_lint.md - - searchvar: pages/commands/kapitan_searchvar.md - - validate: pages/commands/kapitan_validate.md - - kapitan dotfile: pages/commands/kapitan_dotfile.md + - Remote repositories: pages/remote_repositories.md + - External dependencies: pages/external_dependencies.md + - CLI reference: + - compile: pages/commands/kapitan_compile.md + - inventory: pages/commands/kapitan_inventory.md + - lint: pages/commands/kapitan_lint.md + - searchvar: pages/commands/kapitan_searchvar.md + - validate: pages/commands/kapitan_validate.md + - kapitan dotfile: pages/commands/kapitan_dotfile.md - Examples: - Kubernetes: pages/examples/kubernetes.md - Terraform: pages/examples/terraform.md + - Blog: + - 2023: + - New Kapitan release: pages/blog/2023-01-16.md + - 2022: + - 5 years of Kapitan: pages/blog/2022-12-04.md + - Support: + - Ask for support: support.md + - Related Projects: related.md + - Contribute: + - Sponsor Us: pages/contribute/sponsor.md + - Talk about Kapitan: pages/contribute/talk.md + - Active contributions: + - Documentation: pages/contribute/documentation.md + - Kapitan Code: pages/contribute/code.md + - Proposals: proposals.md - FAQ: FAQ.md markdown_extensions: