cloudera.cluster.cm_autotls module – Manage and configure Auto-TLS and Cloudera Manager CA

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

New in cloudera.cluster 5.0.0

Synopsis

  • Enables and configures Auto-TLS and Cloudera Manager as a CA.

  • Disabling of Auto-TLS is also supported.

  • Note that disabling Auto-TLS does not remove the TLS resources (keys, truststores, etc.) created during the enable process.

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"

ca_cert

string

The certificate for the user-provided certificate authority in PEM format.

Required and only used if custom_ca is True.

cm_host_cert

string

The certificate for the CM host in PEM format.

Required and only used if custom_ca is True.

cm_host_key

string

The private key for the CM host in PEM format.

Required and only used if custom_ca is True.

configure_all_services

boolean

Whether to configure all existing services to use Auto-TLS.

If false, only MGMT services will be configured to use Auto-TLS.

All future services will be configured to use Auto-TLS regardless of this setting.

Choices:

  • false

  • true ← (default)

connection_passphrase

string

The passphrase associated with the private key used to authenticate with the hosts.

connection_password

string

The password used to authenticate with the hosts.

Specify either this or a connection_private_key.

connection_private_key

string

The private key to authenticate with the hosts.

Specify either this or a connection_password.

The private key, if specified, needs to be a standard PEM-encoded key as a single string, with all line breaks replaced with the line-feed control character ‘\n’.

connection_ssh_port

integer

SSH port to connect to each host.

connection_user_name

string

The username used to authenticate with the hosts.

Root access to your hosts is required to install Cloudera packages.

The installer will connect to your hosts via SSH and log in either directly as root or as another user with password-less sudo privileges to become root.

custom_ca

boolean

Whether to generate an internal CMCA false or use user-provided certificates true.

When true, the following parameters must be given - cm_host_cert, cm_host_key, ca_cert, keystore_passwd and truststore_passwd.

Choices:

  • false ← (default)

  • true

debug

aliases: debug_endpoints

boolean

Capture the HTTP interaction logs with the CM API endpoint.

Choices:

  • false ← (default)

  • true

force

boolean

Forces enabling Auto-TLS even if it is already determined to be enabled.

Applicable only when state is true.

Choices:

  • false ← (default)

  • true

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.

host_certs

list / elements=dictionary

A list of cert objects for each host.

This associates a hostname with the corresponding certificate and private key.

Only used if custom_ca is True.

certificate

string

The certificate for this host in PEM format.

hostname

string

The FQDN of a host in the deployment.

key

string

The private key for this host in PEM format.

interpret_as_filenames

boolean

Whether specific parameters are interpreted as filenames local to the Cloudera Manager host.

When true, the following parameter are filenames - cm_host_cert, cm_host_key, ca_cert, keystore_passwd, truststore_passwd, trusted_ca_certs, host_certs[].certificate and host_certs[].key.

Choices:

  • false

  • true ← (default)

keystore_passwd

string

The password used for all Auto-TLS keystores.

Required and only used if custom_ca is True.

location

string

The location on disk to store the CMCA directory.

If there is already a CMCA created there, it will be backed up, and a new one will be created in its place.

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.

ssl_ca_cert

aliases: tls_cert, ssl_cert

path

Path to SSL CA certificate to use for validation.

state

string

The declarative state of Auto-TLS.

Disabling Auto-TLS does not remove the TLS resources (keys, truststores, etc.) created during the enable process.

Choices:

  • "present" ← (default)

  • "absent"

trusted_ca_certs

string

A list of CA certificates that will be imported into the Auto-TLS truststore and distributed to all hosts.

truststore_passwd

string

The password used for all Auto-TLS truststores.

Required and only used if custom_ca is True.

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

Notes

Note

  • Using the cm_config with purge=yes will remove the Cloudera Manager configurations set by this module.

  • Requires cm_client.

See Also

See also

cloudera.cluster.cm_config

Manage the configuration of Cloudera Manager.

Examples

---
- name: Enable Auto-TLS
  cloudera.cluster.cm_autotls:
    host: example.cloudera.com
    username: "jane_smith"
    password: "S&peR4Ec*re"
    state: present
    connection_user_name: clouduser
    connection_private_key: "-----BEGIN YOUR KEY -----\n[base-64 encoded key]\n-----END YOUR KEY-----"

- name: Disable Auto-TLS
  cloudera.cluster.cm_autotls:
    host: example.cloudera.com
    username: "jane_smith"
    password: "S&peR4Ec*re"
    state: absent

Return Values

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

Key

Description

cm_config

list / elements=dictionary

Cloudera Manager Server configurations with Auto-TLS settings where available.

Returned: always

default

string

The default value.

Returned: when supported

description

string

A textual description of the parameter.

Returned: when supported

display_name

string

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

Returned: when supported

name

string

The canonical name that identifies this configuration parameter.

Returned: always

string

If applicable, contains the related configuration variable used by the source project.

Returned: when supported

required

boolean

Whether this configuration is required for the object.

If any required configuration is not set, operations on the object may not work.

Returned: when supported

sensitive

boolean

Whether this configuration is sensitive, i.e. contains information such as passwords.

This parameter might affect how the value of this configuration might be shared by the caller.

Returned: when supported

validate_state

string

State of the configuration parameter after validation.

For example, OK, WARNING, and ERROR.

Returned: when supported

validation_message

string

A message explaining the parameter’s validation state.

Returned: when supported

validation_warnings_suppressed

boolean

Whether validation warnings associated with this parameter are suppressed.

In general, suppressed validation warnings are hidden in the Cloudera Manager UI.

Configurations that do not produce warnings will not contain this field.

Returned: when supported

value

string

The user-defined value.

When absent, the default value (if any) will be used.

Can also be absent, when enumerating allowed configs.

Returned: when supported

Authors

  • Jim Enright (@jimright)