[Feat] Add common error/exception handling

- Add main exception handler
- Add more detailed, individual exceptions for common Armada failure points
- Add exception documentation

armada/exceptions/armada_exceptions.py

@@ -0,0 +1,37 @@
+# Copyright 2017 The Armada Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import base_exception
+
+class ArmadaException(base_exception.ArmadaBaseException):
+    '''Base class for Armada handler exception and error handling.'''
+
+    message = 'An unknown Armada handler error occured.'
+
+class KnownReleasesException(ArmadaException):
+    '''Exception that occurs when no known releases are found'''
+
+    message = 'No known releases found'
+
+class ChartSourceException(ArmadaException):
+    '''Exception for unknown chart source type.'''
+
+    def __init__(self, chart_name, source_type):
+        self._chart_name = chart_name
+        self._source_type = source_type
+
+        self._message = 'Unknown source type \"' + self._source_type + '\" for \
+                        chart \"' + self._chart_name + '\"'
+
+        super(ChartSourceException, self).__init__(self._message)

armada/exceptions/base_exception.py

@@ -0,0 +1,31 @@
+# Copyright 2017 The Armada Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from oslo_config import cfg
+from oslo_log import log as logging
+
+LOG = logging.getLogger(__name__)
+
+DEFAULT_TIMEOUT = 3600
+CONF = cfg.CONF
+DOMAIN = "armada"
+
+logging.setup(CONF, DOMAIN)
+
+class ArmadaBaseException(Exception):
+    '''Base class for Armada exception and error handling.'''
+
+    def __init__(self, message=None):
+        self.message = message or self.message
+        super(ArmadaBaseException, self).__init__(self.message)

armada/exceptions/chartbuilder_exceptions.py

@@ -0,0 +1,63 @@
+# Copyright 2017 The Armada Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import base_exception
+
+class ChartBuilderException(base_exception.ArmadaBaseException):
+    '''Base class for the Chartbuilder handler exception and error handling.'''
+
+    message = 'An unknown Armada handler error occured.'
+
+class DependencyException(ChartBuilderException):
+    '''Exception that occurs when dependencies cannot be resolved.'''
+
+    def __init__(self, chart_name):
+        self._chart_name
+        self._message = 'Failed to resolve dependencies for ' + \
+                        self._chart_name + '.'
+
+        super(DependencyException, self).__init__(self._message)
+
+class HelmChartBuildException(ChartBuilderException):
+    '''Exception that occurs when Helm Chart fails to build.'''
+
+    def __init__(self, chart_name):
+        self._chart_name
+        self._message = 'Failed to build Helm chart for ' + \
+                        self._chart_name + '.'
+
+        super(HelmChartBuildException, self).__init__(self._message)
+
+class IgnoredFilesLoadException(ChartBuilderException):
+    '''Exception that occurs when there is an error loading ignored files.'''
+
+    message = 'An error occured while loading the ignored files in \
+              .helmignore'
+
+class MetadataLoadException(ChartBuilderException):
+    ''' Exception that occurs when metadata loading fails.'''
+
+    message = 'Failed to load metadata from chart yaml file'
+
+class UnknownChartSourceException(ChartBuilderException):
+    '''Exception for unknown chart source type.'''
+
+    def __init__(self, chart_name, source_type):
+        self._chart_name = chart_name
+        self._source_type = source_type
+
+        self._message = 'Unknown source type \"' + self._source_type + '\" for \
+                         chart \"' + self._chart_name + '\"'
+
+        super(UnknownChartSourceException, self).__init__(self._message)

armada/exceptions/git_exceptions.py

@@ -0,0 +1,38 @@
+# Copyright 2017 The Armada Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import base_exception
+
+class GitException(base_exception.ArmadaBaseException):
+    '''Base class for Git exceptions and error handling.'''
+
+    message = 'An unknown error occured while cloning a Git repository.'
+
+class GitLocationException(GitException):
+    '''Exception that occurs when an error occurs cloning a Git repository.'''
+
+    def __init__(self, location):
+        self._location = location
+        self._message = self._location + ' is not a valid git repository.'
+
+        super(GitLocationException, self).__init__(self._message)
+
+class SourceCleanupException(GitException):
+    '''Exception that occurs for an invalid dir.'''
+
+    def __init__(self, target_dir):
+        self._target_dir = target_dir
+        self._message = self._target_dir + ' is not a valid directory.'
+
+        super(SourceCleanupException, self).__init__(self._message)

