Ansible modules and plugins

Mikhail Serov

You can use additional modules and plugins to change ADCM internal metadata during the execution of playbooks. All modules and plugins are described in detail in the sections below.

adcm_multi_state_set

This is a special ADCM-only module that is useful to add new multistates for various objects. Multistates are supported for clusters, services, hosts, components, and hostproviders.

Using service_name gives you the ability to switch between services.

Using component_name gives you the ability to switch between components.

Options
Attribute Description Required

type

Object type. One of: cluster, service, component, host, or hostprovider

Yes

state

State value

Yes

service_name

Service name

No

component_name

Component name

No

host_id

Host identifier that is used to set host multistates from a hostprovider

No
NOTE
You can change the state of one service from another one, yet there is a risk of running concurrent jobs that change the same state. Be careful.

Examples

- adcm_multi_state_set:
    type: "cluster"
    state: "state value"
- adcm_multi_state_set:
    type: "service"
    service_name: "First"
    state: "state value"
- adcm_multi_state_set:
    type: "component"
    component_name: "another_component"
    state: "state value"
- adcm_multi_state_set:
    type: "component"
    service_name: "another service"
    component_name: "another_component"
    state: "state value"
- adcm_multi_state_set:
    type: "host"
    host_id: {{ host_id }}
    state: "state value"

Return values

state:
  returned: success
  type: str
  example: "operational"

adcm_multi_state_unset

This is a special ADCM-only module that is useful to change multistates for various objects. Changes are supported for cluster, service, host, component, and hostprovider multistates.

Using service_name gives you the ability to switch between services.

Using component_name gives you the ability to switch between components.

Options
Attribute Description Required

type

Object type. One of: cluster, service, component, host, or hostprovider

Yes

state

State value

Yes

service_name

Service name

No

component_name

Component name

No

missing_ok

Boolean. If true, then no exception should be rised in case of the multistate being absent from an object. The default value is false

No

host_id

Host identifier that is used to unset host multistates from a hostprovider

No
NOTE
You can change the state of one service from another one, yet there is a risk of running concurrent jobs that change the same state. Be careful.

Examples

- adcm_multi_state_unset:
    type: "cluster"
    state: "state value"
- adcm_multi_state_unset:
    type: "service"
    service_name: "First"
    state: "state value"
- adcm_multi_state_unset:
    type: "component"
    component_name: "another_component"
    state: "state value"
- adcm_multi_state_unset:
    type: "component"
    service_name: "another service"
    component_name: "another_component"
    missing_ok: true
    state: "state value"
- adcm_multi_state_unset:
    type: "host"
    host_id: {{ host_id }}
    state: "state value"

Return values

state:
  returned: success
  type: str
  example: "operational"

adcm_state

This is a special ADCM-only module that is useful to set states for various objects. Cluster, service, component, host, and hostprovider states are supported.

Using service_name gives you the ability to switch between services.

Using component_name gives you the ability to switch between components.

Options
Attribute Description Required

type

Object type. One of: cluster, service, component, host, or hostprovider

Yes

state

State value

Yes

service_name

Service name

No

component_name

Component name

No

host_id

Host identifier that is used to unset host multistates from a hostprovider

No
NOTE
You can change the state of one service from another one, yet there is a risk of running concurrent jobs that change the same state. Be careful.

Examples

- adcm_state:
    type: "cluster"
    state: "state value"
register: out
- adcm_state:
    type: "service"
    service_name: "First"
    state: "state value"
- adcm_state:
    type: "component"
    component_name: "another_component"
    state: "state value"
- adcm_state:
    type: "component"
    service_name: "another service"
    component_name: "another_component"
    missing_ok: true
    state: "state value"
- adcm_state:
    type: "host"
    host_id: {{ host_id }}
    state: "state value"

Return values

state:
  returned: success
  type: str
  example: "operational"

adcm_check

This plugin is designed to log results of JSON log storage checks. The log containing those results is also displayed in the ADCM web interface.

Every call of the adcm_check plugin adds an entry to the JSON log storage. You can invoke adcm_check with a single job identifier any number of times per playbook.

Options
Attribute Description Required

group_title

Group check name

No

