Documentation for Exceptions

Adds documentation for Drydock exceptions.

Change-Id: I99d5396a6deb46e8fb135f037292a295e855abd5
Note: Does not include unused exceptions.

docs/source/exceptions/api_error.inc

@@ -0,0 +1,35 @@
+..
+      Copyright 2017 AT&T Intellectual Property.
+      All Rights Reserved.
+
+      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.
+
+API Errors
+----------
+
+.. list-table::
+  :widths: 5 50
+  :header-rows: 1
+
+  * - Exception Name
+    - Description
+  * - ClientError
+    - .. autoexception:: drydock_provisioner.error.ClientError
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - InvalidFormat
+    - .. autoexception:: drydock_provisioner.error.InvalidFormat
+         :members:
+         :show-inheritance:
+         :undoc-members:

docs/source/exceptions/bootaction_error.inc

@@ -0,0 +1,41 @@
+..
+      Copyright 2017 AT&T Intellectual Property.
+      All Rights Reserved.
+
+      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.
+
+
+Bootaction Errors
+-----------------
+
+.. list-table::
+  :widths: 5 50
+  :header-rows: 1
+
+  * - Exception Name
+    - Description
+  * - InvalidAssetLocation
+    - .. autoexception:: drydock_provisioner.error.InvalidAssetLocation
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - PipelineFailure
+    - .. autoexception:: drydock_provisioner.error.PipelineFailure
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - UnknownPipelineSegment
+    - .. autoexception:: drydock_provisioner.error.UnknownPipelineSegment
+         :members:
+         :show-inheritance:
+         :undoc-members:

docs/source/exceptions/build_data_error.inc

@@ -0,0 +1,30 @@
+..
+      Copyright 2017 AT&T Intellectual Property.
+      All Rights Reserved.
+
+      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.
+
+
+BuildData Errors
+----------------
+.. list-table::
+  :widths: 5 50
+  :header-rows: 1
+
+  * - Exception Name
+    - Description
+  * - BuildDataError
+    - .. autoexception:: drydock_provisioner.error.BuildDataError
+         :members:
+         :show-inheritance:
+         :undoc-members:

docs/source/exceptions/client_error.inc

@@ -0,0 +1,35 @@
+..
+      Copyright 2017 AT&T Intellectual Property.
+      All Rights Reserved.
+
+      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.
+
+Client Errors
+-------------
+
+.. list-table::
+  :widths: 5 50
+  :header-rows: 1
+
+  * - Exception Name
+    - Description
+  * - ClientForbiddenError
+    - .. autoexception:: drydock_provisioner.error.ClientForbiddenError
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - ClientUnauthorizedError
+    - .. autoexception:: drydock_provisioner.error.ClientUnauthorizedError
+         :members:
+         :show-inheritance:
+         :undoc-members:

docs/source/exceptions/design_error.inc

@@ -0,0 +1,40 @@
+..
+      Copyright 2017 AT&T Intellectual Property.
+      All Rights Reserved.
+
+      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.
+
+Design Errors
+-------------
+
+.. list-table::
+  :widths: 5 50
+  :header-rows: 1
+
+  * - Exception Name
+    - Description
+  * - DesignError
+    - .. autoexception:: drydock_provisioner.error.DesignError
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - IngesterError
+    - .. autoexception:: drydock_provisioner.error.IngesterError
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - InvalidDesignReference
+    - .. autoexception:: drydock_provisioner.error.InvalidDesignReference
+         :members:
+         :show-inheritance:
+         :undoc-members:

docs/source/exceptions/driver_error.inc

@@ -0,0 +1,50 @@
+..
+      Copyright 2017 AT&T Intellectual Property.
+      All Rights Reserved.
+
+      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.
+
+Driver Errors
+-------------
+
+.. list-table::
+  :widths: 5 50
+  :header-rows: 1
+
+  * - Exception Name
+    - Description
+  * - DriverError
+    - .. autoexception:: drydock_provisioner.error.DriverError
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - InvalidSizeFormat
+    - .. autoexception:: drydock_provisioner.error.InvalidSizeFormat
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - NotEnoughStorage
+    - .. autoexception:: drydock_provisioner.error.NotEnoughStorage
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - PersistentDriverError
+    - .. autoexception:: drydock_provisioner.error.PersistentDriverError
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - TransientDriverError
+    - .. autoexception:: drydock_provisioner.error.TransientDriverError
+         :members:
+         :show-inheritance:
+         :undoc-members:

docs/source/exceptions/exceptions.rst

@@ -0,0 +1,26 @@
+..
+      Copyright 2017 AT&T Intellectual Property.
+      All Rights Reserved.
+
+      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.
+
+Drydock Exceptions
+==================
+
+.. include:: api_error.inc
+.. include:: bootaction_error.inc
+.. include:: client_error.inc
+.. include:: design_error.inc
+.. include:: driver_error.inc
+.. include:: orchestrator_error.inc
+.. include:: build_data_error.inc

