cloudera.services.ml_project_job_run module – Start or stop a Cloudera Machine Learning (CML) project job run

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

New in cloudera.services 1.0.0

Synopsis

  • Start or stop a run of a Cloudera Machine Learning (CML) project job.

  • The module is idempotent with respect to the job’s most recent run.

  • The module supports check_mode.

Parameters

Parameter

Comments

api_key

aliases: token

string / required

The CML API key (bearer token) used to authenticate to the Workspace API.

If not set, the value of the CML_API_KEY environment variable is used.

arguments

string

The command-line arguments passed to the job run.

Applied only when starting a new run.

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

delay

integer

The interval, in seconds, between status checks when wait=true.

Default: 15

env

aliases: env_vars

dictionary

Environment variables to set on the job run.

Applied only when starting a new run.

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

http_agent

aliases: user_agent

string

The User-Agent string to send with API requests.

Default: "cloudera-services-module"

id

aliases: job_id

string

The unique identifier of the job to run.

Mutually exclusive with name.

name

aliases: job

string

The name of the job to run.

Mutually exclusive with id.

page_size

aliases: default_page_size

integer

The number of items to return per page in a paginated API response.

Default: 100

project_id

string

The unique identifier of the enclosing project for the job.

Mutually exclusive with project_name.

project_name

string

The name of the enclosing project for the job.

Mutually exclusive with project_id.

state

string

The declarative state of the job run.

started ensures a run is active, starting one if the latest run is not already active.

stopped ensures the latest run is not active, stopping it if necessary.

Choices:

  • "started" ← (default)

  • "stopped"

timeout

aliases: timeout_seconds

integer

The timeout in seconds for any API requests.

Default: 60

url

aliases: endpoint, endpoint_url, workspace_url

string / required

The base URL of the CML Workspace API endpoint, including the port if necessary.

If not set, the value of the CML_ENDPOINT environment variable is used.

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)

wait

boolean

Whether to wait for the run to reach a terminal state.

Choices:

  • false ← (default)

  • true

wait_timeout

aliases: execution_timeout

integer

The maximum time, in seconds, to wait for a terminal state when wait=true.

Default: 3600

Examples

- name: Start a job run
  cloudera.services.ml_project_job_run:
    url: "https://ml-workspace.example.com"
    api_key: "{{ cml_api_key }}"
    project_name: my-project
    name: nightly-etl
    state: started

- name: Start a job run and wait for it to succeed
  cloudera.services.ml_project_job_run:
    project_id: "{{ project_id }}"
    id: "{{ job_id }}"
    arguments: "--verbose"
    wait: true
    wait_timeout: 1800

- name: Stop the active run of a job
  cloudera.services.ml_project_job_run:
    project_id: "{{ project_id }}"
    name: nightly-etl
    state: stopped

Return Values

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

Key

Description

job_run

dictionary

The CML job run details.

Returned: always

arguments

string

The command-line arguments passed to the job run.

Returned: when available

created_at

string

The timestamp when the job run was created.

Returned: when available

creator

dictionary

Details of the user that started the job run.

Returned: when available

environment

dictionary

The environment variables of the job run.

Returned: when available

finished_at

string

The timestamp when the job run finished.

Returned: when available

id

string

The unique identifier of the job run.

Returned: always

job_id

string

The identifier of the enclosing job.

Returned: when available

project_id

string

The identifier of the enclosing project.

Returned: when available

scheduling_at

string

The timestamp when the job run was scheduled.

Returned: when available

starting_at

string

The timestamp when the job run started.

Returned: when available

status

string

The status of the job run.

Returned: when available

sdk_out

string

Returns the captured REST API log.

Returned: when supported

sdk_out_lines

list / elements=string

Returns a list of each line of the captured REST API log.

Returned: when supported

Authors

  • Webster Mudge (@wmudge)