Kapitan

https://kapitan.dev/latest/
Admin
Kapitan is a one-stop configuration management solution that streamlines complex deployments across...
Tokens:49,978
Snippets:733
Trust Score:7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Complete Development Environment Setup

Source: https://kapitan.dev/latest/pages/contribute/code

Use this command for a full setup of your development environment, including installing dependencies and external tools.

```bash
# Complete development environment setup
make setup
```

--------------------------------

### Install Cruft for Minimal Repository Setup

Source: https://kapitan.dev/latest/getting_started

Install the cruft tool, which is used for creating minimal Kapitan reference repositories based on cookiecutters.

```bash
pip3 install cruft


```

--------------------------------

### Install Pre-commit Hooks

Source: https://kapitan.dev/latest/pages/contribute/code?q=

Configure pre-commit hooks for automatic code quality checks before commits. Run 'make setup' or install manually.

```bash
make install_pre_commit
# or directly:
poetry run pre-commit install
```

--------------------------------

### Install Kapitan via Pip (User Install - Linux/Mac)

Source: https://kapitan.dev/latest/getting_started

Install or upgrade Kapitan for the current user using pip. This method installs Kapitan in the user's local directory, avoiding system-wide changes.

```bash
pip3 install --user --upgrade kapitan


```

--------------------------------

### Complete Development Environment Setup

Source: https://kapitan.dev/latest/pages/contribute/code?q=

Use this command for a full setup of your development environment, including Poetry, Python dependencies, and external tools.

```bash
# Complete development environment setup
make setup

```

--------------------------------

### Fetch Output Example

Source: https://kapitan.dev/latest/pages/remote_repositories

Example output from 'kapitan compile --fetch' command, showing inventory fetching and saving, dependency fetching, and compilation.

```text
[WARNING] Reclass class not found: 'dockerfiles'. Skipped!
[WARNING] Reclass class not found: 'dockerfiles'. Skipped!
Inventory https://github.com/kapicorp/kapitan: fetching now
Inventory https://github.com/kapicorp/kapitan: successfully fetched
Inventory https://github.com/kapicorp/kapitan: saved to inventory/classes
Dependency https://github.com/kapicorp/kapitan: saved to components
Dependency https://github.com/kapicorp/kapitan: saved to templates
Compiled docker (0.11s)

```

--------------------------------

### Clone Kapitan Examples Repository

Source: https://kapitan.dev/latest/getting_started?q=

Clone the reference repository to access working examples of Kapitan functionalities. Navigate into the cloned directory.

```bash
$ git clone git@github.com:kapicorp/kapitan-reference.git kapitan-templates
$ cd kapitan-templates
```

--------------------------------

### Install Kapitan via Pip (System-wide Install)

Source: https://kapitan.dev/latest/getting_started

Install or upgrade Kapitan system-wide using pip. This method is not recommended as it affects all users on the system.

```bash
sudo pip3 install --upgrade kapitan


```

--------------------------------

### Clone Kapitan Examples Repository

Source: https://kapitan.dev/latest/getting_started

Clone the reference repository to access working examples of Kapitan functionalities. Navigate into the cloned directory.

```bash
$ 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)


```

--------------------------------

### Install Kapitan using Pip (User Install - Linux)

Source: https://kapitan.dev/latest/getting_started?q=

Install or upgrade Kapitan for the current user on Linux using pip. The executable will be available in the user's local bin directory.

```bash
pip3 install --user --upgrade kapitan
```

--------------------------------

### Install Pre-commit Hooks

Source: https://kapitan.dev/latest/pages/contribute/code

Installs pre-commit hooks for automatic code quality checks. This can be done via 'make setup' or manually.

```bash
make install_pre_commit
# or directly:
poetry run pre-commit install

```

--------------------------------

### Fetch Output Example (HTTP)

Source: https://kapitan.dev/latest/pages/remote_repositories

Example output from compiling with fetch for an HTTP type inventory. It shows the fetching of the remote inventory file and its successful saving.

```text
./kapitan compile -t mysql-generator-fetch --fetch
Inventory https://raw.githubusercontent.com/kapicorp/kapitan-reference/master/inventory/classes/kapitan/generators/kubernetes.yml: fetching now
Inventory https://raw.githubusercontent.com/kapicorp/kapitan-reference/master/inventory/classes/kapitan/generators/kubernetes.yml: successfully fetched
Inventory https://raw.githubusercontent.com/kapicorp/kapitan-reference/master/inventory/classes/kapitan/generators/kubernetes.yml: saved to inventory/classes/kapitan/generators/kubernetes.yml

... cut ...

Compiled mysql-generator-fetch (0.06s)

```

--------------------------------

### Install Kapitan using Pip (System-wide)

Source: https://kapitan.dev/latest/getting_started?q=

Install or upgrade Kapitan system-wide using pip. This method is not recommended due to potential permission issues and conflicts.

```bash
sudo pip3 install --upgrade kapitan
```

--------------------------------

### Git Type Inventory Example

Source: https://kapitan.dev/latest/pages/remote_repositories

Example of fetching classes and dependencies from a Git repository. This example uses external dependencies to fetch items.

```yaml
classes:
  - dockerfiles
parameters:
  kapitan:
    vars:
      target: docker
    inventory:
      - type: git
        source: https://github.com/kapicorp/kapitan
        subdir: examples/docker/inventory/classes/
        output_path: classes/
    dependencies:
      - type: git
        source: https://github.com/kapicorp/kapitan
        subdir: examples/docker/components
        output_path: components/
      - type: git
        source: https://github.com/kapicorp/kapitan
        subdir: examples/docker/templates
        output_path: templates/
dockerfiles:
  - name: web
    image: amazoncorretto:11
  - name: worker
    image: amazoncorretto:8

```

--------------------------------

### Install Python Dependencies

Source: https://kapitan.dev/latest/pages/contribute/code?q=

Installs all necessary Python dependencies for development, testing, and documentation. Supports installing with specific extras.

