[docs] update deploy env docs

nuvo · Dec 24, 2018 · 13effeb · 13effeb
1 parent aff2d86
commit 13effeb
Show file tree

Hide file tree

Showing 2 changed files with 31 additions and 27 deletions.
diff --git a/README.md b/README.md
@@ -67,8 +67,9 @@ Additional actions:
 
 #### Get the "stable" environment and deploy the same configuration to a new environment, with override(s)
 
-Useful for creating test environments for a single service.
+Useful for creating test environments for a single service or for multiple services. Handy for testing a single feature spanning across one or more services.
 This will deploy the "stable" configuration to a destination namespace, except for the specified override(s), which will be deployed with version `CHART_VERSION`.
+The following commands will be a part of all CI\CD processes in all services:
 
 ```
 orca get env --name $SRC_NS --kube-context $SRC_KUBE_CONTEXT > charts.yaml
@@ -78,10 +79,14 @@ orca deploy env --name $DST_NS -c charts.yaml \
     --override $CHART_NAME=$CHART_VERSION
 ```
 
-#### Get the "stable" environment and deploy the same configuration to a new environment, with override(s) and existence check
+* If the environment already exists, only the specified override(s) will be deployed.
+* After deploying from (for example) 3 different repositories, the new environment will have the "stable" configuration, except for the 3 services which are currently under test, which will be deployed with their respective `CHART_VERSION`s.
+* Orca also handles a potential race condition between 2 or more services by "locking" the environment during deployment (using a `busy` annotation on the namespace).
+
+#### Get the "stable" environment and deploy the same configuration to the same new environment from multiple CI\CD processes with environment refresh
 
-Useful for creating test environments for multiple services. Handy for testing a single feature spanning across multiple services.
-This will deploy the same configuration to a destination namespace, except for the specified override(s), which will be deployed with version CHART_VERSION. If the environment already exists, only the specified override(s) will be deployed (using the `-x` flag - deploy only override if environment exists).
+Useful for creating test environments for a single service or for multiple services, when you have a rapidly changing reference environment.
+This will deploy the same configuration to a destination namespace, except for the specified override(s), which will be deployed with version CHART_VERSION. If the reference environment has changed between environment deployments, the new environment will be updated with these changes.
 The following commands will be a part of all CI\CD processes in all services:
 
 ```
@@ -90,15 +95,14 @@ orca deploy env --name $DST_NS -c charts.yaml \
     --kube-context $DST_KUBE_CONTEXT \
     --repo myrepo=$REPO_URL \
     --override $CHART_NAME=$CHART_VERSION \
-    -x
+    --protected-chart $CHART_NAME \
+    --refresh
 ```
 
-When the first service's process starts, it creates the environment and deploys the configuration from the "stable" environment (exactly the same as the previous example). When the Nth service's process starts, the environment already exists, and only the specified override(s) are deployed.
-Orca also handles a potential race condition between 2 or more services by "locking" the environment during deployment (using a `busy` annotation on the namespace).
-
-Using the `-x` flag, after deploying from (for example) 3 different repositories, the new environment will have the "stable" configuration, except for the 3 services which are currently under test, which will be deployed with their respective `CHART_VERSION`s.
+When the first service's process starts, it creates the environment and deploys the configuration from the "stable" environment (exactly the same as the previous example). In addition, it will set an annotation stating that `CHART_NAME` is protected and can only be overridden by itself.
+When the Nth service's process starts, the environment already exists, and a previous chart that was deployed is `protected`. The current service will also be marked as `protected`, and will update the environment, without changing the previous protected service(s).
 
-You can add the `-x` flag even if this service is completely isolated (for consistency).
+* You can add the `--protected-chart` flag even if this service is completely isolated (for consistency).
 
 ### Create and update static environments
 

diff --git a/docs/commands/README.md b/docs/commands/README.md
@@ -77,23 +77,23 @@ Aliases:
   env, environment
 
 Flags:
-      --annotations strings                  additional environment (namespace) annotations (can specify multiple): annotation=value
-  -c, --charts-file string                   path to file with list of Helm charts to install. Overrides $ORCA_CHARTS_FILE
-  -x, --deploy-only-override-if-env-exists   if environment exists - deploy only override(s) (avoid environment update). Overrides $ORCA_DEPLOY_ONLY_OVERRIDE_IF_ENV_EXISTS
-      --helm-tls-store string                path to TLS certs and keys. Overrides $HELM_TLS_STORE
-      --inject                               enable injection during helm upgrade. Overrides $ORCA_INJECT (requires helm inject plugin: https://github.com/maorfr/helm-inject)
-      --kube-context string                  name of the kubeconfig context to use. Overrides $ORCA_KUBE_CONTEXT
-      --labels strings                       environment (namespace) labels (can specify multiple): label=value
-  -n, --name string                          name of environment (namespace) to deploy to. Overrides $ORCA_NAME
-      --override strings                     chart to override with different version (can specify multiple): chart=version
-  -p, --parallel int                         number of releases to act on in parallel. set this flag to 0 for full parallelism. Overrides $ORCA_PARALLEL (default 1)
-      --protected-chart strings              chart name to protect from being overridden (can specify multiple)
-      --repo string                          chart repository (name=url). Overrides $ORCA_REPO
-  -s, --set strings                          set additional parameters
-      --timeout int                          time in seconds to wait for any individual Kubernetes operation (like Jobs for hooks). Overrides $ORCA_TIMEOUT (default 300)
-      --tls                                  enable TLS for request. Overrides $ORCA_TLS
-      --validate                             perform environment validation after deployment. Overrides $ORCA_VALIDATE
-  -f, --values strings                       values file to use (packaged within the chart)
+      --annotations strings       additional environment (namespace) annotations (can specify multiple): annotation=value
+  -c, --charts-file string        path to file with list of Helm charts to install. Overrides $ORCA_CHARTS_FILE
+      --helm-tls-store string     path to TLS certs and keys. Overrides $HELM_TLS_STORE
+      --inject                    enable injection during helm upgrade. Overrides $ORCA_INJECT (requires helm inject plugin: https://github.com/maorfr/helm-inject)
+      --kube-context string       name of the kubeconfig context to use. Overrides $ORCA_KUBE_CONTEXT
+      --labels strings            environment (namespace) labels (can specify multiple): label=value
+  -n, --name string               name of environment (namespace) to deploy to. Overrides $ORCA_NAME
+      --override strings          chart to override with different version (can specify multiple): chart=version
+  -p, --parallel int              number of releases to act on in parallel. set this flag to 0 for full parallelism. Overrides $ORCA_PARALLEL (default 1)
+      --protected-chart strings   chart name to protect from being overridden (can specify multiple)
+      --refresh                   refresh the environment based on reference environment. Overrides $ORCA_REFRESH
+      --repo string               chart repository (name=url). Overrides $ORCA_REPO
+  -s, --set strings               set additional parameters
+      --timeout int               time in seconds to wait for any individual Kubernetes operation (like Jobs for hooks). Overrides $ORCA_TIMEOUT (default 300)
+      --tls                       enable TLS for request. Overrides $ORCA_TLS
+      --validate                  perform environment validation after deployment. Overrides $ORCA_VALIDATE
+  -f, --values strings            values file to use (packaged within the chart)
 ```
 
 `helm-tls-store` - path to directory containing `<kube-context>.cert.pem` and `<kube-context>.key.pem` files