docs/source/exceptions/index.rst

@@ -0,0 +1,25 @@
+..
+      Copyright 2017 AT&T Intellectual Property.
+      All Rights Reserved.
+
+      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.
+
+
+Exceptions Guide
+================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   exceptions

docs/source/exceptions/orchestrator_error.inc

@@ -0,0 +1,36 @@
+..
+      Copyright 2017 AT&T Intellectual Property.
+      All Rights Reserved.
+
+      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.
+
+
+Orchestrator Errors
+-------------------
+
+.. list-table::
+  :widths: 5 50
+  :header-rows: 1
+
+  * - Exception Name
+    - Description
+  * - MaxRetriesReached
+    - .. autoexception:: drydock_provisioner.error.MaxRetriesReached
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - OrchestratorError
+    - .. autoexception:: drydock_provisioner.error.OrchestratorError
+         :members:
+         :show-inheritance:
+         :undoc-members:

docs/source/index.rst

@@ -35,6 +35,8 @@ Drydock Configuration Guide
    configuration
    sampleconf
    policy-enforcement
+   exceptions/index
+
 
 API Documentation
 -----------------

drydock_provisioner/error.py

@@ -15,14 +15,42 @@ import json
 
 
 class DesignError(Exception):
+    """
+    **Message:** *Invalid Network model*.
+
+    **Troubleshoot:**
+
+    **Message:** *Network <network_key> not found in design state*.
+
+    **Troubleshoot:**
+
+    **Message:** *Design <design_id> not found*.
+
+    **Troubleshoot:**
+    """
     pass
 
 
 class IngesterError(DesignError):
+    """
+    **Message:** *Error parsing YAML <various>*.
+
+    **Troubleshoot:**
+    """
     pass
 
 
 class InvalidDesignReference(DesignError):
+    """
+    **Message:** *Invalid reference scheme <design_url.scheme>: no handler*.
+
+    **Troubleshoot:**
+
+    **Message:** *Cannot resolve design reference <design_ref>: unable to
+    parse as valid URI*.
+
+    **Troubleshoot:**
+    """
     pass
 
 
@@ -35,10 +63,41 @@ class TaskNotFoundError(StateError):
 
 
 class OrchestratorError(Exception):
+    """
+    **Message:** *Could find task <task_id>*.
+
+    **Troubleshoot:**
+
+    **Message:** *Unable to render effective site design.*
+
+    **Troubleshoot:**
+
+    **Message:** *Cannot specify both failures and successes*.
+
+    **Troubleshoot:**
+
+    **Message:** *Unknow filter set type*.
+
+    **Troubleshoot:**
+
+    **Message:** *Error processing node filter*.
+
+    **Troubleshoot:**
+
+    **Message:** *Orchestrator requires instantiated state manager and
+    ingester*.
+
+    **Troubleshoot:**
+    """
     pass
 
 
 class MaxRetriesReached(OrchestratorError):
+    """
+    **Message:** *Retries reached max attempts*.
+
+    **Troubleshoot:**
+    """
     pass
 
 
@@ -59,38 +118,212 @@ class BootactionError(Exception):
 
 
 class UnknownPipelineSegment(BootactionError):
+    """
+    **Message:** *Bootaction pipeline segment <various> unknown*.
+
+    **Troubleshoot:**
+    """
     pass
 
 
 class PipelineFailure(BootactionError):
+    """
+    **Message:** *Error when running bootaction pipeline segment <various>*.
+
+    **Troubleshoot:**
+    """
     pass
 
 
 class InvalidAssetLocation(BootactionError):
+    """
+    **Message:** *Unable to resolve asset reference <various>*.
+
+    **Troubleshoot:**
+    """
     pass
 
 
 class BuildDataError(Exception):
+    """
+    **Message:** *Error saving build data - data_element type <data_element>
+    could not be cast to string.
+
+    **Troubleshoot:**
+
+    **Message:** *Error selecting build data*.
+
+    **Troubleshoot:**
+    """
     pass
 
 
 class DriverError(Exception):
