add en doc for ansible and helm

docs/en/ansible.md

@@ -1,3 +1,52 @@
 # Ansible
 
-Todo
+Sail uses ONLY one ansible playbook to construct the installation steps for all components.
+This is playbook SHOULD be named `sail.yaml` and be placed at `products/<productName>/sail.yaml`.
+
+The `sail.yaml` playbook looks like the following:
+
+```yaml
+- name: kafka
+  hosts: "{{ _ansiblepattern_kafka | default('kafka') }}"
+  roles:
+    - role: kafka
+      tags:
+        - kafka
+  tags:
+    - play-kafka
+
+- name: etcd
+  hosts: "{{ _ansiblepattern_etcd | default('etcd') }}"
+  roles:
+    - role: etcd
+      tags:
+        - etcd
+  tags:
+    - play-etcd
+```
+
+For each component, there should be an seperated ansible play (playbook is composed of plays).
+
+The order in the playbook also indicates the installation sequence for the components of the product.
+
+## Generate `sail.yaml`
+
+If the product contains a lot of components, `sail` can help to generate the `sail.yaml` playbook for you.
+Please run `sail gen-sail -p <productName>`.
+
+You can indicate the installation order for the components by `order.yaml`.
+The `order.yaml` is a list of components. You don't need to specified ALL components into `order.yaml`.
+Those unspecified components are automatically appended to the last by alphabetical order.
+
+```yaml
+# order.yaml content
+- mysql
+- kafka
+- myapp-web
+- myapp-api
+...
+```
+
+1. `sail` gets the components list of the product by parsing `components.yaml` and `components/*.yaml`.
+2. `sail` gets the order by parsing `order.yaml`.
+3. `sail` generates the `sail.yaml` playbook.

docs/en/helm.md

@@ -1,3 +1,60 @@
 # Helm
 
-Todo
+When deploying the product, all components or some components may need to deployed to K8S.
+
+Sail deploys the pod components by using **Helm Chart**.
+Sail supports two mode to use helm chart.
+
+1. Treat the product as a whole helm chart. `_sail_helm_mode: "product"`
+2. Treat each component as standalone helm chart. `_sail_helm_mode: "component"`
+
+> These two modes CAN NOT be used simultaneously for a product.
+
+You can specify the helm mode by set `_sail_helm_mode` to proper value in `<target_name>/<zone_name>/vars.yaml`.
+
+## Treat the product as a whole helm chart
+
+You can use the `products/<productName>` as a standarad helm chart directory.
+
+```bash
+components/*.yaml
+components.yaml
+vars.yaml
+
+Chart.yaml      # helm Chart.yaml
+values.yaml     # helm values.yaml
+templates/      # helm templates
+crds/           # helm crds
+charts/         # helm charts
+```
+
+You can put K8S manifest files of each component under `templates`.
+
+```bash
+templates/foobar-api-service.yaml
+templates/foobar-api-deployment.yaml
+templates/foobar-api-configmap.yaml
+templates/foobar-web-service.yaml
+templates/foobar-web-deployment.yaml
+templates/foobar-web-configmap.yaml
+templates/...
+```
+
+## Treat each component as standalone helm chart.
+
+The chart directory for each component: `products/<productName>/roles/<roleName>/helm/<componentName>/`.
+It's a standarad helm chart directory.
+
+```bash
+Chart.yaml
+values.yaml
+templates/
+crds/
+charts/
+```
+
+Even in `_sail_helm_mode: "component"` mode，you can optionally still define a global values.yaml file `products/<productName>/values.yaml`。
+
+## Helm Runing
+
+Todo.

docs/en/sail-commands.md

@@ -1,9 +1,76 @@
 # sail commands
 
+```yaml
+$ cat ~/.sailrc.yaml
+products-dir: /path/to/products
+targets-dir: /path/to/targets
+packages-dir: /path/to/packages
+```
+
+## sail list-components
+
+List all components for the specified product.
+
+```bash
+$ ./sail list-components -p <productName>
+the product <productName> contains the following components:
+- <componentName1>
+- <componentName2>
+- ...
+```
+
 ## sail conf-create
 
+Create a new deploy target environments.
+You have to specify a target name and a zone name, and the name of the product which will be deployed in this environment.
+
+The product name is persisted under zone's variables. So you won't need to specify the product when running other `sail` commands.
+When running other `sail` commands, ONLY the envionment (`-t <targetName> -z <zoneName>`) may need to be specified.
+
+```bash
+$ sail conf-create -t <targetName> -z <zoneName> \
+    -p <productName> \
+    --hosts ip1,ip2,ip3 \                   # will be used for all components which are not explicityly specified by --hosts options
+    --hosts componentName1/ip1,ip2,ip3 \
+    --hosts componentName2/ip11,ip12,ip13
+```
+
 ## sail conf-update
 
+Syncs, updates, and computes the vars for the zone and dumps them into files.
+Thus `ansible-playbook` and/or `helm` can load these variables files from the command line.
+
+Actually, all the things did by `sail conf-update` are also automatically executed in other `sail` commands,
+like `sail apply` and `sail upgrade`.
+So there is no need to manually run `sail conf-update` by yourself before you run other `sail` commands.
+
+Only on the cases that you want to check and see what the computed variables looks like,
+you can run `sail conf-update` manually.
+
+```bash
+$ sail conf-update -t <targetName> -z <zoneName>
+```
+
 ## sail apply
 
+`sail apply` will execute `ansible-playbook` for the server components, and execute `helm` for the pod components.
+
+```bash
+$ sail apply -t <targetName> -z <zoneName> [-c <componentName>]
+```
+
 ## sail upgrade
+
+`sail upgrade` will execute `ansible-playbook` for the server components, and execute `helm` for the pod components.
+
+```bash
+$ sail upgrade -t <targetName> -z <zoneName> [-c <componentName>]
+```
+
+> Actually, there's very little differences between `sail apply` and `sail upgrade`.
+> When execute `helm` for pod components, there are no differeneces at all.
+> When execute `ansible-playbook` for server components, if no server components are explicitly specified on the command line,
+> then `sail apply` and `sail upgrade` are totally same.
+> If there are server components explicitly specified, then
+> `sail apply` pass `--tags play-<componentName>` options to `ansible-palybook` and
+> `sail upgrade` pass `--tags update-<componentName>` options to `ansible-playbook`.

pkg/commands/apply/apply.go

@@ -93,7 +93,7 @@ func (o *ApplyOptions) Run(args []string) error {
 
 	var ansiblePlaybookTags []string
 	for componentName := range serverComponents {
-		ansiblePlaybookTag := componentName
+		ansiblePlaybookTag := "play-" + componentName
 		ansiblePlaybookTags = append(ansiblePlaybookTags, ansiblePlaybookTag)
 	}