group_success_msg

Group check result success description

No

group_fail_msg

Group check result fail description

No

title

Check name

Yes

result

Check result

Yes

msg

Check results description

Yes, if no success_msg and fail_msg fields

success_msg

Check result success description

Yes, if no msg field

fail_msg

Check result fail description

Yes, if no msg field

severity

Indicates the severity level of a failed check result. Used when result: no. Possible values: error, warning, and info. The default value is error

No

Examples

- name: ADCM Check
  adcm_check:
    title: "Check"
    msg: "This is message"
    result: no
    severity: error
- name: ADCM Check
  adcm_check:
    title: "Check"
    success_msg: "This is success message"
    fail_msg: "This is fail message"
    result: yes
- name: ADCM check
  adcm_check:
    group_title: "Group 1"
    group_success_msg: "This is success message"
    group_fail_msg: "This is fail message"
    title: "Check"
    msg: "This is message"
    result: yes

adcm_custom_log

This plugin is designed to log results of JSON or TXT log storage checks. The log containing those results is also displayed in ADCM.

Every call of the adcm_custom_log plugin adds an entry to the JSON or TXT log storage. You can invoke adcm_custom_log with a single job identifier any number of times per playbook.

Options
Attribute Description Required

name

Log name

Yes

format

Format: json or txt

Yes

path

File path

Yes, if no content field

content

Text

Yes, if no path field

Examples

- name: custom log
  adcm_custom_log:
    name: "Custom log json"
    format: "json"
    path: "/home/user/log.json"
- name: custom log
  adcm_custom_log:
    name: "Custom log txt"
    format: "txt"
    content: "This is log"

adcm_config

This is a special ADCM-specific module that allows modifying configuration parameter values and groups for various objects. It supports configurations of clusters, services, components, hosts, and hostproviders.

For precise parameter addressing, the following capabilities are provided:

  • The service_name attribute is used to select the target service or component.

  • The component_name attribute allows for management at the level of individual components.

Options
Attribute Description Required

type

Object type. One of: cluster, service, component, host, or hostprovider

Yes

parameters

The option for declaring a set of key/value pairs

No

key

Key name

Yes, if no parameters

value

Key value. Can contain several key/value pairs (key1: value1, key2: value2, and so on)

No

active

The option for changing the state of an activatable group

No

service_name

Service or component name

Yes, if type = service

component_name

Component name

Yes, if type = component

host_id

Host identifier that is used to set host config from a hostprovider

Yes, if type = host
NOTE

  • You can modify configuration keys of a service from another service, but there is a risk of running concurrent jobs that change the same object. Be careful.

  • The module does not support selection_group. For this purpose, use the config_apply functionality.

Examples

- adcm_config:
    type: "service"
    service_name: "First"
    key: "some_int"
    value: 111
register: out
- adcm_config:
    type: "service"
    service_name: "my service"
    key: "some_activatable_group"
    active: true
- adcm_config:
    type: "cluster"
    key: "some_map"
    value:
        key1: value1
        key2: value2
- adcm_config:
    type: "component"
    component_name: "another_component"
    key: "some_map"
    value: value
- adcm_config:
    type: "component"
    service_name: "another service"
    component_name: "another_component"
    key: "key"
    value: value
- adcm_config:
    type: "host"
    parameters:
      - key: "some_group/some_string"
        value: "string"
      - key: "some_map"
        value:
          key1: value1
          key2: value2
      - key: "some_string"
        value: "string"
- adcm_config:
    type: "host"
    host_id: {{ host_id }}
    key: "{{ config.key }}"
    value: "{{ config.value }}"

Return values

value:
  returned: success
  type: complex

adcm_manage_revision

This plugin is designed to allow a bundle to check for changes in the configuration parameter values when applying the configuration of an object (such as cluster, hostprovider, host, service, or component) and create a configuration revision, for example, if a certain configuration parameter is changed. This allows implementing complex deployment logic, for example, executing certain tasks only when the values of specific parameters change.

