API Reference

Метаданные — механизм, с помощью которого Nova передает информацию о конфигурации запускаемым виртуальным машинам (ВМ). Метаданные широко используются вспомогательными приложениями вроде cloud-init для указания параметров, которые должны использовать ВМ — например, пароля суперпользователя (root password).
Метаданные доступны через диск конфигурации (config drive) либо сетевую службу метаданных (metadata service). Кроме того, пользователь может их самостоятельно настроить с помощью функции пользовательских данных (user data).
В данном руководстве представлен краткий обзор этих функций и описание доступных типов метаданных.

Типы метаданных

Метаданные делятся на три типа в зависимости от того, кто передает их виртуальным машинам.

Данные, предоставленные пользователем

Пользователь, запустивший ВМ, может передавать метаданные этой ВМ несколькими способами.
Для пар ключей аутентификации можно использовать функции пар ключей nova API для загрузки ключа и последующего указания этого ключа во время commandline-команды nova boot.
Для менее структурированных данных можно передавать небольшой нечеткий блок данных с помощью функции userdata, т.е функции пользовательских данных nova API.

Данные, предоставленные Nova

Сама Nova должна передавать информацию виртуальной машине с помощью внутренней реализации системы метаданных. Данная информация содержит такие данные, как запрашиваемое имя хоста ВМ и зона доступности этой ВМ. Все это происходит по умолчанию и не требует вмешательства пользователя либо разработчика.

Nova предоставляет как OpenStack metadata API, так и API, совместимое с EC2. И то и другое имеет разные версии, названные по дате выпуска.

Данные, предоставленные разработчиком

Разработчику OpenStack может понадобиться передать данные виртуальной машине. Эти данные могут быть неизвестны пользователю, запускающему ВМ. Например, в случае с криптографическим токеном, используемым для регистрации ВМ в Active Directory после загрузки, пользователь не имеет доступа к Active Directory для создания токена, зато развертывание nova может иметь разрешение на создание токена от имени пользователя. Для этого нужно настроить функцию данные производителя (vendordata), которую может выполнить ваш оператор облачных вычислений.

Служба метаданных

Данный раздел содержит информацию для конечного пользователя о службе метаданных.

Служба метаданных позволяет виртуальным машинам извлекать данные по отдельным ВМ с помощью REST API. ВМ получают доступ к этой службе по адресу 169.254.169.254 или fe80::a9fe:a9fe. Через эту службу возможен доступ ко всем типам метаданных — предоставленным пользователем, Nova и производителем.

Служба метаданных доступна по протоколу IPv6 по адресу локальной связи fe80::a9fe:a9fe.

Как и во всех локальных адресах IPv6, IPv6-адрес метаданных не является полным без идентификатора зоны (в гостевой системе Linux это обычно имя интерфейса, отображающееся после знака процента). Обратите внимание, что в URL-адресах требуется зашифровывать знак процента самостоятельно. Например, если основной сетевой интерфейс в гостевой системе — ens2, то http://[fe80::a9fe:a9fe%25ens2]:80/... нужно заменить на http://169.254.169.254/....

Использование службы метаданных

Чтобы получить список поддерживаемых версий для OpenStack metadata API, выполните GET-запрос к http://169.254.169.254/openstack, который вернет список каталогов:

$ curl http://169.254.169.254/openstack
2012-08-10
2013-04-04
2013-10-17
2015-10-15
2016-06-30
2016-10-06
2017-02-22
2018-08-27
latest

Информацию о содержании и структуре этих каталогов см. в разделе Метаданные в формате OpenStack.

Чтобы получить список поддерживаемых версий для метаданных API, совместимых с EC2, выполните GET-запрос к http://169.254.169.254, который точно так же вернет список каталогов:

curl http://169.254.169.254
1.0
2007-01-19
2007-03-01
2007-08-29
2007-10-10
2007-12-15
2008-02-01
2008-09-01
2009-04-04
latest

Информацию о содержании и структуре этих каталогов см. в разделе Метаданные, совместимые с EC2.

Диски конфигурации

Данный раздел содержит информацию для конечного пользователя о дисках конфигурации.

Диски конфигурации — это специальные диски, которые подключаются к ВМ при ее загрузке. ВМ может смонтировать такой диск и считывать с него файлы для получения информации, которая обычно доступна через службу метаданных.

Один из вариантов применения диска конфигурации — передача сетевой конфигурации, когда не используется DHCP для назначения IP-адресов виртуальным машинам. Например, можно передавать конфигурацию IP-адреса для ВМ через диск конфигурации, который ВМ установит самостоятельно и получит к нему доступ, прежде чем будут настроены сетевые параметры для ВМ.

Использование диска конфигурации