```bash
make install
# or manually:
poetry install --with dev --with test --with docs --extras "gojsonnet reclass-rs omegaconf"

```

--------------------------------

### Install Python and Dependencies (Mac)

Source: https://kapitan.dev/latest/getting_started?q=

Install Python 3 and libyaml on Mac systems using Homebrew. These are required for Kapitan's Python-based installation.

```bash
brew install python3 libyaml
```

--------------------------------

### Install Kapitan with Omegaconf Support

Source: https://kapitan.dev/latest/pages/inventory/omegaconf?q=

Install the Kapitan package with the optional omegaconf dependency using pip.

```bash
pip install kapitan[omegaconf]

```

--------------------------------

### Dynamic Backend Reference Example

Source: https://kapitan.dev/latest/references

Example of a reference whose backend dynamically changes based on assigned cloud classes, shown for MySQL root password.

```yaml
classes:
- cloud.aws

parameters:
  ...
  mysql:
    # the secret backend will change based on the cloud assigned to this target
    root_password: ?{${backend}:targets/${target_name}/mysql/root_password}
  ...
```

--------------------------------

### Install External Tools

Source: https://kapitan.dev/latest/pages/contribute/code

Installs external tools required for some tests, such as Helm, Kustomize, and CUE.

```bash
make install_external_tools
# This installs:
# - Helm (Kubernetes package manager)
# - Kustomize (Kubernetes manifest management)
# - CUE (data validation and configuration)
```

--------------------------------

### Git Fetch Output Example

Source: https://kapitan.dev/latest/pages/remote_repositories?q=

Example output from 'kapitan compile --fetch' showing the process of fetching Git inventories and dependencies. It includes warnings for missing classes and success messages for fetched items.

```text
[WARNING] Reclass class not found: 'dockerfiles'. Skipped!
[WARNING] Reclass class not found: 'dockerfiles'. Skipped!
Inventory https://github.com/kapicorp/kapitan: fetching now
Inventory https://github.com/kapicorp/kapitan: successfully fetched
Inventory https://github.com/kapicorp/kapitan: saved to inventory/classes
Dependency https://github.com/kapicorp/kapitan: saved to components
Dependency https://github.com/kapicorp/kapitan: saved to templates
Compiled docker (0.11s)


```

--------------------------------

### HTTP Fetch Output Example

Source: https://kapitan.dev/latest/pages/remote_repositories?q=

Example output from 'kapitan compile --fetch' when fetching from an HTTPS URL. It shows the fetching process, successful retrieval, and saving of the inventory file to the specified output path.

```text
Inventory https://raw.githubusercontent.com/kapicorp/kapitan-reference/master/inventory/classes/kapitan/generators/kubernetes.yml: fetching now
Inventory https://raw.githubusercontent.com/kapicorp/kapitan-reference/master/inventory/classes/kapitan/generators/kubernetes.yml: successfully fetched
Inventory https://raw.githubusercontent.com/kapicorp/kapitan-reference/master/inventory/classes/kapitan/generators/kubernetes.yml: saved to inventory/classes/kapitan/generators/kubernetes.yml

... cut ...

Compiled mysql-generator-fetch (0.06s)


```

--------------------------------

### Target and Class Structure Example

Source: https://kapitan.dev/latest/pages/inventory/introduction?q=

This example shows the basic structure of both class and target YAML files, including references to other classes and parameter definitions.

```yaml
classes:
  - common
  - my.other.class

parameters:
  key: value
  key2:
    subkey: value

```

--------------------------------

### Example Class File

Source: https://kapitan.dev/latest/pages/inventory/introduction?q=

This YAML file defines a 'kapicorp.common' class, including parameters like namespace and base domain, which can be included in other configurations.

```yaml
# classes/kapicorp/common.yml
classes:
  - common

parameters:
  namespace: ${target_name}
  base_docker_repository: quay.io/kapicorp
  base_domain: kapicorp.com

```

--------------------------------

### Kustomize Configuration Example

Source: https://kapitan.dev/latest/pages/input_types/kustomize?q=

This configuration demonstrates how to set up Kustomize as an input type in Kapitan, specifying input paths, output path, and optional namespace and patches.

```yaml
kapitan:
  compile:
    - output_path: manifests
      input_type: kustomize
      input_paths:
        - path/to/kustomize/overlay
      namespace: my-namespace  # Optional: Set namespace for all resources
      patches:  # Optional: Apply patches to resources
        patch-name:
          target:
            kind: Deployment
            name: my-deployment
            namespace: my-namespace
          patch:
            apiVersion: apps/v1
            kind: Deployment
            metadata:
              name: my-deployment
              namespace: my-namespace
            spec:
              template:
                spec:
                  containers:
                    - name: my-container
                      image: nginx:1.19

```

--------------------------------

### Example Production Web Target

Source: https://kapitan.dev/latest/pages/inventory/targets

An example of a production web target configuration, demonstrating class inheritance, parameter overrides, and variable interpolation for environment-specific settings.

```yaml
# inventory/targets/production/web.yml
classes:
  - common
  - components.nginx

parameters:
  environment: production
  description: ${environment} environment
  nginx:
    replicas: 3
  namespace: ${environment}


```

--------------------------------

### Install Python and Dependencies (Linux)

Source: https://kapitan.dev/latest/getting_started?q=

Install Python 3.8 development headers, pip, and PyYAML on Linux systems using apt-get. These are necessary for installing Kapitan via pip.

```bash
sudo apt-get update && sudo apt-get install -y python3.8-dev python3-pip python3-yaml
```

--------------------------------

### Install External Tools

Source: https://kapitan.dev/latest/pages/contribute/code?q=

Installs external tools required for certain tests, such as Helm, Kustomize, and CUE.

```bash
make install_external_tools
# This installs:
# - Helm (Kubernetes package manager)
# - Kustomize (Kubernetes manifest management)
# - CUE (data validation and configuration)

```

--------------------------------

### Install Poetry Package Manager

Source: https://kapitan.dev/latest/pages/contribute/code

