cloudera.services.atlas_entity_info module – Retrieve an entity from Apache Atlas

Note

This module is part of the cloudera.services collection (version 1.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 git+https://github.com/cloudera-labs/cloudera.services.git.

To use it in a playbook, specify: cloudera.services.atlas_entity_info.

New in cloudera.services 1.1.0

Synopsis 

Retrieve a single entity instance from Apache Atlas, with its attributes, labels, classifications, and business metadata.
Identify the entity either by its GUID or by its type name and unique attributes, usually its qualifiedName.
Returns no entities, and does not fail, when the entity does not exist.

Parameters 

Parameter	Comments
client_cert path	The path to a client certificate for authenticating to the API endpoint.
client_key path	The path to a client key for authenticating to the API endpoint.
debug aliases: debug_endpoints boolean	A flag to enable debug logging of the module’s execution. Choices: `false` ← (default) `true`
force boolean	A flag to force a refresh of the API request, ignoring any cached results. Choices: `false` ← (default) `true`
force_basic_auth boolean	A flag to force basic authentication for API requests. Choices: `false` ← (default) `true`
guid string	GUID of the entity. Atlas deletes entities softly, so a GUID lookup can return an entity whose `entities[].status` is `DELETED`. Mutually exclusive with `type_name`, `qualified_name`, and `unique_attributes`.
http_agent aliases: user_agent string	The User-Agent string to send with API requests. Default: `"cloudera-services-module"`
page_size aliases: default_page_size integer	The number of items to return per page in a paginated API response. Default: `100`
qualified_name string	Value of the `qualifiedName` unique attribute of the entity. Shorthand for `unique_attributes=qualifiedName`. Requires `type_name`; mutually exclusive with `unique_attributes`.
timeout aliases: timeout_seconds integer	The timeout in seconds for any API requests. Default: `60`
type_name string	Name of the entity type, e.g. `hive_table`. Requires `qualified_name` or `unique_attributes`. A type name that does not exist fails the module, so a misspelled type is not mistaken for a missing entity. A lookup by unique attributes never returns a deleted entity.
unique_attributes dictionary	Unique attribute names and values that identify the entity within `type_name`. Attribute names are Atlas names and are used as given, e.g. `qualifiedName`. Requires `type_name`; mutually exclusive with `qualified_name`.
url aliases: endpoint, endpoint_url string / required	The base URL of the API endpoint, including the port if necessary.
url_password string	The password for authenticating to the API endpoint.
url_username string	The username for authenticating to the API endpoint.
use_gssapi boolean	A flag to enable or disable GSSAPI authentication for API requests. Choices: `false` ← (default) `true`
use_proxy boolean	A flag to enable or disable the use of a proxy for API requests. Choices: `false` `true` ← (default)
validate_certs boolean	A flag to enable or disable SSL certificate validation for API requests. Choices: `false` `true` ← (default)

Attributes 

Attribute	Support	Description
check_mode	Support: full	This module supports check mode.

Examples 

# NOTE: Examples do not include connection and authentication fields
- name: Retrieve an entity by its qualified name
  cloudera.services.atlas_entity_info:
    type_name: hive_table
    qualified_name: default.sales@cluster1
  register: table

- name: Retrieve an entity by its GUID
  cloudera.services.atlas_entity_info:
    guid: fc0fd256-be16-4775-99ad-9e0b7e304ae5
  register: entity

- name: Retrieve an entity by several unique attributes
  cloudera.services.atlas_entity_info:
    type_name: my_custom_type
    unique_attributes:
      qualifiedName: orders@cluster1
  register: orders

- name: Fail unless the entity exists and is active
  ansible.builtin.assert:
    that:
      - table.entities | length == 1
      - table.entities[0].status == 'ACTIVE'

- name: List the classifications attached to an entity
  ansible.builtin.debug:
    msg: "{{ table.entities[0].classifications | map(attribute='type_name') | list }}"
  when: table.entities | length > 0

- name: Wait for a hook to register a table before using it
  cloudera.services.atlas_entity_info:
    type_name: hive_table
    qualified_name: default.sales@cluster1
  register: table
  until: table.entities | length > 0
  retries: 12
  delay: 10

Return Values 

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

Key	Description
entities list / elements=dictionary	The entity, as a list with zero or one item. Top-level keys are snake_case; the names inside the attribute dictionaries are exactly the names Atlas uses (e.g. `qualifiedName`). Returned: always
attributes dictionary	The entity attributes, keyed by Atlas attribute name. Returned: success
business_attributes dictionary	The business metadata attached to the entity, keyed by business metadata name and then attribute name. Returned: success
classifications list / elements=dictionary	The classifications attached to or propagated to the entity. Returned: success
attributes dictionary	The classification attributes, keyed by Atlas attribute name. Returned: success
entity_guid string	GUID of the entity the classification is attached to. A different GUID than the entity’s own means it was propagated. Returned: success
entity_status string	Status of the entity the classification is attached to. Returned: success
propagate boolean	Whether the classification propagates to related entities. Returned: success
remove_propagations_on_entity_delete boolean	Whether propagations are removed when the entity is deleted. Returned: success
type_name string	Name of the classification. Returned: success
validity_periods list / elements=dictionary	The time windows in which the classification is valid. Returned: success
create_time integer	Creation time in epoch milliseconds. Returned: success
created_by string	User that created the entity. Returned: success
custom_attributes dictionary	The user-defined custom attributes. Returned: success
guid string	Atlas-assigned identifier. Returned: success
is_incomplete boolean	Whether Atlas holds only a partial copy of the entity. Returned: success
labels list / elements=string	The labels attached to the entity. Returned: success
relationship_attributes dictionary	The relationship attributes, keyed by Atlas attribute name. Returned: success
status string	Entity status, `ACTIVE` or `DELETED`. Returned: success
type_name string	Name of the entity type. Returned: success
update_time integer	Last update time in epoch milliseconds. Returned: success
updated_by string	User that last updated the entity. Returned: success
version integer	Atlas version number of the entity. Returned: success

Authors 

Webster Mudge (@wmudge)

cloudera.services.atlas_entity_info module – Retrieve an entity from Apache Atlas

Synopsis

Parameters

Attributes

Examples

Return Values

Authors

Collection Links