add docs and fix render.sh

README.md

@@ -1,68 +1,104 @@
-Note: `DECAPOD (DEClarative APplication Orchestration & Delivery)` is a pilot project leveraging Kustomize, Helm Operator, Argo Workflow to deploy applications on Kubernetes. 
-
 # decapod-base-yaml
-`decapod-base-yaml` helps templating Kubernetes yaml files according to your environment.  
-Currently, it provides `LMA` and `OpenStack` templates.
-
-Prerequisite
-------------
-- Install [Docker](https://docs.docker.com/get-docker/)
-
+This project provides an easy way to create/maintain complex YAML files using kustomize and kustomize plugin.  
+It works with [decapod-site-yaml](https://github.com/openinfradev/decapod-site-yaml) which contain differences between each environment (_e.g. development, staging and production environment_).  
 
 ## Features
-_Provide `Easily Identifiable` and `Easily Configurable` Templates_
+* `base-yaml` and `site-yaml` structure
+  * `base-yaml` is containig YAML resources and [overlays](https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#overlay).
+  * `site-yaml` contains a [site value](docs/glossary#site-value) and [variant](https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#variant).
+* Qualified [product](docs/glossary.md#product)
+  * LMA(Logging, Monitoring, Alert)
+  * OpenStack
+  * Cloud Console
 
+## Documents
+* [Quick start](docs/quickstart.md)
+* [Concept](docs/concept.md)
+* [Glossary](docs/glossary.md)
+* [Contribution](docs/contribution.md)
 
-OpenStack Structures:
+## Example
+### Layout 
+An example of decapod-base-yaml:
 ```
-.
+ product
  ├── base
  │   ├── kustomization.yaml
  │   ├── resources.yaml
  │   └── site-values.yaml
- └── network
-     ├── linuxbridge-flat-vlan.yaml
-     ├── linuxbridge-flat-vlan-vxlan.yaml
-     ├── openvswitch-flat-vlan.yaml
-     └── openvswitch-flat-vlan-vxlan.yaml
+ ├── image
+ │   └── image-values.yaml 
+ └── storage
+     ├── ceph.yaml
+     └── local-path.yaml
+```
+
+An example of decapod-site-yaml:
+```
+ product
+ ├── site
+ │   ├── kustomization.yaml
+ │   ├── ceph.yaml
+ │   └── site-values.yaml
+ └── output
+     └── product-manifest.yaml 
 ```
 
-Usage
-=============
-> FYI, Below example is based on OpenStack.
-### 1) Build your own site
-First, you should choose image, network site-values in LMA/OpenStack and write own `kustomization.yaml`.
-Feel free to use sample yaml. [Here](https://github.com/jabbukka/site-yaml/) it is.
+### Render a [variant](https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#variant)
 
-> ```
-> $ mkdir -p lma/site/dev/
-> $ touch lma/site/dev/kustomization.yaml  
-> ```
+**Base**  
+_decapod-base-yaml/lma/base/resources.yaml_:
+```yaml
+apiVersion: helm.fluxcd.io/v1
+kind: HelmRelease
+metadata:
+  name: elasticsearch-operator
+spec:
+  chart:
+    repository: https://openinfradev.github.io/hanu-helm-repo
+    name: elasticsearch-operator
+    version: 1.0.3
+  releaseName: elasticsearch-operator
+  targetNamespace: elastic-system
+  values:
+    elasticsearchOperator:
+      nodeSelector: {} # TO_BE_FIXED
+```
 
-lma/site/dev/kustomization.yaml:
-> ```
->resources:
->  - ../../base
->    
->transformers:
->  - site-values.yaml
->```
+**Site**  
+_decapod-site-yaml/lma/site/dev/site-values.yaml_:
+```yaml
+apiVersion: openinfradev.github.com/v1
+kind: HelmValuesTransformer
+metadata:
+  name: site
 
-### 2) Override site-values.yaml
-Copy site-values.yaml and update the values.
-> ```
-> $ cp base/site-values.yaml site/dev/
-> $ vi site/dev/site-values.yaml
-> ```
+global:
+  nodeSelector:
+    taco-lma: enabled
 
-### 3) Build OpenStack templates with `kustomize-plugin`
-Option 1. Using docker image
-> ```
-> $ docker run -it -v $(pwd)/site:/site -v $(pwd)/decapod-base-yaml/$APP_NAME/base:/base -v $(pwd)/$APP_NAME/output:/output sktdev/decapod-kustomize:alpha-v2.0 /site/dev -o output-manifest.yaml
-> ```
+charts:
+- name: elasticsearch-operator
+  override:
+    elasticsearchOperator.nodeSelector: $(nodeSelector)
+```
 
-Option 2. Using a [render.sh](https://github.com/openinfradev/decapod-base-yaml/blob/main/render.sh) script
-> ```
-> $ # ./render.sh APP_NAME SITE_NAME
-> $ ./render.sh lma dev
-> ```
+**Variant** 
+_decapod-site-yaml/lma/output/dev/lma-manifest.yaml_:
+```yaml
+apiVersion: helm.fluxcd.io/v1
+kind: HelmRelease
+metadata:
+  name: elasticsearch-operator
+spec:
+  chart:
+    repository: https://openinfradev.github.io/hanu-helm-repo
+    name: elasticsearch-operator
+    version: 1.0.3
+  releaseName: elasticsearch-operator
+  targetNamespace: elastic-system
+  values:
+    elasticsearchOperator:
+      nodeSelector:
+        taco-lma: enabled
+```

docs/README.md

@@ -0,0 +1,19 @@
+
+
+## Features
+_Provide `Easily Identifiable` and `Easily Configurable` Templates_
+
+
+OpenStack Structures:
+```
+.
+ ├── base
+ │   ├── kustomization.yaml
+ │   ├── resources.yaml
+ │   └── site-values.yaml
+ └── network
+     ├── linuxbridge-flat-vlan.yaml
+     ├── linuxbridge-flat-vlan-vxlan.yaml
+     ├── openvswitch-flat-vlan.yaml
+     └── openvswitch-flat-vlan-vxlan.yaml
+```

docs/concept.md

@@ -0,0 +1,83 @@
+# Concept
+
+## Background
+There are tons of resources and helm charts to deploy in several environment (dev, stage, production...).  
+Configuring YAML files according to the complex requirments takes a considerable amount of time and is easy to make a mistake.  
+To improve this, `decapod-base-yaml` and `decapod-site-yaml` is designed to maintain base resources and site values seperately. 
+
+## Decapod-yaml Design
+![decapod-yaml-design](assets/decapod-yaml-design.png)
+
+## Default Layout
+```yaml
+ product # product name is a root directory.
+ ├── base
+ │   ├── kustomization.yaml
+ │   ├── resources.yaml # All resources are defined with default values.
+ │   └── site-values.yaml # patch of values overrided depending on environment.
+ └── overlay_type_name # e.g. network, storage, plugin...
+     └── overlay-values.yaml # patch of values
+```
+
+
+## How to write YAML
+Suppose some assumptions:
+- Here's a helm chart called `prometheus-operator`.
+- Requirements:
+  1. deploy chart in several environment(dev, stage, production).
+  2. `nodeSelector` is set to `environment_name: 1`.
+  3. `replicas` is flexible according to environment.  
+
+_Original YAML file_:
+```yaml
+apiVersion: helm.fluxcd.io/v1
+kind: HelmRelease
+metadata:
+  labels:
+    name: prometheus-operator
+  name: prometheus-operator
+spec:
+  chart:
+    repository: https://prometheus-community.github.io/helm-charts
+    name: prometheus-operator
+    version: 9.3.2
+  releaseName: prometheus-operator
+  values:
+    nodeSelector:
+      kubernetes.io/hostname: localhost
+    replicas: 2
+```
+
+_base/resources.yaml_:
+```yaml
+apiVersion: helm.fluxcd.io/v1
+kind: HelmRelease
+metadata:
+  labels:
+    name: prometheus-operator
+  name: prometheus-operator
+spec:
+  chart:
+    repository: https://prometheus-community.github.io/helm-charts
+    name: prometheus-operator
+    version: 9.3.2
+  releaseName: prometheus-operator
+  values:
+    nodeSelector: {} # Set to empty map. Because key value is flexible.
+    replicas: TO_BE_FIXED # Specify the value could be overrided  
+```
+
+_base/site-values.yaml_:
+```yaml
+apiVersion: openinfradev.github.com/v1
+kind: HelmValuesTransformer
+metadata:
+  name: site
+
+charts:
+- name: prometheus-operator
+  override:
+    replicas: 1 # Override replicas
+    nodeSelector:
+      site_name: 1
+```

docs/contribution.md

@@ -0,0 +1,14 @@
+Contribution
+------------
+Please keep in perspective of `Better Readability` and `Simple Documentation` for YAML documentation.  
+
+### Bug Report & Feature Request
+Please search issues [here](https://github.com/openinfradev/decapod-base-yaml/issues) before register new issue.  
+If there are no similar issues, you can create new issue.
+
+### How to Develop
+#### Code of Conduct
+Please note that this project complies with the [Code of Conduct(KOR)](https://github.com/openinfradev/community/blob/main/code-of-conduct.md) of HANU Community.  
+
+#### Build and Test
+To install and test, please refer to the [Quick Start](quickstart.md).  

docs/glossary.md

@@ -0,0 +1,12 @@
+# Glossary
+Glossary of terms
+
+## site value
+A _site value_ is one of the [overlay](https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#overlay) that contain values that vary depending on the environment - e.g. dev, stage, production and so on.  
+
+## site name
+A _site name_ is a name of the environment. 
+
+## product
+A _product_ is a set of one or more Kubernetes resources(Deployment, Service, Custom Resource and so on).  
+

docs/quickstart.md

@@ -0,0 +1,68 @@
+# Quick Start
+
+## Prerequisite
+- Install [Docker](https://docs.docker.com/get-docker/)
+
+
+## Render decapod-base-yaml
+```console
+$ git clone https://github.com/openinfradev/decapod-base-yaml.git
+
+$ # build lma
+$ docker run --rm -i -v decapod-base-yaml:/decapod-base-yaml sktdev/decapod-kustomize:latest kustomize build --enable_alpha_plugins /decapod-base-yaml/lma/base
+
+$ # build openstack
+$ docker run --rm -i -v decapod-base-yaml:/decapod-base-yaml sktdev/decapod-kustomize:latest kustomize build --enable_alpha_plugins /decapod-base-yaml/openstack
+```
+
+## Render decapod-site-yaml
+`decapod-site-yaml` is a sample site YAML.  
+```console
+$ git clone https://github.com/openinfradev/decapod-site-yaml.git
+$ cd decapod-site-yaml
+$ .github/workflows/render.sh product_name # replace product_name to lma or openstack or cloud-console.
+Fetch base with main branch/tag........
+Cloning into 'decapod-base-yaml'...
+remote: Enumerating objects: 35, done.
+remote: Counting objects: 100% (35/35), done.
+remote: Compressing objects: 100% (23/23), done.
+remote: Total 254 (delta 19), reused 21 (delta 11), pack-reused 219
+Receiving objects: 100% (254/254), 81.52 KiB | 397.00 KiB/s, done.
+Resolving deltas: 100% (75/75), done.
+Start to build for lma
+[hanu-deploy-apps] Clean up existing lma-manifest.yaml
+[hanu-deploy-apps] Rendering lma-manifest.yaml for hanu-deploy-apps site
+2021/01/14 07:23:02 Attempting plugin load from '/root/.config/kustomize/plugin/openinfradev.github.com/v1/helmvaluestransformer/HelmValuesTransformer.so'
+[hanu-deploy-apps] Successfully Completed!
+
+$ ls lma/output/hanu-deploy-apps
+lma-manifest.yaml
+```
+
+## Make your own site-yaml
+1. Fork [decapod-site-yaml](https://github.com/openinfradev/decapod-site-yaml) to your repository.
+2. Clone decapod-site-yaml from your repository.
+3. Make your site directory
+   ```console
+   $ # In case of LMA
+   $ mkdir -p decapod-site-yaml/lma/site/YOUR_SITE_NAME
+   ```
+4. Copy [site-values.yaml](https://github.com/openinfradev/decapod-base-yaml/blob/main/lma/base/site-values.yaml) and overlays (image, network ...) into your site directory.  
+   ```console
+   $ cp decapod-base-yaml/lma/base/site-values.yaml decapod-site-yaml/lma/site/YOUR_SITE_NAME
+   $ # (Optional)
+   $ cp decapod-base-yaml/lma/image/image-values.yaml decapod-site-yaml/lma/site/YOUR_SITE_NAME
+   ```
+5. Write kustomization.yaml into `decapod-site-yaml/lma/site/YOUR_SITE_NAME`.
+   ```yaml
+   resources:
+     - ../../base
+
+   transformers:
+     - site-values.yaml
+     #- image-values.yaml
+   ```
+6. run render.sh
+   ```console
+   $ .github/workflows/render.sh lma
+   ```