armada/exceptions/lint_exceptions.py

@@ -0,0 +1,45 @@
+# Copyright 2017 The Armada Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import base_exception
+
+class LintException(base_exception.ArmadaBaseException):
+    '''Base class for linting exceptions and errors.'''
+
+    message = 'An unknown linting error occured.'
+
+class InvalidManifestException(LintException):
+    '''Exception for invalid manifests.'''
+
+    message = 'Armada manifest invalid.'
+
+class InvalidChartNameException(LintException):
+    '''Exception that occurs when an invalid filename is encountered.'''
+
+    message = 'Chart name must be a string,'
+
+class InvalidChartDefinitionException(LintException):
+    '''Exception when invalid chart definition is encountered.'''
+
+    message = 'Invalid chart definition.Chart definition must be array.'
+
+class InvalidReleaseException(LintException):
+    '''Exception that occurs when a release is invalid.'''
+
+    message = 'Release needs to be a string.'
+
+class InvalidArmadaObjectException(LintException):
+    '''Exception that occurs when an Armada object is not declared.'''
+
+    message = 'An Armada object was not declared.'

armada/exceptions/tiller_exceptions.py

@@ -0,0 +1,118 @@
+# Copyright 2017 The Armada Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import base_exception
+
+class TillerException(base_exception.ArmadaBaseException):
+    '''Base class for Tiller exceptions and error handling.'''
+
+    message = 'An unknown Tiller error occured.'
+
+class TillerServicesUnavailableException(TillerException):
+    '''Exception for tiller services unavailable.'''
+
+    message = 'Tiller services unavailable.'
+
+class ChartCleanupException(TillerException):
+    '''Exception that occures during chart cleanup.'''
+
+    def __init__(self, chart_name, source_type):
+        super(ChartCleanupException, self).__init__('An error occred during \
+                                                     cleanup while removing \
+                                                     the chart ' + chart_name)
+
+class ListChartsException(TillerException):
+    '''Exception that occurs when listing charts'''
+
+    message = 'There was an error listing the helm chart releases.'
+
+class PostUpdateJobDeleteException(TillerException):
+    '''Exception that occurs when a job deletion'''
+
+    def __init__(self, name, namespace):
+        self._name = name
+        self._namespace = namespace
+
+        self._message = 'Failed to delete k8s job ' + self._name + ' in ' + \
+                        self._namespace + ' namspace.'
+
+        super(PostUpdateJobDeleteException, self).__init__(self._message)
+
+class PostUpdateJobCreateException(TillerException):
+    '''Exception that occurs when a job creation fails.'''
+
+    def __init__(self, name, namespace):
+        self._name = name
+        self._namespace = namespace
+
+        self._message = 'Failed to create k8s job ' + self._name + ' in ' + \
+                        self._namespace + ' namespace.'
+
+        super(PostUpdateJobCreateException, self).__init__(self._message)
+
+class PreUpdateJobDeleteException(TillerException):
+    '''Exception that occurs when a job deletion'''
+
+    def __init__(self, name, namespace):
+        self._name = name
+        self._namespace = namespace
+
+        self._message = 'Failed to delete k8s job ' + self._name + ' in ' + \
+                        self._namespace + ' namspace.'
+
+        super(PreUpdateJobDeleteException, self).__init__(self._message)
+
+class PreUpdateJobCreateException(TillerException):
+    '''Exception that occurs when a job creation fails.'''
+
+    def __init__(self, name, namespace):
+        self._name = name
+        self._namespace = namespace
+
+        self._message = 'Failed to create k8s job ' + self._name + ' in ' + \
+                        self._namespace + ' namespace.'
+
+        super(PreUpdateJobCreateException, self).__init__(self._message)
+
+class ReleaseUninstallException(TillerException):
+    '''Exception that occurs when a release fails to uninstall.'''
+
+    def __init__(self, name, namespace):
+        self._name = name
+        self._message = 'Failed to uninstall release' + self._name + '.'
+
+        super(ReleaseUninstallException, self).__init__(self._message)
+
+class ReleaseInstallException(TillerException):
+    '''Exception that occurs when a release fails to install.'''
+
+    def __init__(self, name, namespace):
+        self._name = name
+        self._message = 'Failed to install release' + self._name + '.'
+
+        super(ReleaseInstallException, self).__init__(self._message)
+
+class ReleaseUpdateException(TillerException):
+    '''Exception that occurs when a release fails to update.'''
+
+    def __init__(self, name, namespace):
+        self._name = name
+        self._message = 'Failed to update release' + self._name + '.'
+
+        super(ReleaseUpdateException, self).__init__(self._message)
+
+class ChannelException(TillerException):
+    '''Exception that occurs during a failed GRPC channel creation'''
+
+    message = 'Failed to create GRPC channel.'

