This module’s goals are:
| Getting the dse.ldif parameters |
| Name | Optional | Kind | Description |
|---|---|---|---|
| ds389 | True | Dict | The instances parameters for [1] (Manage instances) |
| ds389info | True | Dict | The prefix parameters for [2] (Gather facts) |
They are the first level parameters of the ds389_server action plugin :
| Plugin Name | Optional | Kind | Description |
|---|---|---|---|
| State | True | String (Enum) |
Determine the state of the instances |
| ds389_instances | False | List of dict | The instance configuration |
| ds389_agmts | True | List of dict | Data about replication agreement targets |
| ds389option* | True | List of dict | Data used to merge/append value in parameters (Because Ansible overrides dicts and lists instead of merging them) |
| ds389_prefix | True | String | Path of ds389 install prefix |
| ansible_host | False | String | The remote host currently handled by the playbook. Used locally by the plugin to generate the ds389 parameters sent to the module from the host map |
| ansible_verbosity | False | Integer | number of v when running ansible-playbook -vvv playbook.yml. Used locally by the plugin and also sent to the module |
| ansible_check_mode | False | Boolean | When true the action plugin should not change the state but only reports what it would change. |
| verbosity | logs |
|---|---|
| 0 | None |
| 1 | module_args, plugin_args, WARNING python logs |
| 2 | |
| 3 | action plugin hosts data, INFO python logs |
| 4 | action plugin backends, DEBUG python logs |
| 5 | Inventory,”variable” (i.e names that can be used as ds389option* name) |
| State | Action |
|---|---|
| present | Update 389ds configuration without deleting resources that are not listed. |
| absent | Delete all specified instances |
| updated | Synchronize 389ds configuration. Beware: Resources that are not listed are deleted. |
| started | Ensure that all listed instances are started |
| stopped | Ensure that all listed instances are stopped |
The details of the options should be fully documented in the ansible_collections/ds389/ansible_ds/playbooks/roles/ds389_server/README.md file that is delivered with the ds389.ansible collection (The list is quite long To ensure that the document is accurate, this file will be generated dynamically from the module options table)
Each dict in the list has the following format:
| Field | Optional | Description | Action |
|---|---|---|---|
| name | True | Mostly used when the dict needs to be a target for a ds389option* merge | ignored |
| target | False | a string used to determine what are the target replicas or a list of such strings. |
targets are resolved and for each replicas a ds389.agmts dict is added containing this dict attributes (except the target) and the target backend attributes |
| * | True | Other standard 389ds agreement values. (Typically those related to the supplier side) | kept as is |
Note: it is still possible to describe agreements as children of the backend. That can be useful to target a replica that is not managed by ansible
Each dict in the list has one of the following formats:
| Field | Optional | Type | Description | Action |
|---|---|---|---|---|
| name | False | String | A space separated list used to determine the targetted dict(s) | Handled locally within the plugin |
| merge | False | Dict | Contains the dict of attribute to mege with the targetted dict(s) |
or
| Field | Optional | Type | Description | Action |
|---|---|---|---|---|
| name | False | String | A space separated list used to determine the targetted list(s) | Handled locally within the plugin |
| append | False | List | Append the list items to the targetted list(s) |
Nested dict are referred by using a dot notation: The first item is either an instance name or a agmt name The second item is the backend name The third item is either an index name or agmt (the backend children one) name In the append case, the last item is a parameter name which expect a list
and * may be used to match all items (i.e) localhost.*.myattr will refers to myattr index of all backends of localhost instance
The module result in stdout is a dict in json format. Its keys are:
List of implemented Standard ansible return keys:
| Key | Notes |
|---|---|
| ansible_facts | Result for [2] (Gather fact) |
| changed | |
| exception | only in case of failure |
| failed | only in case of failure |
| invocation | Parameters as the module received them |
| msg | Some additionnal messages like the changes that have been or should be done or an error message |
| stderr | only in error cases |
| Key | Value | Description | Origin |
|---|---|---|---|
| cooked_message | dict | Parameters once the module processed them | The module |
| original_message | dict | Parameters as the module received them | The module |
| debug | list of str | Python log output (depends on the verbosity) | The module |
| module_args | dict | Parameters sent by the plugin to the module | Both plugins |
The role of this plugin is to gather the data from inventory and generate the module parameters.
| args name | Description | Handling |
|---|---|---|
| state | The optional state | Sent to the module as ds389.state |
| Common data processing | Any ds389_* variable provided as argument override the inventory ones | Common data processing |
| task_vars name | Description | Handling |
|---|---|---|
| ansible_host | The remote host currently handled by the playbook. | Used locally by the plugin to generate the ds389 parameters sent to the module from the host map |
| ansible_verbosity | number of v when running ansible-playbook -vvv playbook.yml. | Used locally by the plugin and also sent to the module as ds389.ansible_vars.ansible_verbosity |
| ansible_version | ansible version | Not used (maybe useful later on to clear some cached data) |
| ansible_user_uid | The remote user uid | Not used (maybe useful later on to check it is 0 if there is no prefix) |
| ansible_check_mode | Tells when the action can change | Sent to the module in ds389.ansible_vars.ansible_check_mode |
| hostvars | dict of hosts dict | Common data processing is applied on every host to collect the backends data from the hosts because are needed to compute the agreements data.) |
ansible_verbosity levels:
| Verbosity | Debug data returned |
|---|---|
| 0 | None except the error messages |
| 1 | Plugin calling parameters Module calling parameters. Note: only “safe” values that do not contain data extracted from vault are logged. |
| 2 | Module “INFO” traces |
| 3 | Module “DEBUG” traces |
The following data are collected from each hosts in task_vars.hostsvars to generate a map of host –> backend list that will be used for agmts target resolution
| task_vars name | Description | Handling |
|---|---|---|
| : | 389ds instances list for current remote host | Stored in ds389.instances |
| ds389_agmts | 389ds agreements list for current remote host | Stored in ds389.agmts after the target resolution |
| ds389_prefix | 389ds install prefix for current remote host | Stored in ds389.prefix |
| ds389option* | Option modifier to append item in list or merge item in dict | Processed locally to update the matching variable for the processed host |
The processing for a given host extracted from the hostsvars list
walk the variables and check if they match the wanted variable. i
if that is the case:
store the variable in the: per name map, per entity+parentname
Detect if it is an unsafe value (that include jinja2 expression with vault_ variable)
Evaluate jinja2 expr
As the module only receives the data related the current host, validation tests about the global topology must be done at the plugin level. And while doing these tests some other consistency test are also done at the plugin level. Typically:
The role of this plugin is to call the modules to generate facts from the the hosts dse.ldif configurations files
They are the first level parameters of the ds389_server action plugin :
| Plugin Name | Optional | Kind | Description |
|---|---|---|---|
| ds389_prefix | True | String | Path of ds389 install prefix |
| ansible_verbosity | False | Integer | number of v when running ansible-playbook -vvv playbook.yml. Used locally by the plugin and also sent to the module |
| ansible_check_mode | False | Boolean | When true the action plugin should not change the state but only reports what it would change. |