There is a new idp management module placed in the plugins folder:
plugins/modules/ipaidp.py
The idp module allows to ensure presence or absence of external Identity
Providers.
Here is the documentation for the module:
README-idp.md
New idp example playbooks:
playbooks/idp/idp-present.yml
playbooks/idp/idp-absent.yml
New tests for the module:
tests/idp/test_idp.yml
tests/idp/test_idp_client_context.yml
The use of del os.environ assumes that the environment variable exists.
If the variable does not exist, this call will result in a traceback.
The solution is to use os.environ.pop(VARIABLE, None) instead.
This is the ansible-freeipa fix for https://pagure.io/freeipa/issue/9446
(Nightly test failure for replica installation with --setup-ca)
Fix ipa_command_invalid_param_choices for IPA 4.6 (RHEL-7)
- krbprincipalauthind in host_add does not have choices defined
- krbprincipalauthind in service_add does not have choices defined
api.Command[command].params[name].cli_metavar returns "STR" and
ast.literal_eval failes with a ValueError "malformed string".
There is no way to verify that the given values are valid or not in
this case. The check is done later on while applying the change
with host_add, host_mod, service_add and service_mod.
New IPAAnsibleModule.ipa_command_invalid_param_choices method to return
invalid parameter choices for an IPA command.
This is needed to verify for example if userauthtype and authind are
supporting the idp value.
Export Ansible's 'boolean' parsing function so it can be used to verify
if a string can be handled as a truthy value, allowing module parameters
to use strings instead of bools, as strings can be cleared by using
empty strings.
There is a new certificate management module placed in the plugins
folder:
plugins/modules/ipacert.py
The certificate module allows to request, revoke, release and retrieve
certificates for users, hosts and services.
Here is the documentation for the module:
README-cert.md
New example playbooks have been added:
playbooks/cert/cert-hold.yml
playbooks/cert/cert-release.yml
playbooks/cert/cert-request-host.yml
playbooks/cert/cert-request-service.yml
playbooks/cert/cert-request-user.yml
playbooks/cert/cert-retrieve.yml
playbooks/cert/cert-revoke.yml
New tests for the module can be found at:
tests/cert/test_cert_client_context.yml
tests/cert/test_cert_host.yml
tests/cert/test_cert_service.yml
tests/cert/test_cert_user.yml
The module has been co-authored by Sam Morris (@yrro) and Rafael
Guterres Jeffman (@rjeffman).
The function exit_raw_json is a replacement for AnsibleModule.exit_json
without flterting out values for no_log parameters.
Ansible added checks for pylint to forbid print and also sys.exit and
fails with ansible-bad-function. As the check is not known outside of
ansible-test, the disable line needed also W0012:
# pylint: disable=W0012,ansible-bad-function
A combination of ansible-freeipa modifications and a newer version of
IPA has brought a regression regarding different OS localization.
For properly setting environment to use "C" language, as required by
ansible-freeipa, the setting must be executed before importing the
module 'ipaserver.dcerpc', so setting environment language was moved
closer to the 'import os' statement, so that it is always set, as soon
as possible.
Note that 'import os' should always be imported before any FreeIPA
module.
This patch modifies the way that the certificate load function is
defined, depending on the dependency version, so that the resulting
identifier for the function is always set and static analysis tools,
like linters don't complain about variables being used before being
set.
The same idiom is applied to both the ipaclient role and the plugins
ansible_module_utils.
All imports that are only available after installing IPA need to be in a
try exception clause to be able to pass the fake execution test. The old
workaround "if 'ansible.executor' in sys.modules:" is not working with
this test anymore.
If the imports can not be done, all used and needed attributes are
defines with the value None.
A check has been added to IPAAnsibleModule.__init__ to make sure that it
fails if the imports have not been done successfully.
The FreeIPABaseModule class has been maked deprecated with
ansible-freeipa version 1.5.0. It is not used in the code any more
therefore it is time to finally remove it.
api_check_ipa_version was using packaging.version. IPA is using
pkg_resources.parse_version in ipaplatform.tasks.parse_ipa_version.
With this change tasks.parse_ipa_version from ipaplatform is used to
have exactly the same version comparison that also IPA has.
Additionally tasks is added to __all__.
The fallback function used to compare IPA versions was spliting the
version string into a tuple of strings, and the comparison of the tuple
would fail if comparing a field with one digit aginst a two-digit one,
for example, '8' with '10', as the string comparison would put '10'
before the '8'.
This patch forces the version fields to be converted to integers, so
a numerical comparison will be performed. If a version string field
cannot be converted to a number, than the string comparison will still
be used.
FreeIPA 4.9.10+ and 4.10 use proper mapping for boolean values, and
only searching for "TRUE" does not work anymore.
This patch fix ipadnszone plugin and IPAParamMapping class handling
of boolean values.
Python 3.11 dropped compat inspect.getargspec. As the roles and modules
need to support Python2 and Python3, the code for getargspec has been
copied from Python 3.10 and is added as a fallback as soon as getargspec
can not be imported from inspect. The copied getargspec is using
getfullargspec internally.
Fixes: #855 (Python's inspect.getargspec was removed in version 3.11)
When managing idranges, it might be needed to obtain the domain SID
from the domain name. As this method needs to use the IPA API object
and requires imorting some ipaserver modules, teh best place for this
method to be implemented is on ansible_module_utils.
This change modifies the comparison of the retrieved IPA object and the
provided arguments on ansible_freeipa_module.compare_args_ipa when the
provider argument is an empty string.
If an attribute is not available in 'ipa', its value is considered to be
a list with an empty string (['']), possibly forcing the conversion of
the 'args' attribute to a list for comparison. This allows, for example,
the usage of empty strings which should compare as equals to inexistent
attributes (None), as is done in IPA API.
So far it is possible to pass list parameters with empty strings to the
modules. The use of empty strings in list does not make a lot of sense,
though. The simple solution is to add a check to module_params_get for
empty strings in returned lists.
The option allow_empty_string can be set to True to allow an empty string
in the list with a list len of 1. The option defaults to False. It is
needed for some parameters the modules, like for example userauthtype in
the user module. It is using "" to reset to the default value.
module_params_get_lowercase has been changed to use module_params_get to
have one place to add the check.
Due to an issue in Ansible it is possible to use the empty string "" for
lists with choices, even if the empty list is not part of the choices.
Ansible issue https://github.com/ansible/ansible/issues/77108
Allows the creation of IPAAnsibleModule objects with specific
`ipa_arguments` which are defined in a dictionary of argumets in
the base class.
Every module using `delete_continue` should provide the proper behavior
and the module must be instantiated with:
ansible_module = IPAAnsibleModule(
...,
ipa_arguments=["delete_continue"]
)
The plugin documentation must be extended with
'ipamodule_arguments.delete_continue'.
Ensuring absence of members (services and targets) that do not exist may
not fail as they are not members for servicedelegationtarget and
servicedelegationrule.
servicedelegation_normalize_principals in ansible_freeipa_module has
been extended with a check_exists argument that defaults to False. state
== "present" is now given as this argument to turn on the element exists
check only if elements should be added.
This function will be used in servicedelegation target and rule modules
to normalize principals given in the tasks. These can be service and host
principals and also aliases.
Note: The use of host principals requires IPA 4.9.0 or later. fail_json
is called if the version is lower.
servicedelegation_normalize_principals contains two embedded fuctions.
One is normalize_principal_name that has been copied from
ipaserver/plugins/servicedelegation.py, the other is the generic
function _check_exists to be able to check if a host or service exists.
Some attributes retrieved by the IPA API backend don't change, and are
used more than once, in different places of the code. IPA API domain
is one of these attributes.
This patch adds a cache to the attribute, so there is only one request
for the API, improving access time to the object and alowing multiple
calls with no efficiency penalty.
These functions have been added to get the basedb from api.env for use
with DN for example.
api_get_basedn is returning api.env.basedn
IPAAnsibleModule.ipa_get_basedn is a wrapper for api_get_basedn
This patch add several deprecate warnings to FreeIPABaseModule, and
creates adapters to ease conversion of client classes to
IPAAnsibleModule.
There is no 'ipa_commands' management in IPAAnsibleModule, as 'command's
is a list of tuples containing '(command, name, args)', and should be
managed by the module itself. Commands with no arguments should use an
empty dictionary as 'args'.
The 'ipa_run' method should be replaced by:
```
exit_args = {}
ipaapi_context = self.params_get("ipaapi_context")
with self.ipa_connect(context=ipaapi_context):
self.check_ipa_params()
self.define_ipa_commands()
changed = self.execute_ipa_commands(
self.ipa_commands,
result_handler=my_custom_handler,
exit_args=exit_args
)
self.exit_json(changed=changed, **exit_args)
```
The 'process_command_result' method should be changed to a result
handler:
```
def my_result_handler(self, result, command, name, args, exit_args):
"""Process command result.""'
```
Use of 'ipa_params' should be replaced by IPAAnsibleModule.params_get.
If 'get_ipa_command_args' is used, then the mapping can be created with
class IPAParamMapping (formelly AnsibleFreeIPAParams), which also
enables the same property-like usage of 'ipa_params':
```
param_mapping = IPAParamMapping(module, mapping)
```
The goal is to have all ansible-freeipa modules using the same codebase,
reducing code duplication, and allowing better object composition, for
example, with the IPAParamMapping class.
Many module member attributes must be handled in a case insensitive
manner. To ease handling these cases, a function and a method to get
the module parameters converted to lowercase is provided.
This patch adds support for configuring IPA API connection use of
LDAP cache. It adds a new variable 'ipaapi_ldap_cache' to the base
module, and provides the variable documentation in its doc fragment.
This change adds a keyword parameter to api_connect() which can be
used to configure IPA API connection, for example, controlling the
use of LDAP cache, by passing 'ldap_cache' as an argument.
Also, IPAAnsibleModule is modified to automatically filter all
parameters of the module starting with 'ipaapi_' to be used as
arguments to configure api_connect(). The argument name will have
the same name as the module parameter with 'ipaapi_' stripped off.
Almost all modules require an algorithm ta validade if the user
provided arguments for the playbook are valid for the requested
state and/or action.
This patch provides a function that tests if any of a list of
arguments were set, and fail with a standardized message, making
all modules fail in the same way.
Add a new configuration variable, `ipaapi_context` to IPAAnsibleModule
base specs, accepting only 'server' or 'client' values.
By using this variable, an user can select the environment context in
which the module will execute, server or client. This change will allow
configuration of the server without requiring login access (e.g. `ssh`)
to the server.
The default behavior is to use a `server` context, but this behavior
can be modified by the plugin, if it sets the `context` parameter when
connecting to IPA API.
In the provided example for the class documentation, the parameters
passed to the `ipa_command` method were wrong, as a single list was
used instead of a parameter list.
The staticmethod member_error_handler is handing the default member
related failures that can occur for modules with member support.
This can simply be enabled with fail_on_member_errors=True for
execute_ipa_commands.
An exception handler is also now usable with execute_ipa_commands. In
addition to the the exception it is also getting the same user defined
arguments that the result_handler is getting.
handle_result has been renamed in result_handler and handle_result_user_args
has been renamed to handlers_user_args.
Additionally the errors list does not need to be defined in the module.
The method execute_ipa_commands is doing this internally and is also
adding error: error to handlers_user_args if the handler is having errors
in the argspec and errors is not yet set in handlers_user_args.
Tests have been added to make sure that no user args for the handler
have been set without an own result or exception handler. Also the use of
fail_on_member_errors together with a result_andler is leading to an
error.
Moved ipamodule_base_spec into IPAAnsibleModule.
This simplifies to add addtitional base vars to derived classes without
the need to dusplicae the code to extend argument_spec.
Removed execute_api_command.
This is not used anymore.
Removed get_ipamodule_base_vars.
This is not used anymore.
Removed self.ipaadmin_* and self.ccache_* from IPAAnsibleModule.__init__
These are not used and therefore can be removed.
execute_ipa_commands executes IPA API commands from the given command
list. With the handle_result and handle_result_user_args it is possible
to have a handling of the result return by the ipa commands for example
to return passwords.
Parameters
commands: list of string tuple
The list of commands in the form (name, command and args)
For commands that do not require a 'name', None needs be
used.
handle_result: function
The user function to handle results of the single commands
handle_result_user_args: dict (user args mapping)
The user args to pass to handle_result function
Example (ipauser module)
def handle_result(result, command, name, args, exit_args):
if "random" in args and command in ["user_add", "user_mod"] \
and "randompassword" in result["result"]:
exit_args.setdefault(name, {})["randompassword"] = \
result["result"]["randompassword"]
exit_args = {}
changed = module.execute_ipa_commands(commands, handle_result,
exit_args=exit_args)
if len(names) == 1:
ansible_module.exit_json(changed=changed,
user=exit_args[names[0]])
else:
ansible_module.exit_json(changed=changed, user=exit_args)
By making IPAAnsibleModule the base class of FreeIPABaseModule, instead
of AnsibleModule, some methods on FreeIPABaseModule can be removed and
suport for commom parameters in modules using the older class can use
the same commom parameters (ipaadmin_principal and ipaadmin_password)
as the other parameters. This will also allow easier deprecation of
FreeIPABaseModule, which is hard to maintain.
To be able to use IPAAnsibleModule as the base class, it was moved
within the file, to position before FreeIPABaseModule declaration.
This patch also modifies IPAAnsibleModule by:
* removing usage of `self` in methods not requiring it, turning
the methods into @statimethod;
* adding comments to all the methods in IPAAnsibleModule, which
makes it easier to understand what the individual methods do,
and what their parameters represent.
This class is an extended version of the Ansible Module that provides
IPA specific methods to simplify module generation.
Simple example:
from ansible.module_utils.ansible_freeipa_module import \
IPAAnsibleModule
def main():
ansible_module = IPAAnsibleModule(
argument_spec=dict(
name=dict(type="str", aliases=["cn"], default=None),
state=dict(type="str", default="present",
choices=["present", "absent"]),
),
)
# Get parameters
name = ansible_module.params_get("name")
state = ansible_module.params_get("state")
# Connect to IPA API
with ansible_module.ipa_connect():
# Execute command
if state == "present":
ansible_module.ipa_command(["command_add", name, {}])
else:
ansible_module.ipa_command(["command_del", name, {}])
# Done
ansible_module.exit_json(changed=True)
if __name__ == "__main__":
main()
This PR sets pylint to version 2.10.2 in all linter actions, and
fixes code in plugins so that this version new checks are either
satisfied or ignored if needed.
There are common parameters in all modules like ipaadmin_principal and
ipaadmin_password. As this list of common parameters will be extended
soon, there is a need to reduce the code and documentation duplicates.
A ModuleDocFragment is added to provide the module documentation for the
common parameters. This is used in the modules with
extends_documentation_fragment.
ansible_freeipa_module has additional ipamodule_base_spec and
get_ipamodule_base_vars. ipamodule_base_spec extends argument_spec in
the module and get_ipamodule_base_vars is used to return a dict
containing the common parameters.
