Docs: Fix Armada apply --set flag documentation

This PS updates the Armada apply --set flag documentation to
be in line with the actual implementation. Each override
must be of the form:

  manifest:simple-armada:release_name="wordpress"

Or:

  manifest:simple-armada:chart_goups="foo","bar"

This PS also adds a few more unit tests for Override handler.

Change-Id: Ie280752ceee75a9a13d1ffafb40589c294407b46

armada/cli/apply.py

@@ -42,19 +42,19 @@ command will execute upgrade.
 To see how to create an Armada manifest:
     http://armada-helm.readthedocs.io/en/latest/operations/
 
-To obtain install/upgrade charts:
+To install or upgrade charts, run:
 
     \b
     $ armada apply examples/simple.yaml
 
-To obtain override manifest:
+To override a specific value in a Manifest, run:
 
     \b
     $ armada apply examples/simple.yaml \
 --set manifest:simple-armada:release_name="wordpress"
 
-    \b
-    or
+Or to override several values in a Manifest, reference a values.yaml-formatted
+file:
 
     \b
     $ armada apply examples/simple.yaml \
@@ -87,7 +87,10 @@ SHORT_DESC = "Command installs manifest charts."
               is_flag=True)
 @click.option('--set',
               help=("Use to override Armada Manifest values. Accepts "
-                    "overrides that adhere to the format <key>=<value>"),
+                    "overrides that adhere to the format "
+                    "<path>:<to>:<property>=<value> to specify a primitive or "
+                    "<path>:<to>:<property>=<value1>,...,<valueN> to specify "
+                    "a list of values."),
               multiple=True,
               type=str,
               default=[])

armada/handlers/override.py

@@ -69,6 +69,8 @@ class Override(object):
             doc_path[0], doc_path[1])
 
     def array_to_dict(self, data_path, new_value):
+        # TODO(fmontei): Handle `json.decoder.JSONDecodeError` getting thrown
+        # better.
         def convert(data):
             if isinstance(data, str):
                 return str(data)

armada/tests/unit/handlers/test_override.py

@@ -12,10 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import testtools
-import yaml
-import os
 import copy
+import json
+import os
+import yaml
+
+import testtools
 
 from armada.handlers.override import Override
 from armada.exceptions import override_exceptions
@@ -61,9 +63,25 @@ class OverrideTestCase(testtools.TestCase):
             original_documents = list(yaml.safe_load_all(f.read()))
             documents_copy = copy.deepcopy(original_documents)
             values_documents = list(yaml.safe_load_all(g.read()))
-        override = ('manifest:simple-armada:chart_groups=\
-            blog-group3,blog-group4',)
 
+        override = ('manifest:simple-armada:release_prefix='
+                    'overridden',)
+
+        # Case 1: Checking if primitive gets updated.
+        ovr = Override(original_documents, override, [values_yaml])
+        ovr.update_manifests()
+
+        # updating values changed the original document
+        self.assertNotEqual(original_documents, documents_copy)
+        # since overrides done, these documents aren't same anymore
+        self.assertNotEqual(original_documents, values_documents)
+        self.assertEqual('overridden',
+                         ovr.documents[-1]['data']['release_prefix'])
+
+        override = ('manifest:simple-armada:chart_groups='
+                    'blog-group3,blog-group4',)
+
+        # Case 2: Checking if list gets updated.
         ovr = Override(original_documents, override, [values_yaml])
         ovr.update_manifests()
         # updating values changed the original document
@@ -76,6 +94,17 @@ class OverrideTestCase(testtools.TestCase):
         self.assertEqual(original_documents[2]['data']['chart_groups'],
                          comparison_documents[0]['data']['chart_groups'])
 
+    def test_update_manifests_invalid_override_format(self):
+        with open(self.base_manifest) as f:
+            original_documents = list(yaml.safe_load_all(f.read()))
+
+        original_documents[-1]['data']['test'] = {'foo': 'bar'}
+        override = ('manifest:simple-armada:test='
+                    '{"foo": "bar"}',)
+
+        ovr = Override(original_documents, override, [])
+        self.assertRaises(json.decoder.JSONDecodeError, ovr.update_manifests)
+
     def test_load_yaml_file(self):
         with open(self.base_manifest) as f:
             documents = list(yaml.safe_load_all(f.read()))

docs/source/commands/apply.rst

@@ -18,15 +18,16 @@ Commands
       To see how to create an Armada manifest:
       http://armada-helm.readthedocs.io/en/latest/operations/
 
-      To obtain install/upgrade charts:
+      To install or upgrade charts, run:
 
           $ armada apply examples/simple.yaml
 
-      To obtain override manifest:
+      To override a specific value in a Manifest, run:
 
           $ armada apply examples/simple.yaml --set manifest:simple-armada:release_name="wordpress"
 
-          or
+      Or to override several values in a Manifest, reference a values.yaml-
+      formatted file:
 
           $ armada apply examples/simple.yaml --values examples/simple-ovr-values.yaml
 
@@ -38,7 +39,10 @@ Commands
       --enable-chart-cleanup        Clean up unmanaged charts.
       --set TEXT                    Use to override Armada Manifest values.
                                     Accepts overrides that adhere to the format
-                                    <key>=<value>
+                                    <path>:<to>:<property>=<value> to specify a
+                                    primitive or
+                                    <path>:<to>:<property>=<value1>,...,<valueN>
+                                    to specify a list of values.
       --tiller-host TEXT            Tiller host IP.
       --tiller-port INTEGER         Tiller host port.
       -tn, --tiller-namespace TEXT  Tiller namespace.