Installs the Poetry package manager. This can be done via the Makefile or manually.

```bash
make install_poetry
# or manually:
pip install poetry
```

--------------------------------

### Install Poetry Package Manager

Source: https://kapitan.dev/latest/pages/contribute/code?q=

Installs the Poetry package manager. This can be done via the Makefile or manually.

```bash
make install_poetry
# or manually:
pip install poetry

```

--------------------------------

### Basic Kustomize Usage in Kapitan Inventory

Source: https://kapitan.dev/latest/pages/input_types/kustomize

Example Kapitan inventory file demonstrating basic Kustomize usage with a specified input path and namespace.

```yaml
# inventory/targets/my-app.yml
classes:
  - common

parameters:
  target_name: my-app
  kapitan:
    compile:
      - output_path: manifests
        input_type: kustomize
        input_paths:
          - kubernetes/base
        namespace: my-app

```

--------------------------------

### Install Python Dependencies

Source: https://kapitan.dev/latest/pages/contribute/code

Installs all necessary Python dependencies for development, testing, and documentation. This can be done via the Makefile or manually with Poetry.

```bash
make install
# or manually:
poetry install --with dev --with test --with docs --extras "gojsonnet reclass-rs omegaconf"
```

--------------------------------

### Install Python and Dependencies (Mac)

Source: https://kapitan.dev/latest/getting_started

Install Python 3 and libyaml on macOS using Homebrew. These are necessary dependencies for running Kapitan.

```bash
brew install python3 libyaml


```

--------------------------------

### Install Python and Dependencies (Linux)

Source: https://kapitan.dev/latest/getting_started

Install Python 3.8 development headers, pip, and PyYAML on Debian-based Linux systems. These are prerequisites for installing Kapitan via pip.

```bash
sudo apt-get update && sudo apt-get install -y python3.8-dev python3-pip python3-yaml


```

--------------------------------

### Install GCC on macOS

Source: https://kapitan.dev/latest/pages/contribute/code?q=

Troubleshooting step for macOS users to install a specific version of GCC if needed.

```bash
brew install gcc@5

```

--------------------------------

### kapitan lint Command Output Example

Source: https://kapitan.dev/latest/pages/commands/kapitan_lint?q=

Example output from the `kapitan lint` command, showing yamllint issues and a list of orphan classes found in the inventory.

```text
Running yamllint on all inventory files...

.yamllint not found. Using default values
File ./inventory/classes/components/echo-server.yml has the following issues:
        95:29: forbidden implicit octal value "0550" (octal-values)
File ./inventory/classes/terraform/gcp/services.yml has the following issues:
        15:11: duplication of key "enable_compute_service" in mapping (key-duplicates)

Total yamllint issues found: 2

Checking for orphan classes in inventory...

No usage found for the following 6 classes:
{'components.argoproj.cd.argocd-server-oidc',
'components.helm.cert-manager-helm',
'components.rabbitmq-operator.rabbitmq-configuration',
'components.rabbitmq-operator.rabbitmq-operator',
'features.gkms-demo',
'projects.localhost.kubernetes.katacoda'}

```

--------------------------------

### Example Target File

Source: https://kapitan.dev/latest/pages/inventory/introduction?q=

This YAML file defines a 'production' target, including references to relevant classes and setting the target_name parameter.

```yaml
# targets/production.yml
classes:
  - kapicorp.common
  - components.web
  - environments.production

parameters:
  target_name: web

```

--------------------------------

### Example Jinja2 Configuration

Source: https://kapitan.dev/latest/pages/input_types/jinja?q=

Configuration snippet showing how to use the jinja2 input type to compile multiple template files from specified input paths.

```yaml
templates: 
    - docs/nginx/README.md
    - components/nginx-deploy.sh

  kapitan:
    compile:
      - output_path: . 
        input_type: jinja2
        input_paths: ${templates}
```

--------------------------------

### Example Secret File Content

Source: https://kapitan.dev/latest/references

An example of a Kubernetes Secret YAML file containing GPG-encrypted references for root passwords.

```yaml
apiVersion: v1
data:
  MYSQL_ROOT_PASSWORD: ?{gpg:targets/minikube-mysql/mysql/password:ec3d54de}
  MYSQL_ROOT_PASSWORD_SHA256: ?{gpg:targets/minikube-mysql/mysql/password_sha256:122d2732}
kind: Secret
metadata:
  annotations: {}
  labels:
    name: example-mysql
  name: example-mysql
  namespace: minikube-mysql
type: Opaque
```

--------------------------------

### Kapitan Inventory Configuration Example

Source: https://kapitan.dev/latest/pages/commands/kapitan_inventory

This snippet shows a sample configuration for the Kapitan inventory, including database connection parameters and namespace settings.

```yaml
bind-address: 127.0.0.1
max_allowed_packet: 64M
thread_concurrency: 8
namespace: mysql
scripts: []
target_name: mysql
```

--------------------------------

### Compile with Fetch Command (HTTP Example)

Source: https://kapitan.dev/latest/pages/remote_repositories?q=

Command to compile a Kapitan project, fetching remote inventory from an HTTP/HTTPS source. The --fetch flag ensures that the specified remote inventory files are downloaded.

```bash
./kapitan compile -t mysql-generator-fetch --fetch

```

--------------------------------

### Jinja2 Inventory Global Access Example

Source: https://kapitan.dev/latest/pages/input_types/jinja?q=

A Jinja2 template demonstrating how to iterate through `inventory_global` to generate a global README.md with links to all generated targets.

```jinja2
| *Target*                                                               |
|------------------------------------------------------------------------|
{% for target in inventory_global | sort() %}
{% set p = inventory_global[target].parameters %}
|[{{target}}](../{{target}}/docs/README.md)                              |
{% endfor %}

```

--------------------------------

### Target Configuration with Component Merging

Source: https://kapitan.dev/latest/pages/inventory/omegaconf?q=

Example of a Kapitan target file demonstrating component merging using OmegaConf's 'merge' function.

