2021-05-13 23:48:51 +00:00
---
2023-01-31 12:48:17 +00:00
title: ClearML Agent
2021-05-13 23:48:51 +00:00
---
2023-09-04 11:37:36 +00:00
< div class = "vid" >
< iframe style = {{position: ' absolute ' , top: ' 0 ' , left: ' 0 ' , bottom: ' 0 ' , right: ' 0 ' , width: ' 100 % ' , height: ' 100 % ' } }
src="https://www.youtube.com/embed/MX3BrXnaULs"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen"
allowfullscreen>
< / iframe >
< / div >
2023-09-10 11:25:37 +00:00
< br / >
2022-05-19 06:59:10 +00:00
**ClearML Agent** is a virtual environment and execution manager for DL / ML solutions on GPU machines. It integrates with the **ClearML Python Package** and ClearML Server to provide a full AI cluster solution. < br />
2021-05-13 23:48:51 +00:00
Its main focus is around:
- Reproducing experiments, including their complete environments.
- Scaling workflows on multiple target machines.
2022-05-19 06:59:10 +00:00
ClearML Agent executes an experiment or other workflow by reproducing the state of the code from the original machine
2021-07-20 07:34:10 +00:00
to a remote machine.
2021-05-13 23:48:51 +00:00
2022-02-17 12:09:17 +00:00
![ClearML Agent flow diagram ](img/clearml_agent_flow_diagram.png )
2021-05-13 23:48:51 +00:00
2023-08-09 10:28:25 +00:00
The preceding diagram demonstrates a typical flow where an agent executes a task:
2021-07-20 07:34:10 +00:00
1. Enqueue a task for execution on the queue.
1. The agent pulls the task from the queue.
1. The agent launches a docker container in which to run the task's code.
1. The task's execution environment is set up:
1. Execute any custom setup script configured.
1. Install any required system packages.
1. Clone the code from a git repository.
1. Apply any uncommitted changes recorded.
1. Set up the python environment and required packages.
1. The task's script/code is executed.
2023-09-05 11:50:57 +00:00
:::note Python Version
ClearML Agent uses the Python version available in the environment or docker in which it executes the code. It does not
install Python, so make sure to use a docker or environment with the version you need.
:::
2023-09-04 11:37:36 +00:00
While the agent is running, it continuously reports system metrics to the ClearML Server (these can be monitored in the
[**Orchestration** ](webapp/webapp_workers_queues.md ) page).
2021-06-20 22:00:16 +00:00
2023-03-12 08:30:13 +00:00
Continue using ClearML Agent once it is running on a target machine. Reproduce experiments and execute
2021-05-13 23:48:51 +00:00
automated workflows in one (or both) of the following ways:
2023-03-12 08:30:13 +00:00
* Programmatically (using [`Task.enqueue` ](references/sdk/task.md#taskenqueue ) or [`Task.execute_remotely` ](references/sdk/task.md#execute_remotely ))
* Through the ClearML Web UI (without working directly with code), by cloning experiments and enqueuing them to the
queue that a ClearML Agent is servicing.
2023-03-19 10:34:17 +00:00
The agent facilitates [overriding task execution detail ](webapp/webapp_exp_tuning.md ) values through the UI without
code modification. Modifying a task clone’ s configuration will have the ClearML agent executing it override the
original values:
* Modified package requirements will have the experiment script run with updated packages
* Modified recorded command line arguments will have the ClearML agent inject the new values in their stead
* Code-level configuration instrumented with [`Task.connect` ](references/sdk/task.md#connect ) will be overridden by modified hyperparameters
2021-05-13 23:48:51 +00:00
2022-08-15 14:31:02 +00:00
For more information, see [ClearML Agent Reference ](clearml_agent/clearml_agent_ref.md ),
2021-05-13 23:48:51 +00:00
and [configuration options ](configs/clearml_conf.md#agent-section ).
## Installation
:::note
2022-01-18 11:23:47 +00:00
If ClearML was previously configured, follow [this ](#adding-clearml-agent-to-a-configuration-file ) to add
2021-05-13 23:48:51 +00:00
ClearML Agent specific configurations
:::
2021-08-24 10:16:25 +00:00
To install ClearML Agent, execute
2021-05-13 23:48:51 +00:00
```bash
pip install clearml-agent
```
2021-08-24 10:16:25 +00:00
:::info
Install ClearML Agent as a system Python package and not in a Python virtual environment.
2023-02-08 11:19:08 +00:00
An agent that runs in Virtual Environment Mode or Conda Environment Mode needs to create virtual environments, and
it can't do that when running from a virtual environment.
2021-08-24 10:16:25 +00:00
:::
2021-05-13 23:48:51 +00:00
## Configuration
1. In a terminal session, execute
```bash
clearml-agent init
```
2022-01-19 12:37:16 +00:00
The setup wizard prompts for ClearML credentials (see [here ](webapp/webapp_profile.md#clearml-credentials ) about obtaining credentials).
2022-02-17 12:09:17 +00:00
```
Please create new clearml credentials through the settings page in your `clearml-server` web app,
or create a free account at https://app.clear.ml/settings/webapp-configuration
2021-05-13 23:48:51 +00:00
2022-02-17 12:09:17 +00:00
In the settings > workspace page, press "Create new credentials", then press "Copy to clipboard".
2021-05-13 23:48:51 +00:00
2022-02-17 12:09:17 +00:00
Paste copied configuration here:
```
2021-05-13 23:48:51 +00:00
If the setup wizard's response indicates that a configuration file already exists, follow the instructions [here ](#adding-clearml-agent-to-a-configuration-file ).
The wizard does not edit or overwrite existing configuration files.
2022-01-19 12:37:16 +00:00
1. At the command prompt `Paste copied configuration here:` , copy and paste the ClearML credentials and press **Enter** .
2021-05-13 23:48:51 +00:00
The setup wizard confirms the credentials.
2022-02-17 12:09:17 +00:00
```
Detected credentials key="********************" secret="*******"
```
2021-05-13 23:48:51 +00:00
2022-01-18 11:23:47 +00:00
1. **Enter** to accept default server URL, which is detected from the credentials or enter a ClearML web server URL.
2021-05-13 23:48:51 +00:00
A secure protocol, https, must be used. **Do not use http.**
2022-02-17 12:09:17 +00:00
```
WEB Host configured to: [https://app.clear.ml]
```
2021-05-13 23:48:51 +00:00
:::note
If you are using a self-hosted ClearML Server, the default URL will use your domain.
:::
1. Do as above for API, URL, and file servers.
1. The wizard responds with your configuration:
2022-02-17 12:09:17 +00:00
```
CLEARML Hosts configuration:
Web App: https://app.clear.ml
API: https://api.clear.ml
File Store: https://files.clear.ml
2021-05-13 23:48:51 +00:00
2022-02-17 12:09:17 +00:00
Verifying credentials ...
Credentials verified!
```
2021-05-13 23:48:51 +00:00
2021-10-05 06:02:44 +00:00
1. Enter your Git username and password. Leave blank for SSH key authentication or when only using public repositories.
2021-05-13 23:48:51 +00:00
This is needed for cloning repositories by the agent.
2022-02-17 12:09:17 +00:00
```
Enter git username for repository cloning (leave blank for SSH key authentication): []
Enter password for user '< username > ':
```
The setup wizard confirms your git credentials.
```
Git repository cloning will be using user=< username > password=< password >
```
2021-10-05 06:02:44 +00:00
1. Enter an additional artifact repository, or press **Enter** if not required.
2021-05-13 23:48:51 +00:00
This is needed for installing Python packages not found in pypi.
2022-02-17 12:09:17 +00:00
```
Enter additional artifact repository (extra-index-url) to use when installing python packages (leave blank if not required):
```
2021-05-13 23:48:51 +00:00
The setup wizard completes.
2022-02-17 12:09:17 +00:00
```
New configuration stored in /home/< username > /clearml.conf
CLEARML-AGENT setup completed successfully.
```
2021-05-13 23:48:51 +00:00
The configuration file location depends upon the operating system:
* Linux - `~/clearml.conf`
* Mac - `$HOME/clearml.conf`
* Windows - `\User\<username>\clearml.conf`
2022-10-24 07:17:33 +00:00
1. Optionally, configure ClearML options for **ClearML Agent** (default docker, package manager, etc.). See the [ClearML Configuration Reference ](configs/clearml_conf.md )
and the [ClearML Agent Environment Variables reference ](clearml_agent/clearml_agent_env_var.md ).
2021-10-21 06:42:11 +00:00
:::note
The ClearML Enterprise server provides a [configuration vault ](webapp/webapp_profile.md#configuration-vault ), the contents
of which are categorically applied on top of the agent-local configuration
:::
2021-05-13 23:48:51 +00:00
2021-09-09 10:17:46 +00:00
### Adding ClearML Agent to a Configuration File
2021-05-13 23:48:51 +00:00
In case a `clearml.conf` file already exists, add a few ClearML Agent specific configurations to it.< br />
**Adding ClearML Agent to a ClearML configuration file:**
2022-01-30 10:54:40 +00:00
1. Open the ClearML configuration file for editing. Depending upon the operating system, it is:
2021-05-13 23:48:51 +00:00
* Linux - `~/clearml.conf`
* Mac - `$HOME/clearml.conf`
* Windows - `\User\<username>\clearml.conf`
2022-06-19 09:35:31 +00:00
1. After the `api` section, add your `agent` section. For example:
```
agent {
# Set GIT user/pass credentials (if user/pass are set, GIT protocol will be set to https)
git_user=""
git_pass=""
# all other domains will use public access (no user/pass). Default: always send user/pass for any VCS domain
git_host=""
# Force GIT protocol to use SSH regardless of the git url (Assumes GIT user/pass are blank)
force_git_ssh_protocol: false
# unique name of this worker, if None, created based on hostname:process_id
# Overridden with os environment: CLEARML_WORKER_NAME
worker_id: ""
}
```
View a complete ClearML Agent configuration file sample including an `agent` section [here ](https://github.com/allegroai/clearml-agent/blob/master/docs/clearml.conf ).
2021-05-13 23:48:51 +00:00
1. Save the configuration.
2022-11-27 14:06:06 +00:00
## Deployment
2021-05-13 23:48:51 +00:00
2021-09-09 10:17:46 +00:00
### Spinning Up an Agent
2022-08-01 07:53:43 +00:00
You can spin up an agent on any machine: on-prem and/or cloud instance. When spinning up an agent, you assign it to
service a queue(s). Utilize the machine by enqueuing tasks to the queue that the agent is servicing, and the agent will
pull and execute the tasks.
2021-05-13 23:48:51 +00:00
2022-10-11 11:51:59 +00:00
:::tip cross-platform execution
ClearML Agent is platform agnostic. When using the ClearML Agent to execute experiments cross-platform, set platform
specific environment variables before launching the agent.
For example, to run an agent on an ARM device, set the core type environment variable before spinning up the agent:
```bash
export OPENBLAS_CORETYPE=ARMV8
clearml-agent daemon --queue < queue_name >
```
:::
2021-05-13 23:48:51 +00:00
#### Executing an Agent
To execute an agent, listening to a queue, run:
```bash
clearml-agent daemon --queue < queue_name >
```
#### Executing in Background
To execute an agent in the background, run:
```bash
clearml-agent daemon --queue < execution_queue_to_pull_from > --detached
```
#### Stopping Agents
To stop an agent running in the background, run:
```bash
clearml-agent daemon < arguments > --stop
```
#### Allocating Resources
To specify GPUs associated with the agent, add the `--gpus` flag.
To execute multiple agents on the same machine (usually assigning GPU for the different agents), run:
```bash
clearml-agent daemon --detached --queue default --gpus 0
clearml-agent daemon --detached --queue default --gpus 1
```
To allocate more than one GPU, provide a list of allocated GPUs
```bash
2023-06-05 09:11:48 +00:00
clearml-agent daemon --gpus 0,1 --queue dual_gpu
2021-05-13 23:48:51 +00:00
```
#### Queue Prioritization
A single agent can listen to multiple queues. The priority is set by their order.
```bash
clearml-agent daemon --detached --queue high_q low_q --gpus 0
```
2022-01-30 10:54:40 +00:00
This ensures the agent first tries to pull a Task from the `high_q` queue, and only if it is empty, the agent will try to pull
2022-01-24 13:42:17 +00:00
from the `low_q` queue.
2021-05-13 23:48:51 +00:00
To make sure an agent pulls from all queues equally, add the `--order-fairness` flag.
```bash
clearml-agent daemon --detached --queue group_a group_b --order-fairness --gpus 0
```
2022-01-24 13:42:17 +00:00
It will make sure the agent will pull from the `group_a` queue, then from `group_b` , then back to `group_a` , etc. This ensures
2022-01-30 10:54:40 +00:00
that `group_a` or `group_b` will not be able to starve one another of resources.
2021-05-13 23:48:51 +00:00
2022-10-24 07:17:33 +00:00
#### SSH Access
2023-01-19 15:28:08 +00:00
By default, ClearML Agent maps the host's `~/.ssh` into the container's `/root/.ssh` directory (configurable,
see [clearml.conf ](configs/clearml_conf.md#docker_internal_mounts )).
2022-10-24 07:17:33 +00:00
2023-01-19 15:28:08 +00:00
If you want to use existing auth sockets with ssh-agent, you can verify your host ssh-agent is working correctly with:
2022-10-24 07:17:33 +00:00
2023-01-19 15:28:08 +00:00
```commandline
2023-01-22 11:34:04 +00:00
echo $SSH_AUTH_SOCK
2022-10-24 07:17:33 +00:00
```
2023-01-19 15:28:08 +00:00
You should see a path to a temporary file, something like this:
```console
/tmp/ssh-< random > /agent.< random >
2022-10-24 07:17:33 +00:00
```
2023-01-22 11:34:04 +00:00
Then run your `clearml-agent` in Docker mode, which will automatically detect the `SSH_AUTH_SOCK` environment variable,
2023-01-19 15:28:08 +00:00
and mount the socket into any container it spins.
2023-01-22 11:34:04 +00:00
You can also explicitly set the `SSH_AUTH_SOCK` environment variable when executing an agent. The command below will
execute an agent in Docker mode and assign it to service a queue. The agent will have access to
the SSH socket provided in the environment variable.
```
SSH_AUTH_SOCK=< file_socket > clearml-agent daemon --gpus < your config > --queue < your queue name > --docker
```
2022-11-27 14:06:06 +00:00
### Kubernetes
Agents can be deployed bare-metal or as dockers in a Kubernetes cluster. ClearML Agent adds the missing scheduling
capabilities to Kubernetes, allows for more flexible automation from code, and gives access to all of ClearML Agent’ s
features (scheduling, job prioritization, and more).
There are two options for deploying the ClearML Agent to a Kubernetes cluster:
* Spin ClearML Agent as a long-lasting service pod
* Map ClearML jobs directly to K8s jobs with Kubernetes Glue (available in the ClearML Enterprise plan)
2023-08-09 10:28:25 +00:00
For more details, see [Kubernetes integration ](https://github.com/allegroai/clearml-agent#kubernetes-integration-optional ).
2022-11-27 14:06:06 +00:00
2021-09-09 10:17:46 +00:00
### Explicit Task Execution
2021-05-13 23:48:51 +00:00
ClearML Agent can also execute specific tasks directly, without listening to a queue.
2021-09-09 10:17:46 +00:00
#### Execute a Task without Queue
2021-05-13 23:48:51 +00:00
Execute a Task with a `clearml-agent` worker without a queue.
```bash
clearml-agent execute --id < task-id >
```
2021-09-09 10:17:46 +00:00
#### Clone a Task and Execute the Cloned Task
2021-05-13 23:48:51 +00:00
Clone the specified Task and execute the cloned Task with a `clearml-agent` worker without a queue.
```bash
clearml-agent execute --id < task-id > --clone
```
#### Execute Task inside a Docker
Execute a Task with a `clearml-agent` worker using a Docker container without a queue.
```bash
clearml-agent execute --id < task-id > --docker
```
### Debugging
2023-01-23 13:04:24 +00:00
Run a `clearml-agent` daemon in foreground mode, sending all output to the console.
2021-05-13 23:48:51 +00:00
```bash
clearml-agent daemon --queue default --foreground
```
## Execution Environments
ClearML Agent supports executing tasks in multiple environments.
### PIP Mode
By default, ClearML Agent works in PIP Mode, in which it uses [pip ](https://en.wikipedia.org/wiki/Pip_(package_manager ))
as the package manager. When ClearML runs, it will create a virtual environment
2023-09-18 07:49:13 +00:00
(or [reuse an existing one ](clearml_agent.md#virtual-environment-reuse )).
2021-05-13 23:48:51 +00:00
Task dependencies (Python packages) will be installed in the virtual environment.
### Conda Mode
This mode is similar to the PIP mode but uses [Conda ](https://docs.conda.io/en/latest/ ) as the package
manager. To enable Conda mode, edit the `clearml.conf` file, and modify the `type: pip` to `type: conda` in the “package_manager” section.
If extra conda channels are needed, look for “conda_channels” under “package_manager”, and add the missing channel.
### Poetry Mode
This mode is similar to the PIP mode but uses [Poetry ](https://python-poetry.org/ ) as the package manager.
To enable Poetry mode, edit the `clearml.conf` file, and modify the `type: pip` to `type: poetry` in the “package_manager”
section.
2022-01-25 16:18:17 +00:00
:::note Using Poetry with Pyenv
Some versions of poetry (using `install-poetry.py` ) do not respect `pyenv global` .
If you are using pyenv to control the environment where you use ClearML Agent, you can:
* Use poetry v1.2 and above (which [fixes this issue ](https://github.com/python-poetry/poetry/issues/5077 ))
* Install poetry with the deprecated `get-poetry.py` installer
:::
2021-05-13 23:48:51 +00:00
### Docker Mode
:::note
Docker Mode is only supported in linux.< br / >
Docker Mode requires docker service v19.03 or higher installed.
:::
When executing the ClearML Agent in Docker mode, it will:
1. Run the provided Docker container
1. Install ClearML Agent in the container
1. Execute the Task in the container, and monitor the process.
ClearML Agent uses the provided default Docker container, which can be overridden from the UI.
2023-09-04 11:37:36 +00:00
:::tip Setting Docker Container via UI
You can set the docker container via the UI:
1. Clone the experiment
2. Set the Docker in the cloned task's **Execution** tab ** > Container** section
2023-09-10 11:25:37 +00:00
![Container section ](img/webapp_exp_container.png )
2023-09-04 11:37:36 +00:00
3. Enqueue the cloned task
The task will be executed in the container specified in the UI.
:::
2022-01-30 10:54:40 +00:00
All ClearML Agent flags (such as `--gpus` and `--foreground` ) are applicable to Docker mode as well.
2021-05-13 23:48:51 +00:00
To execute ClearML Agent in Docker mode, run:
```bash
clearml-agent daemon --queue < execution_queue_to_pull_from > --docker [optional default docker image to use]
```
To use the current `clearml-agent` version in the Docker container, instead of the latest `clearml-agent` version that is
automatically installed, run:
```bash
clearml-agent daemon --queue default --docker --force-current-version
```
For Kubernetes, specify a host mount on the daemon host. Do not use the host mount inside the Docker container.
Set the environment variable `CLEARML_AGENT_K8S_HOST_MOUNT` .
For example:
```
CLEARML_AGENT_K8S_HOST_MOUNT=/mnt/host/data:/root/.clearml
```
## Environment Caching
ClearML Agent caches virtual environments so when running experiments multiple times, there's no need to spend time reinstalling
pre-installed packages. To make use of the cached virtual environments, enable the virtual environment reuse mechanism.
2023-09-04 11:37:36 +00:00
### Virtual Environment Reuse
2021-05-13 23:48:51 +00:00
The virtual environment reuse feature may reduce experiment startup time dramatically.
By default, ClearML uses the package manager's environment caching. This means that even if no
new packages need to be installed, checking the list of packages can take a long time.
ClearML has a virtual environment reuse mechanism which, when enabled, allows using environments as-is without resolving
installed packages. This means that when executing multiple experiments with the same package dependencies,
the same environment will be used.
:::note
ClearML does not support environment reuse when using Poetry package manager
:::
To enable environment reuse, modify the `clearml.conf` file and unmark the venvs_cache section.
```
venvs_cache: {
# maximum number of cached venvs
max_entries: 10
# minimum required free space to allow for cache entry, disable by passing 0 or negative value
free_space_threshold_gb: 2.0
# unmark to enable virtual environment caching
# path: ~/.clearml/venvs-cache
},
```
2021-07-23 09:18:25 +00:00
## Dynamic GPU Allocation
2022-01-13 11:20:11 +00:00
:::important Enterprise Feature
This feature is available under the ClearML Enterprise plan
2021-07-23 09:18:25 +00:00
:::
The ClearML Enterprise server supports dynamic allocation of GPUs based on queue properties.
Agents can spin multiple Tasks from different queues based on the number of GPUs the queue
needs.
`dynamic-gpus` enables dynamic allocation of GPUs based on queue properties.
To configure the number of GPUs for a queue, use the `--queue` flag and specify the queue name and number of GPUs:
```console
clearml-agent daemon --dynamic-gpus --queue dual_gpus=2 single_gpu=1
```
### Example
2022-01-18 11:23:47 +00:00
Let's say a server has three queues:
2021-07-23 09:18:25 +00:00
* `dual_gpu`
* `quad_gpu`
* `opportunistic`
An agent can be spun on multiple GPUs (e.g. 8 GPUs, `--gpus 0-7` ), and then attached to multiple
queues that are configured to run with a certain amount of resources:
```console
2021-08-22 12:08:57 +00:00
clearml-agent daemon --dynamic-gpus --gpus 0-7 --queue quad_gpu=4 dual_gpu=2
2021-07-23 09:18:25 +00:00
```
The agent can now spin multiple Tasks from the different queues based on the number of GPUs configured to the queue.
The agent will pick a Task from the `quad_gpu` queue, use GPUs 0-3 and spin it. Then it will pick a Task from `dual_gpu`
queue, look for available GPUs again and spin on GPUs 4-5.
Another option for allocating GPUs:
```console
2021-08-22 12:08:57 +00:00
clearml-agent daemon --dynamic-gpus --gpus 0-7 --queue dual=2 opportunistic=1-4
2021-07-23 09:18:25 +00:00
```
2022-01-18 11:23:47 +00:00
Notice that a minimum and maximum value of GPUs is specified for the `opportunistic` queue. This means the agent
2021-07-23 09:18:25 +00:00
will pull a Task from the `opportunistic` queue and allocate up to 4 GPUs based on availability (i.e. GPUs not currently
being used by other agents).
2021-05-13 23:48:51 +00:00
## Services Mode
2021-12-01 14:18:55 +00:00
ClearML Agent supports a **Services Mode** where, as soon as a task is launched off of its queue, the agent moves on to the
next task without waiting for the previous one to complete. This mode is intended for running resource-sparse tasks that
are usually idling, such as periodic cleanup services or a [pipeline controller ](references/sdk/automation_controller_pipelinecontroller.md ).
2021-05-13 23:48:51 +00:00
To run a `clearml-agent` in services mode, run:
```bash
clearml-agent daemon --services-mode --queue services --create-queue --docker < docker_name > --cpu-only
```
2022-03-13 10:28:31 +00:00
To limit the number of simultaneous tasks run in services mode, pass the maximum number immediately after the
`--services-mode` option (e.g. `--services-mode 5` )
2021-12-01 14:18:55 +00:00
:::note Notes
* `services-mode` currently only supports Docker mode. Each service spins on its own Docker image.
* The default `clearml-server` configuration already runs a single `clearml-agent` in services mode that listens to the
`services` queue.
2021-05-13 23:48:51 +00:00
:::
2021-12-01 14:18:55 +00:00
Launch a service task like any other task, by enqueuing it to the appropriate queue.
2023-02-09 13:13:17 +00:00
:::caution
2021-12-01 14:18:55 +00:00
Do not enqueue training or inference tasks into the services queue. They will put an unnecessary load on the server.
2021-05-13 23:48:51 +00:00
:::
2021-05-18 22:31:01 +00:00
### Setting Server Credentials
2021-05-13 23:48:51 +00:00
2022-12-26 09:08:10 +00:00
Self-hosted [ClearML Server ](deploying_clearml/clearml_server.md ) comes by default with a services queue.
2022-01-20 12:12:28 +00:00
By default, the server is open and does not require username and password, but it can be [password-protected ](deploying_clearml/clearml_server_security.md#user-access-security ).
2021-12-02 17:53:37 +00:00
In case it is password-protected, the services agent will need to be configured with server credentials (associated with a user).
2021-05-18 22:31:01 +00:00
2023-01-25 11:25:29 +00:00
To do that, set these environment variables on the ClearML Server machine with the appropriate credentials:
2021-05-18 22:31:01 +00:00
```
CLEARML_API_ACCESS_KEY
CLEARML_API_SECRET_KEY
```
2021-06-20 22:00:16 +00:00
2021-07-23 09:18:25 +00:00
## Exporting a Task into a Standalone Docker Container
2021-06-20 22:00:16 +00:00
2021-07-23 09:18:25 +00:00
### Task Container
2021-06-20 22:00:16 +00:00
2021-07-23 09:18:25 +00:00
Build a Docker container that when launched executes a specific experiment, or a clone (copy) of that experiment.
2021-06-20 22:00:16 +00:00
2021-07-23 09:18:25 +00:00
- Build a Docker container that at launch will execute a specific Task.
```bash
clearml-agent build --id < task-id > --docker --target < new-docker-name > --entry-point reuse_task
```
2023-01-25 11:25:29 +00:00
- Build a Docker container that at launch will clone a Task specified by Task ID, and will execute the newly cloned Task.
2021-07-23 09:18:25 +00:00
```bash
clearml-agent build --id < task-id > --docker --target < new-docker-name > --entry-point clone_task
```
- Run built Docker by executing:
```bash
docker run < new-docker-name >
```
2021-06-20 22:00:16 +00:00
2022-09-04 08:45:24 +00:00
Check out [this tutorial ](guides/clearml_agent/executable_exp_containers.md ) for building executable experiment
containers.
2021-07-23 09:18:25 +00:00
### Base Docker Container
2021-06-20 22:00:16 +00:00
2022-09-04 08:45:24 +00:00
Build a Docker container according to the execution environment of a specific task.
2021-06-20 22:00:16 +00:00
2021-07-23 09:18:25 +00:00
```bash
clearml-agent build --id < task-id > --docker --target < new-docker-name >
2021-06-20 22:00:16 +00:00
```
2022-09-04 08:45:24 +00:00
It's possible to add the Docker container as the base Docker image to a task (experiment), using one of the following methods:
2021-06-20 22:00:16 +00:00
2021-07-23 09:18:25 +00:00
- Using the **ClearML Web UI** - See [Base Docker image ](webapp/webapp_exp_tuning.md#base-docker-image ) on the "Tuning
Experiments" page.
2022-03-13 13:07:06 +00:00
- In the ClearML configuration file - Use the ClearML configuration file [agent.default_docker ](configs/clearml_conf.md#agentdefault_docker )
2021-07-23 09:18:25 +00:00
options.
2021-06-20 22:00:16 +00:00
2022-09-04 08:45:24 +00:00
Check out [this tutorial ](guides/clearml_agent/exp_environment_containers.md ) for building a Docker container
replicating the execution environment of an existing task.
2021-07-23 09:18:25 +00:00
## Google Colab
2021-06-20 22:00:16 +00:00
2021-12-02 17:53:37 +00:00
ClearML Agent can run on a [Google Colab ](https://colab.research.google.com/ ) instance. This helps users to leverage
compute resources provided by Google Colab and send experiments for execution on it.
2021-10-05 06:02:44 +00:00
2021-12-05 09:29:59 +00:00
Check out [this tutorial ](guides/ide/google_colab.md ) on how to run a ClearML Agent on Google Colab!
2021-06-20 22:00:16 +00:00
2021-09-09 10:17:46 +00:00
## Scheduling Working Hours
2021-06-20 22:00:16 +00:00
2022-01-13 11:20:11 +00:00
:::important Enterprise Feature
This feature is available under the ClearML Enterprise plan
2021-06-20 22:00:16 +00:00
:::
The Agent scheduler enables scheduling working hours for each Agent. During working hours, a worker will actively poll
queues for Tasks, fetch and execute them. Outside working hours, a worker will be idle.
Schedule workers by:
* Setting configuration file options
* Running `clearml-agent` from the command line (overrides configuration file options)
Override worker schedules by:
* Setting runtime properties to force a worker on or off
* Tagging a queue on or off
2021-09-09 10:17:46 +00:00
### Running clearml-agent with a Schedule (Command Line)
2021-06-20 22:00:16 +00:00
Set a schedule for a worker from the command line when running `clearml-agent` . Two properties enable setting working hours:
2023-02-09 13:13:17 +00:00
:::caution
2021-06-20 22:00:16 +00:00
Use only one of these properties
:::
* `uptime` - Time span during which a worker will actively poll a queue(s) for Tasks, and execute them. Outside this
time span, the worker will be idle.
* `downtime` - Time span during which a worker will be idle. Outside this time span, the worker will actively poll and
execute Tasks.
Define `uptime` or `downtime` as `"<hours> <days>"` , where:
* `<hours>` - A span of hours (`00-23`) or a single hour. A single hour defines a span from that hour to midnight.
* `<days>` - A span of days (`SUN-SAT`) or a single day.
Use `-` for a span, and `,` to separate individual values. To span before midnight to after midnight, use two spans.
For example:
* `"20-23 SUN"` - 8 PM to 11 PM on Sundays.
* `"20-23 SUN,TUE"` - 8 PM to 11 PM on Sundays and Tuesdays.
* `"20-23 SUN-TUE"` - 8 PM to 11 PM on Sundays, Mondays, and Tuesdays.
* `"20 SUN"` - 8 PM to midnight on Sundays.
* `"20-00,00-08 SUN"` - 8 PM to midnight and midnight to 8 AM on Sundays
* `"20-00 SUN", "00-08 MON"` - 8 PM on Sundays to 8 AM on Mondays (spans from before midnight to after midnight).
2021-09-09 10:17:46 +00:00
### Setting Worker Schedules in the Configuration File
2021-06-20 22:00:16 +00:00
Set a schedule for a worker using configuration file options. The options are:
2023-02-09 13:13:17 +00:00
:::caution
2022-05-26 09:31:35 +00:00
Use only one of these properties
2021-06-20 22:00:16 +00:00
:::
* ``agent.uptime``
* ``agent.downtime``
Use the same time span format for days and hours as is used in the command line.
For example, set a worker's schedule from 5 PM to 8 PM on Sunday through Tuesday, and 1 PM to 10 PM on Wednesday.
agent.uptime: ["17-20 SUN-TUE", "13-22 WED"]
2021-09-09 10:17:46 +00:00
### Overriding Worker Schedules Using Runtime Properties
2021-06-20 22:00:16 +00:00
Runtime properties override the command line uptime / downtime properties. The runtime properties are:
2023-02-09 13:13:17 +00:00
:::caution
2021-06-20 22:00:16 +00:00
Use only one of these properties
:::
* `force:on` - Pull and execute Tasks until the property expires.
* `force:off` - Prevent pulling and execution of Tasks until the property expires.
Currently, these runtime properties can only be set using an ClearML REST API call to the `workers.set_runtime_properties`
endpoint, as follows:
* The body of the request must contain the `worker-id` , and the runtime property to add.
2022-01-24 13:42:17 +00:00
* An expiry date is optional. Use the format `"expiry":<time>` . For example, `"expiry":86400` will set an expiry of 24 hours.
* To delete the property, set the expiry date to zero, `"expiry":0` .
2021-06-20 22:00:16 +00:00
For example, to force a worker on for 24 hours:
curl --user < key > :< secret > --header "Content-Type: application/json" --data '{"worker":"< worker_id > ","runtime_properties":[{"key": "force", "value": "on", "expiry": 86400}]}' http://< api-server-hostname-or-ip > :8008/workers.set_runtime_properties
2021-09-09 10:17:46 +00:00
### Overriding Worker Schedules Using Queue Tags
2021-06-20 22:00:16 +00:00
Queue tags override command line and runtime properties. The queue tags are the following:
2023-02-09 13:13:17 +00:00
:::caution
2021-06-20 22:00:16 +00:00
Use only one of these properties
:::
* ``force_workers:on`` - Any worker listening to the queue will keep pulling Tasks from the queue.
* ``force_workers:off`` - Prevent all workers listening to the queue from pulling Tasks from the queue.
Currently, you can set queue tags using an ClearML REST API call to the ``queues.update`` endpoint, or the
APIClient. The body of the call must contain the ``queue-id`` and the tags to add.
For example, force workers on for a queue using the APIClient:
2022-01-24 13:42:17 +00:00
from clearml.backend_api.session.client import APIClient
2021-06-20 22:00:16 +00:00
client = APIClient()
2022-01-24 13:42:17 +00:00
client.queues.update(queue="< queue_id > ", tags=["force_workers:on"]
2021-06-20 22:00:16 +00:00
Or, force workers on for a queue using the REST API:
2022-01-24 13:42:17 +00:00
```bash
curl --user < key > :< secret > --header "Content-Type: application/json" --data '{"queue":"< queue_id > ","tags":["force_workers:on"]}' http://< api-server-hostname-or-ip > :8008/queues.update
```
2023-01-31 12:48:17 +00:00
## References
* See [ClearML Agent CLI ](clearml_agent/clearml_agent_ref.md ) for a reference for `clearml-agent` 's CLI commands.
* See [ClearML Agent Environment Variables ](clearml_agent/clearml_agent_env_var.md ) for a list of environment variables
to configure ClearML Agent