Key features of the plugin:

  1. Change analysis: comparing current parameter values with the last fixed revision.

  2. Metadata tracking: recording changes in activated groups (type: group, activatable:true) and mutually exclusive nested groups (type: selection_group).

  3. Revision management: saving the applied configuration as a revision to track further changes.

  4. Support for operations on multiple objects: the ability to process multiple configurations within a single database request.

Options
Attribute Description Required

operation

Operation executed by the plugin. Possible values:

  • get_primary_diff — receives changes between parameter values of the current primary configuration version and the latest configuration with the commited revision;

  • set_primary_revision — marks the current configuration of the object as applied (in other words, creates the revision).

Yes

objects

List of objects to the configurations of which the specified operation will be applied (see the structure below)

Yes

Attributes of the objects list items:

  • type — object type. Possible values: cluster, service, component, host, or hostprovider.

  • service_name — service name. Required if type is service or component.

  • component_name — component name. Required if type is component.

Response structure

When performing the get_primary_diff operation, the plugin generates a response structure where the root key depends on the object type. This allows for the unambiguous identification of data across different configuration levels:

  • Cluster/hostprovider: data (diff, attr_diff) is available under the CLUSTER key.

  • Service: data is nested in the services dictionary under the key corresponding to the service name.

  • Component: data is nested in the components dictionary under the service_name.component_name key.

  • Host: data is nested in the HOSTS dictionary under the key corresponding to the host FQDN.

Regardless of object type, change information is represented by two dictionaries: diff and attr_diff. For each key in these dictionaries, the value is provided as the value object containing a list in the [old_value, new_value] format.

  • diff — dictionary of parameter value changes. The keys are group and parameter names. Example: [ "8080", "9090" ] (port changed from 8080 to 9090).

  • attr_diff — dictionary of group attribute (metadata) changes:

    • active — change in the state of an activated group. Example: [ false, true ] (the group was disabled and then enabled).

    • selection — change of the selected value in selection_group. Example: [ "LDAP", "Internal" ].

    The key is the full path to the group. Example: main/auth_settings.

NOTE

  • If no previous revision is found or the configuration has not changed, the plugin returns an empty dictionary {}.

  • During the first run (when no revisions exist), no comparison is performed, and the result will also be empty. To establish an initial configuration revision, the set_primary_revision operation should be executed.

Examples

- name: Get difference between current/previous
  adcm_manage_revision:
    operation: get_primary_diff
    objects:
      - type: component
        service_name: "kafka"
  register: diff_result

- name: Set configuration as applied
  adcm_manage_revision:
    operation: set_primary_revision
    objects:
      - type: component
        service_name: "kafka"

Return value of get_primary_diff

changed: false
failed: false
services:
  kafka:
    attr_diff:
      hdfs_tired_storage:
        active:
          value:
            - false
            - true
    diff:
      hdfs_tired_storage:
        storage.hdfs.upload.buffer.size:
          value:
            - 8192
            - 16384
      server_properties:
        log.dirs:
          value:
            - /kafka-logs
            - - /data1/kafka-logs
              - /data2/kafka-logs

This example demonstrates the separation of changes by type:

  • The attr_diff block reflects changes to group values (their metadata). In this example, the activated hdfs_tired_storage group was changed from false to true, meaning it was enabled.

  • The diff block reflects changes to the values of the actual configuration parameters. In this example:

    • Within the activated hdfs_tired_storage group, the value of the storage.hdfs.upload.buffer.size parameter was changed from 8192 to 16384.

    • In the server_properties group, the value of the log.dirs parameter (type: list) was changed from [/kafka-logs] to [/data1/kafka-logs, /data2/kafka-logs].

adcm_add_host

This module is designed to enable adding new hosts to the ADCM database. The module should be run only in the hostprovider context. The hostprovider identifier is taken from the context.

Options
Attribute Description Required

fqdn

Fully qualified domain name of a new host

Yes

description

Optional description of a new host

No

Examples

- adcm_add_host:
    fqdn: my.host.org
    description: "my cool host"

Return values

result:
  host_id: 42

adcm_delete_host

This module is designed to enable removing the hosts from the ADCM database. The module should be run only in the host context. The host identifier is taken from the context.

Examples

- adcm_delete_host:

Return values

None

adcm_add_host_to_cluster

