docs: start rewriting docs

docs/10_overview.md

@@ -1,23 +1,41 @@
 # mlp CLI
 
-[`mlp`](https://github.com/mia-platform/mlp) is a comman line tool responsible for creating, updating and deleting
-kubernetes resources based on files generated by Mia-Platform Console.  
-The main subcommands that the tool has are:
+`mlp`is a Command Line Interface that is responsible for creating, updating and deleting Kubernetes resources
+based on files generated by Mia-Platform Console.  
+It can be viewed as a superpowered `kubectl apply` command that introduce additional functionalities to simply sending
+patches to the api-server.
 
-- [`interpolate`](./30_interpolate.md): fill placeholders in kubernetes files with the values of ENV variables
-- [`generate`](./40_generate.md): create files for kubernetes `ConfigMap` and `Secret` based on files and/or ENV values
-- [`deploy`](./50_deploy.md): create and/or update resources in a kubernetes namespace with the interpolated/generated files
-- `kustomize`: run kustomize build
-- [`hydrate`](./70_hydrate.md): helper to fill kustomization.yml with resources and patches
-- `completion`: generate the autocompletion
+`mlp` can prune resources that are not present anymore between different deploys becasue it keeps an inventory
+of all the resources that has applyed the last time.  
+It can force new deployment rollout even if there are no differeces between deploys, running Jobs immediately from
+CronJob definitions, and it will add annotations to workload resources about their Secrets and ConfigMaps depedencies.  
+The cli will also automatically watch the progression of the applied resources and it will report what and how many
+resources failed to reach a ready or successfull state.
+
+In addition `mlp` can also generate ConfigMaps or Secrets via a dedicate configuration file using a combination of
+environment variabiles, literal values and files, giving the user the ability to not commiting sensitive data and giving
+the ability to use different configuration for different runtime environments.
+
+## Functionalities
+
+- `deploy`: the main command, is used for creating, updating and pruning resources in a kubernetes
+	environment using the resouce files created by the Mia-Platform Console
+- `generate`: create kubernetes `ConfigMap` and `Secret` based on a configuration file
+- `hydrate`: is an helper function for configuring correctly the kustomization files inside the target folder
+	with all the files and patches found
+- `interpolate`: will run through all the files passed and run through a templating function for render the final
+	manifests
+- `kustomize`: is the same command of `kustomize build` and can be used if you project is using the kustomize structure
+	to render the resources to pass to the `interpolate` command
+
+For more information about the various options available to the various commands you can always run
+`mlp <command> --help` to see the helpers.
 
 ## Guides
 
 Below, you can find additional documentation for `mlp`:
 
 - [Setup](./20_setup.md)
-- Commands
-  - [Interpolate](./30_interpolate.md)
-  - [Generate](./40_generate.md)
-  - [Deploy](./50_deploy.md)
-  - [Hydrate](./70_hydrate.md)
+- [Generation Configuration](./30_generate.md)
+- [Hydration Logic](./40_hydrate.md)
+- [Interpolatation Template](./50_interpolate.md)

docs/20_setup.md

@@ -23,6 +23,8 @@ If you have [Homebrew] installed on your system `mlp` is only a command away:
 brew install mia-platform/tap/mlp
 ```
 
+This method will also automatically setup the shell completions for `bash`, `zsh` and `fish`.
+
 #### Go
 
 If you have [Golang] installed with a version >= 1.13 in your system and you have the `$GOPATH`env set, you can

docs/30_generate.md

@@ -0,0 +1,97 @@
+# Generation Configuration
+
+The `generate` command is used to generate secrets and configmaps from a configuration `.yaml`, interpolating it
+with environment variables when necessary and saves the generated files in a specified directory.
+
+The configuration file supports environment variable interpolation following the regular expression `{{[A-Z0-9_]+}}`.
+The interpolation works in the same way described in the [interpolate](./40_interpolate.md) guide.  
+The file has a `secrets` section where the keys `tls`,`docker`, and`data` are mutually exclusive and a
+`config-maps` section where the only section supported is `data`.
+
+An configuration file example can be like this:
+
+```yaml
+secrets:
+- name: tls-secret
+  when: once
+  tls:
+    cert:
+      from: literal
+      value: value
+    key:
+      from: file
+      file: /path/to/file
+      value: value
+- name: docker-pull-secret
+  when: always
+  docker:
+    username: username
+    password: password
+    email: [email protected]
+    server: example.com
+- name: secret-name
+  when: always
+  data:
+  - from: file
+    file: ./path/to/file
+    key: key
+config-maps:
+- name: config-map-name
+  when: always
+  data:
+  - from: literal
+    key: key
+    value: value
+```
+
+## Details
+
+We will going more in depth on the meaning and possible values of the various sections of the configuration file.
+
+## `secrets` and `config-maps`
+
+These sections are the more obvious ones, and they are used to indicate what type of Kubernetes resource you want to
+generate.  
+`secrets` will generate one or more `Secret` resource and `config-maps` will generate one or more `ConfigMap`.
+
+## `when`
+
+The `when` option will accept only the value of `once` and `always`. Omitting the key or setting to another value
+will fallback on the `always`value.
+
+This key is used during apply time, and if set to `once` will generate a configuration with a particular annotation
+that will apply the generated file only if a resources of the same kind, name and namespace is not already present
+on the remote Kubernetes cluster.  
+This option can be useful for generating resources with placeholder values that will be updated from other tools but
+are necessary for the correct rollout of other resources that might depedends of them. A tipical application
+can be a `Secret` resource of `tls` type that contains a tls that will be handled by an external tools for keeping it
+updated before the end of the valid timestamp.
+
+## `data`
+
+The `data` block is the only valid block for a `ConfigMap` resource and one of the valid one for the `Secret`
+resource.  
+This block is used for setting one or more key in the resouce using literal values or files.
+
+The `from` key can be one of `literal` or `file` and is used to select where to find the value used to popolate `key`
+in the final resource. If the value is `literal` the `value` key is used and its values is used; in the other case the
+`file` key is used as path to find the file to load for the value. The path can be absolute or relative to the folder
+where the command will be launched.
+
+## `docker`
+
+The `docker` block is a special block valid only for `secrets` and will generate a Kubernete `Secret` of type
+`kubernetes.io/dockerconfigjson` that can be used as an `ImagePullSecret` for setting authorization to one or more
+docker registries.  
+The four keys `username`, `password`, `email` and `server` are used for generate the json configuration and must
+contains a valid authorized user for the given `server` url of a remote repository.
+
+## `tls`
+
+The `tls` block is the last supported type of `secrets` and will generate a Kubernetes `Secret` of type
+`kubernetes.io/tls`. This secret is usually used to set a certificate/private key pair for a TLS connection like
+exposing an HTTPS connection for an `Ingress` the keys of the object are always `tls.crt` for the certificate and
+`tls.key` for the private key.
+
+The valus can be passed by file or directly in the configuration, but we highly reccomend to use files for avoiding
+to accidentaly leak sensible data.

docs/40_hydrate.md

@@ -0,0 +1,15 @@
+# Hydration Logic
+
+The `hydrate` subcommand is an helper to fill kustomization configuration files with resources and patches.
+
+For doing so wihtout launching multiple commands with different parameters, and leaving the user being able to add
+specific patches that needs custom targetign will only add files that conform to specific regex and we will skip files
+that are already present in the relative section in the file.
+
+The first regex will match any file that ends with `.patch.yaml` or `.patch.yml` and the files `patch.yaml`
+and `patch.yml`. These files will be assumed that they contains a strategic-merge-style patch and they will be
+added to the `patches` section of the kustomize file.
+
+The other regex will match every file that has the `yaml` or `yml` extensions that has not been matched in the previous
+regex.  
+These files will be added to the `resources` section.

docs/40_interpolate.md

@@ -0,0 +1 @@
+# Interpolatation Template