DigitalOcean Metadata: как использовать и обезопасить

Логотип DigitalOcean

Быстрые ссылки

Default Metadata
Metadata Fields
Getting All Available Metadata
User Data
Other Ways of Accessing Metadata
Summary

Введение

Служба метаданных DigitalOcean дает Droplet доступ к информации о самом инстансе и его окружении. Кроме системных полей, вы можете передавать произвольные данные (user-data), чтобы делать конфигурацию и автоматизацию переносимой и предсказуемой.

Главный адрес службы метаданных — это специальный link-local IP:

169.254.169.254

Подключитесь к Droplet по SSH и экспериментируйте через curl или любой HTTP-клиент.

Как получить базовый список полей

Простой запрос выдаст список доступных полей:

curl http://169.254.169.254/metadata/v1/

Скриншот вывода полей сервиса метаданных DigitalOcean

Чтобы получить конкретное поле, добавьте его имя к базовому URL:

curl http://169.254.169.254/metadata/v1/id

Команда вернёт IP-адрес или другой формат в зависимости от поля. Это удобно для вставки в сценарии без сложного парсинга JSON.

Доступные поля метаданных

Ниже перечислены основные поля, которые просматриваются через metadata API:

id — IP-адрес Droplet (публичный адрес, если он назначен).
hostname — имя хоста Droplet, совпадает с именем, указанным при создании (может не совпадать с /etc/hostname, если вы изменяли его вручную).
user-data — пользовательские данные, предоставленные при создании Droplet (обычно cloud-init конфигурация).
vendor-data — данные, предоставленные DigitalOcean для конфигурации Droplet.
public-keys — SSH-публичные ключи, добавленные при создании; автоматически добавляются в аккаунт root.
region — регион дата-центра (например, nyc1, lon1).
interfaces — информация о сетевых интерфейсах; содержит private и public массивы объектов с полями ipv4 и mac.
floating_ip — сведения о Floating IP, если он назначен Droplet.
dns — подполе nameservers с используемыми системой DNS-серверами.
tags — список пользовательских тегов, назначенных Droplet.
features — объект с активированными возможностями DigitalOcean для Droplet.

Поля с вложенными объектами или массивы можно обойти через REST-пути. Пример: получить IP первого приватного интерфейса:

curl http://169.254.169.254/metadata/v1/interfaces/private/0/ipv4/address

Эта модель упрощает извлечение одиночных значений для скриптов.

Получение всех метаданных в JSON

Чтобы получить полный набор метаданных в формате JSON, добавьте суффикс .json:

curl http://169.254.169.254/metadata/v1.json

В JSON-представлении символ - в именах полей преобразуется в _.

User Data и cloud-init

При создании Droplet вы можете передать user-data через форму в панели управления или флаг --user-data командной строки doctl compute droplet create. Содержимое user-data доступно через поле user-data в metadata API.

User-data неизменяемо после создания Droplet — оно предназначено для первичной конфигурации. Чаще всего это cloud-config YAML, который обрабатывается cloud-init при первом запуске.

Пример корректной cloud-config конфигурации (YAML), которая обновляет пакеты, создаёт файл и пользователя:

#cloud-config
users:
  - name: example
    groups: sudo
    shell: /bin/bash
write_files:
  - path: /example.txt
    content: "Произвольные данные здесь"
package_update: true
packages: []

Поместите такой YAML в поле user-data при создании Droplet — cloud-init выполнит инструкции при первом запуске.

Important: user-data нельзя изменить после создания Droplet; если нужна изменяемая конфигурация, храните её во внешнем хранилище или в конфиг-сервере.

Примеры использования в скриптах

Получить ID и использовать в doctl для создания snapshot’а:

DROPLET_ID=$(curl -s http://169.254.169.254/metadata/v1/id)
doctl compute snapshot create --droplet-id "$DROPLET_ID" --name "pre-upgrade-$(date +%F)"

Получить приватный IP и настроить приложение:

PRIVATE_IP=$(curl -s http://169.254.169.254/metadata/v1/interfaces/private/0/ipv4/address)
sed -i "s/{{HOST_IP}}/$PRIVATE_IP/" /etc/myapp/config.yml
systemctl restart myapp

Простая проверка доступности metadata-сервиса:

if curl -s --max-time 2 http://169.254.169.254/metadata/v1/ >/dev/null; then
  echo "metadata доступна"
else
  echo "metadata недоступна — проверьте сетевые настройки или cloud-init"
fi

Другие способы доступа к данным Droplet

Сама метадата доступна только изнутри Droplet. Ни Doctl CLI, ни основной REST API DigitalOcean не возвращают точно ту же структуру, что сервис внутри Droplet. Чтобы получить похожие сведения извне, используйте:

doctl compute droplet get — возвращает большую часть информации о Droplet, включая сеть, теги и ограничения ресурсов.
Основной REST API DigitalOcean (через токен) — для получения списка дроплетов, их IP, тегов и т.д.

Если нужна централизованная конфигурация или изменяемые параметры, храните их в внешнем хранилище (Vault, S3-совместимое хранилище, конфиг-сервер) и передавайте ссылку или креденшелы через user-data.

Когда метаданные недоступны — примеры ошибок и причины

Сетевой стек на Droplet настроен так, что link-local адреса блокируются или маршрутизируются неправильно.
Брандмауэр (iptables/ufw) или политики SELinux/AppArmor ограничивают исходящие соединения к 169.254.169.254.
Если образ ОС внутри Droplet радикально изменён и не поддерживает curl/HTTP (редкий кейс), доступ будет затруднён.
user-data изменяемо только до создания — попытки обновить его после создания не приведут к результату.

Эти случаи полезно учитывать при написании робустных скриптов: добавляйте таймауты, проверки и механизмы отката.

Безопасность и приватность

Metadata API доступен любому процесса внутри Droplet. Не храните в user-data чувствительные секреты (пароли, токены) в открытом виде.
Если нужно передать секреты, лучше использовать один из следующих подходов: передавать URL зашифрованного секрета + ключ для расшифровки, или использовать систему управления секретами (HashiCorp Vault, AWS Secrets Manager) с кратковременными учётными данными.
Логи cloud-init могут хранить часть user-data — проверьте политику логирования и очистку временных файлов.
GDPR/конфиденциальность: если user-data содержит персональные данные, убедитесь, что вы выполняете требования хранения и удаления данных в вашей юрисдикции.

Рекомендация: держите минимальный набор конфигурации в user-data, используйте metadata для идентификации и обнаружения, а не для хранения секретов.

Мини‑методология: как безопасно использовать metadata при развёртывании

План: определите, какая информация действительно нужна экземпляру при первом запуске.
Минимизируйте user-data: передавайте только конфигурацию и ссылку на секреты.
Защитите доступ: ограничьте, что записывается в логи и временные файлы.
Отказоустойчивость: скрипты должны корректно обрабатывать недоступность metadata (таймаут, повторы, fallback).
Инвентаризация: используйте теги и region для фильтрации Droplet через API извне.

Чек-листы по ролям

DevOps / SRE:

Проверить доступ к 169.254.169.254 из образа.
Использовать metadata для автоматического конфигурирования сети и мониторинга.
Не хранить секреты в user-data.

Разработчик приложения:

Учитывать, что hostname может отличаться от /etc/hostname.
Делать конфигурацию приложения параметризуемой (использовать переменные окружения или шаблоны).

Инженер безопасности:

Проверить, что sensitive data не попадает в user-data.
Настроить аудит и ротацию секретов через внешние сервисы.

Шпаргалка (cheat sheet)

Базовый список полей: curl http://169.254.169.254/metadata/v1/
Полный JSON: curl http://169.254.169.254/metadata/v1.json
Приватный IP: curl http://169.254.169.254/metadata/v1/interfaces/private/0/ipv4/address
User-data: curl http://169.254.169.254/metadata/v1/user-data

Критерии приёмки (тесты / acceptance)

Скрипт успешно получает droplet ID: проверка curl http://169.254.169.254/metadata/v1/id возвращает непустую строку.
Скрипт корректно обрабатывает таймаут: при искусственной недоступности metadata выводится понятная ошибка и применяется fallback.
Cloud-init применяет user-data: проверка файла /example.txt создан и содержит ожидаемое содержимое.
Секреты не записаны в логи: в /var/log облачные логи не содержат чувствительной информации.

Контраргументы / Когда metadata не решит задачу

Если вам нужен централизованный, изменяемый конфиг для множества инстансов, metadata отдельных Droplet не заменит конфиг-сервер.
Если необходима высокая безопасность хранения секретов, metadata (user-data) не лучший выбор.
Для аудита и историзации изменений следует использовать централизованные API и инструменты управления конфигурацией.

Короткая сводка и рекомендации

Metadata — это инструмент для локальной самоидентификации Droplet и начальной автоматизации. Используйте его для передачи неизменяемых параметров и первичной конфигурации (cloud-init). Для обновляемых и конфиденциальных данных применяйте внешние хранилища секретов и API.

Notes: метаданные специфичны для каждого Droplet; для поиска других инстансов используйте основной API DigitalOcean или doctl.

Факты — витрина ключевых значений

Адрес metadata: 169.254.169.254 (link-local).
Формат полного ответа: JSON при запросе /metadata/v1.json.
User-data — неизменяем во время жизненного цикла Droplet.

Глоссарий (одна строка каждое)

metadata: локальная служба, возвращающая данные о Droplet и окружении.
user-data: данные, переданные пользователем при создании Droplet, обрабатываемые cloud-init.
cloud-init: инструмент инициализации облачных инстансов при первом запуске.

Summary