This module is designed to enable adding the existing hosts to a cluster in the ADCM database. The module should be run only in the cluster, service, or component context. The cluster identifier is taken from the context.

Options
Attribute Description Required

fqdn

Fully qualified domain name of the new host

You should specify either fqdn or host_id of the new host

host_id

Host identifier of the new host in the ADCM database

You should specify either fqdn or host_id of the new host

Examples

- adcm_add_host_to_cluster:
    fqdn: my.host.org
- adcm_add_host_to_cluster:
    host_id: 42

Return values

None

adcm_remove_host_from_cluster

This module is designed to enable removing the hosts from a cluster in the ADCM database. The module should be run only in the cluster or service context. The cluster identifier is taken from the context.

Options
Attribute Description Required

fqdn

Fully qualified domain name of the removed host

You should specify either fqdn or host_id of the removed host

host_id

Host identifier of the removed host in the ADCM database

You should specify either fqdn or host_id of the removed host

Examples

- adcm_remove_host_from_cluster:
    fqdn: my.host.org
- adcm_remove_host_from_cluster:
    host_id: 42

Return values

None

adcm_hc

This module is designed to enable changing the host-component map for a cluster. You can break the component constraints during the sequence of operations. All constraints are checked only once during the operation sequence being performed. The module should be run only in the cluster, service, or component context. The cluster identifier is taken from the context.

Examples

- name: move master component from host1.company.com to host2.company.com
  adcm_hc:
    operations:
      -
        action: "remove"
        service: "hadoop"
        component: "master"
        host: "host.company.com"
      -
        action: "add"
        service: "hadoop"
        component: "master"
        host: "host2.company.com"

Return values

None

adcm_delete_service

This module is designed to enable removing a service from the ADCM database. The module should be run only in the cluster or service context. The service name is taken from the context, if run in the service context. If run in the cluster context, the service name should be given.

Options
Attribute Description Required

service

Service name for the cluster context

No
NOTE
If you run this module in the service context, the call of this module should be placed last in the list of the Ansible jobs. This is due to the removal of a service in the context of which the current playbook is being run.

Examples

In service context:

- adcm_delete_service:

In cluster context:

- adcm_delete_service:
    service: "First"

Return values

None

adcm_change_maintenance_mode

This module is designed to switch the maintenance mode of a host, service, or component. If an object is in maintenance mode, it is set to normal mode and vice versa.

Options
Attribute Description Required

type

Object type. One of: host, service, or component

Yes

value

Value for switching the maintenance mode. One of: True or False

Yes

Examples

- name: Change host maintenance mode to True
  adcm_change_maintenance_mode:
    type: host
    value: True

- name: Change service maintenance mode to False
  adcm_change_maintenance_mode:
    type: service
    value: False

Return values

None

adcm_change_flag

This module is designed for managing flags on hosts, services, components, clusters, and hostproviders. The up operation creates a flag with a unique name, while the down operation removes it.

Options
Attribute Description Required

operation

Operation with the flag. One of: up, down

Yes

name

Internal flag name. If this parameter is not specified, all object’s flags will be lowered when the down operation is performed

No

msg

Additional flag message for use in specific patterns

No

objects

List of the services or components for which you intend to raise/lower the flag (see the structure below). If this parameter is not specified, the flag will be raised or lowered on the action context object. If you wish to raise or lower the flag on the entire cluster, an action within the cluster context is required

No

Attributes of the objects list items:

  • type — object type. Possible values: cluster, service, component, host, or hostprovider.

  • service_name — service name. Required if type is service or component.

  • component_name — component name. Required if type is component.

Examples

- name: "Raise a flag for kafka_broker"
  adcm_change_flag:
    operation: "up"
    name: "adcm_kafka__broker_raise"
    objects:
      - type: component
        service_name: "kafka"
        component_name: "kafka_broker"

- name: "Down an outdated flag"
  adcm_change_flag:
    operation: "down"
    name: "adcm_outdated_config"
    objects:
      - type: service
        service_name: "{{ roles_generic_args.service_name }}"

Return values

value:
  returned: success
  type: complex
  example:
    failed: false
    changed: true
Found a mistake? Seleсt text and press Ctrl+Enter to report it