diff --git a/doc/source/index.rst b/doc/source/index.rst index 0c2ada7..1e2e312 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -15,6 +15,139 @@ Renders template files providing a create/update override interface - The module is an extension of the **copy** module and all of attributes that can be set there are available to be set here. +Examples +-------- + +Example for .conf +^^^^^^^^^^^^^^^^^ +The `config_template` plugin has a variety of tools available. A .conf file +may include options that are not normally supported in an INI file, but are +used in OpenStack, like ListOpt and MultiStrOpt. + +Even though we are generating a .conf file, we specify the `config_type`` of +`ini`` when using config_template. + +Playbook: + +.. code-block :: yaml + + - hosts: localhost + connection: local + gather_facts: no + tasks: + - config_template: + content: | + [foo] + bar = baz + + [section1] + option1 = value1 + dest: "test_dst.conf" + config_type: "ini" + config_overrides: + hello: + cruel: world + section1: + option1: value2 + orderedListSection: + listOpt: + - listItem1 + - listItem2 + multiStrOpSection: + multiStrOpOption: + ? multiStrOp1 + ? multiStrOp2 + +Resulting file on the remote host: + +.. code-block :: ini + + [foo] + bar = baz + + [section1] + option1 = value2 + + [hello] + cruel = world + + [orderedListSection] + listOpt = listItem1,listItem2 + + [multiStrOpSection] + multiStrOpOption = multiStrOp1 + multiStrOpOption = multiStrOp2 + +A practical example would be for something like OpenStack's nova.conf where the input of: + +.. code-block :: yaml + +nova_conf_override: + filter_scheduler: + enabled_filters: + - ComputeFilter + - ServerGroupAntiAffinityFilter + - ServerGroupAffinityFilter + - NUMATopologyFilter + pci: + ? passthrough_whitelist: '{"address":"*:0a:00.*", "physical_network":"physnet1"}' + ? passthrough_whitelist: '{"address": {"domain": ".*", "bus": "02", "slot": "01", "function": "[0-2]"}, "physical_network":"net1"}' + ? passthrough_whitelist: '{"vendor_id":"1137","product_id":"0071"}' + +Would produce: + +.. code-block :: ini + + [filter_scheduler] + enabled_filters = ComputeFilter,ServerGroupAntiAffinityFilter,ServerGroupAffinityFilter,NUMATopologyFilter + + [pci] + passthrough_whitelist = '{"address":"*:0a:00.*", "physical_network":"physnet1"}' + passthrough_whitelist = '{"address": {"domain": ".*", "bus": "02", "slot": "01", "function": "[0-2]"}, "physical_network":"net1"}' + passthrough_whitelist = '{"vendor_id":"1137","product_id":"0071"}' + +Example for .ini with remote_src +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The `remote_src: true` argument instructs `config_template` to use a file that +is already on the remote host as the source content. + +Input file on the remote host: + +.. code-block :: ini + + [foo] + # comment + bar = baz + + [hello] + +Playbook: + +.. code-block :: yaml + + - hosts: remote_host + gather_facts: no + tasks: + - config_template: + remote_src: true + src: "/etc/test_src.ini" + dest: "/etc/test_dst.ini" + config_type: "ini" + config_overrides: + hello: + cruel: world + +Resulting file on the remote host: + +.. code-block :: ini + + [foo] + # comment + bar = baz + + [hello] + cruel = world + Loading ------- @@ -38,11 +171,3 @@ you in a given project. To do this add the following lines to your .. literalinclude:: ../../examples/ansible-role-requirements.yml :language: yaml - -Examples --------- - -.. literalinclude:: ../../library/config_template - :language: yaml - :start-after: EXAMPLES = """ - :end-before: """