Cloud-init в операційній системі Raspberry Pi OS

Як деякі з вас, можливо, вже помітили, остання версія операційної системи Raspberry Pi OS на базі Debian Trixie тепер містить cloud-init. Це знаменує початок переходу від нашої застарілої системи налаштування під час першого запуску, що базувалася на скрипті firstrun.sh.

Cloud-init — це міжплатформовий інструмент, незалежний від дистрибутива, що використовується для автоматичної конфігурації систем під час першого запуску. (Визначення адаптоване з офіційної документації cloud-init.) За допомогою нього ви можете налаштувати образи Raspberry Pi, додавши користувачів, мережеві налаштування, ключі SSH, конфігурації сховищ та багато іншого — і все це без необхідності ручного входу в систему після прошивання образу.

Як мені його використовувати?

Якщо ви завантажили останню версію (випущену 24 листопада 2025 року), то помітите, що на завантажувальному розділі з’явилися три нові файли. Це розділ у форматі FAT32, який ваш комп’ютер автоматично підключає після вставлення картки microSD із щойно прошитою ОС Raspberry Pi. Він уже містить звичні файли, такі як config.txt, але тепер ви також побачите:

  • meta-data
  • network-config
  • user-data

Для більшості користувачів meta-data (метадані) можна залишити без змін — вони просто дозволяють cloud-init правильно обробляти інші файли конфігурації. Досвідчені користувачі можуть використовувати їх для більш складних процесів розгортання, але в типових випадках їх можна сміливо ігнорувати.

Cloud-init використовує YAML для своїх файлів конфігурації. Якщо ви ще не знайомі з YAML, варто швидко ознайомитися з офіційною документацією, оскільки відступи та форматування мають велике значення. Наразі ми зосередимося на двох найважливіших файлах: user-data та network-config.

Загальні налаштування (user-data)

Файл даних користувача (user-data) є основним місцем для зберігання ваших налаштувань. За винятком мережевих налаштувань, майже всі параметри, які cloud-init налаштовує під час першого завантаження, керуються саме звідси.

За допомогою нього можна створити користувача за замовчуванням, налаштувати локаль, встановити додаткові пакети, налаштувати доступ через SSH та багато іншого — про все це докладно розповідається в офіційній документації до cloud-init.

На відміну від багатьох інших дистрибутивів, Raspberry Pi OS містить кілька розширень для налаштування cloud-init, призначених спеціально для Raspberry Pi. Вони дозволяють автоматично вмикати апаратні інтерфейси, такі як I2C, SPI, послідовний порт і 1-Wire, а також активувати режим USB-пристрою (rpi-usb-gadget). 

Ось приклад конфігурації, яка створює обліковий запис користувача та демонструє всі опції, що наразі підтримуються для Raspberry Pi:

#cloud-config

# Set the hostname for this device. This will also update /etc/hosts if manage_etc_hosts is enabled.
hostname: mypi2025
manage_etc_hosts: true

# Set the system timezone
timezone: Europe/London

# Create a default user account and apply permissions
users:
  - name: pi
    groups: users,adm,dialout,audio,netdev,video,plugdev,cdrom,games,input,gpio,spi,i2c,render,sudo
    shell: /bin/bash
    lock_passwd: false  # Set to true to disable password login entirely
    plain_text_password: mysecretpassword123  # Alternatively, use 'passwd:' with a hashed password for better security
    ssh_authorized_keys:
      - ssh-ed25519 mykeystuff  # Replace with your actual SSH public key
    sudo: ALL=(ALL) NOPASSWD:ALL  # Allow passwordless sudo for this user

# Raspberry Pi–specific options (provided by the cc_raspberry_pi module)
rpi:
    spi: true               # Enable SPI interface
    i2c: true               # Enable I2C interface
    serial: true            # Enable serial console and UART interface
    onewire: true           # Enable 1-Wire interface
    enable_usb_gadget: true # Enable USB gadget mode

# Additional Raspberry Pi OS option (not available on generic cloud-init images)
enable_ssh: true  # Enables the SSH server on first boot

# Optional: Disable SSH password authentication if using SSH keys only (recommended for security)
# ssh_pwauth: false

Більш детальну інформацію можна знайти в розділі, присвяченому модулю cc_raspberry_pi, в офіційній документації до cloud-init.

Важливо!

Заголовок #cloud-config у верхній частині файлу є обов’язковим — без нього cloud-init не зможе правильно обробити файл.

Налаштування мережі (network-config)

Файл network-config визначає, як Raspberry Pi має налаштувати свої мережеві інтерфейси під час першого запуску. Як випливає з назви, саме тут ви налаштовуєте параметри Wi-Fi або Ethernet ще до увімкнення пристрою.

Ось простий приклад підключення вашого Raspberry Pi до мережі Wi-Fi:

network:
  version: 2
  wifis:
    # Make sure the target is NetworkManager which is the default on Raspberry Pi OS
    renderer: NetworkManager
    # The connection name
    wlan0:
      dhcp4: true
      # !VERY IMPORTANT! Change this to the ISO/IEC 3166 country code for the country you want to use this microSD card in.
      regulatory-domain: "GB"
      access-points:
        "My Net-Work":
          password: "mysupersecretpassword"
      # Don’t wait at boot for this connection to connect successfully
      optional: true

