[Yandex Cloud documentation](../../../../index.md) > [Monium](../../../index.md) > Data delivery > [Unified Agent](index.md) > Installing and updating # Installing and updating Yandex Unified Agent {% note info %} As of version 25.03.80, Unified Agent can collect and transmit Prometheus metrics. {% endnote %} For more information, see [Prometheus metric collection agent](../../../operations/prometheus/ingestion/prometheus-agent.md). ## List of supported operating systems {#supported-os} Unified Agent is supported by the following operating systems: - Ubuntu 16.04 or higher (you can [install it using any method](#setup)). - 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 {#before-you-begin} Prior to installing Yandex Unified Agent, follow these steps: 1. Create a VM in Yandex Cloud or a host outside of Yandex Cloud on one of the [supported operating systems](#supported-os), e.g., Ubuntu 16.04 or higher. 1. Optionally, [install Docker](https://docs.docker.com/install/) if you want to use Docker to run Unified Agent. Docker is pre-installed in Fedora CoreOS. - Set up a public IPv4 address (recommended). - [Configure Docker to work with IPv6](https://docs.docker.com/config/daemon/ipv6) and [enable network address translation](https://medium.com/@skleeschulte/how-to-enable-ipv6-for-docker-containers-on-ubuntu-18-04-c68394a219a2) if you cannot use a public IPv4 address. 1. [Create a service account](../../../../iam/operations/sa/create.md) in the folder you want to write metrics to and [assign it](../../../../iam/operations/sa/assign-role-for-sa.md) the `monitoring.editor` role. 1. Set up agent authorization in the Monium API: - If the agent is installed on a VM in Yandex Cloud, [link the service account you created](../../../../compute/operations/vm-connect/auth-inside-vm.md#link-sa-with-instance) to the VM. This way, the agent will automatically get the service account IAM token from the metadata service. - If the agent is installed on a host outside Yandex Cloud, [create an authorized key](../../../../iam/operations/authentication/manage-authorized-keys.md#create-authorized-key) for service accounts. For more information about delivering metrics from hosts outside Yandex Cloud, see [Delivering metrics from hosts outside Yandex Cloud](../../../operations/unified-agent/non-yc.md). ## Installation {#setup} Install Unified Agent using one of the following methods: {% list tabs group=unified_agent %} - Docker image {#docker} Install Docker Engine. Use [this guide](https://docs.docker.com/engine/install/#supported-platforms) to install and run Docker for your operating system. 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](../../../operations/unified-agent/linux_metrics.md) in Monium. To upload a Docker image, run this command: ```bash sudo docker pull cr.yandex/yc/unified-agent:latest ``` - deb package {#deb} Unified Agent is distributed as a deb package for Ubuntu 16.04 or higher and Debian 9 or higher. The package contains a binary file with the agent and a configuration file located at `/etc/yandex/unified_agent/config.yml`. To install Unified Agent: 1. Download the latest deb package version: ```bash ubuntu_name="" \ ua_version=$(curl --silent https://storage.yandexcloud.net/yc-unified-agent/latest-version) 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 in `ubuntu--` format. Specify the value exactly as it is used in the package folder name: * `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` {% note info %} When installing Unified Agent on Debian 9, only deb packages for `ubuntu-16.04-xenial` and lower are supported; on Debian 10, only packages for `ubuntu-18.04-bionic` and lower are supported. {% endnote %} If you do not know the exact `ubuntu_name` value, display the list of available options for the latest Unified Agent version: ```bash ua_version=$(curl --silent https://storage.yandexcloud.net/yc-unified-agent/latest-version) aws s3 ls s3://yc-unified-agent/releases/${ua_version}/deb/ \ --endpoint-url https://storage.yandexcloud.net \ --no-sign-request | awk '{print $2}' | tr -d '/' ``` You can also download a specific Unified Agent version. Do it by looking up the available versions and specifying the one you need instead of `latest-version`: ```bash curl --silent https://storage.yandexcloud.net/yc-unified-agent/all-versions ``` 1. Check the downloaded `deb` package version using the `ls` command. Result: ```bash yandex-unified-agent__amd64.deb ``` Where `` is the downloaded `deb` package version, e.g., `24.12.01`. 1. To install the downloaded deb package, run this command: ```bash sudo dpkg -i yandex-unified-agent__amd64.deb ``` 1. To make sure Unified Agent is successfully installed and started, run this command: ```bash systemctl status unified-agent ``` Result: ```bash ● unified-agent.service - Yandex Unified Agent service Loaded: loaded (/lib/systemd/system/unified-agent.service; enabled; vendor preset: enabled) Active: active (running) since Wed 2025-10-01 08:49:44 UTC; 27min ago Main PID: 1106 (unified_agent) Tasks: 8 (limit: 2308) Memory: 5.2M CPU: 136ms CGroup: /system.slice/unified-agent.service └─1106 /usr/bin/unified_agent --config /etc/yandex/unified_agent/config.yml --log-priority NOTICE ``` The Unified Agent installation involves the following steps: * Installing the `unified_agent` executable. * Installing the main configuration file. The configuration file is set up to send [basic VM metrics](../../../../monitoring/concepts/data-collection/unified-agent/inputs.md#linux_metrics_input) and [agent health metrics](../../../../monitoring/concepts/data-collection/unified-agent/inputs.md#agent_metrics_input). You will be [charged](../../../../monitoring/pricing.md) for metric delivery. You can also [configure](../../../../monitoring/concepts/data-collection/unified-agent/configuration.md) the delivery of custom metrics or [logs to Monium.Logs](../../../../monitoring/concepts/data-collection/unified-agent/outputs.md#yc_logs_output). * Configuring the initialization system and adding the new `unified-agent` service. This service runs at system startup. * Creating the `unified_agent` user with uid `1515` and a group with the same name and gid `1515`. If these uid and gid are not available (already in use), the user and group are created without explicitly specifying any uid and gid. * Creating and configuring access to the `/etc/yandex/unified_agent/conf.d` custom configuration directory. * Creating and configuring access to the `/var/lib/yandex/unified_agent` custom storage directory. - Binary file {#binary} 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: ```bash 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' ``` - When creating a VM {#vm} 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](https://console.yandex.cloud), enable **Monitoring** under **Agent for delivering metrics**. To install the agent via the CLI, API, or Terraform, provide the following string in the [user metadata](../../../../compute/concepts/metadata/sending-metadata.md) (`user-data`): ```text #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 Unified Agent installation involves the following steps: * Installing the `unified_agent` executable. * Installing the main configuration file. The configuration file is set up to send [basic VM metrics](../../../../monitoring/concepts/data-collection/unified-agent/inputs.md#linux_metrics_input) and [agent health metrics](../../../../monitoring/concepts/data-collection/unified-agent/inputs.md#agent_metrics_input). You will be [charged](../../../../monitoring/pricing.md) for metric delivery. You can also [configure](../../../../monitoring/concepts/data-collection/unified-agent/configuration.md) the delivery of custom metrics or [logs to Monium.Logs](../../../../monitoring/concepts/data-collection/unified-agent/outputs.md#yc_logs_output). * Configuring the initialization system and adding the new `unified-agent` service. This service runs at system startup. * Creating the `unified_agent` user with uid `1515` and a group with the same name and gid `1515`. If these uid and gid are not available (already in use), the user and group are created without explicitly specifying any uid and gid. * Creating and configuring access to the `/etc/yandex/unified_agent/conf.d` custom configuration directory. * Creating and configuring access to the `/var/lib/yandex/unified_agent` custom storage directory. Once the VM is deployed, Unified Agent will be started automatically and begin delivering basic VM metrics to Monium. Update the agent manually via a binary file. {% endlist %} ## Updating {#update} Update Unified Agent using one of the following methods: {% list tabs group=unified_agent %} - Docker image {#docker} 1. Stop the `ua` container: ```bash sudo docker stop ua ``` 1. Delete the container: ```bash sudo docker rm ua ``` 1. [Run](run-and-stop.md#run) the container. - deb package {#deb} Re-download and [install](#setup) the latest deb package. - Binary file {#binary} 1. Delete the existing agent binary file. 1. Download the latest version of the agent as a binary file: ```bash 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' ``` 1. Once you have downloaded the agent executable, create a configuration file, e.g., with settings for [delivering Linux system metrics](../../../../monitoring/operations/unified-agent/linux_metrics.md). For more information on agent configuration, see [Configuration](../../../../monitoring/concepts/data-collection/unified-agent/configuration.md). 1. Move the downloaded file to the `/bin/unified_agent` folder. 1. [Restart](../../../../monitoring/concepts/data-collection/unified-agent/run-and-stop.md#run) the agent. To find out all available versions of the agent, run this command: ```(bash) curl --silent https://storage.yandexcloud.net/yc-unified-agent/all-versions ``` - When creating a VM {#vm} 1. Delete the existing agent binary file. 1. Download the latest version of the agent as a binary file: ```bash 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' ``` 1. Once you have downloaded the agent executable, create a configuration file, e.g., with settings for [delivering Linux system metrics](../../../../monitoring/operations/unified-agent/linux_metrics.md). For more information on agent configuration, see [Configuration](../../../../monitoring/concepts/data-collection/unified-agent/configuration.md). 1. Move the downloaded file to the `/bin/unified_agent` folder. 1. [Restart](../../../../monitoring/concepts/data-collection/unified-agent/run-and-stop.md#run) the agent. To find out all available versions of the agent, run this command: ```(bash) curl --silent https://storage.yandexcloud.net/yc-unified-agent/all-versions ``` {% endlist %} ## Installation and configuration example {#example} This example shows how to install Unified Agent from a deb package and configure it to collect metrics. To set up Unified Agent on a virtual machine, follow these steps: 1. [Create a service account](../../../../iam/operations/sa/create.md) in the folder you want to write metrics to and [assign it](../../../../iam/operations/sa/assign-role-for-sa.md) the `monitoring.editor` role. 1. [Create](../../../../compute/operations/vm-create/create-linux-vm.md) your VM. Under **Additional**, select the service account you created in the previous step. 1. [Connect to the VM over SSH](../../../../compute/operations/vm-connect/ssh.md). 1. Install Unified Agent: 1. Get superuser privileges: ```bash sudo -i ``` 1. Download the deb package with the latest version of Unified Agent for your OS (e.g., `ubuntu-22.04-jammy`): ```bash ubuntu_name="ubuntu-22.04-jammy" ua_version=$(curl -s https://storage.yandexcloud.net/yc-unified-agent/latest-version) bash -c 'curl -s -O https://storage.yandexcloud.net/yc-unified-agent/releases/${ua_version}/deb/${ubuntu_name}/yandex-unified-agent_${ua_version}_amd64.deb' ``` The command will find the latest version of Unified Agent and download its deb package to your VM. 1. Install the Unified Agent version from the package (e.g., `24.07.02`): ```bash dpkg -i yandex-unified-agent_24.07.02_amd64.deb ``` 1. Check the Unified Agent status: ```bash systemctl status unified-agent.service ``` {% cut "Result" %} ```bash unified-agent.service - Yandex Unified Agent service Loaded: loaded (/usr/lib/systemd/system/unified-agent.service; enabled; preset: enabled) Active: active (running) since Mon 2024-08-19 17:32:24 UTC; 1min 49s ago Main PID: 7106 (unified_agent) Tasks: 7 (limit: 2275) Memory: 3.6M (peak: 3.9M) CPU: 19ms CGroup: /system.slice/unified-agent.service └─7106 /usr/bin/unified_agent --config /etc/yandex/unified_agent/config.yml --log-priority NOTICE CGroup: /system.slice/unified-agent.service Aug 19 17:32:24 ua-test-vm systemd[1]: Started unified-agent.service - Yandex Unified Agent service. Aug 19 17:32:24 ua-test-vm unified_agent[7106]: 2024-08-19T17:32:24.815279Z 7106 15778840110569512124 NOTICE agent starting, revision [14433827] Aug 19 17:32:24 ua-test-vm unified_agent[7106]: 2024-08-19T17:32:24.815307Z 7106 15778840110569512124 NOTICE agent monitoring service [:16300] Aug 19 17:32:24 ua-test-vm unified_agent[7106]: 2024-08-19T17:32:24.815632Z 7106 15778840110569512124 NOTICE agent status service [localhost:16301] Aug 19 17:32:24 ua-test-vm unified_agent[7106]: 2024-08-19T17:32:24.816002Z 7106 15778840110569512124 NOTICE agent started ``` {% endcut %} 1. Configure Unified Agent: 1. Open the Unified Agent configuration file: ```bash vim /etc/yandex/unified_agent/config.yml ``` 1. Add the metrics collection settings to the configuration file. The final file should look like this: ```yaml monitoring: port: 16300 status: port: 16301 channels: - name: yc_metrics_channel channel: output: plugin: yc_metrics config: folder_id: "a1bs81qpemb4********" iam: cloud_meta: {} routes: - input: id: linux_metrics_input plugin: linux_metrics config: poll_period: 60s channel: channel_ref: name: yc_metrics_channel import: - /etc/yandex/unified_agent/conf.d/*.yml ``` 1. Restart Unified Agent: ```bash systemctl restart unified-agent.service ``` 1. Check the Unified Agent status: ```bash systemctl status unified-agent.service ``` Check the collected metrics: {% list tabs group=instructions %} - Management console {#console} 1. In the [management console](https://console.yandex.cloud), select the folder where metrics are collected. 1. Navigate to **Monium**. 1. In the left-hand panel, select ![image](../../../../_assets/console-icons/rectangle-pulse.svg) **Metrics**. 1. In the query editor, in the ![image](../../../../_assets/monitoring/chart.svg) line with the cloud and folder names, specify the following: * `service` = `custom` * `cluster` = `default` * `name` = `memory.Active` * `host` = ``. 1. Click **Execute query**. The chart that appears will display metrics collected by Unified Agent. {% endlist %} #### What's next {#what-is-next} - [Learn how to run and stop Unified Agent](run-and-stop.md) - [Read about Unified Agent concepts](index.md) - [Learn more about configuring Unified Agent](configuration.md) - [Read the Unified Agent operating guidelines](best-practices.md)