Чтобы включить диск конфигурации для ВМ, добавьте параметр --config-drive true команде openstack server create.

Следующий пример запускает диск конфигурации и передает файл пользовательских данных с двумя парами значений ключей, которые доступны с диска конфигурации:

$ openstack server create --config-drive true --image my-image-name \
    --flavor 1 --key-name mykey --user-data ./my-user-data.txt \
    --property role=webservers --property essential=false MYINSTANCE

Если ваша гостевая операционная система поддерживает доступ к диску по метке (label), можно подключить диск конфигурации в качестве устройства /dev/disk/by-label/configurationDriveVolumeLabel. В следующем примере диск конфигурации имеет метку тома config-2:

# mkdir -p /mnt/config
# mount /dev/disk/by-label/config-2 /mnt/config

Если ваша гостевая ОС не использует udev, то каталог /dev/disk/by-label отсутствует. Вы можете использовать команду blkid для идентификации блочного устройства, соответствующего диску конфигурации. Например:

# blkid -t LABEL="config-2" -odevice
/dev/vdb

После идентификации устройство можно установить:

# mkdir -p /mnt/config
# mount /dev/vdb /mnt/config

После установки можно просмотреть содержимое диска конфигурации:

$  /mnt/conf

$ cd /mnt/config
$ find . -maxdepth 2
.
./ec2
./ec2/2009-04-04
./ec2/latest
./openstack
./openstack/2012-08-10
./openstack/2013-04-04
./openstack/2013-10-17
./openstack/2015-10-15
./openstack/2016-06-30
./openstack/2016-10-06
./openstack/2017-02-22
./openstack/latest

Файлы, появляющиеся на диске конфигурации, зависят от аргументов, переданных команде openstack server create. Формат этого каталога такой же, как у службы метаданных, за исключением того, что метаданные, совместимые с EC2, теперь расположены в каталоге ec2, а не в корневом каталоге (/).

Информацию о формате файлов и подкаталогов в этих каталогах см. в разделах Метаданные в формате OpenStack и Метаданные, совместимые с EC2.

Настройки образов

$ openstack image set IMG-UUID --property img_config_drive=mandatory

Свойство метаданных образа img_config_drive можно использовать для принудительного включения диска конфигурации. Параметр img_config_drive указывает, нужен ли образу диск конфигурации.

Метаданные Nova

Nova предоставляет свои метаданные в формате OpenStack и в формате, совместимом с EC2.

Метаданные в формате OpenStack

Метаданные из OpenStack API распространяются в формате JSON. Для каждой версии предоставлены два файла: meta_data.json и network_data.json. Файл meta_data.json содержит информацию, относящуюся к Nova, а файл network_data.json содержит информацию, полученную от Neutron. Например:

$ curl http://169.254.169.254/openstack/2018-08-27/meta_data.json

{
   "random_seed": "yu5ZnkqF2CqnDZVAfZgarG...",
   "availability_zone": "nova",
   "keys": [
       {
         "data": "ssh-rsa AAAAB3NzaC1y...== Generated by Nova\n",
         "type": "ssh",
         "name": "mykey"
       }
   ],
   "hostname": "test.novalocal",
   "launch_index": 0,
   "meta": {
      "priority": "low",
      "role": "webserver"
   },
   "devices": [
       {
         "type": "nic",
         "bus": "pci",
         "address": "0000:00:02.0",
         "mac": "00:11:22:33:44:55",
         "tags": ["trusted"]
       },
       {
         "type": "disk",
         "bus": "ide",
         "address": "0:0",
         "serial": "disk-vol-2352423",
         "path": "/dev/sda",
         "tags": ["baz"]
       }
   ],
   "project_id": "f7ac731cc11f40efbc03a9f9e1d1d21f",
   "public_keys": {
       "mykey": "ssh-rsa AAAAB3NzaC1y...== Generated by Nova\n"
   },
   "name": "test"
}

$ curl http://169.254.169.254/openstack/2018-08-27/network_data.json

{
    "links": [
        {
            "ethernet_mac_address": "fa:16:3e:9c:bf:3d",
            "id": "tapcd9f6d46-4a",
            "mtu": null,
            "type": "bridge",
            "vif_id": "cd9f6d46-4a3a-43ab-a466-994af9db96fc"
        }
    ],
    "networks": [
        {
            "id": "network0",
            "link": "tapcd9f6d46-4a",
            "network_id": "99e88329-f20d-4741-9593-25bf07847b16",
            "type": "ipv4_dhcp"
        }
    ],
    "services": [
        {
            "address": "8.8.8.8",
            "type": "dns"
        }
    ]
}

Метаданные, совместимые с EC2

