diff options
26 files changed, 111 insertions, 93 deletions
diff --git a/doc/source/admin/auth-model.rst b/doc/source/admin/auth-model.rst index 51dc42d71..4c7373103 100644 --- a/doc/source/admin/auth-model.rst +++ b/doc/source/admin/auth-model.rst @@ -77,7 +77,7 @@ which is consumed by *only* the trustee to obtain a such that the trustee has limited access to those roles delegated. In addition, the trustee has effective impersonation of the trustor user if it was selected when creating the trust. -For more information, see :doc:`Identity management <identity-management>`. +For more information, see `Identity Management trusts`_. Trusts authorization involves the following steps: @@ -146,3 +146,5 @@ defined, then all the trustor roles are delegated to trustee. The trustor delegated roles must be pre-configured in the OpenStack Identity service before using them in the Orchestration service. + +.. _Identity management trusts: <https://docs.openstack.org/keystone/latest/admin/identity-use-trusts.html> diff --git a/doc/source/admin/stack-domain-users.rst b/doc/source/admin/stack-domain-users.rst index c3f629c13..f5f043bc7 100644 --- a/doc/source/admin/stack-domain-users.rst +++ b/doc/source/admin/stack-domain-users.rst @@ -125,8 +125,7 @@ The following steps are run during stack creation: in the stack domain are still assigned the ``heat_stack_user`` role, so the API surface they can access is limited through the :file:`policy.json` file. - For more information, see :doc:`OpenStack Identity - documentation <identity-management>`. + For more information, see `OpenStack Identity documentation`_. #. When API requests are processed, the Orchestration service performs an internal lookup, and allows stack details for a given stack to be @@ -150,3 +149,5 @@ or:: The stack owner uses the former (via ``openstack stack resource metadata STACK RESOURCE``), and any agents in the instance use the latter. + +.. _OpenStack Identity documentation: https://docs.openstack.org/keystone/latest/ diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst index 5ccf751ad..f9ec6b9f8 100644 --- a/doc/source/api/index.rst +++ b/doc/source/api/index.rst @@ -1,3 +1,5 @@ +:orphan: + =================== Source Code Index =================== diff --git a/doc/source/developing_guides/index.rst b/doc/source/developing_guides/index.rst index 0d9817307..8b29ef4b9 100644 --- a/doc/source/developing_guides/index.rst +++ b/doc/source/developing_guides/index.rst @@ -11,17 +11,19 @@ License for the specific language governing permissions and limitations under the License. +:orphan: + Developing Guides ================= .. toctree:: - :maxdepth: 1 + :maxdepth: 1 - contributing/index - getting_started/on_devstack - developing_guides/architecture - developing_guides/pluginguide - developing_guides/schedulerhints - developing_guides/gmr - developing_guides/supportstatus - developing_guides/rally_on_gates + ../contributing/index + ../getting_started/on_devstack + architecture + pluginguide + schedulerhints + gmr + supportstatus + rally_on_gates diff --git a/doc/source/developing_guides/pluginguide.rst b/doc/source/developing_guides/pluginguide.rst index d368a4ae9..3d1c3630d 100644 --- a/doc/source/developing_guides/pluginguide.rst +++ b/doc/source/developing_guides/pluginguide.rst @@ -669,7 +669,7 @@ directories on the local file system where the engine will search for plug-ins. Simply place the file containing your resource in one of these directories and the engine will make them available next time the service starts. -See :doc:`<../configuration/index>` for more information on configuring the +See :doc:`../configuration/index` for more information on configuring the orchestration service. Testing diff --git a/doc/source/developing_guides/rally_on_gates.rst b/doc/source/developing_guides/rally_on_gates.rst index ab87235d0..41096b1be 100644 --- a/doc/source/developing_guides/rally_on_gates.rst +++ b/doc/source/developing_guides/rally_on_gates.rst @@ -33,6 +33,7 @@ https://github.com/openstack/heat/blob/master/rally-scenarios/heat-fakevirt.yaml Obviously performance analysis make sense, when it can be compared with some another performance data. So two different approaches can be used for it: + - Comparison of one part of code with some custom changes (see :ref:`check_performance_or_detect_regression`) - Comparison of two different code parts @@ -116,6 +117,7 @@ that caching works correct. Also this approach may be used for detecting regressions. In this case workflow may be presented as follow list of steps: + - add to task list (``heat-fakevirt.yaml``) existing or new tasks. - wait a result of this execution. - upload patchset with changes (new feature) and launch the same test again. diff --git a/doc/source/ext/resources.py b/doc/source/ext/resources.py index 68a85c54a..c4e0725ce 100644 --- a/doc/source/ext/resources.py +++ b/doc/source/ext/resources.py @@ -391,6 +391,9 @@ def _filter_resources(prefix=None, path=None, statuses=None): def _load_all_resources(): + from oslo_log import log as logging + logging.getLogger('heat.engine.environment').logger.setLevel(logging.ERROR) + manager = plugin_manager.PluginManager('heat.engine.resources') resource_mapping = plugin_manager.PluginMapping('resource') res_plugin_mappings = resource_mapping.load_all(manager) diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst index 254201013..fdc07fcdd 100644 --- a/doc/source/getting_started/index.rst +++ b/doc/source/getting_started/index.rst @@ -11,6 +11,8 @@ License for the specific language governing permissions and limitations under the License. +:orphan: + Getting Started Guides ====================== diff --git a/doc/source/operating_guides/upgrades_guide.rst b/doc/source/operating_guides/upgrades_guide.rst index 5c04d0846..9d13cad99 100644 --- a/doc/source/operating_guides/upgrades_guide.rst +++ b/doc/source/operating_guides/upgrades_guide.rst @@ -37,7 +37,7 @@ Plan to upgrade Cold Upgrades ============= -Heat already supports "cold-upgrades" [1]_, where the heat services have to be +Heat already supports "`cold-upgrades`_", where the heat services have to be down during the upgrade. For time-consuming upgrades, it may be unacceptable for the services to be unavailable for a long period of time. This type of upgrade is quite simple, follow the bellow steps: @@ -66,7 +66,7 @@ A rolling upgrade would provide a better experience for the users and operators of the cloud. A rolling upgrade would allow individual heat-api and heat-engine services to be upgraded one at a time, with the rest of the services still available. This upgrade would have minimal downtime. Please -check specs about rolling upgrades [2]_. +check `spec about rolling upgrades`_. Prerequisites ------------- @@ -108,8 +108,8 @@ These following steps are the process to upgrade Heat with minimal downtime: for all upgrade services. 5. Stop heat-engine gracefully, Heat has supported graceful shutdown features - [2]_. Then start new heat-engine with new code (and corresponding - configuration). + (see the `spec about rolling upgrades`_). Then start new heat-engine with + new code (and corresponding configuration). .. note:: @@ -143,16 +143,16 @@ These following steps are the process to upgrade Heat with minimal downtime: unprocessed and any IN_PROGRESS stacks would get stuck without any forward progress. The operator must be careful when shutting down the last engine, make sure queues have no unprocessed messages before - doing it. The operator can check the queues directly with RabbitMQ's - management plugin [3]. + doing it. The operator can check the queues directly with `RabbitMQ`_'s + management plugin. 8. Once all services are upgraded, double check the DB and services References ========== -.. [1] https://governance.openstack.org/tc/reference/tags/assert_supports-upgrade.html +.. _cold-upgrades: https://governance.openstack.org/tc/reference/tags/assert_supports-upgrade.html -.. [2] https://review.openstack.org/#/c/407989/ +.. _spec about rolling upgrades: https://review.openstack.org/#/c/407989/ -.. [3] http://www.rabbitmq.com/management.html +.. _RabbitMQ: http://www.rabbitmq.com/management.html diff --git a/doc/source/template_guide/environment.rst b/doc/source/template_guide/environment.rst index b7faed80d..b7a3060a7 100644 --- a/doc/source/template_guide/environment.rst +++ b/doc/source/template_guide/environment.rst @@ -52,16 +52,14 @@ It also can contain some other sections: Merge strategies for merging parameters and parameter defaults from the environment file. -Use the :option:`-e` option of the :command:`openstack stack create` command to -create a stack using the environment defined in such a file. +Use the `-e` option of the :command:`openstack stack create` command to create +a stack using the environment defined in such a file. You can also provide environment parameters as a list of key/value pairs using -the :option:`--parameter` option of the :command:`openstack stack create` -command. +the `--parameter` option of the :command:`openstack stack create` command. In the following example the environment is read from the :file:`my_env.yaml` -file and an extra parameter is provided using the :option:`--parameter` -option:: +file and an extra parameter is provided using the `--parameter` option:: $ openstack stack create my_stack -e my_env.yaml --parameter "param1=val1;param2=val2" -t my_tmpl.yaml diff --git a/heat/common/environment_util.py b/heat/common/environment_util.py index c8e769d99..f060ca019 100644 --- a/heat/common/environment_util.py +++ b/heat/common/environment_util.py @@ -152,7 +152,7 @@ def merge_environments(environment_files, files, :param files: mapping of stack filenames to contents :type files: dict :param params: parameters describing the stack - :type dict: + :type params: dict :param param_schemata: parameter schema dict :type param_schemata: dict """ diff --git a/heat/engine/environment.py b/heat/engine/environment.py index 74bfe7f11..1efb9f374 100644 --- a/heat/engine/environment.py +++ b/heat/engine/environment.py @@ -382,7 +382,7 @@ class ResourceRegistry(object): For a given resource we get the set of restricted actions. - Actions are set in this format via `resources`: + Actions are set in this format via `resources`:: { "restricted_actions": [update, replace] @@ -410,7 +410,7 @@ class ResourceRegistry(object): For a given resource and a hook type, we check to see if the passed group of resources has the right hook associated with the name. - Hooks are set in this format via `resources`: + Hooks are set in this format via `resources`:: { "res_name": { diff --git a/heat/engine/function.py b/heat/engine/function.py index 234a0cb6c..9dfc8d3d5 100644 --- a/heat/engine/function.py +++ b/heat/engine/function.py @@ -331,7 +331,7 @@ def dep_attrs(snippet, resource_name): appropriate. :returns: an iterator over the attributes of the specified resource that - are referenced in the template snippet. + are referenced in the template snippet. """ if isinstance(snippet, Function): @@ -354,7 +354,7 @@ def all_dep_attrs(snippet): appropriate. :returns: an iterator over the resource name, attribute name tuples of all - attributes that are referenced in the template snippet. + attributes that are referenced in the template snippet. """ if isinstance(snippet, Function): diff --git a/heat/engine/resource.py b/heat/engine/resource.py index 83bec5dc5..54e022721 100644 --- a/heat/engine/resource.py +++ b/heat/engine/resource.py @@ -1380,7 +1380,7 @@ class Resource(status.ResourceStatus): return False def needs_replace_failed(self): - """Needs replace if resource is in *_FAILED.""" + """Needs replace if resource is in ``*_FAILED``.""" return True def _needs_update(self, after, before, after_props, before_props, diff --git a/heat/engine/resources/aws/cfn/wait_condition_handle.py b/heat/engine/resources/aws/cfn/wait_condition_handle.py index 32bd5e8d1..92ff0addb 100644 --- a/heat/engine/resources/aws/cfn/wait_condition_handle.py +++ b/heat/engine/resources/aws/cfn/wait_condition_handle.py @@ -50,13 +50,14 @@ class WaitConditionHandle(wc_base.BaseWaitConditionHandle): def handle_signal(self, details=None): """Validate and update the resource metadata. - metadata must use the following format: - { - "Status" : "Status (must be SUCCESS or FAILURE)", - "UniqueId" : "Some ID, should be unique for Count>1", - "Data" : "Arbitrary Data", - "Reason" : "Reason String" - } + metadata must use the following format:: + + { + "Status" : "Status (must be SUCCESS or FAILURE)", + "UniqueId" : "Some ID, should be unique for Count>1", + "Data" : "Arbitrary Data", + "Reason" : "Reason String" + } """ if details is None: return diff --git a/heat/engine/resources/openstack/heat/software_deployment.py b/heat/engine/resources/openstack/heat/software_deployment.py index ba428eb95..99cd8794e 100644 --- a/heat/engine/resources/openstack/heat/software_deployment.py +++ b/heat/engine/resources/openstack/heat/software_deployment.py @@ -51,7 +51,7 @@ class SoftwareDeployment(signal_responder.SignalResponder): Whenever this resource goes to an IN_PROGRESS state, it creates an ephemeral config that includes the inputs values plus a number of extra - inputs which have names prefixed with deploy_. The extra inputs relate + inputs which have names prefixed with ``deploy_``. The extra inputs relate to the current state of the stack, along with the information and credentials required to signal back the deployment results. diff --git a/heat/engine/resources/openstack/heat/wait_condition_handle.py b/heat/engine/resources/openstack/heat/wait_condition_handle.py index bf7cac8ee..48205ca2e 100644 --- a/heat/engine/resources/openstack/heat/wait_condition_handle.py +++ b/heat/engine/resources/openstack/heat/wait_condition_handle.py @@ -195,12 +195,14 @@ class HeatWaitConditionHandle(wc_base.BaseWaitConditionHandle): """Validate and update the resource metadata. Metadata is not mandatory, but if passed it must use the following - format: - { - "status" : "Status (must be SUCCESS or FAILURE)", - "data" : "Arbitrary data", - "reason" : "Reason string" - } + format:: + + { + "status" : "Status (must be SUCCESS or FAILURE)", + "data" : "Arbitrary data", + "reason" : "Reason string" + } + Optionally "id" may also be specified, but if missing the index of the signal received will be used. """ diff --git a/heat/engine/resources/openstack/keystone/role_assignments.py b/heat/engine/resources/openstack/keystone/role_assignments.py index b47a1f010..d2717c99a 100644 --- a/heat/engine/resources/openstack/keystone/role_assignments.py +++ b/heat/engine/resources/openstack/keystone/role_assignments.py @@ -22,30 +22,32 @@ from heat.engine import support class KeystoneRoleAssignmentMixin(object): """Implements role assignments between user/groups and project/domain. - heat_template_version: 2013-05-23 - - parameters: - ... Group or User parameters - group_role: - type: string - description: role - group_role_domain: - type: string - description: group role domain - group_role_project: - type: string - description: group role project - - resources: - admin_group: - type: OS::Keystone::Group OR OS::Keystone::User - properties: - ... Group or User properties - roles: - - role: {get_param: group_role} - domain: {get_param: group_role_domain} - - role: {get_param: group_role} - project: {get_param: group_role_project} + For example:: + + heat_template_version: 2013-05-23 + + parameters: + ... Group or User parameters + group_role: + type: string + description: role + group_role_domain: + type: string + description: group role domain + group_role_project: + type: string + description: group role project + + resources: + admin_group: + type: OS::Keystone::Group OR OS::Keystone::User + properties: + ... Group or User properties + roles: + - role: {get_param: group_role} + domain: {get_param: group_role_domain} + - role: {get_param: group_role} + project: {get_param: group_role_project} """ PROPERTIES = ( diff --git a/heat/engine/resources/openstack/neutron/quota.py b/heat/engine/resources/openstack/neutron/quota.py index b60ce7ae4..0c2c1d45d 100644 --- a/heat/engine/resources/openstack/neutron/quota.py +++ b/heat/engine/resources/openstack/neutron/quota.py @@ -25,6 +25,7 @@ class NeutronQuota(neutron.NeutronResource): Neutron Quota is used to manage operational limits for projects. Currently, this resource can manage Neutron's quotas for: + - subnet - network - floatingip diff --git a/heat/engine/resources/openstack/nova/quota.py b/heat/engine/resources/openstack/nova/quota.py index e04f3af89..269fcdaa7 100644 --- a/heat/engine/resources/openstack/nova/quota.py +++ b/heat/engine/resources/openstack/nova/quota.py @@ -25,6 +25,7 @@ class NovaQuota(resource.Resource): Nova Quota is used to manage operational limits for projects. Currently, this resource can manage Nova's quotas for: + - cores - fixed_ips - floating_ips diff --git a/heat/engine/service.py b/heat/engine/service.py index 44bc61e33..5156ed165 100644 --- a/heat/engine/service.py +++ b/heat/engine/service.py @@ -1185,11 +1185,11 @@ class EngineService(service.ServiceBase): :param params: Stack Input Params :param files: Files referenced from the template :param environment_files: optional ordered list of environment file - names included in the files dict + names included in the files dict :type environment_files: list or None :param show_nested: if True, any nested templates will be checked :param ignorable_errors: List of error_code to be ignored as part of - validation + validation """ LOG.info('validate_template') if template is None: diff --git a/heat/engine/stack.py b/heat/engine/stack.py index a909893d9..a08d1e04c 100644 --- a/heat/engine/stack.py +++ b/heat/engine/stack.py @@ -616,6 +616,7 @@ class Stack(collections.Mapping): error if this option is lost. Note: + - This doesn't return the args(name, template) but only the kwargs. - We often want to start 'fresh' so don't want to maintain the old status, action and status_reason. @@ -1127,13 +1128,14 @@ class Stack(collections.Mapping): :param action: action that should be executed with stack resources :param reverse: define if action on the resources need to be executed - in reverse order (resources - first and then res dependencies ) + in reverse dependency order :param post_func: function that need to be executed after - action complete on the stack + action complete on the stack :param aggregate_exceptions: define if exceptions should be aggregated :param pre_completion_func: function that need to be executed right - before action completion. Uses stack ,action, status and reason as - input parameters + before action completion; uses stack, + action, status and reason as input + parameters """ try: lifecycle_plugin_utils.do_pre_ops(self.context, self, @@ -2082,12 +2084,12 @@ class Stack(collections.Mapping): 1. Delete the resources from DB. 2. If the stack failed, update the current_traversal to empty string - so that the resource workers bail out. + so that the resource workers bail out. 3. Delete previous raw template if stack completes successfully. 4. Deletes all sync points. They are no longer needed after stack has completed/failed. 5. Delete the stack if the action is DELETE. - """ + """ resource_objects.Resource.purge_deleted(self.context, self.id) exp_trvsl = self.current_traversal diff --git a/heat/engine/template.py b/heat/engine/template.py index bcc851b7b..5f7065622 100644 --- a/heat/engine/template.py +++ b/heat/engine/template.py @@ -337,9 +337,9 @@ class Template(collections.Mapping): not provided, a new empty HOT template of version "2015-04-30" is returned. - :param version: A tuple containing version header of the - template: version key and value. E.g. ("heat_template_version", - "2015-04-30") + :param version: A tuple containing version header of the template + version key and value, + e.g. ``('heat_template_version', '2015-04-30')`` :returns: A new empty template. """ if from_template: diff --git a/heat/rpc/client.py b/heat/rpc/client.py index 2a6cc23c8..5e833f93e 100644 --- a/heat/rpc/client.py +++ b/heat/rpc/client.py @@ -217,7 +217,7 @@ class EngineClient(object): :param ctxt: RPC context. :param stack_identity: Name of the stack you want to show, or None to - show all + show all :param resolve_outputs: If True, stack outputs will be resolved """ return self.call(ctxt, self.make_msg('show_stack', @@ -381,10 +381,10 @@ class EngineClient(object): :param params: Stack Input Params/Environment :param files: files referenced from the environment/template. :param environment_files: ordered list of environment file names - included in the files dict + included in the files dict :param show_nested: if True nested templates will be validated :param ignorable_errors: List of error_code to be ignored as part of - validation + validation """ return self.call(ctxt, self.make_msg( 'validate_template', @@ -498,11 +498,11 @@ class EngineClient(object): def list_template_functions(self, ctxt, template_version, with_condition=False): - """Get a list of available functions in a given template. + """Get a list of available functions in a given template type. :param ctxt: RPC context - :param template_name : name of the template which function list you - want to get + :param template_version: template format/version tuple for which you + want to get the list of functions. :param with_condition: return includes condition functions. """ return self.call(ctxt, @@ -206,6 +206,3 @@ input_file = heat/locale/heat.pot keywords = _ gettext ngettext l_ lazy_gettext mapping_file = babel.cfg output_file = heat/locale/heat.pot - -[build_sphinx] -warning-is-error = False @@ -68,7 +68,7 @@ basepython = python3 deps = -r{toxinidir}/doc/requirements.txt commands = rm -rf doc/build - sphinx-build -b html doc/source doc/build/html + sphinx-build -W -b html doc/source doc/build/html [testenv:api-ref] basepython = python3 |