Введение

Привет, Хабр! Сегодня я хочу осветить тему работы с системой контейнеризации Docker прямиком из программы на Rust. Эта статья будет полезна тем, кто хочет разрабатывать различные программы для автоматизации рутинных действий Docker.

Важное предупреждение!

В этой статье продемонстрирован пример работы с Docker контейнером исключительно в контексте получения из него логов. Здесь нет полноценного регламента и плана работы с Docker, в конечном счёте только вам выбирать удобную реализацию для своих целей.

Рентабельность

Не секрет, что Docker стал неотъемлемой частью современного IT-мира. Существует огромное количество инструментов, благодаря которым можно проводить контроль над контейнерами. Не редко появляется необходимость автоматизировать рутинный процесс. Для решения таких задач отлично подходит язык программирования Rust с крейтом Bollard.

Подключение к Docker

Самой важной частью статьи является подключение к Docker. Для работы с Docker существует крейт bollard. Крейт предоставляет широкий спектр возможностей, начиная от подключения к контейнеру разными способами (о которых поговорим чуть позже), заканчивая различными возможностями управления. Перечень основных методов подключения:

Docker::connect_with_defaults() - Основной метод подключения, который в случае Unix использует сокет, а в случае Windows именованный канал named pipe или HTTP. Методы подключения здесь можно определить с помощью переменной DOCKER_HOST.
Docker::connect_with_socket_defaults() - Прямое подключение к стандартному Unix-сокету (/var/run/docker.sock) или Windows каналу.
Docker::connect_with_http_defaults() - Подключение с использованием незащищённого протокола HTTP, как правило, использует порт 2375.
Docker::connect_with_ssl_defaults() - Подключение с использованием защищённого протокола HTTPS, использует сертификаты из переменной окружения DOCKER_CERT_PATH, как правило, использует порт 2376.
Docker::connect_with_ssh_defaults() - Подключение через SSH-тунель.
Docker::connect_with_podman_defaults() - Подключение к сокету Podman с автоматическим определением (rotless/system).

Выбор подключения всегда остаётся за вами и зависит от вашей архитектуры, но по умолчанию рекомендуется использовать Docker::connect_with_defaults().

С подключением должно быть понятно, а для основных операций над контейнерами рекомендую обратить внимание на структуру Docker, так как именно с ней и придётся взаимодействовать, там множество различных методов, суть которых переписывать сюда не вижу смысла, но должен перечислить основные возможности:

Работа с конфигурационными файлами контейнеров (к примеру nginx.conf), а именно их создание, редактирование, удаление и обновление. Будьте бдительны! Эти методы не подходят для создания конфигурационных файлов с конфиденциальной информацией! Также имейте в виду, что методы работают только в Swarm.
Управление контейнерами, а именно: получение списка контейнеров, их создание, удаление, редактирование, получение информации и перезагрузка (также есть функционал ожидания завершения wait).
Получение логов из контейнера (эта тема будет более подробно рассмотрена ниже).
Получение изменений в файловой системе контейнера.
Получение статистики контейнера на основе используемых ресурсов.
Операции по работе с “чекпоинтами” (снимков состояния работающего контейнера) Эти функции экспериментальные! Будьте осторожны при их использовании!.

Пример реализации программы

Для большего понимания, хотелось бы предоставить пример рабочего кода и немного его разобрать. Вот ссылка на Github, где вы можете ознакомиться с кодом более подробно, а также протестировать программу, произведя клонирование репозитория и собрав проект.

Для подключения к Docker в этой программе используется стандартный метод Docker::connect_with_defaults():

pub async fn connect_to_docker() -> Docker {
    let docker = match Docker::connect_with_defaults() {
        Ok(docker) => { docker }
        Err(_) => { 
            eprintln!("Error connecting to Docker!");
            std::process::exit(1);
        }
   };

   docker
}

