Contact UsGet started

Installing and updating Yandex Unified Agent

Written by
Updated at April 28, 2025

List of supported operating systems

Unified Agent is supported by the following operating systems:

  • Ubuntu 16.04 or higher (you can install it using any method).
  • Debian 9 or higher (Docker image, deb package, or binary file).
  • CentOS 7 or higher (Docker image).
  • Fedora 32 or higher (Docker image).
  • Fedora CoreOS (Docker image).

Before you begin installation

Prior to installing Yandex Unified Agent, follow these steps:

  1. Create a VM in Yandex Cloud or a host outside Yandex Cloud on one of the supported operating systems, e.g., Ubuntu 16.04 or higher.

  2. (Optional) Install Docker if you want to use Docker to run Unified Agent. Docker is pre-installed in Fedora CoreOS.

  3. Create a service account in the folder you want to write metrics to and assign it the monitoring.editor role.

  4. Set up agent authorization in the Yandex Monitoring API:

Installation

Install Unified Agent using one of the following methods:

Unified Agent is distributed as a Docker image. The image is published in the cr.yandex/yc repository with the unified_agent name and the latest tag. The image includes a binary file with the agent and a configuration file used to set up the agent for Linux system metric delivery in Yandex Monitoring.

To upload a Docker image, run this command:

sudo docker pull cr.yandex/yc/unified-agent:latest

Unified Agent is distributed as a deb package for Ubuntu 16.04 or higher. The package contains a binary file with the agent and an empty configuration file located at /etc/yandex/unified_agent/config.yml.

To install Unified Agent:

  1. Download the latest deb package:

    ubuntu_name="<OS_version>" \
ua_version=$(curl --silent https://storage.yandexcloud.net/yc-unified-agent/latest-version) \
bash -c 'curl --silent --remote-name https://storage.yandexcloud.net/yc-unified-agent/releases/${ua_version}/deb/${ubuntu_name}/yandex-unified-agent_${ua_version}_amd64.deb'

    Where ubuntu_name is the operating system version:

    • ubuntu-16.04-xenial
    • ubuntu-18.04-bionic
    • ubuntu-20.04-focal
    • ubuntu-22.04-jammy (starting with 23.03.02)
    • ubuntu-24.04-noble

    You can also download a specific Unified Agent version. To do this, check the available versions and specify the one you need instead of latest-version:

    curl --silent https://storage.yandexcloud.net/yc-unified-agent/all-versions

  2. Check the downloaded deb package version using the ls command.

  3. Run this command:

    sudo dpkg -i yandex-unified-agent_<version>_amd64.deb

    Where <version> is the downloaded deb package version, e.g., 24.12.01.

Unified Agent is distributed as a binary file built for the x86-64/amd64 architecture for Ubuntu 16.04 or higher.

To download the latest version of the agent's binary file, run:

ua_version=$(curl --silent https://storage.yandexcloud.net/yc-unified-agent/latest-version) \
bash -c 'curl --silent --remote-name https://storage.yandexcloud.net/yc-unified-agent/releases/$ua_version/unified_agent && chmod +x ./unified_agent'

You can install Unified Agent when creating a VM through the management console, CLI, API, or Terraform.

To install the agent from the management console, enable Agent for delivering metrics under Monitoring.

To install the agent via the CLI, API, or Terraform, provide the following string in the user metadata (user-data):

#cloud-config\nruncmd:\n  - wget -O - https://monitoring.api.cloud.yandex.net/monitoring/v2/unifiedAgent/config/install.sh | bash

To install the agent and send metrics, make sure the VM has access to the internet.

The agent is installed with a default configuration file located at /etc/yc/unified_agent/config.yml.

The configuration file is set up to send basic virtual machine metrics and agent health metrics. You will be charged for metric delivery.

You can also configure the delivery of custom metrics or logs to Cloud Logging.

Once the VM is deployed, Unified Agent will be started automatically and begin delivering basic VM metrics to Yandex Monitoring.

Update the agent manually via a binary file.

Updating

Update Unified Agent using one of the following methods:

  1. Stop the ua container:

    sudo docker stop ua

  2. Delete the container:

    sudo docker rm ua

  3. Run the container.

Re-download and install the deb package:

  1. Download the latest deb package:

    ubuntu_name="<OS_version>" \
ua_version=$(curl --silent https://storage.yandexcloud.net/yc-unified-agent/latest-version) \
bash -c 'curl --silent --remote-name https://storage.yandexcloud.net/yc-unified-agent/releases/${ua_version}/deb/${ubuntu_name}/yandex-unified-agent_${ua_version}_amd64.deb'

    Where ubuntu_name is the operating system version:

    • ubuntu-16.04-xenial
    • ubuntu-18.04-bionic
    • ubuntu-20.04-focal
    • ubuntu-22.04-jammy (starting with 23.03.02)
    • ubuntu-24.04-noble

    You can also download a specific Unified Agent version. To do this, check the available versions and specify the one you need instead of latest-version:

    curl --silent https://storage.yandexcloud.net/yc-unified-agent/all-versions

  2. Check the downloaded deb package version using the ls command.

  3. Run this command:

    sudo dpkg -i yandex-unified-agent_<version>_amd64.deb

    Where <version> is the downloaded deb package version, e.g., 24.12.01.

  1. Delete the existing agent binary file.

  2. Download the latest version of the agent as a binary file:

    ua_version=$(curl --silent https://storage.yandexcloud.net/yc-unified-agent/latest-version) \
bash -c 'curl --silent --remote-name https://storage.yandexcloud.net/yc-unified-agent/releases/$ua_version/unified_agent && chmod +x ./unified_agent'

  3. Once you have downloaded the agent executable, create a configuration file, e.g., with settings for delivering Linux system metrics. For more information on agent configuration, see Configuration.

  4. Move the downloaded file to the /bin/unified_agent folder.

  5. Restart the agent.

To find out all available versions of the agent, run this command:

curl --silent https://storage.yandexcloud.net/yc-unified-agent/all-versions

  1. Delete the existing agent binary file.

  2. Download the latest version of the agent as a binary file:

    ua_version=$(curl --silent https://storage.yandexcloud.net/yc-unified-agent/latest-version) \
bash -c 'curl --silent --remote-name https://storage.yandexcloud.net/yc-unified-agent/releases/$ua_version/unified_agent && chmod +x ./unified_agent'

  3. Once you have downloaded the agent executable, create a configuration file, e.g., with settings for delivering Linux system metrics. For more information on agent configuration, see Configuration.

  4. Move the downloaded file to the /bin/unified_agent folder.

  5. Restart the agent.

To find out all available versions of the agent, run this command:

curl --silent https://storage.yandexcloud.net/yc-unified-agent/all-versions

What's next

Previous
Overview
Next
Starting and stopping