RETURN variable¶
When a module finishes running, F5 usually wants to report back to the user with the new state of the module and anything that may be relevant to them.
The general rule of thumb is to return data that is in the same format that the user supplied to the module.
Why is this important?
Parameter consistency and validity¶
Imagine, if you will, a scenario where you go to your bank to have a $20 bill broken up into a smaller denomination of money. For example:
- A $10 bill
- A $5 bill
- And five $1 bills
When you reach the teller and hand them your money, they instead give you back:
- A duck
- A chicken
- A crow
Technically, these are all birds, but combined, they have no relevance to what you put in to the transaction. If you put money in, you expected money out; not various fowl.
The same principal applies with to the F5 Modules for Ansible. If you put in a list of dictionaries, such as the example below:
actions:
- type: forward
pool: pool-svrs
Then it would make sense that after the module completes and makes any changes it deems necessary, you should receive data back out that is in the same usable form.
Exceptions to the rule¶
Not all information that the user puts in is information that is relevant on its way back
out. For example, the state
variable usually contains information that is not typically
re-used in Ansible.
There are some instances though when the state
is “more” relevant, such as when it contains
more than just absent
and present
, such as in the bigip_virtual_server
module.
Another example would be when the module consumes otherwise sensitive information. For example,
the bigip_ssl_certificate
and bigip_ssl_key
modules consume parameters that you
probably do not want echoed back out (like keys and certs). Therefore, we suppress that in
the return value.
One more example is in situations where modules can consume a whole lot of data. For example,
the bigip_data_group
module can consume megabytes or more of data. It makes no sense to
echo all this back out to the user.
RETURN variable for the example module¶
With the above made known, here is the content of the RETURN
variable as it applies to
the module we are in the process of writing.
RETURN = r'''
actions:
description: The new list of actions applied to the rule
returned: changed
type: complex
contains:
type:
description: The action type
returned: changed
type: string
sample: forward
pool:
description: Pool for forward to
returned: changed
type: string
sample: foo-pool
sample: hash/dictionary of values
conditions:
description: The new list of conditions applied to the rule.
returned: changed
type: complex
contains:
type:
description: The condition type
returned: changed
type: string
sample: http_uri
path_begins_with_any:
description: List of strings that the URI begins with.
returned: changed
type: list
sample: [foo, bar]
sample: hash/dictionary of values
description:
description: The new description of the rule.
returned: changed
type: string
sample: My rule
'''
Conclusion¶
When the Ansible module documentation is generated, these values are output in a table.
You can see an example of the kind of table that is created here. This is the final
documentation-related blob that will be added to the module. Up next, we will cover the
import
block.