```yaml
# inventory/targets/example.yml
classes:
  - templates.deployment

parameters:

  target_name: ${_kapitan_.name.short}

  components:
    # merge each component with a deployment
    backend: ${merge:${deployment}, ${backend}}
    keycloak: ${merge:${deployment}, ${keycloak}}
    keycloak-copy: ${merge:${keycloak}, ${keycloak-copy}} # merge with another component to specify even more

  # components config (would be in their own classes)

  # backend config
  backend:
    image: backend:latest

  # keycloak config
  keycloak:
    namespace: example1
    image: keycloak:latest

    env:
      [...]

  # keycloak-copy config (inherits env and namespace from keycloak)
  keycloak-copy:
    namespace: example2

```

--------------------------------

### Example HTTP Dependency

Source: https://kapitan.dev/latest/pages/external_dependencies

Downloads the README.md file from GitHub's raw content URL. The file is saved as `README.md` in the target directory and then processed.

```yaml
parameters:
  kapitan:
    vars:
      target: kapitan-example
    dependencies:
    - type: https
      output_path: README.md
      source: https://raw.githubusercontent.com/kapicorp/kapitan/master/README.md
    compile:
    - input_paths:
      - README.md
      input_type: jinja2
      output_path: .
```

--------------------------------

### Kustomize for Multiple Environments in Kapitan

Source: https://kapitan.dev/latest/pages/input_types/kustomize?q=

Demonstrates managing multiple environments using Kustomize overlays within Kapitan. This setup utilizes a base configuration and applies environment-specific patches, such as replica counts.

```yaml
# inventory/targets/my-app-prod.yml
classes:
  - common

parameters:
  target_name: my-app-prod
  kapitan:
    compile:
      - output_path: manifests
        input_type: kustomize
        input_paths:
          - kubernetes/overlays/prod
        namespace: my-app-prod

```

```yaml
# kubernetes/overlays/prod/kustomization.yaml
resources:
  - ../../base
patches:
  - path: patches/replicas.yaml

```

```yaml
# kubernetes/overlays/prod/patches/replicas.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3

```

--------------------------------

### Example Class Definition

Source: https://kapitan.dev/latest/pages/core_concepts

A class definition includes 'classes' and 'parameters' similar to targets.

```yaml
# inventory/classes/common.yaml
classes:
    - kapitan.common

parameters:
    organization: ACME
    headquarters: London
    timezone: Europe/London

```

--------------------------------

### Helm Template Namespace Example

Source: https://kapitan.dev/latest/pages/input_types/helm

Example demonstrating how to explicitly set the namespace for resources when using the Helm input type, as `helm template` does not automatically add `metadata.namespace`.

```yaml
metadata:
  namespace: {{ .Release.Namespace }} # or any other custom values
```

--------------------------------

### Example Inventory Output for MySQL Target

Source: https://kapitan.dev/latest/pages/commands/kapitan_inventory?q=

This is an example of the structured output generated by `kapitan inventory -t mysql`. It details the reclass information, applications, classes, environments, exports, parameters, and Kapitan-specific configurations for the target.

```yaml
__reclass__:
  environment: base
  name: mysql
  node: mysql
  timestamp: Wed Nov 23 23:19:28 2022
  uri: yaml_fs:///src/inventory/targets/examples/mysql.yml
applications: []
classes:
  - kapitan.kube
  - kapitan.generators.kubernetes
  - kapitan.generators.argocd
  - kapitan.generators.terraform
  - kapitan.generators.rabbitmq
  - kapitan.common
  - common
  - components.mysql
environment: base
exports: {}
parameters:
  _reclass_:
    environment: base
    name:
      full: mysql
      short: mysql
  components:
    mysql:
      config_maps:
        config:
          data:
            mysql.cnf:
              value: ignore-db-dir=lost+found
            mytemplate.cnf:
              template: components/mysql/mytemplate.cnf.j2
              values:
                mysql:
                  client:
                    port: 3306
                    socket: /var/run/mysqld/mysqld.sock
                  mysqld:
                    bind-address: 127.0.0.1
                    max_allowed_packet: 64M
                    thread_concurrency: 8
          mount: /etc/mysql/conf.d/
      env:
        MYSQL_DATABASE: ''
        MYSQL_PASSWORD:
          secretKeyRef:
            key: mysql-password
        MYSQL_ROOT_PASSWORD:
          secretKeyRef:
            key: mysql-root-password
        MYSQL_USER: ''
      image: mysql:5.7.28
      ports:
        mysql:
          service_port: 3306
      secrets:
        secrets:
          data:
            mysql-password:
              value: ?{plain:targets/mysql/mysql-password||randomstr|base64}
            mysql-root-password:
              value: ?{plain:targets/mysql/mysql-root-password||randomstr:32|base64}
          versioned: true
      type: statefulset
      volume_claims:
        datadir:
          spec:
            accessModes:
              - ReadWriteOnce
            resources:
              requests:
                storage: 10Gi
            storageClassName: standard
      volume_mounts:
        datadir:
          mountPath: /var/lib/mysql
  docs:
    - templates/docs/README.md
  generators:
    manifest:
      default_config:
        annotations:
          manifests.kapicorp.com/generated: 'true'
        service_account:
          create: false
        type: deployment
  kapitan:
    compile:
      - input_paths:
          - components/generators/kubernetes
        input_type: kadet
        output_path: manifests
        output_type: yml
      - input_params:
          function: generate_docs
          template_path: templates/docs/service_component.md.j2
        input_paths:
          - components/generators/kubernetes
        input_type: kadet
        output_path: docs
        output_type: plain
      - input_params:
          function: generate_pre_deploy
        input_paths:
          - components/generators/kubernetes
        input_type: kadet
        output_path: pre-deploy
        output_type: yml
      - input_paths:
          - components/generators/argocd
        input_type: kadet
        output_path: argocd
        output_type: yml
      - input_params:
          generator_root: resources.tf
        input_paths:
          - components/generators/terraform
        input_type: kadet
        output_path: terraform
        output_type: json
      - ignore_missing: true
        input_paths:
          - resources/state/mysql/.terraform.lock.hcl
        input_type: copy
        output_path: terraform/
      - input_paths:
          - components/generators/rabbitmq
        input_type: kadet
        output_path: rabbitmq
        output_type: yml
      - input_paths:
          - templates/docs/README.md
        input_type: jinja2
        output_path: docs
      - input_paths: []
        input_type: jinja2
        output_path: scripts
      - input_paths: []
        input_type: jsonnet
        output_path: manifests
        output_type: yml
    dependencies:
      - output_path: lib/kube.libsonnet
        source: https://raw.githubusercontent.com/bitnami-labs/kube-libsonnet/master/kube.libsonnet
        type: https
      - output_path: lib/kube-platforms.libsonnet
        source: https://raw.githubusercontent.com/bitnami-labs/kube-libsonnet/master/kube-platforms.libsonnet
        type: https
      - output_path: components/generators/kubernetes
        ref: master
        source: https://github.com/kapicorp/kapitan-reference.git
        subdir: components/generators/kubernetes
        type: git
      - output_path: components/generators/terraform
        ref: master
        source: https://github.com/kapicorp/kapitan-reference.git
        subdir: components/generators/terraform
        type: git
    vars:
      target: mysql
  manifests: []
  mysql:
    settings:
      client:
        port: 3306
        socket: /var/run/mysqld/mysqld.sock
      mysqld:

```

