Merge pull request #12 from robertchoi80/main

update document contents

docs/concepts/deployment.md

@@ -1,25 +1,27 @@
 # Deployment
 ## Overview
-Decapod은 Argo Workflow와 Argo CD를 통해 Application Group을 배포한다.  
-여러 Application(혹은 Helm Chart)를 배포할 때, 각 Application은 동시에 설치할 수도 있지만 의존성의 문제로 순차적으로 배포해야할 때가 있다.  
+Decapod는 Argo Workflow와 Argo CD를 통해 Application Group을 배포한다.  
+여러 Application(혹은 Helm Chart)를 배포할 때, 각 Application들은 동시에 설치될 수도 있지만 의존성의 문제로 순차적으로 배포해야할 때가 있다.  
 Argo Workflow는 이러한 sequential deployment를 가능하게 한다.
 
-또 Argo CD를 통해 Application를 생성하고 배포하여 decapod-manifests의 파일이 변경될 때 automated sync 기능을 통해 자동으로 최신 버전을 유지할 수 있다.
+또 Argo CD를 통해 Application들이 배포되므로, 향후 decapod-manifests 파일이 변경될 때 automated sync 기능을 통해 자동으로 변경 사항이 적용되어 항상 최신 버전을 유지할 수 있다.
 
 ![decapod-flow-details](../assets/decapod-flow-details.svg)
 
 ## decapod-flow
 _[github link](https://github.com/openinfradev/decapod-flow)_  
-Argo Workflow를 통해 LMA, Service Mesh같은 Application Group을 배포한다.  
-이 때 필요한 Argo Workflow의 WorkflowTemplate과 그 외의 설정을 `decapod-flow`에 정의하였다.  
+Argo Workflow를 통해 LMA, Service Mesh 등의 Application Group을 배포한다.  
+이 때 필요한 Argo Workflow Template과 그 외의 설정을 `decapod-flow`에 정의하였다.  
 
 ### Workflow Templates
 | Name | Description | Link |
 |------|-------------|------|
 |prepare-argocd|Argo CD 인증 정보를 저장하고, project들을 만든다.|[prepare-argocd-wftpl.yaml](https://github.com/openinfradev/decapod-flow/blob/main/templates/argo-cd/prepare-argocd-wftpl.yaml)|
 |create-application|decapod-manifests repository에 저장된 YAML 파일을 통해 Argo CD에 Application을 생성한다.|[createapp-wftpl.yaml](https://github.com/openinfradev/decapod-flow/blob/main/templates/argo-cd/createapp-wftpl.yaml)|
-|lma-federation|federation 형상의 LMA를 설치한다. 일반 LMA에서 추가로 Grafana, thanos 등이 설치된다.|[lma-federation-wftpl.yaml](https://github.com/openinfradev/decapod-flow/blob/main/templates/decapod-apps/lma-federation-wftpl.yaml)|
-|lma|일반적인 형상의 LMA을 설치한다.|[lma-wftpl.yaml](https://github.com/openinfradev/decapod-flow/blob/main/templates/decapod-apps/lma-wftpl.yaml)|
+|delete-apps|Argo CD Application을 삭제한다.|[delete-apps-wftpl.yaml](https://github.com/openinfradev/decapod-flow/blob/main/templates/argo-cd/delete-apps-wftpl.yaml)|
+|lma-federation|federation 형상의 LMA를 설치한다. Grafana, thanos 등이 포함된다.|[lma-federation-wftpl.yaml](https://github.com/openinfradev/decapod-flow/blob/main/templates/decapod-apps/lma-federation-wftpl.yaml)|
 |service-mesh|Service Mesh를 설치한다.|[service-mesh-wftpl.yaml](https://github.com/openinfradev/decapod-flow/blob/main/templates/decapod-apps/service-mesh-wf.yaml)|
 |openstack-infra|OpenStack의 Memcached, Ceph과 같은 Infra에 해당하는 서비스들을 설치한다.|[openstack-infra-wftpl.yaml](https://github.com/openinfradev/decapod-flow/blob/main/templates/decapod-apps/openstack-infra-wftpl.yaml)|
-|openstack-components|OpenStack의 Infra 외의 모든 서비스들을 설치한다.|[openstack-components-wf.yaml](https://github.com/openinfradev/decapod-flow/blob/main/templates/decapod-apps/openstack-components-wf.yaml)|
+|openstack-components|OpenStack의 Infra 외의 모든 서비스들을 설치한다.|[openstack-components-wf.yaml](https://github.com/openinfradev/decapod-flow/blob/main/templates/decapod-apps/openstack-components-wf.yaml)|
+
+위의 template 외에 "remove-APPGROUP" template의 경우 해당 app group을 삭제하는 역할을 수행한다.

docs/concepts/documentation.md

@@ -1,11 +1,11 @@
 # Documentation
 ## Overview
-Decapod의 Documentation 기능은 반복적인 복잡한 Yaml 파일 작성을 줄여준다.  
+Decapod의 Documentation 기능은 반복적이고 복잡한 Yaml 파일 작성을 줄여준다.  
 다수의 Helm Chart를 하나의 Application Group으로 묶어서 관리하고 하나의 파일에서 모든 차트의 value를 override할 수 있다.  
 
 모든 YAML 설정을 Git Repository에 저장하여 배포하는 GitOps 체계이다.  
 
-YAML 설정을 Base와 Site로 나뉘어 관리하며 Base는 Application Group에 대한 Default YAML을 정의한다. 
+YAML 설정을 Base와 Site로 나뉘어 관리하며 Base는 Application Group에 대한 Default YAML, 즉 각 환경과 독립적인 공통적인 설정값들을 정의한다.  
 Base의 값을 내 환경에 맞게 변경하고자 한다면 Site에서 Value Override를 할 수 있다.  
 이는 Helm Chart에서 `Template`과 `values.yaml` 같은 역할이라 볼 수 있다.
 
@@ -14,9 +14,9 @@ Base의 값을 내 환경에 맞게 변경하고자 한다면 Site에서 Value O
 ## decapod-base-yaml 
 _[github link](https://github.com/openinfradev/decapod-base-yaml)_  
 
-kustomize의 base resources file들을 미리 정의해 놓은 곳이다.  
+kustomize 규격에 맞게 base resources file들을 미리 정의해 놓은 곳이다.  
 여러 Helm chart를 묶어서 LMA, Service Mesh 등의 Application Group으로 정의하였으며,  
-환경별로 쉽게 값을 수정할 수 있도록 `site-values.yaml` 을 제공한다.
+환경별로 주로 수정할 value들을 모아놓은 `site-values.yaml` 을 제공한다.
 
 ### Layout
     service-mesh
@@ -50,9 +50,11 @@ _[github link](https://github.com/openinfradev/decapod-site)_
 1. LMA (Logging, Monitoring and Alarm)
 2. Service Mesh
 3. OpenStack
+
+
 ## decapod-site
-decapod-base-yaml에 정의된 Application Group을 배포 환경에 맞게 커스터마이징한 설정을 저장하는 곳이다.  
-github action을 통해 decapod-site main branch로 PR이 merge되면 자동으로 kustomize build가 되어 decapod-manifests에 저장된다.  
+decapod-base-yaml에 정의된 Application Group을 배포 환경에 맞게 customize하기 위한 설정을 저장하는 곳이다.
+사용자들이 올린 PR이 decapod-site main branch로 merge되면 github action을 통해 자동으로 kustomize build 명령이 수행되어 결과물이 decapod-manifests repository에 저장된다.
 ### Layout
     ├── 사이트명
     │   ├── application이름
@@ -78,12 +80,12 @@ github action을 통해 decapod-site main branch로 PR이 merge되면 자동으
             └── site-values.yaml
 
 최상단 디렉토리는 사이트(환경)으로 구분된다. 온라인 환경을 위한 sample site는 `decapod-reference` 이고,
-오프라인 환경을 위한 sample site는 `decapod-reference-offline` 이다.
+오프라인(Air-gapped) 환경을 위한 sample site는 `decapod-reference-offline` 이다.
 
 ## decapod-manifests
 _[github link](https://github.com/openinfradev/decapod-manifests)_  
-decapod-base-yaml과 decapod-site를 통해 kustomize build된 **결과물**이 저장되는 곳이다.  
-decapod-site와 동일한 directory 구조를 가져가지만, 최종 output의 형태는 Helm chart로부터 생성된 plain text yaml이다.  
+decapod-base-yaml과 decapod-site로부터 kustomize build된 **결과물**이 저장되는 곳이다.  
+decapod-site와 동일한 directory 구조를 가지지만, 최종 output의 형태는 Helm chart로부터 생성된 plaintext yaml이다.  
 ## Example
 base(1) + site(2) => manifests(3)
 

docs/concepts/index.md

@@ -1,6 +1,6 @@
 # Basics
-Decapod은 Kubernetes Cluster 환경을 기반으로 하며 Argo Workflow, Argo CD, Kustomize를 사용하고 있다.  
-Decapod을 사용하기 앞서, 각 프로젝트에 대한 기본적인 이해를 하면 Decapod에 대해 더 쉽게 이해할 수 있다.
+Decapod는 Kubernetes Cluster 환경을 기반으로 하며 Argo Workflow, Argo CD, Kustomize 등의 오픈소스 S/W를 활용하고 있다.  
+Decapod를 사용하기 앞서, 각 프로젝트에 대한 기본적인 이해를 하면 Decapod에 대해 더 쉽게 이해할 수 있다.
 
 ## 알아보기
 ### Kubernetes

docs/getting-started/customize-yaml.md

@@ -1,5 +1,5 @@
-# Customizing
-Decapod-site를 배포할 환경에 맞게 수정하여 Argo CD가 사용할 decapod-manifests를 생성한다.
+# Customizing configurations
+Decapod-site를 배포할 환경에 맞게 수정하여 Argo CD app들에서 참조할 decapod-manifests를 생성한다.
 
 ## 사전 준비
 * [decapod-site](https://github.com/openinfradev/decapod-site)를 자신의 repo로 fork한다. 
@@ -23,9 +23,9 @@ Decapod-site를 배포할 환경에 맞게 수정하여 Argo CD가 사용할 dec
     $ ls <SITE_NAME>
     admin-tools   cloud-console lma           openstack     service-mesh
 
-## 커스터마이징
+## Configuration 수정
 !!! note
-    이 문서는 LMA를 커스터마이징하는 예시이다. service-mesh, openstack 등은 site-values.yaml 내용이 다르므로 각 site-values.yaml 파일 내용을 보고 수정해야한다.
+    이 문서는 LMA 관련 설정을 커스터마이즈하는 예시이다. service-mesh, openstack 등은 site-values.yaml 내용이 다르므로 각 site-values.yaml 파일 내용을 보고 수정해야한다.
 
 _decapod-site/<SITE_NAME\>/lma/site-values.yaml_:
 
@@ -59,28 +59,31 @@ global:
     prometheus.prometheusSpec.nodeSelector: $(nodeSelector)
 ```
 
-## 로컬 빌드
+## Local Build(rendering)
 !!! note 
-    로컬에서 빌드하기 위해서는 `docker` 가 설치되어 있는 환경이어야한다.  
-    로컬 빌드는 documentation 검증을 위한 절차로,  
-    로컬에서 빌드된 결과물이 decapod-manifests와 같은 github repository에 올라가지 않으면 배포할 수 없다.
+    로컬 환경에서 빌드하기 위해서는 `docker` 가 설치되어 있어야한다.  
+    로컬 빌드는 단순히 documentation 검증을 위한 절차이며,  
+    로컬에서 빌드된 결과물이 decapod-manifests와 같은 github repository에 push되어야 실제 배포가 가능하다.
 
 `decapod-site/.github/workflows/render-cd.sh` 파일을 사용하여 빌드한다.
 
 ```bash
 $ cd decapod-site
-$ .github/workflows/render-cd.sh <DECAPOD-BASE-BRANCH> <OUTPUT_DIR> <SITE_NAME>
+$ .github/workflows/render-cd.sh --base-url <DECAPOD-BASE-URL>
+
+# 특정 site에 대해서만 rendering할 경우
+$ .github/workflows/render-cd.sh --base-url <DECAPOD-BASE-URL> --site <YOUR-SITE-NAME>
 ```
 
 실제 배포를 위해서는 빌드된 최종 결과물을 미리 생성해놓은 'decapod-manifest' repository로 push해준다
 ```
 $ cd <YOUR-DECAPOD-SITE-DIRECTORY>
-$ cd cd   # 'cd' is directory for output manifests
+$ cd output   # 'output' is directory for output manifests
 $ mv ./* <YOUR-DECAPOD-MANIFEST_DIRECTORY>/
 $ cd <YOUR-DECAPOD-MANIFEST_DIRECTORY>
 $ git commit
 $ git push
 ```
 
-## 자동 빌드
+## 자동 Build
 Decapod-site는 Github Action을 통해 빌드를 자동화하였다. Repository에 pull request가 생성되어 main branch에 merge되면, 렌더링된 결과물이 decapod-manifest repo로 자동으로 push 되며, 자세한 내용은 [여기](https://github.com/openinfradev/decapod-site/blob/main/.github/workflows/merge_main.yml)를 참고할 수 있다.

docs/getting-started/deploying.md

@@ -1,29 +1,26 @@
-# Deploying
+# Deploying applications
 
 ## 사전 준비
 * argo CLI 가 설치되어 있어야 한다.
     * [argo CLI 설치](https://github.com/argoproj/argo-workflows/releases) 
 
-* Argo Workflow에 decapod-flow에서 제공하는 `WorkflowTemplate` 을 아래와 같이 생성한다. 각각은 decapod에서 제공하는 pre-defined workflow 템플릿이다.
+* decapod-flow에서 제공하는 `WorkflowTemplate` 을 아래와 같이 Argo Workflow Server에 등록한다.  
+  각각은 decapod에서 제공하는 pre-defined workflow 템플릿이다.
 ```bash
 git clone https://github.com/openinfradev/decapod-flow.git
 cd decapod-flow/templates
 
 # argo 를 위한 rbac manifest 를 적용한다.
 kubectl apply -f argo-additional-rbac.yaml
 
-argo template create argo-cd/prepare-argocd-wftpl.yaml
-argo template create argo-cd/createapp-wftpl.yaml
-
-argo template create decapod-apps/lma-uniformed-wftpl.yaml
-argo template create decapod-apps/openstack-components-wf.yaml
-argo template create decapod-apps/openstack-infra-wftpl.yaml
-argo template create decapod-apps/service-mesh-wf.yaml
+# workflow template을 argo workflow server에 등록한다.
+kubectl apply -f ./argo-cd/
+kubectl apply -f ./decapod-apps/
 ``` 
 
 ## 배포
 !!! note
-    이 문서에서는 LMA (Logging,Monitoring,Allerting) 배포에 대해서만 다룬다. 
+    이 문서에서는 LMA (Logging/Monitoring/Allerting) 배포에 대해서만 다룬다. 
 ### Argo CLI로 배포
 1. 최초 한 번만 prepare-argocd를 실행한다. parameter는 환경에 맞게 수정한다.  
   ```sh
@@ -38,27 +35,33 @@ argo template create decapod-apps/service-mesh-wf.yaml
   argo list -n argo # 생성된 workflow가 완료될 때까지 기다린다.
   ```
 
-2. lma 배포
+2. lma 배포  
+  현재 LMA app group 중 logging componet의 경우 [loki](https://grafana.com/docs/loki/latest/)와 [efk](https://www.digitalocean.com/community/tutorials/how-to-set-up-an-elasticsearch-fluentd-and-kibana-efk-logging-stack-on-kubernetes) 중에서 선택할 수 있으며, 간단한 테스트 목적의 경우 좀더 lightweight한 'loki'를 권장한다.
   ```sh
   argo submit -n argo --from wftmpl/lma-federation \
     -p site_name="사이트명" # decapod-manifests의 사이트 디렉토리명과 반드시 일치해야한다. \
-    -p app_name="lma" \
-    -p repository_url="https://github.com/{YOUR_REPO_NAME}/decapod-manifests" # decapod-manifests repository 주소
+    -p logging_component="loki" \
+    -p manifest_repo_url="https://github.com/{YOUR_REPO_NAME}/decapod-manifests" # decapod-manifests repository 주소
 
   argo list -n argo # 생성된 workflow가 완료될 때까지 기다린다.
   ```
 
 3. 배포 확인  
-
-    LMA가 정상적으로 배포되면 다음과 같은 UI에 정상적으로 접근할 수 있어야한다.  
-
-    * Prometheus 30008 NodePort
-    * Grafana 30009 NodePort
-    * Kibana 30001 NodePort
-
-    다음과 같은 명령어로 모든 pod의 상태를 확인할 수 있다.
-    ```sh
-    kubectl get pod -n lma
-    ```
+  LMA가 정상적으로 배포되면 다음과 같이 pod 및 service 상태를 확인 후 브라우져를 통해 서비스에 접속해본다.  
+  실제 service의 NodePort 번호 등은 설정에 따라 조금씩 다를 수 있다.
+  ```sh
+  $ kubectl get pod -n lma
+  NAME                                            READY   STATUS      RESTARTS       AGE
+  prometheus-lma-prometheus-0                     3/3     Running     0              18d
+  loki-0                                          1/1     Running     0              20h
+  grafana-7d5546bb4b-hvkqg                        3/3     Running     0              18d
+  promtail-fctfs                                  1/1     Running     0              18d
+  ...
 
-
+  $ kubectl get svc -n lma
+  NAME                           TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                           AGE
+  grafana                        ClusterIP   10.233.59.153   <none>        80/TCP                            18d
+  lma-prometheus                 NodePort    10.233.45.183   <none>        9090:30008/TCP                    18d
+  loki                           ClusterIP   10.233.62.51    <none>        3100/TCP                          18d
+  ...
+  ```