API, совместимые с EC2, также совместимы с версией 2009-04-04 службы метаданных Amazon EC2. Поэтому образы виртуальных машин, разработанные для EC2, будут корректно работать с OpenStack.

API EC2 предоставляет отдельный URL-адрес для каждого элемента метаданных. Чтобы получить список этих элементов, выполните GET-запрос к http://169.254.169.254/2009-04-04/meta-data/. Например:

$ curl http://169.254.169.254/2009-04-04/meta-data/
ami-id
ami-launch-index
ami-manifest-path
block-device-mapping/
hostname
instance-action
instance-id
instance-type
kernel-id
local-hostname
local-ipv4
placement/
public-hostname
public-ipv4
public-keys/
ramdisk-id
reservation-id
security-groups

$ curl http://169.254.169.254/2009-04-04/meta-data/block-device-mapping/
ami

$ curl http://169.254.169.254/2009-04-04/meta-data/placement/
availability-zone

$ curl http://169.254.169.254/2009-04-04/meta-data/public-keys/
0=mykey

Виртуальные машины могут получать открытый SSH-ключ (идентифицируемый по имени пары ключей, когда пользователь запрашивает новый ВМ), отправляя GET-запрос на http://169.254.169.254/2009-04-04/meta-data/public-keys/0/openssh-key:

$ curl http://169.254.169.254/2009-04-04/meta-data/public-keys/0/openssh-key
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDYVEprvtYJXVOBN0XNKVVRNCRX6BlnNbI+US\
LGais1sUWPwtSg7z9K9vhbYAPUZcq8c/s5S9dg5vTHbsiyPCIDOKyeHba4MUJq8Oh5b2i71/3B\
ISpyxTBH/uZDHdslW2a+SrPDCeuMMoss9NFhBdKtDkdG9zyi0ibmCP6yMdEX8Q== Generated\
by Nova

Пользовательские данные

Пользовательские данные — это блок данных, которые пользователь может указать при запуске ВМ. ВМ получает доступ к этим данным через службу метаданных или диск конфигурации. Обычно подобные данные используются для передачи скрипта оболочки (shell script), который ВМ запускает при загрузке.

Пользовательские данные используются в таких приложениях, как cloud-init — пакете Ubuntu с открытым исходным кодом, доступном в различных дистрибутивах Linux, который быстро справляется с инициализацией облачной ВМ.

Вы можете добавить пользовательские данные в локальный файл и включить их через параметр --user-data <user-data-file> при создании ВМ.

$ openstack server create --image ubuntu-cloudimage --flavor 1 \
    --user-data mydata.file VM_INSTANCE

Примечание. Предоставленные пользовательские данные не должны быть закодированы в base64, поскольку они будут автоматически закодированы для передачи допустимых входных данных в REST API, который имеет ограничение в 65535 байт после кодирования.

После загрузки вы можете получить доступ к этим данным из ВМ, используя либо службу метаданных, либо диск конфигурации. Чтобы получить к ним доступ через службу метаданных, отправьте GET-запрос к http://169.254.169.254/openstack/{version}/user_data (OpenStack API) либо к http://169.254.169.254/{version}/user-data (API, совместимый с EC2). Например:

$ curl http://169.254.169.254/openstack/2018-08-27/user_data

#!/bin/bash
echo 'Extra user data here'

Данные производителя

Данный раздел содержит информацию для конечного пользователя о функции vendordata.

Там, где они настроены, ВМ могут извлекать данные по конкретному производителю из службы метаданных или диска конфигурации. Чтобы получить к ним доступ через службу метаданных, отправьте GET-запрос в зависимости от настроек инсталляции либо к http://169.254.169.254/openstack/{version}/vendor_data.json, либо к http://169.254.169.254/openstack/{version}/vendor_data2.json. Например:

$ curl http://169.254.169.254/openstack/2018-08-27/vendor_data2.json

{
    "testing": {
        "value1": 1,
        "value2": 2,
        "value3": "three"
    }
}

Примечание. Наличие и содержимое данного файла варьируется в зависимости от настроек инсталляции.

Общие рекомендации

Не полагайтесь на наличие метаданных EC2 в API метаданных или на диске конфигурации, поскольку эти данные могут быть удалены в будущем релизе. В частности, не полагайтесь на файлы в каталоге ec2.

При создании образов, которые обращаются к службе метаданных или данным диска конфигурации — и при этом многие подкаталоги с метаданными расположены внутри каталога openstack — всегда выбирайте самую новую версию API по дате, которую поддерживает ваш клиент. Например, если ваш гостевой образ поддерживает версии 2012-03-05, 2012-08-05 и 2013-04-13, сначала попробуйте 2013-04-13 и вернитесь к предыдущей версии, если 2013-04-13 отсутствует.