--------------------------------

### Basic Kustomize Usage in Kapitan Inventory

Source: https://kapitan.dev/latest/pages/input_types/kustomize?q=

Example of a Kapitan inventory file using Kustomize to compile manifests from a base directory. Ensure the specified input paths and directory structure are correctly set up.

```yaml
# inventory/targets/my-app.yml
classes:
  - common

parameters:
  target_name: my-app
  kapitan:
    compile:
      - output_path: manifests
        input_type: kustomize
        input_paths:
          - kubernetes/base
        namespace: my-app

```

```yaml
# kubernetes/base/kustomization.yaml
resources:
  - deployment.yaml

```

```yaml
# kubernetes/base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      containers:
        - name: my-app
          image: nginx:latest

```

--------------------------------

### Example Target Definition

Source: https://kapitan.dev/latest/pages/core_concepts

A basic target definition includes 'classes' and 'parameters' sections.

```yaml
# inventory/targets/production.yaml
classes:
  - common
  - acme.applications.super

parameters:
    description: My Super Application

```

--------------------------------

### Compile with Validation Output

Source: https://kapitan.dev/latest/pages/commands/kapitan_validate?q=

Example output when running 'kapitan compile --validate', including compilation steps and successful manifest validation.

```text
Rendered inventory (0.27s)
Compiled labels (0.23s)
Compiled removal (0.00s)
Compiled busybox (0.24s)
Compiled minikube-nginx-jsonnet (0.49s)
Compiled minikube-nginx-kadet (0.25s)
Compiled minikube-mysql (0.59s)
Compiled minikube-es (1.17s)
Compiled all-glob (1.55s)
Validation: manifest validation successful for ./compiled/minikube-mysql/manifests/mysql_secret.yml
Validation: manifest validation successful for ./compiled/minikube-mysql/manifests/mysql_service_jsonnet.yml
Validation: manifest validation successful for ./compiled/minikube-mysql/manifests/mysql_service_simple.yml

```

--------------------------------

### HTTP Type Inventory Example

Source: https://kapitan.dev/latest/pages/remote_repositories

Example of fetching an inventory file from a remote URL using the HTTPS type. This configuration specifies the source URL and the output path for the fetched file.

```yaml
classes:
  - common
  - kapitan.generators.kubernetes
parameters:
  kapitan:
    inventory:
      - type: https
        source: https://raw.githubusercontent.com/kapicorp/kapitan-reference/master/inventory/classes/kapitan/generators/kubernetes.yml
        output_path: classes/kapitan/generators/kubernetes.yml
  components:
    mysql:
      image: mysql

```

--------------------------------

### Install Cruft for Cookiecutter

Source: https://kapitan.dev/latest/getting_started?q=

Install the 'cruft' tool, which is a cookiecutter utility, using pip. This is a prerequisite for using the minimal repository setup.

```bash
pip3 install cruft
```

--------------------------------

### Install Pre-commit Hooks

Source: https://kapitan.dev/latest/pages/contribute/code

Configures Git pre-commit hooks to ensure code quality and formatting before commits.

```bash
make install_pre_commit
```

--------------------------------

### Kustomize Patching in Kapitan Inventory

Source: https://kapitan.dev/latest/pages/input_types/kustomize?q=

This example shows how to apply a specific image update patch to a deployment using Kustomize within a Kapitan inventory file. Verify the target resource and patch details match.

```yaml
# inventory/targets/my-app.yml
classes:
  - common

parameters:
  target_name: my-app
  kapitan:
    compile:
      - output_path: manifests
        input_type: kustomize
        input_paths:
          - kubernetes/base
        namespace: my-app
        patches:
          update-image:
            target:
              kind: Deployment
              name: my-app
              namespace: my-app
            patch:
              apiVersion: apps/v1
              kind: Deployment
              metadata:
                name: my-app
                namespace: my-app
              spec:
                template:
                  spec:
                    containers:
                      - name: my-app
                        image: nginx:1.19

```

--------------------------------

### Using Omegaconf Resolvers in Inventory

Source: https://kapitan.dev/latest/pages/inventory/omegaconf?q=

Demonstrates how to use defined Omegaconf resolvers within inventory files to achieve dynamic values. Examples include string concatenation, arithmetic operations, default values, and list manipulation.

```yaml
string: ${concat:Hello, World} # --> Hello World
int: ${plus_ten:90} # --> 100
default: ${default:} # --> DEFAULT
list: ${split:hello.world} # --> yaml list [hello, world]

```

--------------------------------

### Generate Documentation with Jinja and SubVars

