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 ADCM.

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

Examples

- name: ADCM Check
  adcm_check:
    title: "Check"
    msg: "This is message"
    result: yes

- 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-only module that is useful to set the specified config keys for various objects. Cluster, service, component, host, and hostprovider configs 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
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 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 change the config keys of a service from another service, yet there is a risk of running concurrent jobs that change the same object. Be careful.

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_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 operations 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 to toggle flags on hosts, services, components, clusters, and hostproviders, signaling changes in status.

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. 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

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