`foreman_helper` module

class foreman_helper.ForemanAnsibleModule(**kwargs)

Baseclass for all foreman related Ansible modules. It handles connection parameters and adds the concept of the foreman_spec. This adds automatic entities resolution based on provided attributes/ sub entities options.

It adds the following options to foreman_spec ‘entity’ and ‘entity_list’ types:

search_by (str): Field used to search the sub entity. Defaults to ‘name’ unless parent was set, in which case it defaults to title.
search_operator (str): Operator used to search the sub entity. Defaults to ‘=’. For fuzzy search use ‘~’.
resource_type (str): Resource type used to build API resource PATH. Defaults to pluralized entity key.
resolve (boolean): Defaults to ‘True’. If set to false, the sub entity will not be resolved automatically
ensure (boolean): Defaults to ‘True’. If set to false, it will be removed before sending data to the foreman server.

_copy_entity(resource, desired_entity, current_entity, params)

Copy a given entity

Parameters

resource (str) – Plural name of the api resource to manipulate
desired_entity (dict) – Desired properties of the entity
current_entity (dict) – Current properties of the entity
params (dict, optional) – Lookup parameters (i.e. parent_id for nested entities)

Returns

The new current state of the entity

Return type

dict

_create_entity(resource, desired_entity, params, foreman_spec)

Create entity with given properties

Parameters

resource (str) – Plural name of the api resource to manipulate
desired_entity (dict) – Desired properties of the entity
params (dict, optional) – Lookup parameters (i.e. parent_id for nested entities)
foreman_spec (dict) – Description of the entity structure

Returns

The new current state of the entity

Return type

dict

_delete_entity(resource, current_entity, params)

Delete a given entity

Parameters

resource (str) – Plural name of the api resource to manipulate
current_entity (dict) – Current properties of the entity
params (dict, optional) – Lookup parameters (i.e. parent_id for nested entities)

Returns

The new current state of the entity

Return type

Union[dict,None]

_patch_content_uploads_update_api(): This is a workaround for the broken content_uploads update apidoc in Katello. See https://projects.theforeman.org/issues/27590

_patch_cv_filter_rule_api(): This is a workaround for missing params of CV Filter Rule update controller in Katello. See https://projects.theforeman.org/issues/30908

_patch_location_api(): This is a workaround for the broken taxonomies apidoc in foreman. see https://projects.theforeman.org/issues/10359

_patch_organization_update_api(): This is a workaround for the broken organization update apidoc in Katello. See https://projects.theforeman.org/issues/27538

_patch_subnet_externalipam_group_api(): This is a workaround for the broken subnet apidoc for External IPAM. See https://projects.theforeman.org/issues/30890

_patch_subnet_rex_api(): This is a workaround for the broken subnet apidoc in foreman remote execution. See https://projects.theforeman.org/issues/19086 and https://projects.theforeman.org/issues/30651

_patch_subscription_index_api(): This is a workaround for the broken subscriptions apidoc in Katello. See https://projects.theforeman.org/issues/27575

_patch_sync_plan_api(): This is a workaround for the broken sync_plan apidoc in Katello. See https://projects.theforeman.org/issues/27532

_patch_templates_resource_name(): Need to support both singular and plural form. Not checking for the templates plugin here, as the check relies on the new name. The resource was made plural per https://projects.theforeman.org/issues/28750

_revert_entity(resource, current_entity, params)

Revert a given entity

Parameters

resource (str) – Plural name of the api resource to manipulate
current_entity (dict) – Current properties of the entity
params (dict, optional) – Lookup parameters (i.e. parent_id for nested entities)

Returns

The new current state of the entity

Return type

dict

_update_entity(resource, desired_entity, current_entity, params, foreman_spec)

Update a given entity with given properties if any diverge

Parameters

resource (str) – Plural name of the api resource to manipulate
desired_entity (dict) – Desired properties of the entity
current_entity (dict) – Current properties of the entity
params (dict, optional) – Lookup parameters (i.e. parent_id for nested entities)
foreman_spec (dict) – Description of the entity structure

Returns

The new current state of the entity

Return type

dict

_validate_supported_payload(resource, action, payload)

Check whether the payload only contains supported keys. Emits a warning for keys that are not part of the apidoc.