Source: https://kapitan.dev/latest/references?q=

Combine Jinja templating with subvars to dynamically generate documentation. This example creates a markdown string detailing cluster information.

```text
{% set p = inventory.parameters %}
# Documentation for {{p.target_name}}

Cluster [{{p.cluster.name}}]({{p.cluster.link}}) has release channel {{p.cluster.release_channel}}
```

--------------------------------

### Example Git Dependency

Source: https://kapitan.dev/latest/pages/external_dependencies

Fetches a specific Python file from a git repository. It downloads the `version.py` file from the `kapitan` repository into the `source/kapitan` directory and then copies it to the target output.

```yaml
parameters:
  kapitan:
    vars:
      target: kapitan-example
    dependencies:
    - type: git
      output_path: source/kapitan
      source: git@github.com:kapicorp/kapitan.git
      subdir: kapitan
      ref: master
      submodules: true
    compile:
    - input_paths:
      - source/kapitan/version.py
      input_type: jinja2 # just to copy the file over to target
      output_path: .
```

--------------------------------

### Helm Input Type Configuration

Source: https://kapitan.dev/latest/pages/input_types/helm

Configuration example for the Helm input type within Kapitan's compile parameters. This shows how to specify input paths, override values, use values files, and set Helm parameters.

```yaml
parameters:
  kapitan:
    compile:
    - output_path: <output_path>
      input_type: helm
      input_paths:
        - <chart_path>
      helm_values:
        <object_with_values_to_override>
      helm_values_files:
        - <values_file_path>
      helm_path: <helm binary>
      helm_params:
        name: <chart_release_name>
        namespace: <substitutes_.Release.Namespace>
        output_file: <string>
        validate: true
        …
```

--------------------------------

### Target Directory Structure Example

Source: https://kapitan.dev/latest/pages/inventory/targets

Illustrates how targets can be organized into subdirectories within the inventory to create a hierarchical structure. The target name is derived from its full path.

```yaml
inventory/
└── targets/
    └── clusters/
        └── production/
            └── my-cluster.yml


```

--------------------------------

### Configure Helm Input Type

Source: https://kapitan.dev/latest/pages/input_types/introduction

Example of configuring the helm input type for Kapitan compilation. Specifies input paths and a generic output type.

```yaml
parameters:
  kapitan:
    compile:
    - output_path: <output_path_in_target_dir>
      input_type: helm
      prune: false 
      input_paths:
        - directory/
        - file
        - globbed/path/*
      output_type: <output_type_specific_to_input_type>


```

--------------------------------

### Serve Documentation Locally

Source: https://kapitan.dev/latest/pages/contribute/documentation

Follow these steps to serve the documentation site locally for testing changes. Ensure you have edited the mkdocs.yml configuration first.

```bash
make local_serve_documentation
```

--------------------------------

### Kapitan Copy Input Configuration

Source: https://kapitan.dev/latest/pages/input_types/copy?q=

Example configuration for the Kapitan copy input type. This snippet demonstrates how to specify input paths and an output path for copying files. The `ignore_missing` flag can be set to true to prevent errors if the specified input paths do not exist.

```yaml
kapitan:
   compile:
    - input_type: copy
      ignore_missing: true  # Do not error if path is missing. Defaults to False
      input_paths:
        - resources/state/${target_name}/.terraform.lock.hcl
      output_path: terraform/
```

--------------------------------

### Install reclass-rs with Kapitan

Source: https://kapitan.dev/latest/pages/inventory/reclass-rs

Install the reclass-rs optional dependency for Kapitan using pip. This command ensures that Kapitan is installed with support for the reclass-rs inventory backend.

```bash
pip install kapitan[reclass-rs]

```

--------------------------------

### Example Inventory Output

Source: https://kapitan.dev/latest/pages/commands/kapitan_inventory

The output of the `kapitan inventory` command shows a detailed breakdown of the target's inventory. This includes reclass information, application definitions, classes, environment settings, exported parameters, and specific component configurations like MySQL settings.

