Add vnf package conf options and sample config file to docs

1. Added new config options for vnf packages.

2. This will generate a new sample config each time build
   sphinx is run. This is then used on a new docs page
   where you can either view the file in its entirety,
   or download the file.

Partial-Implements: blueprint tosca-csar-mgmt-driver

Co-Author: Bhagyashri Shewale <bhagyashri.shewale@nttdata.com>
Co-Author: Neha Alhat <neha.alhat@nttdata.com>
Change-Id: I900af00af7f939e6069411104caa714f396dc509

.gitignore

@@ -28,9 +28,11 @@ subunit.log
 .eggs/
 .stestr/
 SP1_res.yaml
+etc/tacker/tacker.conf.sample
 etc/tacker/policy.yaml.sample
 
 releasenotes/build
 etc/tacker/tacker.conf.sample
 doc/source/contributor/api
+doc/source/_static/tacker.conf.sample
 doc/source/_static/tacker.policy.yaml.sample

doc/source/admin/index.rst

@@ -70,5 +70,3 @@ of individual command can be referred by **openstack help <command-name>**.
    openstack vnf network forwarding path show      Show information of a given NFP.
    openstack nfv event show                        Show event given the event id.
    openstack nfv event list                        List events of resources.
-
-

doc/source/conf.py

@@ -23,10 +23,15 @@ extensions = [
     'sphinxcontrib.apidoc',
     'stevedore.sphinxext',
     'openstackdocstheme',
+    'oslo_config.sphinxext',
+    'oslo_config.sphinxconfiggen',
     'oslo_policy.sphinxext',
     'oslo_policy.sphinxpolicygen',
 ]
 
+config_generator_config_file = '../../etc/config-generator.conf'
+sample_config_basename = '_static/tacker'
+
 policy_generator_config_file = [
     ('../../etc/tacker-policy-generator.conf', '_static/tacker'),
 ]

doc/source/configuration/api-paste.ini.rst

@@ -0,0 +1,8 @@
+=============
+api-paste.ini
+=============
+
+The Tacker service stores its API configuration settings in the
+``api-paste.ini`` file.
+
+.. literalinclude:: /../../etc/tacker/api-paste.ini

doc/source/configuration/config.rst

@@ -0,0 +1,9 @@
+=====================
+Configuration Options
+=====================
+
+The following is an overview of all available configuration options in Tacker.
+For a sample configuration file, refer to :doc:`/configuration/sample_config`.
+
+.. show-options::
+   :config-file: etc/config-generator.conf

doc/source/configuration/index.rst

@@ -18,19 +18,22 @@
 Tacker Configuration Guide
 ==========================
 
-The Tacker service is configured in the ``/etc/tacker/tacker.conf`` file.
-These are described below.
+The static configuration for tacker lives in three main files:
+``api-paste.ini``, ``tacker.conf`` and ``policy.json``.
+These are described below. For a bigger picture view on configuring
+tacker to solve specific problems.
 
-The sample configuration can also be viewed in :download:`file form
-</_extra/tacker.conf.sample>`.
+Configuration
+-------------
 
-.. important::
+* :doc:`API Paste ini <api-paste.ini>`: A complete reference of
+  api-paste.ini available in the ``api-paste.ini`` file.
 
-   The sample configuration file is auto-generated from tacker when this
-   documentation is built. You must ensure your version of tacker matches the
-   version of this documentation.
+* :doc:`Config Reference <config>`: A complete reference of all
+  configuration options available in the ``tacker.conf`` file.
 
-.. literalinclude:: /_extra/tacker.conf.sample
+* :doc:`Sample Config File <sample_config>`: A sample config
+  file with inline documentation.
 
 Policy
 ------
@@ -50,5 +53,8 @@ permissions on REST API actions.
 .. toctree::
    :hidden:
 
+   api-paste.ini
    policy
    sample_policy
+   config
+   sample_config

doc/source/configuration/sample_config.rst

@@ -0,0 +1,18 @@
+=========================
+Sample Configuration File
+=========================
+
+The following is a sample tacker configuration for adaptation and use. For a
+detailed overview of all available configuration options, refer to
+:doc:`/configuration/config`.
+
+The sample configuration can also be viewed in :download:`file form
+</_static/tacker.conf.sample>`.
+
+.. important::
+
+   The sample configuration file is auto-generated from tacker when this
+   documentation is built. You must ensure your version of tacker matches the
+   version of this documentation.
+
+.. literalinclude:: /_static/tacker.conf.sample

etc/config-generator.conf

@@ -2,6 +2,7 @@
 output_file = etc/tacker/tacker.conf.sample
 wrap_width = 79
 namespace = tacker.common.config
+namespace = tacker.conf
 namespace = tacker.wsgi
 namespace = tacker.service
 namespace = tacker.nfvo.nfvo_plugin

setup.cfg

@@ -76,6 +76,7 @@ tacker.tacker.policy.actions =
     vdu_autoheal = tacker.vnfm.policy_actions.vdu_autoheal.vdu_autoheal:VNFActionVduAutoheal
 oslo.config.opts =
     tacker.common.config = tacker.common.config:config_opts
+    tacker.conf = tacker.conf.opts:list_opts
     tacker.wsgi = tacker.wsgi:config_opts
     tacker.service = tacker.service:config_opts
     tacker.nfvo.nfvo_plugin = tacker.nfvo.nfvo_plugin:config_opts