Коли ви увімкнете Raspberry Pi з вставленою карткою microSD, cloud-init обробить цю конфігурацію та спробує автоматично підключитися до вказаної мережі — це дозволить вам підключитися через SSH або продовжити роботу без необхідності підключення монітора чи клавіатури.

Ви можете налаштувати набагато більше, ніж лише базові облікові дані Wi-Fi: підтримуються кілька мереж, перехід на резервну мережу за пріоритетом, призначення статичних IP-адрес, VLAN та багато іншого. Повну інформацію дивіться в офіційній документації щодо мереж cloud-init.

З впровадженням cloud-init операційна система Raspberry Pi OS також включає Netplan — уніфікований рівень абстракції для налаштування мережі, який використовується в багатьох сучасних дистрибутивах Linux.

Детальніше про Netplan

Зараз Netplan є основним джерелом достовірної інформації щодо мережевих налаштувань в Raspberry Pi OS. Він використовує власний формат конфігурації на основі YAML і може генерувати мережеві налаштування як для systemd-networkd, так і для NetworkManager, залежно від того, який рендерер ви оберете. Головною перевагою такого підходу є сумісність — конфігурацію Netplan можна використовувати в будь-якому дистрибутиві Linux, що її підтримує, незалежно від того, чи використовується в ньому NetworkManager чи networkd.

Щоб використовувати Netplan безпосередньо, розмістіть файли конфігурації в каталозі /etc/netplan/ — саме туди cloud-init зберігає згенеровану мережеву конфігурацію з network-config без змін. Звідти ви можете згенерувати активну конфігурацію за допомогою команди:

sudo netplan generate

Це створює відповідні файли конфігурації для обраного сервісу (NetworkManager в Raspberry Pi OS). Щоб активувати конфігурацію, виконайте:

sudo netplan apply

Ви як і раніше можете використовувати nmcli для перегляду або управління підключеннями. Оскільки багато існуючих інструментів та скриптів використовують nmcli або API D-Bus NetworkManager, між Netplan і NetworkManager має бути рівень взаємодії. Canonical надає три виправлення, які забезпечують цю двосторонню взаємодію, дозволяючи NetworkManager повідомляти Netplan про зміни в конфігурації.

Щодо Raspberry Pi OS, ми пішли ще далі та впровадили додаткові виправлення для вдосконалення цього робочого процесу:

  • NetworkManager взаємодіє лише з тими підключеннями, які мають префікс «netplan-». Якщо ви хочете, щоб нове підключення зберігалося в Netplan, додайте цей префікс під час його створення, і воно буде збережено в конфігурації Netplan.
  • Під час створення профілів NetworkManager завантажує всі з'єднання, визначені Netplan, і записує свою інтерпретовану конфігурацію виконання у форматі, зрозумілому для Netplan.
  • Під час цього процесу всі файли з розширеннями .yaml та .yml у каталозі /etc/netplan/ видаляються, щоб уникнути конфлікту визначень на різних рівнях.
  • Це не впливає на створені вручну з'єднання, що зберігаються в /etc/NetworkManager/system-connections/.
  • Усі профілі, створені Netplan під час виконання, з’являться в розділі /run/NetworkManager/system-connections/ and will also use the netplan-prefix.

Такий підхід забезпечує узгодженість між обома системами та запобігає відхиленням у налаштуваннях під час редагування або перезавантаження профілів за допомогою інструментів NetworkManager.

На завершення...

Завдяки інтеграції cloud-init та Netplan в Raspberry Pi OS налаштування під час першого запуску стало набагато потужнішим, відтворюваним та сумісним з різними конфігураціями. Незалежно від того, чи ви налаштовуєте окремий пристрій, чи готуєте десятки Raspberry Pi для класу, лабораторії або впровадження різноманітних речей в Інтернеті (IoT), ці нові інструменти дозволяють легко визначити всі параметри заздалегідь — користувачів, мережу, інтерфейси тощо — ще до того, як система увімкнеться.

З випуском Raspberry Pi Imager 2.0 конфігурація cloud-init для Raspberry Pi OS тепер створюється за замовчуванням. Це спрощує подальше налаштування системи після запису образу — достатньо просто відредагувати створені файли user-data або network-config у завантажувальному розділі. Imager 2.0 також розуміє специфічні для Raspberry Pi опції rpi:, тому такі функції, як SPI або I2C, можна ввімкнути безпосередньо в інтерфейсі налаштування.

Старий метод все ще працює, але cloud-init і Netplan відкривають можливості для набагато гнучкішого та сучаснішого робочого процесу. У майбутніх версіях ми продовжимо розширювати підтримку модулів cloud-init, призначених спеціально для Raspberry Pi, а також вдосконалювати функції розгортання.

Якщо ви створюєте цікаві шаблони даних користувачів або налаштувань мережі (user-data або network-config), або маєте відгуки щодо нової системи, ми будемо раді почути вашу думку на форумах.