```yaml
__reclass__:
  environment: base
  name: mysql
  node: mysql
  timestamp: Wed Nov 23 23:19:28 2022
  uri: yaml_fs:///src/inventory/targets/examples/mysql.yml
applications: []
classes:
  - kapitan.kube
  - kapitan.generators.kubernetes
  - kapitan.generators.argocd
  - kapitan.generators.terraform
  - kapitan.generators.rabbitmq
  - kapitan.common
  - common
  - components.mysql
environment: base
exports: {}
parameters:
  _reclass_:
    environment: base
    name:
      full: mysql
      short: mysql
  components:
    mysql:
      config_maps:
        config:
          data:
            mysql.cnf:
              value: ignore-db-dir=lost+found
            mytemplate.cnf:
              template: components/mysql/mytemplate.cnf.j2
              values:
                mysql:
                  client:
                    port: 3306
                    socket: /var/run/mysqld/mysqld.sock
                  mysqld:
                    bind-address: 127.0.0.1
                    max_allowed_packet: 64M
                    thread_concurrency: 8
          mount: /etc/mysql/conf.d/
      env:
        MYSQL_DATABASE: ''
        MYSQL_PASSWORD:
          secretKeyRef:
            key: mysql-password
        MYSQL_ROOT_PASSWORD:
          secretKeyRef:
            key: mysql-root-password
        MYSQL_USER: ''
      image: mysql:5.7.28
      ports:
        mysql:
          service_port: 3306
      secrets:
        secrets:
          data:
            mysql-password:
              value: "?{plain:targets/mysql/mysql-password||randomstr|base64}"
            mysql-root-password:
              value: "?{plain:targets/mysql/mysql-root-password||randomstr:32|base64}"
          versioned: true
      type: statefulset
      volume_claims:
        datadir:
          spec:
            accessModes:
              - ReadWriteOnce
            resources:
              requests:
                storage: 10Gi
            storageClassName: standard
      volume_mounts:
        datadir:
          mountPath: /var/lib/mysql
  docs:
    - templates/docs/README.md
  generators:
    manifest:
      default_config:
        annotations:
          manifests.kapicorp.com/generated: 'true'
        service_account:
          create: false
        type: deployment
  kapitan:
    compile:
      - input_paths:
          - components/generators/kubernetes
        input_type: kadet
        output_path: manifests
        output_type: yml
      - input_params:
          function: generate_docs
          template_path: templates/docs/service_component.md.j2
        input_paths:
          - components/generators/kubernetes
        input_type: kadet
        output_path: docs
        output_type: plain
      - input_params:
          function: generate_pre_deploy
        input_paths:
          - components/generators/kubernetes
        input_type: kadet
        output_path: pre-deploy
        output_type: yml
      - input_paths:
          - components/generators/argocd
        input_type: kadet
        output_path: argocd
        output_type: yml
      - input_params:
          generator_root: resources.tf
        input_paths:
          - components/generators/terraform
        input_type: kadet
        output_path: terraform
        output_type: json
      - ignore_missing: true
        input_paths:
          - resources/state/mysql/.terraform.lock.hcl
        input_type: copy
        output_path: terraform/
      - input_paths:
          - components/generators/rabbitmq
        input_type: kadet
        output_path: rabbitmq
        output_type: yml
      - input_paths:
          - templates/docs/README.md
        input_type: jinja2
        output_path: docs
      - input_paths: []
        input_type: jinja2
        output_path: scripts
      - input_paths: []
        input_type: jsonnet
        output_path: manifests
        output_type: yml
    dependencies:
      - output_path: lib/kube.libsonnet
        source: https://raw.githubusercontent.com/bitnami-labs/kube-libsonnet/master/kube.libsonnet
        type: https
      - output_path: lib/kube-platforms.libsonnet
        source: https://raw.githubusercontent.com/bitnami-labs/kube-libsonnet/master/kube-platforms.libsonnet
        type: https
      - output_path: components/generators/kubernetes
        ref: master
        source: https://github.com/kapicorp/kapitan-reference.git
        subdir: components/generators/kubernetes
        type: git
      - output_path: components/generators/terraform
        ref: master
        source: https://github.com/kapicorp/kapitan-reference.git
        subdir: components/generators/terraform
        type: git
    vars:
      target: mysql
  manifests: []
  mysql:
    settings:
      client:
        port: 3306
        socket: /var/run/mysqld/mysqld.sock
      mysqld:

```

--------------------------------

### Serve Documentation Locally

Source: https://kapitan.dev/latest/pages/contribute/code

Serves the project documentation locally, typically accessible at http://localhost:8000.

```bash
make docs_serve
```

--------------------------------

### Install GCC on macOS

Source: https://kapitan.dev/latest/pages/contribute/code

Installs GCC version 5 on macOS using Homebrew, which may be required for certain build processes.

```bash
brew install gcc@5
```

--------------------------------

### Build Helm Input Plugin from Source

Source: https://kapitan.dev/latest/pages/input_types/helm

Commands to build the Helm input plugin from source. Requires Go 1.14.

```bash
cd kapitan/inputs/helm
./build.sh

```

--------------------------------

### Importing Libraries and Defining Resources in Kadet

Source: https://kapitan.dev/latest/pages/input_types/kadet?q=

Demonstrates how Kadet supports importing Python libraries and using them to define resources like Nginx deployments and services. It shows the creation of BaseObj instances and their configuration.

```python
... 
kubelib = kadet.load_from_search_paths("kubelib") 
... 
name = "nginx"
labels = kadet.BaseObj.from_dict({"app": name})
nginx_container = kubelib.Container( 
    name=name, image=inv.parameters.nginx.image, ports=[{"containerPort": 80}]
)
... 
def main():
    output = kadet.BaseObj() 
    output.root.nginx_deployment = kubelib.Deployment(name=name, labels=labels, containers=[nginx_container]) 
    output.root.nginx_service = kubelib.Service( 
        name=name, labels=labels, ports=[svc_port], selector=svc_selector
    )
    return output 

```

--------------------------------

### Import Libraries and Define Resources with Kadet

Source: https://kapitan.dev/latest/pages/input_types/kadet

Demonstrates importing external Python libraries (like 'kubelib') within Kadet and then using classes from those libraries to define resources such as Deployments and Services. It shows how to construct complex objects and return them for Kapitan compilation.

```python
kubelib = kadet.load_from_search_paths("kubelib")

name = "nginx"
labels = kadet.BaseObj.from_dict({"app": name})
nginx_container = kubelib.Container(
    name=name, image=inv.parameters.nginx.image, ports=[{"containerPort": 80}]
)

def main():
    output = kadet.BaseObj()
    output.root.nginx_deployment = kubelib.Deployment(name=name, labels=labels, containers=[nginx_container])
    output.root.nginx_service = kubelib.Service(
        name=name, labels=labels, ports=[svc_port], selector=svc_selector
    )
    return output

```

--------------------------------

### Equivalent Command for Global Inventory Backend

Source: https://kapitan.dev/latest/pages/commands/kapitan_dotfile?q=

Shows the command-line equivalent of setting 'inventory-backend' in the global section of the .kapitan file.

```bash
kapitan compile --inventory-backend=reclass
```

--------------------------------

### Deploy Documentation to GitHub Pages

Source: https://kapitan.dev/latest/pages/contribute/code

Deploys the project documentation to GitHub Pages.

```bash
make docs_deploy
```

--------------------------------

### GPG Encrypted Reference Example

Source: https://kapitan.dev/latest/pages/commands/kapitan_compile?q=

An example of a GPG encrypted reference, showing its structure including data, encoding, and recipients. This is typically stored under the '/refs' directory.

```yaml
data: hQEMA8uOJKdm07XTAQgAp5i [[ CUT ]]
BwqYc3g7PI09HCJZdU=
encoding: base64
recipients:
- fingerprint: D9234C61F58BEB3ED8552A57E28DC07A3CBFAE7C
type: gpg

```

--------------------------------