Parameters

resource (str) – Plural name of the api resource to check
action (str) – Name of the action to check payload against
payload (dict) – API paylod to be checked

Returns

The payload as it can be submitted to the API

Return type

dict

api_connection()

Execute a given code block after connecting to the API.

When the block has finished, call exit_json() to report that the module has finished to Ansible.

apply_apidoc_patches(): Apply patches to the local apidoc representation. When adding another patch, consider that the endpoint in question may depend on a plugin to be available. If possible, make the patch only execute on specific server/plugin versions.

connect()

Connect to the Foreman API.

This will create a new apypie.Api instance using the provided server information, check that the API is actually reachable (by calling status()), apply any required patches to the apidoc and ensure the server has all the plugins installed that are required by the module.

ensure_entity(resource, desired_entity, current_entity, params=None, state=None, foreman_spec=None)

Ensure that a given entity has a certain state

Parameters

resource (str) – Plural name of the api resource to manipulate
desired_entity (dict) – Desired properties of the entity
current_entity (Union[dict,None]) – Current properties of the entity or None if nonexistent
params (dict, optional) – Lookup parameters (i.e. parent_id for nested entities)
state (str, optional) – Desired state of the entity (optionally taken from the module)
foreman_spec (dict, optional) – Description of the entity structure (optionally taken from module)

Returns

The new current state of the entity

Return type

Union[dict,None]

exit_json(changed=False, **kwargs): return from the module, without error

list_resource(resource, search=None, params=None)

Execute the index action on an resource.

Parameters

resource (str) – Plural name of the api resource to show
search (str, optional) – Search string as accepted by the API to limit the results
params (Union[dict,None], optional) – Lookup parameters (i.e. parent_id for nested entities)

show_resource(resource, resource_id, params=None)

Execute the show action on an entity.

Parameters

resource (str) – Plural name of the api resource to show
resource_id (int) – The ID of the entity to show
params (Union[dict,None], optional) – Lookup parameters (i.e. parent_id for nested entities)

status()

Call the status API endpoint to ensure the server is reachable.

Returns: The full API response
Return type: dict

class foreman_helper.ForemanEntityAnsibleModule(**kwargs)

Base class for Foreman entities. To use it, subclass it with the following convention: To manage my_entity entity, create the following sub class:

class ForemanMyEntityModule(ForemanEntityAnsibleModule):
    pass

and use that class to instantiate module:

module = ForemanMyEntityModule(
    argument_spec=dict(
        [...]
    ),
    foreman_spec=dict(
        [...]
    ),
)

This adds a state parameter to the module and provides the run method for the most common usecases.

remove_sensitive_fields(entity): Set fields with ‘no_log’ option to None

run(**kwargs): lookup entities, ensure entity, remove sensitive data, manage parameters.

class foreman_helper.ForemanInfoAnsibleModule(**kwargs)

Base class for Foreman info modules that fetch information about entities

exit_json(**kwargs): return from the module, without error

run(**kwargs): lookup entities

class foreman_helper.ForemanScapDataStreamModule(**kwargs)

run(**kwargs): lookup entities, ensure entity, remove sensitive data, manage parameters.

class foreman_helper.ForemanStatelessEntityAnsibleModule(**kwargs)

Base class for Foreman entities without a state. To use it, subclass it with the following convention: To manage my_entity entity, create the following sub class:

class ForemanMyEntityModule(ForemanStatelessEntityAnsibleModule):
    pass

and use that class to instantiate module:

module = ForemanMyEntityModule(
    argument_spec=dict(
        [...]
    ),
    foreman_spec=dict(
        [...]
    ),
)

It adds the following attributes:

entity_key (str): field used to search current entity. Defaults to value provided by ENTITY_KEYS or ‘name’ if no value found.
entity_name (str): name of the current entity. By default deduce the entity name from the class name (eg: ‘ForemanProvisioningTemplateModule’ class will produce ‘provisioning_template’).
entity_opts (dict): Dict of options for base entity. Same options can be provided for subentities described in foreman_spec.

The main entity is referenced with the key entity in the foreman_spec.

property entity_name_from_class

The entity name derived from the class name.

The class name must follow the following name convention:

It starts with Foreman or Katello.
It ends with Module.

This will convert the class name ForemanMyEntityModule to the entity name my_entity.

Examples:

ForemanArchitectureModule => architecture
ForemanProvisioningTemplateModule => provisioning_template
KatelloProductMudule => product

class foreman_helper.ForemanTaxonomicAnsibleModule(**kwargs): Combine ForemanAnsibleModule with the TaxonomyMixin Mixin.

class foreman_helper.ForemanTaxonomicEntityAnsibleModule(**kwargs): Combine ForemanEntityAnsibleModule with the TaxonomyMixin Mixin.

class foreman_helper.HostMixin(**kwargs)

Host Mixin to extend a ForemanAnsibleModule (or any subclass) to work with host-related entities (Hosts, Hostgroups).

This adds many optional parameters that are specific to Hosts and Hostgroups to the module. It also includes ParametersMixin.

class foreman_helper.KatelloAnsibleModule(**kwargs): Combine ForemanAnsibleModule with the KatelloMixin Mixin.

class foreman_helper.KatelloEntityAnsibleModule(**kwargs): Combine ForemanEntityAnsibleModule with the KatelloScopedMixin Mixin.

class foreman_helper.KatelloInfoAnsibleModule(**kwargs): Combine ForemanInfoAnsibleModule with the KatelloScopedMixin Mixin.

class foreman_helper.KatelloMixin(**kwargs)

Katello Mixin to extend a ForemanAnsibleModule (or any subclass) to work with Katello entities.

This includes:

add a required organization parameter to the module
add Katello to the list of required plugins

class foreman_helper.KatelloScopedMixin(**kwargs): Enhances KatelloMixin with scoping by organization as required by Katello.

class foreman_helper.NestedParametersMixin(**kwargs)

Nested Parameters Mixin to extend a ForemanAnsibleModule (or any subclass) to work with entities that support parameters, but require them to be managed in separate API requests.

This adds optional parameters parameter to the module. It also enhances the run() method to properly handle the provided parameters.

class foreman_helper.ParametersMixin(**kwargs)

Parameters Mixin to extend a ForemanAnsibleModule (or any subclass) to work with entities that support parameters.

This allows to submit parameters to Foreman in the same request as modifying the main entity, thus making the parameters available to any action that might be triggered when the entity is saved.

By default, parametes are submited to the API using the <entity_name>_parameters_attributes key. If you need to override this, set the PARAMETERS_FLAT_NAME attribute to the key that shall be used instead.

This adds optional parameters parameter to the module. It also enhances the run() method to properly handle the provided parameters.

class foreman_helper.ParametersMixinBase

Base Class for the Parameters Mixins.

Provides a function to verify no duplicate parameters are set.

class foreman_helper.TaxonomyMixin(**kwargs)

Taxonomy Mixin to extend a ForemanAnsibleModule (or any subclass) to work with taxonomic entities.

This adds optional organizations and locations parameters to the module.

foreman_helper._check_patch_needed(introduced_version=None, fixed_version=None, plugins=None)

Decorator to check whether a specific apidoc patch is required.

Parameters

introduced_version (str, optional) – The version of Foreman the API bug was introduced.
fixed_version (str, optional) – The version of Foreman the API bug was fixed.
plugins (list, optional) – Which plugins are required for this patch.

foreman_helper._exception2fail_json(msg='Generic failure: {0}'): Decorator to convert Python exceptions into Ansible errors that can be reported to the user.

foreman_helper._flatten_entity(entity, foreman_spec): Flatten entity according to spec

foreman_helper._foreman_spec_helper(spec): Extend an entity spec by adding entries for all flat_names. Extract Ansible compatible argument_spec on the way.

foreman_helper._recursive_dict_keys(a_dict): Find all keys of a nested dictionary

foreman_helper._recursive_dict_without_none(a_dict, exclude=None): Remove all entries with None value from a dict, recursively. Also drops all entries with keys in exclude in the top level.

foreman_helper.parameter_value_to_str(value, parameter_type): Helper to convert the value of parameters to string according to their parameter_type.

foreman_helper.split_fqn(title): Split fully qualified name (title) in name and parent title

foreman_helper module

`foreman_helper` module