From 59146f74d896d7d05c8f6bc10ff2b8b39fb632bb Mon Sep 17 00:00:00 2001 From: Alessandro De Maria Date: Sat, 2 Sep 2023 17:14:05 +0000 Subject: [PATCH] Adds cookiecutter bootstap and improve documentation --- docs/README.md | 76 -------------- docs/getting_started.md | 161 ++++++++++++++++++++++-------- docs/pages/blog/2023-08-27.md | 2 +- docs/pages/examples/kubernetes.md | 5 + docs/pages/examples/terraform.md | 5 + 5 files changed, 129 insertions(+), 120 deletions(-) diff --git a/docs/README.md b/docs/README.md index f4638af2c..710d0d743 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,83 +23,7 @@ ![demo](images/kapitan-demo.gif) -## Install Kapitan -[![Releases](https://img.shields.io/github/release/kapicorp/kapitan.svg)](https://github.com/kapicorp/kapitan/releases) - -!!! success "recommended" - ### Docker - ![Docker Pulls](https://img.shields.io/docker/pulls/kapicorp/kapitan) - [![Docker Image Size](https://img.shields.io/docker/image-size/kapicorp/kapitan/latest.svg)](https://hub.docker.com/r/kapicorp/kapitan) - [![Docker](https://github.com/kapicorp/kapitan/workflows/Docker%20Build%20and%20Push/badge.svg)](https://github.com/kapicorp/kapitan/actions?query=workflow%3A%22Docker+Build+and+Push%22) - - - - - === "Linux" - - ```shell - alias kapitan="docker run -t --rm -u $(id -u) -v $(pwd):/src:delegated kapicorp/kapitan" - kapitan -h - ``` - - === "Mac" - - ```shell - alias kapitan="docker run -t --rm -v $(pwd):/src:delegated kapicorp/kapitan" - kapitan -h - ``` - -### Pip - -#### Install Python - -![Python version](https://img.shields.io/pypi/pyversions/kapitan) -![Unit Tests](https://github.com/kapicorp/kapitan/actions/workflows/test.yml/badge.svg) -=== "Linux" - - ```shell - sudo apt-get update && sudo apt-get install -y python3.8-dev python3-pip python3-yaml - ``` - -=== "Mac" - - ```shell - brew install python3 libyaml libmagic - ``` - -#### Install Kapitan using pip - -![downloads](https://img.shields.io/pypi/dm/kapitan) - -##### User - -=== "Linux" - - !!! note "" - `kapitan` will be installed in `$HOME/.local/lib/python3.7/bin` - - ```shell - pip3 install --user --upgrade kapitan - ``` - -=== "Mac" - - !!! note "" - `kapitan` will be installed in `$HOME/Library/Python/3.7/bin` - - ```shell - pip3 install --user --upgrade kapitan - ``` - - -##### System-wide - -!!! attention "not recommended" - - ```shell - sudo pip3 install --upgrade kapitan - ``` ## Related projects diff --git a/docs/getting_started.md b/docs/getting_started.md index 3907abd1f..a69dc2c92 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -1,15 +1,13 @@ # :kapitan-logo: **Kapitan Overview** -## Setup your repository +## Setup your installation -!!! note - We are currently working on improving the experience to give you an even quicker experience with Kapitan +Using our reference repositories you can easily get started with **Kapitan** -### Quickstart +### Examples repository -[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. +[kapicorp/kapitan-reference](https://github.com/kapicorp/kapitan-reference) repository is meant show you many working examples of things you can do with Kapitan. +You can use this to get familiar with **Kapitan** ``` $ git clone git@github.com:kapicorp/kapitan-reference.git kapitan-templates @@ -30,41 +28,118 @@ 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 +### Minimal repository + +> Using [cruft](https://cruft.github.io/cruft/) based cookiecutter + +```shell +pip3 install cruft +``` + +```shell +cruft create http://github.com/kapicorp/kapitan-reference --checkout cookiecutter --no-input +Dependency https://github.com/kapicorp/generators.git: saved to system/lib +Dependency https://github.com/kapicorp/generators.git: saved to system/generators/kubernetes +Dependency https://github.com/kapicorp/generators.git: saved to system/generators/terraform +Rendered inventory (1.74s) +Compiled echo-server (0.14s) ``` -* `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 +## running **Kapitan** + +!!! success "recommended" + ### `kapitan` wrapper script + If you use the provided repository, we already package a `kapitan` shell script that wraps the docker command to run **Kapitan** + + ```shell + $ ./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) + ``` + +## Other installation methods + +### Docker +[![Releases](https://img.shields.io/github/release/kapicorp/kapitan.svg)](https://github.com/kapicorp/kapitan/releases) + +!!! success "recommended" + ### Docker + ![Docker Pulls](https://img.shields.io/docker/pulls/kapicorp/kapitan) + [![Docker Image Size](https://img.shields.io/docker/image-size/kapicorp/kapitan/latest.svg)](https://hub.docker.com/r/kapicorp/kapitan) + [![Docker](https://github.com/kapicorp/kapitan/workflows/Docker%20Build%20and%20Push/badge.svg)](https://github.com/kapicorp/kapitan/actions?query=workflow%3A%22Docker+Build+and+Push%22) + + + === "Linux" + + ```shell + alias kapitan="docker run -t --rm -u $(id -u) -v $(pwd):/src:delegated kapicorp/kapitan" + kapitan -h + ``` + + === "Mac" + + ```shell + alias kapitan="docker run -t --rm -v $(pwd):/src:delegated kapicorp/kapitan" + kapitan -h + ``` + +### Pip + +#### Install Python + +![Python version](https://img.shields.io/pypi/pyversions/kapitan) +![Unit Tests](https://github.com/kapicorp/kapitan/actions/workflows/test.yml/badge.svg) +=== "Linux" + + ```shell + sudo apt-get update && sudo apt-get install -y python3.8-dev python3-pip python3-yaml + ``` + +=== "Mac" + + ```shell + brew install python3 libyaml libmagic + ``` + +#### Install Kapitan using pip + +![downloads](https://img.shields.io/pypi/dm/kapitan) + +##### User + +=== "Linux" + + !!! note "" + `kapitan` will be installed in `$HOME/.local/lib/python3.7/bin` + + ```shell + pip3 install --user --upgrade kapitan + ``` + +=== "Mac" + + !!! note "" + `kapitan` will be installed in `$HOME/Library/Python/3.7/bin` + + ```shell + pip3 install --user --upgrade kapitan + ``` + + +##### System-wide + +!!! attention "not recommended" + + ```shell + sudo pip3 install --upgrade kapitan + ``` \ No newline at end of file diff --git a/docs/pages/blog/2023-08-27.md b/docs/pages/blog/2023-08-27.md index 55453809b..b5aa46c2a 100644 --- a/docs/pages/blog/2023-08-27.md +++ b/docs/pages/blog/2023-08-27.md @@ -151,7 +151,7 @@ Here are some example "mutation" which separates different `kinds` into differen !!! tip "Catch-all rule" Notice the catchall rule at the end that puts everything that has not matched into the `bundle.yml` file -### `bundle` mutation` +### `bundle` mutation Currently most of the keda related resources are bundled into the `-bundle.yml` file Instead, we want to separate them into their own file. diff --git a/docs/pages/examples/kubernetes.md b/docs/pages/examples/kubernetes.md index 4b48a46c5..cc0c3b048 100644 --- a/docs/pages/examples/kubernetes.md +++ b/docs/pages/examples/kubernetes.md @@ -4,6 +4,11 @@ tags: --- # :kapitan-logo: **Kubernetes examples** +!!! danger + This documentation is not up-to-date. + + Please refer to the [documentation](/pages/kapitan_overview/), [Getting started](/getting_started/) or look at the [Kapitan Reference](https://github.com/kapicorp/kapitan-reference) repository. + Here, we walk through how kapitan could be used to help create kubernetes manifests, whose values are customized for each target according to the inventory structure. The example folder can be found in our repository on Github at . ## Directory structure diff --git a/docs/pages/examples/terraform.md b/docs/pages/examples/terraform.md index e9a5d2890..a0cc49394 100644 --- a/docs/pages/examples/terraform.md +++ b/docs/pages/examples/terraform.md @@ -4,6 +4,11 @@ tags: --- # :kapitan-logo: **Terraform example** +!!! danger + This documentation is not up-to-date. + + Please refer to the [documentation](/pages/kapitan_overview/), [Getting started](/getting_started/) or look at the [Kapitan Reference](https://github.com/kapicorp/kapitan-reference) repository. + We will be looking at how to use Kapitan to compile terraform files with Jsonnet as the input type. It's possible to use other input types, however, Jsonnet is recommended. For example, we could use the Kadet input to generate terraform files but this would require templates to be written in YAML then rendered into JSON. It is possible to allow Kadet to consume JSON as an input. This enables you to integrate your organizations pre-existing terraform JSON file's as templates.