cloudera.services.ml_project_job module – Manage a Cloudera Machine Learning (CML) project job

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.

New in cloudera.services 1.0.0

Synopsis

• Create, update, or delete a Cloudera Machine Learning (CML) project job.

• The module supports check_mode.

Parameters

Parameter	Comments
addons aliases: runtime_addons, runtime_addon_identifiers list / elements=string	A list of runtime addon identifiers for the job. On update, the provided addons are merged with the job’s existing addons.
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 script.
attachments list / elements=string	A list of file attachments (project file paths) delivered with job run notifications. Applied only on job creation.
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.
cpu float	The vCPU allocated to the job.
debug aliases: debug_endpoints boolean	A flag to enable debug logging of the module’s execution. Choices: false ← (default) true
env aliases: env_vars dictionary	Environment variables to set on the job. On update, the provided variables are merged with the job’s existing variables.
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
gpu aliases: nvidia_gpu integer	The count of Nvidia GPUs allocated to the job.
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 an existing job. Mutually exclusive with name.
job_timeout aliases: execution_timeout integer	The job timeout, in seconds.
kernel string	The kernel to use for the job. Not valid for projects whose default engine type is ml_runtime; use runtime instead. Mutually exclusive with runtime. Choices: "python3" "python2" "r" "scala"
kill aliases: kill_on_timeout boolean	Whether to kill the job when it exceeds job_timeout. Requires job_timeout. Choices: false true
memory float	The RAM allocated to the job, in GB.
name aliases: job string	The name of the job. Required when creating a job. 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
parent aliases: parent_job_id string	The unique identifier of a parent job that triggers this job on completion. Mutually exclusive with schedule.
paused boolean	Whether the job schedule is paused. Choices: false true
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.
recipients list / elements=dictionary	A list of email notification recipients for job runs. Applied only on job creation.
email string / required	The email address of the recipient.
failure boolean	Whether to notify on job failure. Choices: false true ← (default)
stopped boolean	Whether to notify when a job is stopped. Choices: false true ← (default)
success boolean	Whether to notify on job success. Choices: false true ← (default)
timeout boolean	Whether to notify on job timeout. Choices: false true ← (default)
runtime aliases: runtime_image_id, runtime_identifier string	The container runtime identifier for the job. Required on creation for projects whose default engine type is ml_runtime. Mutually exclusive with kernel.
schedule string	The cron schedule for the job. Mutually exclusive with parent.
script string	The entrypoint script for the job. Required when creating a job.
state string	The declarative state of the job. Choices: "present" ← (default) "absent"
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)

Examples

- name: Create a job
  cloudera.services.ml_project_job:
    url: "https://ml-workspace.example.com"
    api_key: "{{ cml_api_key }}"
    project_name: my-project
    name: nightly-etl
    script: etl.py
    runtime: "{{ runtime_id }}"
    schedule: "0 2 * * *"
    env:
      LOG_LEVEL: info
    state: present

- name: Update a job's timeout
  cloudera.services.ml_project_job:
    project_id: "{{ project_id }}"
    name: nightly-etl
    job_timeout: 3600
    kill: true

- name: Delete a job
  cloudera.services.ml_project_job:
    project_id: "{{ project_id }}"
    id: "{{ job_id }}"
    state: absent

Return Values

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

Key	Description
job dictionary	The CML job details. Returned: always
arguments string	The command-line arguments passed to the job script. Returned: when available
cpu float	The vCPU allocated to the job. Returned: when available
created_at string	The timestamp when the job was created. Returned: when available
creator dictionary	Details of the user that created the job. Returned: when available
environment dictionary	The environment variables of the job. Returned: when available
id string	The unique identifier of the job. Returned: always
kernel string	The kernel for the job. Returned: when available
kill_on_timeout boolean	Whether the job is killed on timeout. Returned: when available
memory float	The RAM allocated to the job, in GB. Returned: when available
name string	The name of the job. Returned: always
nvidia_gpu integer	The count of Nvidia GPUs allocated to the job. Returned: when available
parent_job_id string	The identifier of the parent job that triggers this job. Returned: when available
paused boolean	Whether the job schedule is paused. Returned: when available
project_id string	The identifier of the enclosing project. Returned: when available
runtime_addon_identifiers list / elements=string	The runtime addon identifiers for the job. Returned: when available
runtime_identifier string	The container runtime identifier for the job. Returned: when available
schedule string	The cron schedule for the job. Returned: when available
script string	The entrypoint script for the job. Returned: when available
timeout integer	The job timeout, in seconds. Returned: when available
updated_at string	The timestamp when the job was last updated. 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)

Collection Links

• Issue Tracker
• Repository (Sources)
• Submit a bug report
• Request a feature