armada/handlers/armada.py

@@ -22,6 +22,12 @@ from supermutes.dot import dotify
 from chartbuilder import ChartBuilder
 from tiller import Tiller
 from manifest import Manifest
+
+from ..exceptions import armada_exceptions
+from ..exceptions import git_exceptions
+from ..exceptions import lint_exceptions
+from ..exceptions import tiller_exceptions
+
 from ..utils.release import release_prefix
 from ..utils import git
 from ..utils import lint
@@ -92,15 +98,13 @@ class Armada(object):
 
         # Ensure tiller is available and yaml is valid
         if not self.tiller.tiller_status():
-            raise Exception("Service: Tiller is not Available")
+            raise tiller_exceptions.TillerServicesUnavailableException()
         if not lint.validate_armada_documents(self.documents):
-            raise Exception("Invalid Armada Manifest")
+            raise lint_exceptions.InvalidManifestException()
+        if not lint.validate_armada_object(self.config):
+            raise lint_exceptions.InvalidArmadaObjectExceptionl()
 
         self.config = self.get_armada_manifest()
-
-        if not lint.validate_armada_object(self.config):
-            raise Exception("Invalid Armada Object")
-
         # Purge known releases that have failed and are in the current yaml
         prefix = self.config.get(KEYWORD_ARMADA).get(KEYWORD_PREFIX)
         failed_releases = self.get_releases_by_status(STATUS_FAILED)
@@ -140,15 +144,15 @@ class Armada(object):
                 try:
                     LOG.info('Cloning repo: %s', location)
                     repo_dir = git.git_clone(location, reference)
-                except Exception as e:
-                    raise ValueError(e)
+                except Exception:
+                    raise git_exceptions.GitLocationException(location)
                 repos[location] = repo_dir
                 ch.get('chart')['source_dir'] = (repo_dir, subpath)
             else:
                 ch.get('chart')['source_dir'] = (repos.get(location), subpath)
         else:
-            raise Exception("Unknown source type %s for chart %s", ct_type,
-                            ch.get('chart').get('name'))
+            chart_name = ch.get('chart').get('name')
+            raise armada_exceptions.ChartSourceException(ct_type, chart_name)
 
     def get_releases_by_status(self, status):
         '''
@@ -178,6 +182,9 @@ class Armada(object):
         known_releases = self.tiller.list_charts()
         prefix = self.config.get(KEYWORD_ARMADA).get(KEYWORD_PREFIX)
 
+        if known_releases is None:
+            raise armada_exceptions.KnownReleasesException()
+
         for release in known_releases:
             LOG.debug("Release %s, Version %s found on tiller", release[0],
                       release[1])

armada/handlers/chartbuilder.py

@@ -21,6 +21,8 @@ from hapi.chart.metadata_pb2 import Metadata
 from hapi.chart.config_pb2 import Config
 from supermutes.dot import dotify
 
+from ..exceptions import chartbuilder_exceptions
+
 from oslo_config import cfg
 from oslo_log import log as logging
 
@@ -76,11 +78,16 @@ class ChartBuilder(object):
         '''
         Load files from .helmignore if present
         '''
-        ignored_files = []
-        if os.path.exists(os.path.join(self.source_directory, '.helmignore')):
-            with open(os.path.join(self.source_directory, '.helmignore')) as f:
-                ignored_files = f.readlines()
-        return [filename.strip() for filename in ignored_files]
+        try:
+            ignored_files = []
+            if os.path.exists(os.path.join(self.source_directory,
+                                           '.helmignore')):
+                with open(os.path.join(self.source_directory,
+                          '.helmignore')) as f:
+                    ignored_files = f.readlines()
+            return [filename.strip() for filename in ignored_files]
+        except Exception:
+            raise chartbuilder_exceptions.IgnoredFilesLoadException()
 
     def ignore_file(self, filename):
         '''
@@ -102,10 +109,14 @@ class ChartBuilder(object):
         Process metadata
         '''
         # extract Chart.yaml to construct metadata
-        chart_yaml = dotify(
-            yaml.load(
-                open(os.path.join(self.source_directory, 'Chart.yaml'))
-                .read()))
+
+        try:
+            chart_yaml = dotify(
+                yaml.load(
+                    open(os.path.join(self.source_directory, 'Chart.yaml'))
+                    .read()))
+        except Exception:
+            raise chartbuilder_exceptions.MetadataLoadException()
 
         # construct Metadata object
         return Metadata(
@@ -176,18 +187,25 @@ class ChartBuilder(object):
         # dependencies
         # [process_chart(x, is_dependency=True) for x in chart.dependencies]
         dependencies = []
-
         for dep in self.chart.dependencies:
             LOG.info("Building dependency chart %s for release %s",
                      self.chart.chart_name, self.chart.release)
-            dependencies.append(ChartBuilder(dep.chart).get_helm_chart())
+            try:
+                dependencies.append(ChartBuilder(dep.chart).get_helm_chart())
+            except Exception:
+                chart_name = self.chart.chart_name
+                raise chartbuilder_exceptions.DependencyException(chart_name)
 
-        helm_chart = Chart(
-            metadata=self.get_metadata(),
-            templates=self.get_templates(),
-            dependencies=dependencies,
-            values=self.get_values(),
-            files=self.get_files(), )
+        try:
+            helm_chart = Chart(
+                metadata=self.get_metadata(),
+                templates=self.get_templates(),
+                dependencies=dependencies,
+                values=self.get_values(),
+                files=self.get_files(), )
+        except Exception:
+            chart_name = self.chart.chart_name
+            raise chartbuilder_exceptions.HelmChartBuildException(chart_name)
 
         self._helm_chart = helm_chart
         return helm_chart

armada/handlers/k8s.py

@@ -16,7 +16,6 @@ import re
 from kubernetes import client, config, watch
 from kubernetes.client.rest import ApiException
 
-
 from oslo_config import cfg
 from oslo_log import log as logging
 
@@ -36,6 +35,7 @@ class K8s(object):
         Initialize connection to Kubernetes
         '''
         config.load_kube_config()
+
         self.client = client.CoreV1Api()
         self.api_client = client.BatchV1Api()
 

armada/handlers/tiller.py

@@ -20,6 +20,8 @@ from hapi.chart.config_pb2 import Config
 
 from k8s import K8s
 from ..const import STATUS_DEPLOYED, STATUS_FAILED
+
+from ..exceptions import tiller_exceptions
 from ..utils.release import release_prefix
 
 from oslo_config import cfg