Для обработки ошибок в этой программе я не использовал распространённые крейты thiserror или anyhow, так как программа достаточно маленькая, не вижу смысла добавлять дополнительные зависимости для этого.

Как уже было сказано выше, эта программа нужна для получения логов из контейнера Docker. Для того чтобы получить логи, необходимо использовать метод Docker::logs(), который принимает два аргумента: имя контейнера (id) и опции к подключению и получению логов. Ниже предоставлена функция для генерации опций:

pub fn create_log_options(since: i32) -> LogsOptions {
    let options = LogsOptions {
        follow: false, 
        stdout: true, 
        stderr: true, 
        timestamps: true,
        tail: "all".to_string(),
        since,
        until: 0 
    };
    options
}

В контексте моей реализации эта функция генерирует опции с заданным параметров since. Давайте рассмотрим более подробно имеющиеся параметры:

follow - необходимо ли поддерживать соединение после вывода логов?
stdout - вывод логов из стандартного потока.
stderr - вывод логов из потока с ошибками.
timestamps - добавлять ли метки времени в каждую линию логов? Этот параметр необходим для работы since и until.
tail - количество логов, можно вернуть как все all, так и какое-то определённое количество с помощью указания целого числа.
since - возвращать логи только с определённого времени (значение в виде временной метки UNIX).
until - возвращать логи только до определённого времени (значение в виде временной метки UNIX).

Метод Docker::logs() возвращает не просто данные в формате вектора или HashMap, а Stream (поток), который и надо обрабатывать, а для работы с потоками использовался крейт futures. Если вы не желаете получать логи в реальном времени, а хотите использовать лишь разовое получение, тогда вы установите в опциях значение fallow на false и сможете сделать вывод, подобный этому:

pub async fn connect_and_get_logs(docker: &Docker, container_id: &String, options: LogsOptions) {

    let logs: Vec<LogOutput> = match docker.logs(&container_id, Some(options)) 
        .try_collect()
        .await {
            Ok(logs) => { logs }
            Err(_) => { 
                eprintln!("Error getting logs! Check Docker or container");
                std::process::exit(1);
            }
        };
        
    for log in logs {
       println!("{}", SelectLogs(log));
    }
}

Здесь поток вывода отдаёт данные и сразу же завершается, позволяя записать данные в вектор с типом LogOutput. Если есть необходимость выводить или же получать логи в реальном времени, то стоит использовать follow: true и уже напрямую обрабатывать поток:

pub async fn connect_and_get_logs_follow(docker: &Docker, container_id: &String) -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
    let options = LogsOptions {
        follow: true, 
        stdout: true, 
        stderr: true, 
        timestamps: true,
        tail: "all".to_string(),
        since: 0,
        until: 0 
    };
   
   let mut logs = docker.logs(container_id, Some(options));
 while let Some(log_result) = logs.next().await {
     match log_result {
         Ok(LogOutput::StdOut { message }) => {
             println!("\n");
             println!("{:?}", message);
         }
         Ok(LogOutput::StdErr { message }) => {
             println!("\n");
             println!("{:?}", message);
         }
         _ => {}
         }
     };
 
    Ok(())
}

В этом примере уже используется futures::StreamExt для поддержки метода .next(). Необходимо понимать, что поток - это не гарант наличия данных, а лишь “контракт”, что если данные будут, они будут поставлены. Следовательно, для поддержки функционирования программы необходимо использовать цикл while let, который будет работать, пока есть поток. Так как LogOutput имеет разные вариации вывода, необходимо использовать match для получения данных из конкретного потока.

Заключение

Работа с Docker - это куда более сложный процесс, который невозможно вместить в одну статью. Bollard предоставляет удобную основу для написания различных программ, а Rust позволит сделать эти программы достаточно быстрыми и безопасными. Если статья стала для вас полезной можете добавить её в избранное, а также использовать мою небольшую программу как шаблон для тестирования возможностей bollard, путём создания собственных реализаций, форков. Благодарю вас за внимание!

Rust и Docker