ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-05-03 07:41:30 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 6
community.general/lib/ansible/modules/cloud/openstack
History
Dag Wieers cd9471ef17 Introduce new 'required_by' argument_spec option (#28662) 
* Introduce new "required_by' argument_spec option

This PR introduces a new **required_by** argument_spec option which allows you to say *"if parameter A is set, parameter B and C are required as well"*.

- The difference with **required_if** is that it can only add dependencies if a parameter is set to a specific value, not when it is just defined.
- The difference with **required_together** is that it has a commutative property, so: *"Parameter A and B are required together, if one of them has been defined"*.

As an example, we need this for the complex options that the xml module provides. One of the issues we often see is that users are not using the correct combination of options, and then are surprised that the module does not perform the requested action(s).

This would be solved by adding the correct dependencies, and mutual exclusives. For us this is important to get this shipped together with the new xml module in Ansible v2.4. (This is related to bugfix https://github.com/ansible/ansible/pull/28657)

```python
    module = AnsibleModule(
        argument_spec=dict(
            path=dict(type='path', aliases=['dest', 'file']),
            xmlstring=dict(type='str'),
            xpath=dict(type='str'),
            namespaces=dict(type='dict', default={}),
            state=dict(type='str', default='present', choices=['absent',
'present'], aliases=['ensure']),
            value=dict(type='raw'),
            attribute=dict(type='raw'),
            add_children=dict(type='list'),
            set_children=dict(type='list'),
            count=dict(type='bool', default=False),
            print_match=dict(type='bool', default=False),
            pretty_print=dict(type='bool', default=False),
            content=dict(type='str', choices=['attribute', 'text']),
            input_type=dict(type='str', default='yaml', choices=['xml',
'yaml']),
            backup=dict(type='bool', default=False),
        ),
        supports_check_mode=True,
        required_by=dict(
            add_children=['xpath'],
            attribute=['value', 'xpath'],
            content=['xpath'],
            set_children=['xpath'],
            value=['xpath'],
        ),
        required_if=[
            ['count', True, ['xpath']],
            ['print_match', True, ['xpath']],
        ],
        required_one_of=[
            ['path', 'xmlstring'],
            ['add_children', 'content', 'count', 'pretty_print', 'print_match', 'set_children', 'value'],
        ],
        mutually_exclusive=[
            ['add_children', 'content', 'count', 'print_match','set_children', 'value'],
            ['path', 'xmlstring'],
        ],
    )
```

* Rebase and fix conflict

* Add modules that use required_by functionality

* Update required_by schema

* Fix rebase issue
2019-02-15 10:57:45 +10:00
..
__init__.py added __init__.py to new cloud subcategories so builds work again 2016-12-08 11:22:25 -05:00
_os_server_actions.py Remove deprecated os_server_actions alias (#47208) 2018-10-18 16:44:44 +10:00
os_auth.py Added Return Values (#51069) 2019-01-23 23:55:07 -05:00
os_client_config.py Add boilerplate and remove wildcard imports for openstack modules (#31461) 2017-10-09 09:56:26 -07:00
os_coe_cluster.py Add OpenStack Magnum cluster module (#44686) 2019-02-12 14:52:11 +00:00
os_coe_cluster_template.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_flavor_facts.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_floating_ip.py Fix dictionary access in os_floating_ip module (#51444) 2019-02-06 11:51:30 -05:00
os_group.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_image.py Update os_image.py (#47222) 2018-11-07 06:18:57 -05:00
os_image_facts.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_ironic.py Fix incorrect use of is for comparisons. 2019-02-12 16:33:13 -08:00
os_ironic_inspect.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_ironic_node.py Fix incorrect use of is for comparisons. 2019-02-12 16:33:13 -08:00
os_keypair.py Close all open filehandle (#50544) 2019-01-11 10:14:08 -05:00
os_keystone_domain.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_keystone_domain_facts.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_keystone_endpoint.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_keystone_role.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_keystone_service.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_listener.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_loadbalancer.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_member.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_network.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_networks_facts.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_nova_flavor.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_nova_host_aggregate.py Bulk module author 2 (#48955) 2018-11-21 10:32:42 +00:00
os_object.py retire shade in favor of openstacksdk for openstack modules (#40532) 2018-05-25 18:40:39 -07:00
os_pool.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_port.py Add port_type argument to os_port module (#47415) 2019-01-24 09:48:08 +00:00
os_port_facts.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_project.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_project_access.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_project_facts.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_quota.py Update os_quota.py fixed typo (#50981) 2019-01-21 16:09:33 +05:30
os_recordset.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_router.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_security_group.py Support project parameter for os_security_group module (#34472) 2018-08-22 13:52:25 -04:00
os_security_group_rule.py os_security_group_rule proper module exit (#50076) 2018-12-20 11:49:52 +00:00
os_server.py add example into os_server for server group (#51375) 2019-01-29 13:42:29 -06:00
os_server_action.py Remove deprecated os_server_actions alias (#47208) 2018-10-18 16:44:44 +10:00
os_server_facts.py Bulk module author 2 (#48955) 2018-11-21 10:32:42 +00:00
os_server_group.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_server_metadata.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_server_volume.py Fix missing exceptions (#45775) 2018-10-30 07:50:46 -04:00
os_stack.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_subnet.py Introduce new 'required_by' argument_spec option (#28662) 2019-02-15 10:57:45 +10:00
os_subnets_facts.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_user.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_user_facts.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
os_user_group.py Bump python support version for openstack modules (#40750) 2018-05-29 08:51:58 -04:00
os_user_role.py os_user_role: Include domain parameter in user lookup (#42913) 2018-10-19 12:16:19 -04:00
os_volume.py openstack: document RETURNS for os_volume (#49559) 2018-12-10 11:29:34 -06:00
os_volume_snapshot.py Fix missing exceptions (#45775) 2018-10-30 07:50:46 -04:00
os_zone.py Convert to reduced list of known types (#50010) 2018-12-19 07:25:30 +10:00
README.md openstack: drop some reference to shade (#47359) 2018-10-30 15:29:11 -05:00

README.md

OpenStack Ansible Modules

These are a set of modules for interacting with OpenStack as either an admin or an end user. If the module does not begin with os_, it's either deprecated or soon to be. This document serves as developer coding guidelines for modules intended to be here.

Naming

  • All modules should start with os_
  • If the module is one that a cloud consumer would expect to use, it should be named after the logical resource it manages. Thus, os_server not os_nova. The reasoning for this is that there are more than one resource that are managed by more than one service and which one manages it is a deployment detail. A good example of this are floating IPs, which can come from either Nova or Neutron, but which one they come from is immaterial to an end user.
  • If the module is one that a cloud admin would expect to use, it should be be named with the service and the resource, such as os_keystone_domain.
  • If the module is one that a cloud admin and a cloud consumer could both use, the cloud consumer rules apply.

Interface

  • If the resource being managed has an id, it should be returned.
  • If the resource being managed has an associated object more complex than an id, it should also be returned.

Interoperability

  • It should be assumed that the cloud consumer does not know a bazillion details about the deployment choices their cloud provider made, and a best effort should be made to present one sane interface to the ansible user regardless of deployer insanity.
  • All modules should work appropriately against all existing known public OpenStack clouds.
  • It should be assumed that a user may have more than one cloud account that they wish to combine as part of a single ansible managed infrastructure.

Libraries

  • All modules should use openstack_full_argument_spec to pick up the standard input such as auth and ssl support.
  • All modules should extends_documentation_fragment: openstack to go along with openstack_full_argument_spec.
  • All complex cloud interaction or interoperability code should be housed in the openstacksdk library.
  • All OpenStack API interactions should happen via the openstacksdk and not via OpenStack Client libraries. The OpenStack Client libraries do no have end users as a primary audience, they are for intra-server communication.

Testing