@@ -77,13 +79,17 @@ class Tiller(object):
         Return a tiller channel
         '''
         tiller_ip = self._get_tiller_ip()
-        return grpc.insecure_channel(
-            '%s:%s' % (tiller_ip, self.tiller_port),
-            options=[
-                ('grpc.max_send_message_length', MAX_MESSAGE_LENGTH),
-                ('grpc.max_receive_message_length', MAX_MESSAGE_LENGTH)
-            ]
-        )
+        tiller_port = self._get_tiller_port()
+        try:
+            return grpc.insecure_channel(
+                '%s:%s' % (tiller_ip, tiller_port),
+                options=[
+                    ('grpc.max_send_message_length', MAX_MESSAGE_LENGTH),
+                    ('grpc.max_receive_message_length', MAX_MESSAGE_LENGTH)
+                ]
+            )
+        except Exception:
+            raise tiller_exceptions.ChannelException()
 
     def _get_tiller_pod(self):
         '''
@@ -173,6 +179,8 @@ class Tiller(object):
                     self.delete_resource(release_name, name, 'pod',
                                          labels, namespace)
         except Exception:
+            raise tiller_exceptions.PreUpdateJobDeleteException(name,
+                                                                namespace)
             LOG.debug("PRE: Could not delete anything, please check yaml")
 
         try:
@@ -184,6 +192,8 @@ class Tiller(object):
                     self.k8s.create_job_action(name, action_type)
                     continue
         except Exception:
+            raise tiller_exceptions.PreUpdateJobCreateException(name,
+                                                                namespace)
             LOG.debug("PRE: Could not create anything, please check yaml")
 
     def delete_resource(self, release_name, resource_name, resource_type,
@@ -228,6 +238,7 @@ class Tiller(object):
                     self.k8s.create_job_action(name, action_type)
                     continue
         except Exception:
+            raise tiller_exceptions.PreUpdateJobCreateException()
             LOG.debug("POST: Could not create anything, please check yaml")
 
     def update_release(self, chart, dry_run, name, namespace, prefix,
@@ -249,19 +260,22 @@ class Tiller(object):
         self._pre_update_actions(release_name, pre_actions, namespace)
 
         # build release install request
-        stub = ReleaseServiceStub(self.channel)
-        release_request = UpdateReleaseRequest(
-            chart=chart,
-            dry_run=dry_run,
-            disable_hooks=disable_hooks,
-            values=values,
-            name=release_name,
-            wait=wait,
-            timeout=timeout)
 
-        stub.UpdateRelease(release_request, self.timeout,
-                           metadata=self.metadata)
+        try:
+            stub = ReleaseServiceStub(self.channel)
+            release_request = UpdateReleaseRequest(
+                chart=chart,
+                dry_run=dry_run,
+                disable_hooks=disable_hooks,
+                values=values,
+                name="{}-{}".format(prefix, name),
+                wait=wait,
+                timeout=timeout)
 
+            stub.UpdateRelease(release_request, self.timeout,
+                               metadata=self.metadata)
+        except Exception:
+            raise tiller_exceptions.ReleaseInstallException(name, namespace)
         self._post_update_actions(post_actions, namespace)
 
     def install_release(self, chart, dry_run, name, namespace, prefix,
@@ -278,19 +292,23 @@ class Tiller(object):
             values = Config(raw=values)
 
         # build release install request
-        stub = ReleaseServiceStub(self.channel)
-        release_request = InstallReleaseRequest(
-            chart=chart,
-            dry_run=dry_run,
-            values=values,
-            name="{}-{}".format(prefix, name),
-            namespace=namespace,
-            wait=wait,
-            timeout=timeout)
+        try:
+            stub = ReleaseServiceStub(self.channel)
+            release_request = InstallReleaseRequest(
+                chart=chart,
+                dry_run=dry_run,
+                values=values,
+                name="{}-{}".format(prefix, name),
+                namespace=namespace,
+                wait=wait,
+                timeout=timeout)
 
-        return stub.InstallRelease(release_request,
-                                   self.timeout,
-                                   metadata=self.metadata)
+            return stub.InstallRelease(release_request,
+                                       self.timeout,
+                                       metadata=self.metadata)
+
+        except Exception:
+            raise tiller_exceptions.ReleaseInstallException(name, namespace)
 
     def uninstall_release(self, release, disable_hooks=False, purge=True):
         '''
@@ -301,13 +319,17 @@ class Tiller(object):
         '''
 
         # build release install request
-        stub = ReleaseServiceStub(self.channel)
-        release_request = UninstallReleaseRequest(name=release,
+        try:
+            stub = ReleaseServiceStub(self.channel)
+            release_req = UninstallReleaseRequest(name=release,
                                                   disable_hooks=disable_hooks,
                                                   purge=purge)
-        return stub.UninstallRelease(release_request,
-                                     self.timeout,
-                                     metadata=self.metadata)
+            return stub.UninstallRelease(release_req,
+                                         self.timeout,
+                                         metadata=self.metadata)
+
+        except Exception:
+            raise tiller_exceptions.ReleaseUninstallException(release)
 
     def chart_cleanup(self, prefix, charts):
         '''

armada/tests/unit/utils/test_git.py

@@ -15,6 +15,8 @@
 import mock
 import unittest
 
+from armada.exceptions import git_exceptions
+
 from armada.utils import git
 
 class GitTestCase(unittest.TestCase):
@@ -31,9 +33,9 @@ class GitTestCase(unittest.TestCase):
 
     def test_git_clone_empty_url(self):
         url = ''
-        dir = git.git_clone(url)
 
-        self.assertFalse(dir)
+        with self.assertRaises(Exception):
+            self.assertFalse(git.git_clone(url))
 
     def test_git_clone_bad_url(self):
         url = 'http://github.com/dummy/armada'
@@ -47,7 +49,11 @@ class GitTestCase(unittest.TestCase):
         mock_path.exists.return_value = True
         path = 'armada'
 
-        git.source_cleanup(path)
+        try:
+            git.source_cleanup(path)
+        except git_exceptions.SourceCleanupException:
+            pass
+
         mock_shutil.rmtree.assert_called_with(path)
 
     @mock.patch('armada.utils.git.shutil')
@@ -55,6 +61,6 @@ class GitTestCase(unittest.TestCase):
     def test_source_cleanup_bad_path(self, mock_path, mock_shutil):
         mock_path.exists.return_value = False
         path = 'armada'
-
-        git.source_cleanup(path)
+        with self.assertRaises(Exception):
+            git.source_cleanup(path)
         mock_shutil.rmtree.assert_not_called()

armada/utils/git.py

@@ -3,16 +3,22 @@ import tempfile
 import shutil
 from os import path
 
+from ..exceptions import git_exceptions
+
 def git_clone(repo_url, branch='master'):
     '''
     clones repo to a /tmp/ dir
     '''
 
     if repo_url == '':
-        return False
+        raise git_exceptions.GitLocationException(repo_url)
 
     _tmp_dir = tempfile.mkdtemp(prefix='armada', dir='/tmp')
-    pygit2.clone_repository(repo_url, _tmp_dir, checkout_branch=branch)
+
+    try:
+        pygit2.clone_repository(repo_url, _tmp_dir, checkout_branch=branch)
+    except Exception:
+        raise git_exceptions.GitLocationException(repo_url)
 
     return _tmp_dir
 
@@ -22,3 +28,5 @@ def source_cleanup(target_dir):
     '''
     if path.exists(target_dir):
         shutil.rmtree(target_dir)
+    else:
+        raise git_exceptions.SourceCleanupException(target_dir)

docs/source/operations/guide-exceptions.rst

@@ -0,0 +1,81 @@
+Armada Exceptions
+=================
+
++------------------------+----------------------------------------------------------+
+| Exception              | Error Description                                        |
++========================+==========================================================+
+| ChartSourceException   | Occurs when an unknown chart source type is encountered. |
++------------------------+----------------------------------------------------------+
+| KnownReleasesException | Occurs when no known releases are found.                 |
++------------------------+----------------------------------------------------------+
+
+Tiller Exceptions
+=================
+
++------------------------------------+--------------------------------------------------------------------------------------------+
+| Exception                          | Error Description                                                                          |
++====================================+============================================================================================+
+|  ChartCleanupException             | An error occurred removing a chart.                                                        |
++------------------------------------+--------------------------------------------------------------------------------------------+
+|  ListChartsException               | An error occurred listing helm charts.                                                     |
++------------------------------------+--------------------------------------------------------------------------------------------+
+| PostUpdateJobDeleteException       | An error occurred deleting a job after an update.                                          |
++------------------------------------+--------------------------------------------------------------------------------------------+
+| PostUpdateJobCreateException       | An error occurred creating a job after an update.                                          |
++------------------------------------+--------------------------------------------------------------------------------------------+
+| PreUpdateJobDeleteException        | An error occurred deleting a job before an update.                                         |
++------------------------------------+--------------------------------------------------------------------------------------------+
+| PreUpdateJobCreateException        | An error occurred creating a job before an update.                                         |
++------------------------------------+--------------------------------------------------------------------------------------------+
+| ReleaseUninstallException          | A release failed to uninstall.                                                             |
++------------------------------------+--------------------------------------------------------------------------------------------+
+| ReleaseInstallException            | A release failed to install.                                                               |
++------------------------------------+--------------------------------------------------------------------------------------------+
+|  ReleaseUpdateException            | A release failed to update.                                                                |
++------------------------------------+--------------------------------------------------------------------------------------------+
+| TillerServicesUnavailableException | Occurs when Tiller services are unavailable.                                               |
++------------------------------------+--------------------------------------------------------------------------------------------+
+
+Chartbuilder Exceptions
+=======================
+
++-----------------------------+-------------------------------------------------------------+
+| Exception                   | Error Description                                           |
++=============================+=============================================================+
+| DepedencyException          | A dependency failed to install.                             |
++-----------------------------+-------------------------------------------------------------+
+| HelmChartBuildException     | An error occurred  building the chart.                      |
++-----------------------------+-------------------------------------------------------------+
+| IgnoredFilesLoadException   | An error occurred loading the ignored files.                |
++-----------------------------+-------------------------------------------------------------+
+| MetadataLoadException       | An error occurred loading the metadata for a chart.         |
++-----------------------------+-------------------------------------------------------------+
+| UnknownChartSourceException | The chart source is unknown or invalid.                     |
++-----------------------------+-------------------------------------------------------------+
+
+Git Exceptions
+===============
+
++------------------------+---------------------------------------------+
+| Exception              | Error Description                           |
++========================+=============================================+
+| GitLocationException   | Repository location is not valid.           |
++------------------------+---------------------------------------------+
+| SourceCleanupException | The source dir of a chart no longer exists. |
++------------------------+---------------------------------------------+
+
+Lint Exceptions
+===============
++----------------------------------+------------------------------+
+| Exception                        | Error Description            |
++==================================+==============================+
+| InvalidManifestException         | Armada manifest invalid.     |
++----------------------------------+------------------------------+
+| InvalidChartNameException        | Chart name invalid.          |
++----------------------------------+------------------------------+
+|  InvalidChartDefinitionException |  Chart definition invalid.   |
++----------------------------------+------------------------------+
+| InvalidReleaseException          | Release invalid.             |
++----------------------------------+------------------------------+
+|  InvalidArmadaObjectException    |  Armada object not declared. |
++----------------------------------+------------------------------+

docs/source/operations/guide-troubleshooting.rst

@@ -25,6 +25,10 @@ When running Armada in the container you can execute docker logs to retrieve log
 
     docker logs [container-name | container-id]
 
+Errors/Exceptions
+-----------------
+
+A guide for interpreting errors/exceptions can be found `here <http://armada-helm.readthedocs.io/en/latest/operations/guide-exceptions.html>`_.
 
 Working with SSL
 ----------------
@@ -49,5 +53,5 @@ Issue
 -----
 
 If the issue that you are having does not appear here please check the aramda
-issues [here](https://github.com/att-comdev/armada/issues). If the issue does
+issues `here <https://github.com/att-comdev/armada/issues>`_. If the issue does
 not exist, please create an issue.