+    """
+    **Message:** *Invalid task <task_id>*.
+
+    **Troubleshoot:**
+
+    **Message:** *Driver <driver_desc> doesn't support task action <action>*.
+
+    **Troubleshoot:**
+
+    **Message:** *Fabric not found in MaaS for fabric_id <fabric_id>,
+    fabric_name <fabric_name>*.
+
+    **Troubeshoot:**
+
+    **Message:** *Cannot locate untagged VLAN on fabric <fabric_id>*.
+
+    **Troubleshoot:**
+
+    **Message:** *Error retrieving node/tag pairs, received HTTP
+    <resp.status_code> from MaaS*.
+
+    **Troubleshoot:**
+
+    **Message:** *Tag <res.name> already exists*.
+
+    **Troubleshoot:**
+
+    **Message:** *Error resetting network on node <resource_id>:
+    <resp.status_code>, <resp.text>*.
+
+    **Troubleshoot:**
+
+    **Message:** *"Error: cannot find storage device <root_device> to set as
+    root device*.
+
+    **Troubleshoot:**
+
+    **Message:** *Error: failed configuring node <resource_id> storage layout:
+    <various>*.
+
+    **Troubleshoot:**
+
+    **Message:** *Error commissioning node, received HTTP <resp.status_code>
+    from MaaS*.
+
+    **Troubleshoot:**
+
+    **Message:** *Error deploying node, received HTTP <resp.status_code> from
+    MaaS*.
+
+    **Troubleshoot:**
+
+    **Message:** *Error setting node metadata, received HTTP <resp.status_code>
+    from MaaS*.
+
+    **Troubleshoot:**
+
+    **Message:** *Node <node_name> not found*.
+
+    **Troubleshoot:**
+
+    **Message:** *Node <node_name> status '<node.status_name>' does not allow
+    deployment, should be 'Ready'*.
+
+    **Troubleshoot:**
+
+    **Message:** *Error acquiring node, MaaS returned <resp.status_code>*.
+
+    **Troubleshoot:**
+
+    **Message:** *Failed updating MAAS url <url> - return code
+    <resp.status_code>*.
+
+    **Troubleshoot:**
+
+    **Message:** *Node OOB type is not IPMI*.
+
+    **Troubleshoot:**
+
+    **Message:** *Node <node_name> has no IPMI address*.
+
+    **Troubleshoot:**
+
+    **Message:** *IPMI command failed*.
+
+    **Troubleshoot:**
+
+    **Message:** *Unsupported action <task_action> for driver <driver_desc>*.
+
+    **Troubleshoot:**
+
+    **Message:** *Failed updating MAAS url <url> - return code
+    <resp.status_code> <resp.text>*
+
+    **Troubleshoot:**
+
+    **Message:** *Invalid JSON for class <class_name>*.
+
+    **Troubleshoot:**
+
+    **Message:** *Error: Could not create logical volume <various>*.
+
+    **Troubleshoot:**
+
+    **Message:** *Error: Could not delete logical volume <various>*.
+
+    **Troubleshoot:**
+
+    **Message:** *Inconsistent data from MaaS*.
+
+    **Troubleshoot:**
+    """
     pass
 
 
 class TransientDriverError(DriverError):
+    """
+    **Message:** *Timeout connection to MaaS*
+
+    **Troubleshoot:** *Coming Soon*
+
+    **Message:** *Recieved 50x error from MaaS*
+
+    **Troubleshoot:** *Coming Soon*
+    """
     pass
 
 
 class PersistentDriverError(DriverError):
+    """
+    **Message:** *Recieved unexpected error from MaaS*
+
+    **Troubleshoot:** *Coming Soon*
+
+    **Message:** *Error accessing MaaS: <details>*
+
+    **Troubleshoot:** *Coming Soon*
+
+    **Message:** *MaaS API Authentication Failed*
+
+    **Troubleshoot:** *Coming Soon*
+    """
     pass
 
 
 class NotEnoughStorage(DriverError):
+    """
+    **Message:** *The calcuted size is not available.*
+
+    **Troubleshoot:** *Coming Soon*
+    """
     pass
 
 
 class InvalidSizeFormat(DriverError):
+    """
+    **Message:** *Invalid size string format: <size of string>*
+
+    **Troubleshoot:** *Coming Soon*
+
+    **Message:** *Sizes using the ">" or "%" format must specify a block device
+    or volume group context*
+
+    **Troubleshoot:** *Coming Soon*
+    """
     pass
 
 
@@ -106,20 +339,48 @@ class ApiError(Exception):
 
 
 class InvalidFormat(ApiError):
+    """
+    **Message:** *Invalid JSON in body: <path>*
+
+    **Code:** 400
+
+    **Troubleshoot:** *Coming Soon*
+    """
     def __init__(self, msg, code=400):
         super(InvalidFormat, self).__init__(msg, code=code)
 
 
 class ClientError(ApiError):
+    """
+    **Message:** *Error - recieved <status code>: <details>*
+
+    **Code:** 500
+
+    **Troubleshoot:** *Coming Soon*
+    """
     def __init__(self, msg, code=500):
         super().__init__(msg)
 
 
 class ClientUnauthorizedError(ClientError):
+    """
+    **Message:** *Unauthorized access to <url>, include valid token.*
+
+    **Code:** 401
+
+    **Troubleshoot:** *Try requesting a new token.*
+    """
     def __init__(self, msg):
         super().__init__(msg, code=401)
 
 
 class ClientForbiddenError(ClientError):
+    """
+    **Message:** *Forbidden access to <url>.*
+
+    **Code:** 403
+
+    **Troubleshoot:** *Coming Soon*
+    """
     def __init__(self, msg):
         super().__init__(msg, code=403)