### GPG Encrypted Reference Example

Source: https://kapitan.dev/latest/pages/commands/kapitan_compile

An example of a GPG encrypted reference, showing its structure including data, encoding, and recipients. This is typically stored under the '/refs' directory.

```yaml
data: hQEMA8uOJKdm07XTAQgAp5i [[ CUT ]] BwqYc3g7PI09HCJZdU=
encoding: base64
recipients:
- fingerprint: D9234C61F58BEB3ED8552A57E28DC07A3CBFAE7C
type: gpg

```

--------------------------------

### Build Docker Image

Source: https://kapitan.dev/latest/pages/contribute/code

Builds the Docker image for Kapitan.

```bash
make build_docker
```

--------------------------------

### Vault Transit Configuration Example

Source: https://kapitan.dev/latest/references

Example inventory configuration for the Vault Transit secret backend. Specifies Vault address, token, skip verification, authentication method, mount point, crypto key, and latest version preference.

```yaml
parameters:
  kapitan:
    vars:
      target: my_target
      namespace: my_namespace
    secrets:
      vaulttransit:
        VAULT_ADDR: http://vault.example.com:8200
        VAULT_TOKEN: s.i53a1DL83REM61UxlJKLdQDY
        VAULT_SKIP_VERIFY: "True"
        auth: token
        mount: transit
        crypto_key: new_key
        always_latest: False
```

--------------------------------

### Format Code with Ruff

Source: https://kapitan.dev/latest/pages/contribute/code

Formats the code using Ruff, ensuring adherence to style guides.

```bash
make format
```

--------------------------------

### Equivalent Command for Global Inventory Path

Source: https://kapitan.dev/latest/pages/commands/kapitan_dotfile?q=

Illustrates how setting 'inventory-path' in the global section of .kapitan is equivalent to using the command-line flag.

```bash
kapitan compile --inventory-path=./some_path
```

--------------------------------

### Kapitan Validate Command Output

Source: https://kapitan.dev/latest/pages/commands/kapitan_validate?q=

Example output from the 'kapitan validate' command, showing successful manifest validation.

```text
created schema-cache-path at ./schemas
Validation: manifest validation successful for ./compiled/minikube-mysql/manifests/mysql_secret.yml
Validation: manifest validation successful for ./compiled/minikube-mysql/manifests/mysql_service_jsonnet.yml
Validation: manifest validation successful for ./compiled/minikube-mysql/manifests/mysql_service_simple.yml

```

--------------------------------

### Git Type Inventory Definition

Source: https://kapitan.dev/latest/pages/remote_repositories

Defines how to configure Git type inventory fetching. Ensure the git binary is installed on your system.

```yaml
parameters:
  kapitan:
    inventory:
    - type: git
      output_path: path/to/dir
      source: git_url
      subdir: relative/path/from/repo/root (optional)
      ref: tag, commit, branch etc. (optional)

```

--------------------------------

### Kapitan Compile Command Help

Source: https://kapitan.dev/latest/pages/commands/kapitan_compile

Displays the help message for the kapitan compile command, showing all available options and their descriptions.

```bash
kapitan compile --help

```

```bash
usage: kapitan compile [-h] [--inventory-backend {reclass}]
               [--search-paths JPATH [JPATH ...]]
               [--jinja2-filters FPATH] [--verbose] [--prune]
               [--quiet] [--output-path PATH] [--fetch]
               [--force-fetch] [--force] [--validate]
               [--parallelism INT] [--indent INT]
               [--refs-path REFS_PATH] [--reveal] [--embed-refs]
               [--inventory-path INVENTORY_PATH] [--cache]
               [--cache-paths PATH [PATH ...]]
               [--ignore-version-check] [--use-go-jsonnet]
               [--compose-target-name] [--schemas-path SCHEMAS_PATH]
               [--yaml-multiline-string-style STYLE]
               [--yaml-dump-null-as-empty]
               [--targets TARGET [TARGET ...] | --labels
               [key=value ...]]

options:
  -h, --help            show this help message and exit
  --inventory-backend {reclass,reclass-rs}
                        Select the inventory backend to use (default=reclass)
  --search-paths JPATH [JPATH ...], -J JPATH [JPATH ...]
                        set search paths, default is [".
```

--------------------------------

### Environment Variable Reference

Source: https://kapitan.dev/latest/references

Use environment variables as references in Kapitan. This example shows how to reference a MySQL root password from an environment variable.

```yaml
parameters:
  ...
  mysql:
    root_password: ?{env:targets/${target_name}/mysql/root_password}
  ...
```

--------------------------------

### Create a New Release

Source: https://kapitan.dev/latest/pages/contribute/code

Creates a new release by specifying the version number.

```bash
make release version=X.Y.Z
```

--------------------------------

### Configure Copy Input Type

Source: https://kapitan.dev/latest/pages/input_types/introduction

Example of configuring the copy input type for Kapitan compilation. Used for directly copying files or directories.

```yaml
parameters:
  kapitan:
    compile:
    - output_path: <output_path_in_target_dir>
      input_type: copy
      prune: false 
      input_paths:
        - directory/
        - file
        - globbed/path/*
      output_type: <output_type_specific_to_input_type>


```

--------------------------------

### Configure Jsonnet Input Type

Source: https://kapitan.dev/latest/pages/input_types/introduction

Example of configuring the jsonnet input type for Kapitan compilation. Includes options for prune and output type.

```yaml
parameters:
  kapitan:
    compile:
    - output_path: <output_path_in_target_dir>
      input_type: jsonnet
      prune: false 
      input_paths:
        - directory/
        - file
        - globbed/path/*
      output_type: ["yaml" | "json"]


```

--------------------------------

### Equivalent Command for Compile Flags

Source: https://kapitan.dev/latest/pages/commands/kapitan_dotfile?q=

Demonstrates the command-line equivalent of setting 'indent' and 'parallelism' flags in the .kapitan file.

```bash
kapitan compile --indent 4 --parallelism 8
```
Tokens:
Raw