tacker/conf/__init__.py

@@ -0,0 +1,25 @@
+# Copyright (C) 2019 NTT DATA
+# 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.
+
+from oslo_config import cfg
+
+from tacker.conf import conductor
+from tacker.conf import vnf_package
+
+
+CONF = cfg.CONF
+
+vnf_package.register_opts(CONF)
+conductor.register_opts(CONF)

tacker/conf/conductor.py

@@ -0,0 +1,34 @@
+# Copyright (C) 2019 NTT DATA
+# 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.
+
+from oslo_config import cfg
+
+
+CONF = cfg.CONF
+
+interval_opts = [
+    cfg.IntOpt('vnf_package_delete_interval',
+               default=1800,
+               help=_('Seconds between running periodic tasks '
+                      'to cleanup residues of deleted vnf packages')),
+]
+
+
+def register_opts(conf):
+    conf.register_opts(interval_opts)
+
+
+def list_opts():
+    return {'DEFAULT': interval_opts}

tacker/conf/opts.py

@@ -0,0 +1,83 @@
+# Copyright 2015 OpenStack Foundation
+# 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.
+
+# TODO(nirajsingh): Most of the config options are scattered all through
+# out the code. In future, move all these config options in new modules
+# under conf/ folder.
+
+"""
+This is the single point of entry to generate the sample configuration
+file for tacker. It collects all the necessary info from the other modules
+in this package. It is assumed that:
+
+* every other module in this package has a 'list_opts' function which
+  return a dict where
+  * the keys are strings which are the group names
+  * the value of each key is a list of config options for that group
+* the tacker.conf package doesn't have further packages with config options
+* this module is only used in the context of sample file generation
+"""
+
+import collections
+import os
+from oslo_utils import importutils
+import pkgutil
+
+LIST_OPTS_FUNC_NAME = "list_opts"
+
+
+def _tupleize(dct):
+    """Take the dict of options and convert to the 2-tuple format."""
+    return [(key, val) for key, val in dct.items()]
+
+
+def list_opts():
+    opts = collections.defaultdict(list)
+    module_names = _list_module_names()
+    imported_modules = _import_modules(module_names)
+    _append_config_options(imported_modules, opts)
+    return _tupleize(opts)
+
+
+def _list_module_names():
+    module_names = []
+    package_path = os.path.dirname(os.path.abspath(__file__))
+    for _, modname, ispkg in pkgutil.iter_modules(path=[package_path]):
+        if modname == "opts" or ispkg:
+            continue
+        else:
+            module_names.append(modname)
+    return module_names
+
+
+def _import_modules(module_names):
+    imported_modules = []
+    for modname in module_names:
+        mod = importutils.import_module("tacker.conf." + modname)
+        if not hasattr(mod, LIST_OPTS_FUNC_NAME):
+            msg = "The module 'tacker.conf.%s' should have a '%s' "\
+                  "function which returns the config options." % \
+                  (modname, LIST_OPTS_FUNC_NAME)
+            raise Exception(msg)
+        else:
+            imported_modules.append(mod)
+    return imported_modules
+
+
+def _append_config_options(imported_modules, config_options):
+    for mod in imported_modules:
+        configs = mod.list_opts()
+        for key, val in configs.items():
+            config_options[key].extend(val)

tacker/conf/vnf_package.py

@@ -0,0 +1,74 @@
+# Copyright (C) 2019 NTT DATA
+# 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.
+
+from oslo_config import cfg
+
+
+CONF = cfg.CONF
+
+OPTS = [
+    cfg.StrOpt('vnf_package_csar_path',
+               default='/var/lib/tacker/vnfpackages/',
+               help="Path to store extracted CSAR file"),
+
+    cfg.FloatOpt('csar_file_size_cap', default=1024, min=0.000001,
+               max=9223372036,
+               help=_("""
+Maximum size of CSAR file a user can upload in GB.
+
+An CSAR file upload greater than the size mentioned here would result
+in an CSAR upload failure. This configuration option defaults to
+1024 GB (1 TiB).
+
+NOTES:
+    * This value should only be increased after careful
+      consideration and must be set less than or equal to
+      8 EiB (~9223372036).
+    * This value must be set with careful consideration of the
+      backend storage capacity. Setting this to a very low value
+      may result in a large number of image failures. And, setting
+      this to a very large value may result in faster consumption
+      of storage. Hence, this must be set according to the nature of
+      images created and storage capacity available.
+
+Possible values:
+    * Any positive number less than or equal to 9223372036854775808
+""")),
+    cfg.StrOpt('hashing_algorithm',
+               default='sha512',
+               help=_("""
+Secure hashing algorithm used for computing the 'hash' property.
+
+Possible values:
+    * sha256, sha512
+
+Related options:
+    * None
+"""))]
+
+vnf_package_group = cfg.OptGroup('vnf_package',
+    title='vnf_package options',
+    help="""
+Options under this group are used to store vnf packages in glance store.
+""")
+
+
+def register_opts(conf):
+    conf.register_group(vnf_package_group)
+    conf.register_opts(OPTS, group=vnf_package_group)
+
+
+def list_opts():
+    return {vnf_package_group: OPTS}