cloudera.cluster.service module – Manage a service in cluster

Note

This module is part of the cloudera.cluster collection (version 5.0.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install cloudera.cluster. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: cloudera.cluster.service.

New in cloudera.cluster 4.4.0

Synopsis

  • Manage a service in a cluster.

Requirements

The below requirements are needed on the host that executes this module.

  • cm-client

Parameters

Parameter

Comments

agent_header

aliases: user_agent

string

Set the HTTP user agent header when interacting with the CM API endpoint.

Default: "ClouderaFoundry"

cluster

aliases: cluster_name

string / required

The associated cluster of the service.

config

dictionary

A set of service-wide configurations for the service.

To unset a configuration, use None as its value.

If purge=True, undeclared configurations will be removed.

debug

aliases: debug_endpoints

boolean

Capture the HTTP interaction logs with the CM API endpoint.

Choices:

  • false ← (default)

  • true

display_name

string

The Cloudera Manager UI display name for the service.

force_tls

boolean

Flag to force TLS during CM API endpoint discovery.

If False, discovery will first try HTTP and follow any redirects.

Choices:

  • false ← (default)

  • true

host

aliases: hostname

string

Hostname of the CM API endpoint.

If set, the host parameter will trigger CM API endpoint discovery, which will follow redirects.

Mutually exclusive with url.

maintenance

aliases: maintenance_mode

boolean

Flag indicating if the service should be in maintenance mode.

Choices:

  • false

  • true

name

aliases: service_name, service

string / required

The service to manage.

This is a unique identifier within the cluster.

password

string / required

Password for access to the CM API endpoint.

This parameter is set to no_log.

port

integer

Port of the CM API endpoint.

If set, CM API endpoint discovery will connect to the designated port first and will follow redirects.

Default: 7180

proxy_server

aliases: proxy, http_proxy

string

Set the HTTP/S proxy server when interacting with the CM API endpoint.

purge

boolean

Flag indicating if the declared service-wide configurations, tags, role config groups, and role assignments and configurations should be append-only or fully reconciled.

If set, the module will actively remove undeclared entries, e.g. remove roles.

To clear all service-wide configurations and tags, set tags={} or config={}, i.e. an empty dictionary, and purge=True.

Choices:

  • false ← (default)

  • true

role_config_groups

list / elements=dictionary

List of base and named (custom) role config groups to declare and configure for the service.

If purge=True, undeclared named (custom) role config groups will be removed and their associated role instances reassigned to each role type’s base role config group. (Base role config groups cannot be removed.)

config

aliases: parameters, params

dictionary

A set of role config group configurations.

To unset a configuration, use None as its value.

If purge=True, undeclared configurations will be removed.

display_name

string

The Cloudera Manager UI display name for the role config group.

name

aliases: role_config_group_name, role_config_group

string

The name of a custom role config group.

role_type

aliases: type

string / required

The role type of the base or named (custom) role config group.

roles

list / elements=dictionary

List of service roles to provision directly to cluster hosts.

If purge=True, undeclared roles for the service will be removed from the hosts.

config

aliases: parameters, params

dictionary

A set of role override configurations for the role instance on the cluster hosts.

To unset a configuration, use None as its value.

If purge=True, undeclared configurations will be removed.

hostnames

aliases: cluster_hosts, cluster_hostnames

list / elements=string / required

List of hostnames of the cluster hosts receiving the role type instance.

role_config_group

string

A named (custom) role config group to assign to the role instance on the cluster hosts.

To unset the assignment, use None as the value.

tags

dictionary

A set of tags applied to the role type instance on the cluster hosts.

To unset a tag, use None as its value.

If purge=True, undeclared tags will be removed.

type

aliases: role_type

string / required

The role instance type to provision on the designated cluster hosts.

skip_redacted

aliases: redacted

boolean

Flag indicating if the declared service-wide configurations, tags, role config groups, and role assignments and configurations should skipped REDACTED parameters during reconciliation.

If set, the module will not attempt to update any existing parameter with a REDACTED value.

Otherwise, the parameter value will be overridden.

Choices:

  • false ← (default)

  • true

ssl_ca_cert

aliases: tls_cert, ssl_cert

path

Path to SSL CA certificate to use for validation.

state

string

The state of the service.

Setting state=restarted will always result in a changed=True result.

Choices:

  • "present" ← (default)

  • "absent"

  • "restarted"

  • "started"

  • "stopped"

tags

dictionary

A set of tags applied to the service.

To unset a tag, use None as its value.

If purge=True, undeclared tags will be removed.

type

aliases: service_type

string

The service type.

Required if state creates a new service.

url

aliases: endpoint, cm_endpoint_url

string

The CM API endpoint URL and should include scheme, host, port, and API root path.

Mutually exclusive with host.

username

aliases: user

string / required

Username for access to the CM API endpoint.

verify_tls

boolean

Verify the TLS certificates for the CM API endpoint.

Choices:

  • false

  • true ← (default)

version

aliases: api_version

string

API version of the CM API endpoint.

Default: "True"

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.

diff_mode

Support: full

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode

platform

Platforms: all

Target OS/families that can be operated against

See Also

See also

cloudera.cluster.service_info

Retrieve information about the services of cluster.

Examples

- name: Establish a cluster service
  cloudera.cluster.service:
    host: example.cloudera.com
    username: "jane_smith"
    password: "S&peR4Ec*re"
    cluster: example_cluster
    service: example_ecs
    type: ECS
    display_name: Example ECS


- name: Stop a cluster service
  cloudera.cluster.service:
    host: example.cloudera.com
    username: "jane_smith"
    password: "S&peR4Ec*re"
    cluster: example_cluster
    service: example_ecs
    state: stopped

- name: Force a restart of a cluster service
  cloudera.cluster.service:
    host: example.cloudera.com
    username: "jane_smith"
    password: "S&peR4Ec*re"
    cluster: example_cluster
    service: example_ecs
    state: restarted

- name: Set a cluster service into maintenance mode
  cloudera.cluster.service:
    host: example.cloudera.com
    username: "jane_smith"
    password: "S&peR4Ec*re"
    cluster: example_cluster
    service: example_ecs
    maintenance: true

- name: Update (append) several tags on a cluster service
  cloudera.cluster.service:
    host: example.cloudera.com
    username: "jane_smith"
    password: "S&peR4Ec*re"
    cluster: example_cluster
    service: example_ecs
    tags:
      tag_one: valueOne
      tag_two: valueTwo

- name: Update (purge) the tags on a cluster service
  cloudera.cluster.service:
    host: example.cloudera.com
    username: "jane_smith"
    password: "S&peR4Ec*re"
    cluster: example_cluster
    service: example_ecs
    tags:
      tag_three: value_three
    purge: true

- name: Remove all the tags on a cluster service
  cloudera.cluster.service:
    host: example.cloudera.com
    username: "jane_smith"
    password: "S&peR4Ec*re"
    cluster: example_cluster
    service: example_ecs
    tags: {}
    purge: true

- name: Update (append) several service-wide configurations on a cluster service
  cloudera.cluster.service:
    host: example.cloudera.com
    username: "jane_smith"
    password: "S&peR4Ec*re"
    cluster: example_cluster
    service: example_ecs
    config:
      param_one: 1
      param_two: Two

- name: Update (purge) the service-wide configurations on a cluster service
  cloudera.cluster.service:
    host: example.cloudera.com
    username: "jane_smith"
    password: "S&peR4Ec*re"
    cluster: example_cluster
    service: example_ecs
    config:
      param_one: 1
      param_three: three
    purge: true

- name: Remove all the service-wide configurations on a cluster service
  cloudera.cluster.service:
    host: example.cloudera.com
    username: "jane_smith"
    password: "S&peR4Ec*re"
    cluster: example_cluster
    service: example_ecs
    config: {}
    purge: true

- name: Provision role instances on cluster hosts for a cluster service
  cloudera.cluster.service:
    host: example.cloudera.com
    username: "jane_smith"
    password: "S&peR4Ec*re"
    cluster: example_cluster
    service: example_ecs
    roles:
      - type: SERVER
        hostnames:
          - host1.example
          - host2.example
        config:
          param_one: 1

- name: Provision role config groups (base and named) for a cluster service
  cloudera.cluster.service:
    host: example.cloudera.com
    username: "jane_smith"
    password: "S&peR4Ec*re"
    cluster: example_cluster
    service: example_ecs
    role_config_group:
      - name: custom_server_1
        display_name: Custom Server (1)
        role_type: SERVER
        config:
          param_two: Two
      - role_type: SERVER # This is the base role config group for SERVER
        config:
          param_three: three

- name: Provision a cluster service with hosts, role config groups, and role assignments
  cloudera.cluster.service:
    host: example.cloudera.com
    username: "jane_smith"
    password: "S&peR4Ec*re"
    cluster: example_cluster
    service: example_ecs
    roles:
      - type: SERVER
        hostnames:
          - host1.example
        config:
          param_two: Twelve
        role_config_group: custom_server_1
      - type: SERVER # Will use the base role config group for SERVER
        hostnames:
          - host2.example
    role_config_group:
      - name: custom_server_1
        display_name: Custom Server (1)
        role_type: SERVER
        config:
          param_two: Two
      - role_type: SERVER # This is the base role config group for SERVER
        config:
          param_three: three

- name: Remove a cluster service
  cloudera.cluster.service:
    host: example.cloudera.com
    username: "jane_smith"
    password: "S&peR4Ec*re"
    cluster: example_cluster
    service: example_ecs
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

service

dictionary

Details about the service.

Returned: success

client_config_staleness_status

string

Status of the client configuration for the service.

Returned: always

Sample: "['FRESH', 'STALE_REFRESHABLE', 'STALE']"

cluster_name

string

The name of the cluster, which uniquely identifies it in a Cloudera Manager installation.

Returned: always

config

dictionary

Service-wide configuration details about a cluster service.

Returned: when supported

config_staleness_status

string

Status of configuration staleness for the service.

Returned: always

Sample: "['FRESH', 'STALE_REFRESHABLE', 'STALE']"

display_name

string

The display name for the service that is shown in the Cloudera Manager UI.

Returned: when supported

health_checks

list / elements=dictionary

Lists all available health checks for Cloudera Manager Service.

Returned: when supported

explanation

string

The explanation of this health check.

Returned: when supported

name

string

Unique name of this health check.

Returned: always

summary

string

The high-level health status of the health check.

Returned: always

Sample: "['DISABLED', 'HISTORY_NOT_AVAILABLE', 'NOT_AVAILABLE', 'GOOD', 'CONCERNING', 'BAD']"

suppressed

boolean

Whether this health check is suppressed.

A suppressed health check is not considered when computing the service’s overall health.

Returned: when supported

health_summary

string

The high-level health status of the service.

Returned: always

Sample: "['DISABLED', 'HISTORY_NOT_AVAILABLE', 'NOT_AVAILABLE', 'GOOD', 'CONCERNING', 'BAD']"

maintenance_mode

boolean

Whether the service is in maintenance mode.

Returned: when supported

maintenance_owners

list / elements=string

The list of objects that trigger this service to be in maintenance mode.

Returned: when supported

Sample: ["CLUSTER", "SERVICE", "ROLE", "HOST", "CONTROL_PLANE"]

name

string

The cluster service name.

Returned: always

role_config_groups

list / elements=dictionary

List of base and custom role config groups for the cluster service.

Returned: when supported

base

boolean

Flag indicating whether this is a base group.

Returned: always

config

dictionary

Set of configurations for the role config group.

Returned: when supported

display_name

string

A user-friendly name of the role config group, as would have been shown in the web UI.

Returned: when supported

name

string

The unique name of this role config group.

Returned: always

role_type

string

The type of the roles in this group.

Returned: always

roles

list / elements=dictionary

List of provisioned role instances on cluster hosts for the cluster service.

Returned: when supported

commission_state

string

Commission state of the cluster service role.

Returned: always

config

dictionary

Set of role configurations for the cluster service role.

Returned: when supported

config_staleness_status

string

Status of configuration staleness for the cluster service role.

Returned: always

Sample: "['FRESH', 'STALE_REFRESHABLE', 'STALE']"

health_checks

list / elements=dictionary

Lists all available health checks for cluster service role.

Returned: when supported

explanation

string

The explanation of this health check.

Returned: when supported

name

string

Unique name of this health check.

Returned: always

summary

string

The high-level health status of the health check.

Returned: always

Sample: "['DISABLED', 'HISTORY_NOT_AVAILABLE', 'NOT_AVAILABLE', 'GOOD', 'CONCERNING', 'BAD']"

suppressed

boolean

Whether this health check is suppressed.

A suppressed health check is not considered when computing the role’s overall health.

Returned: when supported

health_summary

string

The high-level health status of the cluster service role.

Returned: always

Sample: "['DISABLED', 'HISTORY_NOT_AVAILABLE', 'NOT_AVAILABLE', 'GOOD', 'CONCERNING', 'BAD']"

host_id

string

The unique ID of the cluster host.

Returned: always

hostname

string

The hostname of the cluster host.

Returned: always

maintenance_mode

boolean

Whether the cluster service role is in maintenance mode.

Returned: when supported

maintenance_owners

list / elements=string

The list of objects that trigger this service to be in maintenance mode.

Returned: when supported

Sample: ["CLUSTER", "SERVICE", "ROLE", "HOST", "CONTROL_PLANE"]

name

string

The cluster service role name.

Returned: always

role_config_group_name

string

The name of the cluster service role config group, which uniquely identifies it in a Cloudera Manager installation.

Returned: when supported

role_state

string

State of the cluster service role.

Returned: always

Sample: "['HISTORY_NOT_AVAILABLE', 'UNKNOWN', 'STARTING', 'STARTED', 'STOPPING', 'STOPPED', 'NA']"

tags

dictionary

The dictionary of tags for the cluster service role.

Returned: when supported

type

string

The cluster service role type.

Returned: always

Sample: "['NAMENODE', 'DATANODE', 'TASKTRACKER']"

zoo_keeper_server_mode

string

The Zookeeper server mode for this cluster service role.

Note that for non-Zookeeper Server roles, this will be null.

Returned: when supported

service_state

string

State of the service.

Returned: always

Sample: "['HISTORY_NOT_AVAILABLE', 'UNKNOWN', 'STARTING', 'STARTED', 'STOPPING', 'STOPPED', 'NA']"

service_version

string

Version of the service.

Returned: when supported

tags

dictionary

The dictionary of tags for the service.

Returned: when supported

type

string

The cluster service type.

Returned: always

Sample: "['HDFS', 'HBASE', 'ECS']"

Authors

  • Webster Mudge (@wmudge)