Arch Linux: установка у 2025 – диски, шифрування, встановлення системи
0 (0)

26 Травня 2025

Кожного разу, як беруся за встановлення Arch Linux – це як нова подорож: наче з роками нічого особливо і не міняється – але кожного разу щось нове.

Писав про це вже багато, прийшов час написати ще раз, бо купив нового ноута.

Спочатку наче було лінь все робити руками, і вирішив спробувати готові образи. Навіть спробував Fedora – бо дуже проста установка, і все включено – але нє, не моє, бо дуже не вистачало репозиторіїв Pacman/AUR, постійно якісь граблі з апгрейдами, постійно повідомлення, що “ваша система вже не підтримується, оновіться до 42”.

Тому все ж вирішив повернутись на Arch Linux, на якому живу з 2016 року.

Першим спробував EndeavourOS – дуже непогано, насправді. Я ставив з KDE, і все “просто працює” – без всяких танців з бубном. В комплекті йдуть всі батарейки і налаштоване оточення на вибір – KDE/Gnome/LXDE/etc.

Але потім щось я скучив за Openbox та його мінімалістичністю – і вирішив повернутись на нього.

Аналогічно – спочатку вирішив не витрачати час і просто пошукати готові зборки. І такі є, наприклад – Archcraft. Теж все підготовлено, чувак прям дуже красиво все зробив – і екран GRUB, і всякий тюнінг Openbox/Fluxbox/Hyprland – багато всього, на будь-який смак.

Поставив, погрався, і все одно – щось мені в одному місці зудить, хочеться “своє, рідненьке”, бо хочеться знати свою систему – де, що, як, і для чого зроблено. А тому – беремо “голий” Arch Linux ISO, створюємо флешку – і погнали.

Записав багато, тому поділив на кілька частин:

  • спочатку пройдемось по процесу розбивки диска і встановлення чистої системи
    • так як ноут планується для роботи, то тут зроблю з LUKS
  • потім – пройдемось по основним налаштування для початку роботи
  • потім – подивимось на налаштування різних Desktop Environment/Window Managers

Я таки спробував тайлінг менеджери – але ну якось не зайшло. Все ж діло звички, і іноді хочеться просто клацати мишкою, а не пам’ятати 100500 комбінацій клавіш.

Окей, поїхали.

Запуск установки, WiFi

Створюємо флешку з Arch Linux ISO, ребутаємо машинку з неї, налаштовуємо WiFi. Це я більше роблю для себе, бо потім простіше підключитись з іншого компа по SSH, і робити все в повноцінному оточенні, де можна копіпастити команди/результати в RTFM, в цей пост.

iwctl у нас вже є в образі, запускаємо:

# iwctl

Знаходимо доступні мережі:

[iwd]# station wlan0 get-networks

Підключаємось (iwctl підтримує підстановку по TAB, тому не треба повністю руками все набирати):

[iwd]# station wlan0 connect setevoy-tplink-5
Passphrase:*******

Перевіряємо стан – в State має бути Connected:

[iwd]# station wlan0 show

Виходимо по Ctrld+D, можна пінганути якийсь Google для перевірки.

Отримуємо IP:

# ip a s wlan0

Задаємо пароль root:

# passwd root

І підключаємось до цієї машинки з іншого компа:

$ ssh [email protected]

archinstall vs manual installation

Колись в Arch Linux додали скрипт archinstall, який спрощує процес. Але я з ним не подружився – і розбивка диска не дуже зручна, і встановлення пакетів.

Тому робити будемо по The Old School Way – все ручками.

До речі, не пам’ятаю чи взагалі вміє archinstall в шифрування.

Підготовка: диски

Вибір схеми – LVM, розділи

Колись я робив з LVM + LUKS, і в LVM окремі групи для / та /home.

Мати окремі розділи наче зручніше, бо і контроль над вільним місце краще, і перевстановити систему можна без втрати даних в домашніх директоріях, плюс там всякі user settings. А якщо ще і LVM є – то і змінити розмір розділів можна легко, і снапшоти для бекапів робити.

Але за ті роки, скільки в мене ця схема на робочому ноуті (років 5 вже) – жодного разу не користувався цими можливостями.

Тому цього разу вирішив і / і /home робити на одному великому розділі, і без LVM – трохи простіше сетап, простіше дебаг при проблемах, коли треба загрузитись з флешки і перезібрати ядро.

Отже – будемо робити без LVM, але з LUKS, та системою і $HOME на одному розділі.

Пост дописую вже при сетапі іншого, старого ноута, тому тут диск всього 250 гіг.

Розбивка диска з fdisk

Знов-таки – діло звички, але я давно користуюсь fdisk, тому робити будемо з ним.

Перевіряємо девайси:

[root@archiso ~]# fdisk -l
Disk /dev/sda: 232.89 GiB, 250059350016 bytes, 488397168 sectors
Disk model: Samsung SSD 850 
...
Disklabel type: gpt
...

Device         Start       End   Sectors   Size Type
/dev/sda1       4096   4198399   4194304     2G EFI System
/dev/sda2    4198400 416672903 412474504 196.7G Linux filesystem
/dev/sda3  416672904 488397101  71724198  34.2G Linux swap

Disk /dev/sdb: 28.91 GiB, 31037849600 bytes, 60620800 sectors
Disk model: DataTraveler 2.0
...

Device     Boot   Start     End Sectors  Size Id Type
/dev/sdb1  *         64 2074623 2074560 1013M  0 Empty
/dev/sdb2       2074624 2428927  354304  173M ef EFI (FAT-12/16/32)
...

Тут:

  • /dev/sdb: USB з Arch Linux ISO, 30 гігабайт
  • /dev/sda: головний диск, SSD самого ноута, 250 гігабайт

На SSD зараз є розділи і дані від EndeavourOS, видалимо все, зробимо з нуля.

Запускаємо fdisk на sda:

root@archiso ~ # fdisk /dev/sda
...
Command (m for help):

Ще раз перевіримо, що це саме потрібний диск – Samsung SSD, 250 гіг:

...
Command (m for help): p
Disk /dev/sda: 232.89 GiB, 250059350016 bytes, 488397168 sectors
Disk model: Samsung SSD 850 
...

Важливо: далі будемо видаляти ВСІ дані з диску!

Видаляємо всі розділи:

Command (m for help): d
Partition number (1-3, default 3): 

Partition 3 has been deleted.

Command (m for help): d
Partition number (1,2, default 2): 

Partition 2 has been deleted.

Command (m for help): d
Selected partition 1
Partition 1 has been deleted

Записуємо зміни:

Command (m for help): w
The partition table has been altered.
Calling ioctl() to re-read partition table.
Syncing disks.

Запускаємо fdisk ше раз:

root@archiso ~ # fdisk /dev/sda

Перевіряємо що на диску зараз – а нічого 🙂

Command (m for help): p
Disk /dev/sda: 232.89 GiB, 250059350016 bytes, 488397168 sectors 
Disk model: Samsung SSD 850
...
Disklabel type: gpt
Disk identifier: 51B93327-8CC4-4D94-9243-67A797A845B2

Поїхали створювати нові розділи.

Нам буде потрібно чотири:

  • для EFI
  • окремий розділ для /boot – бо треба звідкись завантажити initramfs до того, як буде змога розшифрувати диск
  • для Swap
  • і розділ під саму систему і /home

Порядок створення не те, щоб дуже важливий, бо сучасні системи і ядра самі все знайдуть, але краще дотримуватися стандартного підходу:

  • першим EFI, бо там наш bootloader (там буде шукатись efi-файл)
  • потім /boot – там ядро для загрузки і решта файлів GRUB
  • далі Swap – бо “так історично склалося” з часів механічних HDD, де перші розділи (ближче до краю диску) читались швидше
  • і потім вже основний розділ під / та /home

Створюємо перший розділ, для EFI, 512 мегеабайт:

Command (m for help): n
Partition number (1-128, default 1): 
First sector (2048-2000409230, default 2048): 
Last sector, +/-sectors or +/-size{K,M,G,T,P} (2048-2000409230, default 2000408575): +512M

Created a new partition 1 of type 'Linux filesystem' and of size 512 MiB.
Partition #1 contains a vfat signature.

Do you want to remove the signature? [Y]es/[N]o: Y

The signature will be removed by a write command.

Тепер треба задати тип розділу, EFI – t (type):

Command (m for help): t

Знаходимо всі з L:

Partition type or alias (type L to list all): L
  1 EFI System                     C12A7328-F81F-11D2-BA4B-00A0C93EC93B
  2 MBR partition scheme           024DEE41-33E7-11D3-9D69-0008C781F39F
...

Задаємо значення 1:

Partition type or alias (type L to list all): 1
Changed type of partition 'Linux filesystem' to 'EFI System'.

Створюємо другий розділ, під /boot, де буде initramfs і само ядро системи.

512 мегабайт має вистачити на все – vmlinuz-linux близько 10 мегабайт, initramfs-linux.img ще 20-30, fallback image трохи більший.

Можна глянути на робочій системі:

$ ls -lh /boot/
total 67M
drwxr-xr-x 3 root root 4.0K Jan  1  1970 EFI
drwxr-xr-x 6 root root 4.0K Dec  7  2020 grub
-rw------- 1 root root  39M May  2 16:44 initramfs-linux-fallback.img
-rw------- 1 root root  14M May  2 16:44 initramfs-linux.img
drwx------ 2 root root  16K Dec  7  2020 lost+found
-rw-r--r-- 1 root root  15M May  2 16:44 vmlinuz-linux

Додаємо новий розділ:

...

Command (m for help): n
Partition number (2-128, default 2): 
First sector (1050624-488397134, default 1050624): 
Last sector, +/-sectors or +/-size{K,M,G,T,P} (1050624-488397134, default 488396799): +512M

Created a new partition 2 of type 'Linux filesystem' and of size 512 MiB.
...

Додаємо Swap – раніше робили х2 від доступної оперативної пам’яті.

Зараз, якщо буде використовуватись hibernate – то робимо розмір оперативної + пару гігабайт в запасі.

На цьому ноуті 32 гіга, тому під Swap даємо нехай буде 34:

...
Command (m for help): n
Partition number (3-128, default 3): 
First sector (2099200-488397134, default 2099200): 
Last sector, +/-sectors or +/-size{K,M,G,T,P} (2099200-488397134, default 488396799): +34G

Created a new partition 3 of type 'Linux filesystem' and of size 34 GiB.
...

Знаходимо тип Linux swap – ще раз L:

...
Partition number (1-3, default 3): L
...
 19 Linux swap
...

Задаємо тип з t:

...
Partition number (1-3, default 3): 
Partition type or alias (type L to list all): 19

Changed type of partition 'Linux filesystem' to 'Linux swap'.
...

І останнім – розділ під саму систему, вже на решту місця (просто тиснемо Enter):

...
Command (m for help): n
Partition number (4-128, default 4): 
First sector (73402368-488397134, default 73402368): 
Last sector, +/-sectors or +/-size{K,M,G,T,P} (73402368-488397134, default 488396799): 

Created a new partition 4 of type 'Linux filesystem' and of size 197.9 GiB.
...

Перевіряємо, що у нас вийшло – з p:

...
Command (m for help): p
Disk /dev/sda: 232.89 GiB, 250059350016 bytes, 488397168 sectors
Disk model: Samsung SSD 850 
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: gpt
Disk identifier: BE8FEE73-C9BB-4959-A258-12A3FCF906FF

Device        Start       End   Sectors   Size Type
/dev/sda1      2048   1050623   1048576   512M EFI System
/dev/sda2   1050624   2099199   1048576   512M Linux filesystem
/dev/sda3   2099200  73402367  71303168    34G Linux swap
/dev/sda4  73402368 488396799 414994432 197.9G Linux filesystem
...

Записуємо зміни:

...
Command (m for help): w
The partition table has been altered.
Calling ioctl() to re-read partition table.
Syncing disks

Шифрування з LUKS

Ще раз глянемо що у нас з розділами тепер:

[root@archiso ~]# lsblk
NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
loop0    7:0    0 846.7M  1 loop /run/archiso/airootfs
sda      8:0    0 232.9G  0 disk 
├─sda1   8:1    0   512M  0 part 
├─sda2   8:2    0   512M  0 part 
├─sda3   8:3    0    34G  0 part 
└─sda4   8:4    0 197.9G  0 part 
sdb      8:16   1  28.9G  0 disk 
├─sdb1   8:17   1  1013M  0 part 
└─sdb2   8:18   1   173M  0 part 
sdc      8:32   1     0B  0 disk

4 нових розділи на /dev/sda, з них /dev/sda4 – це рутовий розділ під систему, його і будемо шифрувати.

Використовуємо останній  стандарт, luks2, додаємо ‘-y‘ аби запитало підтвердження пароля:

[root@archiso ~]# cryptsetup -y luksFormat --type luks2 /dev/sda4

WARNING!
========
This will overwrite data on /dev/sda4 irrevocably.

Are you sure? (Type 'yes' in capital letters): YES
Enter passphrase for /dev/sda4: 
Verify passphrase:

Все – дані вже зашифровані.

Тепер, аби встановити систему, нам потрібно розшифрувати диск – тим жеж cryptsetup:

[root@archiso ~]# cryptsetup open /dev/sda4 cryptroot
Enter passphrase for /dev/sda4:

Тепер має з’явитись новий розділ в /dev/mapper який створює cryptsetup коли розшифровує диск, і по факту це просто сімлінк на фізичний розділ:

[root@archiso ~]# ls -l /dev/mapper/cryptroot 
lrwxrwxrwx 1 root root 7 May 26 12:06 /dev/mapper/cryptroot -> ../dm-0

Створення файлових систем

Які нам FS треба:

  • EFI – Fat32
  • / та /boot  – ext4 (стара і перевірена, ніколи не користувався всякими btrfs, хоча може варто було б спробувати)
  • Swap – залишаємо, як є, але виконуємо mkswap (задаємо заголовок LINUX_SWAP), і пізніше робимо swapon

Створюємо файлову систему на основному розділі, /dev/sda4 (або /dev/mapper/cryptroot):

[root@archiso ~]# mkfs.ext4 /dev/mapper/cryptroot
mke2fs 1.47.2 (1-Jan-2025)
Creating filesystem with 51870208 4k blocks and 12967936 inodes
Filesystem UUID: 6bbbd1c2-7396-4d23-91eb-4188079e6df8
Superblock backups stored on blocks: 
        32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632, 2654208, 
        4096000, 7962624, 11239424, 20480000, 23887872

Allocating group tables: done                            
Writing inode tables: done                            
Creating journal (262144 blocks): done
Writing superblocks and filesystem accounting information: done

Аналогічно для⁣ /boot, але тут вже через /dev/sda2:

root@archiso ~ # mkfs.ext4 /dev/sda2

Тепер Fat32 для EFI, /dev/sda1:

[root@archiso ~]# mkfs.fat -F32 /dev/sda1
mkfs.fat 4.2 (2021-01-31)

І Swap:

[root@archiso ~]# mkswap /dev/sda3
Setting up swapspace version 1, size = 34 GiB (36507217920 bytes)
no label, UUID=9132a23f-bb87-43d1-9ac5-33b75bf17f35

Перевіряємо:

[root@archiso ~]# fdisk -l /dev/sda
Disk /dev/sda: 232.89 GiB, 250059350016 bytes, 488397168 sectors
Disk model: Samsung SSD 850 
...

Device        Start       End   Sectors   Size Type
/dev/sda1      2048   1050623   1048576   512M EFI System
/dev/sda2   1050624   2099199   1048576   512M Linux filesystem
/dev/sda3   2099200  73402367  71303168    34G Linux swap
/dev/sda4  73402368 488396799 414994432 197.9G Linux filesystem

Окей, поїхали далі.

Підключення розділів

Монтуємо розділи:

  • sda4 (/dev/mapper/cryptroot), корневий розділ – в /mnt
  • sda2, boot – в /mnt/boot
  • sda1, EFI – в /mnt/boot/efi
  • і swapon для /dev/sda3

Виконуємо:

[root@archiso ~]# mount /dev/mapper/cryptroot /mnt
[root@archiso ~]# mkdir /mnt/boot
[root@archiso ~]# mount /dev/sda2 /mnt/boot
[root@archiso ~]# mkdir /mnt/boot/efi 
[root@archiso ~]# mount /dev/sda1 /mnt/boot/efi
[root@archiso ~]# swapon /dev/sda3

Перевіряємо swap:

[root@archiso ~]# swapon --show
NAME      TYPE      SIZE USED PRIO
/dev/sda3 partition  34G   0B   -2

І решту розділів:

[root@archiso ~]# lsblk /dev/sda
NAME          MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
sda             8:0    0 232.9G  0 disk  
├─sda1          8:1    0   512M  0 part  /mnt/boot/efi
├─sda2          8:2    0   512M  0 part  /mnt/boot
├─sda3          8:3    0    34G  0 part  [SWAP]
└─sda4          8:4    0 197.9G  0 part  
  └─cryptroot 253:0    0 197.9G  0 crypt /mnt

Встановлення системи

З pacstrap встановлюємо необхідні пакети.

Краще тут відразу додати все для WiFi, в тому числі dhcpd аби потім не мати геморою з підключенням, і встановити openssh:

root@archiso ~ # pacstrap -K /mnt base linux linux-firmware grub efibootmgr networkmanager sudo vim iwd dhcpcd openssh
==> Creating install root at /mnt
...
(12/13) Updating linux initcpios...
==> Building image from preset: /etc/mkinitcpio.d/linux.preset: 'default'
==> Using default configuration file: '/etc/mkinitcpio.conf'
  -> -k /boot/vmlinuz-linux -g /boot/initramfs-linux.img
==> Starting build: '6.14.7-arch2-1'
...
==> Initcpio image generation successful
(13/13) Reloading system bus configuration...
  Skipped: Running in chroot.
pacstrap -K /mnt base linux linux-firmware grub efibootmgr networkmanager sud  23.20s user 13.51s system 84% cpu 43.626 total

Iris Xe Graphics

На новому ноуті (Lenovo ThinkPad T14 Gen 5) в мене відеокарта Iris Xe Graphics, і для неї треба трохи танців, бо перші спроби запуску Archcraft приводили до чорного екрану.

Вирішувалось додавання nomodeset в загрузку ядра.

Встановлюємо додаткові пакети:

root@archiso ~ # pacstrap -K /mnt mesa vulkan-intel intel-media-driver libva libva-utils

Переключаємось в нову систему, і якщо є – то видаляємо xf86-video-intel:

[root@archiso /]# pacman -Rns xf86-video-intel
error: target not found: xf86-video-intel

Виходимо зі chroot-оточення, йдемо далі.

Створення fstab

Генеруємо /etc/fstab з розділами:

[root@archiso ~]# genfstab -U /mnt >> /mnt/etc/fstab

Перевіряємо:

[root@archiso ~]# cat /mnt/etc/fstab
# Static information about the filesystems.
# See fstab(5) for details.

# <file system> <dir> <type> <options> <dump> <pass>
# /dev/mapper/cryptroot
UUID=6bbbd1c2-7396-4d23-91eb-4188079e6df8       /               ext4            rw,relatime     0 1

# /dev/sda2
UUID=93dade4c-1579-4256-8491-4e560fc563c4       /boot           ext4            rw,relatime     0 2

# /dev/sda1
UUID=BBE3-903E          /boot/efi       vfat            rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=ascii,shortname=mixed,utf8,errors=remount-ro   0 2

# /dev/sda3
UUID=9132a23f-bb87-43d1-9ac5-33b75bf17f35       none            swap            defaults        0 0

Виглядає наче ОК.

Зборка ядра з mkinitcpio

Так як у нас LUKS, то треба додати дію (власне, “hook“) encrypt, аби ядро при старті системи виконало decrypt розділу.

keyboard і keymap вже мають бути, але краще перевірити – вони використовується, аби можна було ввести сам пароль.

Редагуємо файл /mnt/etc/mkinitcpio.conf (/mnt! – або робимо chroot), заходимо строку з HOOKS:

...
HOOKS=(base udev autodetect microcode modconf kms keyboard keymap consolefont block filesystems fsck)
...

Додаємо encrypt після block і перед filesystems – порядок важливий:

HOOKS=(base udev autodetect microcode modconf kms keyboard keymap consolefont block encrypt resume filesystems fsck)

(якщо будемо використовувати hibernation – то перед filesystem ще додаємо resume)

Чому порядок важливий:

  • block – знаходить диски
  • encrypt – декриптить розділ
  • filesystems – монтує розділи

Якщо не буде encrypt – то initramfs не запитає пароль, і не зможе підключити розділ.

Тут, до речі, важливий нюанс: якщо ми не шифруємо Swap, і крадуть ноут, який був в гібернації – то можуть отримати всю інформацію, яка була в пам’яті.

Тому, якщо вже робити все секьюрно – то Swap теж треба шифрувати. Або використовувати swapfile на рутовому розділі, який шифрується.

Виконуємо arch-chroot:

[root@archiso ~]# arch-chroot /mnt/

Збираємо ядро:

[root@archiso /]# mkinitcpio -P
==> Building image from preset: /etc/mkinitcpio.d/linux.preset: 'default'
==> Using default configuration file: '/etc/mkinitcpio.conf'
  -> -k /boot/vmlinuz-linux -g /boot/initramfs-linux.img
...
  -> Running build hook: [encrypt]
  -> Running build hook: [resume]
  -> Running build hook: [filesystems]
  -> Running build hook: [fsck]
==> Generating module dependencies
==> Creating zstd-compressed initcpio image: '/boot/initramfs-linux-fallback.img'
  -> Early uncompressed CPIO image generation successful
==> Initcpio image generation successful

GRUB

Так як у нас є зашифрований розділ – то його треба вказати в GRUB, аби він передав ядру необхідність виконати decrypt.

Зараз це можна зробити /etc/crypttab – або “the old school way” з GRUB_CMDLINE_LINUX.

Я crypttab не користувався, якихось додаткових розділів в мене нема, тому GRUB_CMDLINE_LINUX буде достатньо.

Додаємо ще три пакети – власне grub, efibootmgr (хоча ми його вже встановили) та intel-ucode, аби мати останні апдейти для ЦПУ (це, звісно, якщо у вас Intel CPU, а не AMD).

Перевірити можна так:

[root@archiso /]# lscpu | grep 'Vendor'
Vendor ID:                            GenuineInte

Якщо AMD – То використовуємо пакет amd-ucode.

Встановлюємо їх:

[root@archiso /]# pacman -S grub efibootmgr intel-ucode

Встановлюємо сам GRUB в розділ EFI:

[root@archiso /]# grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=GRUB
Installing for x86_64-efi platform.
Installation finished. No error reported

Додавання cryptdevice

Знаходимо UUID зашифрованого розділу:

[root@archiso /]# blkid | grep LUKS
/dev/sda4: UUID="738d2f9b-7ffa-4d4e-93be-e00af0a64d5b" TYPE="crypto_LUKS" PARTUUID="32835823-6901-4bbf-9520-1876e64ba109"

(тут я як раз помилився – взяв не той UUID, і система не грузилась, див. в кінці)

Редагуємо /etc/default/grub, знаходимо строку GRUB_CMDLINE_LINUX="", і додаємо параметр cryptdevice:

...
GRUB_CMDLINE_LINUX="cryptdevice=UUID=738d2f9b-7ffa-4d4e-93be-e00af0a64d5b:cryptroot root=/dev/mapper/cryptroot"
...

Додавання resume

Якщо плануємо використовувати hibernate – то ядру треба вказати, з якого розділу зчитувати дані.

Знаходимо UUID розділу Swap:

[root@archiso /]# blkid | grep swap
/dev/sda3: UUID="9132a23f-bb87-43d1-9ac5-33b75bf17f35" TYPE="swap" PARTUUID="d7d38c7c-b8c6-49d5-81c3-0ef34cbd7d52"

Додаємо resume=UUID=9132a23f-bb87-43d1-9ac5-33b75bf17f35 в GRUB_CMDLINE_LINUX:

Генеруємо конфіг для GRUB:

[root@archiso /]# grub-mkconfig -o /boot/grub/grub.cfg
Generating grub configuration file ...
Found linux image: /boot/vmlinuz-linux
Found initrd image: /boot/intel-ucode.img /boot/initramfs-linux.img
Found fallback initrd image(s) in /boot:  intel-ucode.img initramfs-linux-fallback.img
Warning: os-prober will not be executed to detect other bootable partitions.
Systems on them will not be added to the GRUB boot configuration.
Check GRUB_DISABLE_OS_PROBER documentation entry.
Adding boot menu entry for UEFI Firmware Settings ...
done

Тут все.

Пароль root

Задамо пароль root, аби потім залогінитись в нову систему:

[root@archiso /]# passwd root
New password: 
Retype new password: 
passwd: password updated successfully

Виходимо зі chroot, і ребутаємось:

[root@archiso /]# 
exit
root@archiso ~ # reboot

Готово.

Проблеми: “Failed to mount <device> on real root”

З першої спроби не вийшло 🙂

Хоча до цього сетапив на новому ноуті – все пройшло ОК.

Зараз маю помилку:

ERROR: device '/dev/mapper/cryptroot' not found
...
Failed to mount '/dev/mapper/cryptroot' on real root

Ну, давайте розбиратись.

Десь накосячив в конфігах – initramfs не зміг розшифрувати диск, тому cryptroot не запустився, і ядро не знає, де шукати кореневу файлову систему.

Завантажуємось з флешки, монтуємо диски:

[root@archiso ~]# cryptsetup open /dev/sda4 cryptroot
Enter passphrase for /dev/sda4: 
[root@archiso ~]# mount /dev/mapper/cryptroot /mnt
[root@archiso ~]# mount /dev/sda2 /mnt/boot
[root@archiso ~]# mount /dev/sda1 /mnt/boot/efi
[root@archiso ~]# swapon /dev/sda3

Виконуємо chroot:

[root@archiso ~]# arch-chroot /mnt/
[root@archiso /]#

Перевіряємо конфіг для ядра:

[root@archiso /]# cat /etc/mkinitcpio.conf | grep HOOKS | tail -1
HOOKS=(base udev autodetect microcode modconf kms keyboard keymap consolefont block encrypt resume filesystems fsck)

Наче все вірно.

Про всяк випадок – можна ще раз зібрати ядро з mkinitcpio -P.

З lsinitcpio перевіримо що в ядрі – мають бути модулі cryptsetup та crypttab:

[root@archiso /]# lsinitcpio /boot/initramfs-linux.img | grep 'cryptsetup\|crypttab'
usr/bin/cryptsetup
usr/lib/libcryptsetup.so.12
usr/lib/libcryptsetup.so.12.10.0

Все є.

Ну і останнє – UUID розділу, який ми задавали в GRUB – отут в мене і була помилка, бо робив blkid /dev/mapper/cryptroot, а не самого розділу /dev/sda4.

Перевіряємо ID розділу з типом crypto_LUKS:

[root@archiso /]# blkid | grep LUKS
/dev/sda4: UUID="738d2f9b-7ffa-4d4e-93be-e00af0a64d5b" TYPE="crypto_LUKS" PARTUUID="32835823-6901-4bbf-9520-1876e64ba109"

Редагуємо /etc/default/grub, вказуємо коректний UUID для cryptdevice, виконуємо grub-mkconfig -o /boot/grub/grub.cfg – готово:

Після старту системи запускаємо idw:

# systemctl start iwd
# systemctl enable iwd

Запускаємо dhcpcd:

# systemctl start dhcpcd
# systemctl enable dhcpcd

І підключаємось до WiFi з iwctl:


Ну а в другій частині саме цікаве – налаштування робочого оточення 🙂

Loading

AI: пишемо MCP-сервер для VictoriaLogs
0 (0)

10 Травня 2025

В попередньому матеріалі розібрались з тим, що таке MCP взагалі, і створили дуже простенький сервер, який підключили до Windsurf – див. AI: що таке той MCP?

Тепер – давайте спробуємо створити щось більш корисне, наприклад – MCP-сервер, який буде підключатись до VictoriaLogs та отримувати якісь дані.

Насправді команда VictoriaMetrcis вже робить власний, тому тут ми “просто пограємось”, аби подивитись на MCP на більш реальному прикладі.

VictoriaLogs API

Спершу спробуємо зробити запит руками, а потім “загорнемо” його в код на Python.

Відкриваємо локальний порт на VictoriaLogs:

$ kubectl port-forward svc/atlas-victoriametrics-victoria-logs-single-server 9428
Forwarding from 127.0.0.1:9428 -> 9428
Forwarding from [::1]:9428 -> 9428

Для роботи з VictoriaLogs ми можемо використати її HTTP API і зробити запит на кшталт такого:

$ curl -X POST http://localhost:9428/select/logsql/query -d 'query=error' -d 'limit=1'
{"_time":"2025-05-08T11:13:44.36173829Z","_stream_id":"0000000000000000ae9096a01bcfdf58cd1159fc206f3aea","_stream":"{namespace=\"ops-monitoring-ns\"}","_msg":"2025-05-08T11:13:44.361Z\twarn\tVictoriaMetrics/lib/promscrape/scrapework.go:383\tcannot scrape target \"http://atlas-victoriametrics-prometheus-blackbox-exporter.ops-monitoring-ns.svc:9115
...

Окей, ту все працює.

Тепер давайте напишемо Python-функцію, яка зробить те саме.

Можемо навіть попросити Cascade у Windsurf це зробити за нас:

Правда, pip install -r requirements.txt все ж довелось виконувати самому в консолі, бо робимо в Python virtual env (хоча пізніше він все ж запропонував виконати python -m venv venv).

В результаті маємо такий код:

import requests

def query_victoria_logs(query: str, limit: int = 1, host: str = "localhost", port: int = 9428) -> dict:
    """
    Query VictoriaLogs endpoint using the logsql/query endpoint.
    
    Args:
        query: The search query to execute
        limit: Maximum number of results to return
        host: VictoriaLogs host (default: localhost)
        port: VictoriaLogs port (default: 9428)
        
    Returns:
        Dictionary containing the response from VictoriaLogs
    """
    url = f"http://{host}:{port}/select/logsql/query"
    params = {
        'query': query,
        'limit': limit
    }
    
    try:
        response = requests.post(url, data=params)
        response.raise_for_status()  # Raise an exception for bad status codes
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error querying VictoriaLogs: {e}")
        return None

if __name__ == "__main__":
    # Example usage
    result = query_victoria_logs(query="error", limit=1)
    if result:
        print("Query results:")
        print(result)
    else:
        print("No results or error occurred")

В цілому – нормально. Достатньо просто, і працює:

$ python victoria_logs_client.py 
Query results:
{'_time': '2025-05-10T11:43:43.694956594Z', '_stream_id': '0000000000000000ae9096a01bcfdf58cd1159fc206f3aea', '_stream': '{namespace="ops-monitoring-ns"}', '_msg': '2025-05-10T11:43:43.694Z\twarn\tVictoriaMetrics/lib/promscrape/scrapework.go:383\tcannot scrape target "http://atlas-victoriametrics-prometheus-blackbox-exporter.ops-monitoring-ns.svc:9115/probe
...

Але далі, коли я попросив Cascade створити MCP-сервер і додати @tool – то він трохи впав в безкінечний цикл 🙂

Окей, anyway – vibe-кодінг це не про нас, ми любимо все робити власними руками.

Створення MCP-серверу для VictoriaLogs

Використовуємо той самий FastMCP, і трохи спростимо функцію:

#!/usr/bin/env python3

from fastmcp import FastMCP
import requests

mcp = FastMCP("VictoriaLogs MCP Server")

@mcp.tool()
def query_victorialogs(query: str, limit: int = 1) -> str:
    """
    Run a LogsQL query against VictoriaLogs and return raw result.
    """
    url = "http://localhost:9428/select/logsql/query"
    data = {
        "query": query,
        "limit": str(limit)
    }

    try:
        response = requests.post(url, data=data)
        response.raise_for_status()
        return response.text
    except requests.RequestException as e:
        return f"Error: {e}"

if __name__ == "__main__":
    mcp.run(transport="stdio")

Встановлюємо fastmcp пакет напряму:

$ pip install fastmcp

Пробуємо запустити:

$ ./victoria_logs_client.py 
[05/10/25 14:56:43] INFO     Starting server "VictoriaLogs MCP Server"...

Наче навіть працює…

Пробуємо додати до Windsufr – my-mcp-server це старий, з попереднього поста, додаємо новий – victoria-logs-mcp.

Редагуємо файл ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "/home/setevoy/Scripts/Python/MCP/my-mcp-server/.venv/bin/mcp",
      "args": [
        "run",
        "/home/setevoy/Scripts/Python/MCP/my-mcp-server/mcp_server.py"
      ]
    },
    "victoria-logs-mcp": {
      "command": "/home/setevoy/Scripts/Python/MCP/my-mcp-server/.venv/bin/python",
      "args": [
        "/home/setevoy/Scripts/Python/MCP/my-mcp-server/victoria_logs_client.py"
      ]
    }
  }
}

Робимо Refresh у Windsurf Settings > MCP, і спробуємо викликати наш новий сервер з запитом “find first log record woth error“:

Офігєть 🙂

І навіть є пояснення помилки з логу – “I found a warning log from VictoriaMetrics about a failed target scrape. The system couldn’t reach the blackbox exporter service, which is causing the issue“.

@tool: аналіз помилок 5хх

Спочатку давайте знову спробуємо з curl:

$ curl -X POST http://localhost:9428/select/logsql/query -d 'query=_msg:~"status=50[024]"' -d 'limit=100' -d 'format=json'
...
{"_time":"2025-05-09T13:59:40.41620395Z","_stream_id":"0000000000000000ae9096a01bcfdf58cd1159fc206f3aea","_stream":"{namespace=\"ops-monitoring-ns\"}","_msg":"level=warn ...
...

Тепер додаємо новий tool в наш код:

...
@mcp.tool()
def analyze_5xx_logs(limit: int = 100) -> str:
    """
    Analyze recent logs with 5xx HTTP status codes by parsing NDJSON response from VictoriaLogs.
    """
    url = "http://localhost:9428/select/logsql/query"
    query = '_msg:~"status=50[0234]"'

    data = {
        "query": query,
        "limit": str(limit),
        "format": "json"
    }

    try:
        response = requests.post(url, data=data)
        response.raise_for_status()

        # NDJSON: parse each line as a separate JSON object
        entries = []
        for line in response.text.strip().splitlines():
            try:
                entry = json.loads(line)
                entries.append(entry)
            except json.JSONDecodeError:
                continue

    except requests.RequestException as e:
        return f"Request error: {e}"

    if not entries:
        return f"No logs found matching: {query}"

    messages = [entry.get("_msg", "") for entry in entries]
    combined = "\n".join(messages[:limit])
    return f"Found {len(messages)} logs matching `{query}`:\n\n{combined}"
...

Зберігаємо зміни в коді, робимо Reload – і для нашого MCP-серверу з’явився новий tool analyze_5xx_logs:

Питаємо Cascade “Analyze the last 10 logs with 502 or 504 errors“:

Моделька навіть сама вирішила уточнити запит – замість “status=50[0234]” зробити просто “status=50[24]“.

І видала свій вердикт по знайденим помилкам:

Ну і це, власне, все, що треба знати по MCP, аби ним користуватись.

Чекаємо офіційного релізу MCP-серверу від VictoriaMetrics.

Loading

AI: що таке той MCP?
0 (0)

10 Травня 2025

Щось всі навколо тільки і говорять що про море про MCP – тож прийшов час і самому розібратись в темі.

Отже, сьогодні розберемося з основними поняттями – “що воно взагалі таке”, потім напишемо власний “мікро-MCP сервер”, а в наступному пості – щось більш реальне, про роботу з VictoriaLogs.

Обмеження LLM

Будь-яка Large Language Model – це система “сама в собі”: в неї немає доступу до зовнішніх ресурсів і вона не може виконати якісь дії в реальному світі, в реальному оточенні – наприклад, виконати shell-команду на вашому ноутбуці чи надіслати API-запит до GitHub або до AWS.

З часом з’явилась концепція “агентів” – локальних сервісів, які модель може викликати або такі дії виконати.

Але тут постала нова проблема: зовнішній світ і кількість сервісів в ньому безмежні, і такі агенти не можуть знати наперед усе про всі сервіси та як з ними взаємодіяти.

Тому врешті-решт з’явився новий стандарт, протокол – Model Context Protocol (MCP), який як раз дозволив розширити можливості LLM та агентів через єдиний і стандартний спосіб описати контекст того, з чим модель буде мати справу.

And so… The MCP?

Отже, Model Context Protocol – це протокол, “схема”, яка описує стандарт, за яким модель може взаємодіяти із зовнішнім середовищем.

Саму специфікацію можна почитати тут – Specification.

Якщо дуже просто, то MCP – це “інтерфейс”, через який LLM може виконувати якісь дії.

Схема роботи MCP – клієнт-серверна:

  • MCP-клієнт, через який ми передаємо запит у вигляді natural language – “створи новий Pull Request в моєму GitHub-репозиторії”
  • та MCP-сервер, до якого LLM звертається, аби цей запит транслювати у формат “сходити на такий-то URL, пройти аутентифікацію з таким-то токеном, виконати такий-то API-запит”

В ролі клієнта може виступити будь-яке рішення, яке вміє говорити з LLM – Cursor IDE, мобільний застосунок, або навіть просто CLI-утиліта.

А в ролі сервера – сервіс, до якого наш клієнт може звернутись із запитом.

Архітектура MCP

Якщо говорити більш детально, то у нас є кілька компонентів:

  • MCP Host: наприклад, Cursor або Windsurf – приймає запит від юзера, формує структурований MCP-запит (виклик функції або tool), і надсилає його до MCP-клієнта
  • MCP Client: це сама LLM (або AI-агент) + її інтерпретатор (interpreter, runtime, tool router), і вони разом приймають запит від MCP Host, визначає, який саме tool треба використати, виконують цей виклик (через MCP Server), та повертають результат
  • MCP Server: сервіс, який надає один чи декілька tools для MCP Client, та виконує запити від MCP Client, наприклад – запускає shell-команди
  • Data Sources та Remote Services: власне те, з чим напряму буде комунікувати MCP-сервер – логи, бази даних, API-сервери

Сам flow виконання запиту можна визначити так:

  • User -> MCP Host
    • MCP Host -> MCP Client (LLM/агент обробляє запит, визначає інструмент)
      • MCP Client -> MCP Server (використовує tool)
        • MCP Server -> Data Sources та Remote Services (отримує дані, формує відповідь)
      • MCP Server -> MCP Client
    • MCP Client -> MCP Host
  • MCP Host -> User

Документація – Core architecture.

Компоненти MCP

Отже, MCP використовує модель клієнт-сервер, і описує три ключові компоненти (або примітиви):

  • Resources: дані, до яких треба звернутись – логи, метрики, база даних, API-відповіді (docs)
  • Prompts: шаблони або форми подачі запитів до LLM – визначають, як саме ми формулюємо питання, щоб модель краще зрозуміла, яку функцію (tool) викликати (docs)
  • Tools: функції, які доступні на MCP-сервері для виклику MCP-клієнтом, і які викликає модель чи агент після аналізу запиту користувача (docs)
    • такими функціями тут можуть бути як функції, наприклад на Python, так і API-ендпоінти або shell-команди

Транспорти MCP

Для комунікації між клієнтом та сервером MCP визначає Transports – канали зв’язку, через які передаються запити та відповіді.

Наразі є три основних типи (MCP все ще активно розроблюється, тому можливо будуть нові):

  • stdio: стандартні потоки stdin/stdout, що використовується коли клієнт та сервер працюють локально
  • SSE (Server-Sent Events): односторонній канал від сервера до клієнта для передачі даних з результатами виконання запиту у вигляді подій
    • SSE може бути реалізований як stream-like даних передача – тобто, передача великих відповідей невеликими chunks (частинами), або як повернення однієї події одним повідомленням
    • в такому разі клієнт використовує стандартний HTTP POST для відправки самого запиту
  • Streamable HTTP: двосторонній канал, у якому клієнт отримує відповідь від сервера через HTTP streaming

Документація – Transport layer.

RAG vs MCP

Але ж у нас вже є Retrieval-Augmented Generation, RAG? Нашо нам новий інструмент?

Бо RAG виконує пошук інформації в зовнішніх середовищах, і повертає до моделі контекст, дані.

А з MCP – модель виконує саме дії: пошук інформації, запуск Docker-контейнеру на ноутбуці тощо.

Створення MCP Server

Окей – з основними поняттями розібрались, тепер давайте спробуємо створити власний MCP і підключити до якогось IDE.

Я буду використовувати Windsurf, бо в ньому все якось вийшло простіше, і він дуже наглядно відображає використання MCP.

MCP Server на Python

Писати будемо на Python з використанням Python SDK.

Створюємо директорію, активуємо virtual environment:

$ mkdir -p MCP/my-mcp-server
$ cd MCP/my-mcp-server
$ python -m venv .venv
$ . .venv/bin/activate

Встановлюємо бібліотеки:

$ pip install mcp mcp[cli] requests

Пишемо сам код:

#!/usr/bin/env python3

from mcp.server.fastmcp import FastMCP

# instantiate an MCP server client
mcp = FastMCP("My MCP Tools")


# Register a tool
@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two integers and return the result"""
    return a + b


if __name__ == "__main__":
    mcp.run(transport="stdio")

Тут:

  • FastMCP: бібліотека для створення MCP-серверів, яка реалізує специфікацію Model Context Protocol
    • from mcp.server.fastmcp import – входить у Python SDK
  • tools: функції, які зможе використовувати LLM – див. Tools
  • run: метод для запуску FastMCP-серверу – див. Running Your FastMCP Server

Використання MCP Inspector

Є дуже прикольно штука для дебагу MCP-серверів – Inspector. Див. документацію тут>>>. Потребує в системі NodeJS >= 18.

Запускаємо:

$ npx @modelcontextprotocol/inspector python3 mcp_server.py
Starting MCP inspector...
⚙ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 
...

І відкриваємо в браузері http://127.0.0.1:6274, де в Tools можемо побачити наш tool add:

Додавання MCP Server до Windsurf

Так як у нас бібліотека mcp встановлена в Python virtual environment, то для її використання в IDE нам потрібен повний шлях.

В терміналі, в якому у нас активований venv виконуємо:

$ realpath .venv/bin/mcp
/home/setevoy/Scripts/Python/MCP/my-mcp-server/.venv/bin/mcp

Файл налаштувань MCP для Windsurf – ~/.codeium/windsurf/mcp_config.json.

Або просто відкриваємо Windsurf Settings:

Клікаємо Add Server > Add custom server:

І нам відкриється файл mcp_config.json з прикладом додавання серверу:

Додаємо наш:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "/home/setevoy/Scripts/Python/MCP/my-mcp-server/.venv/bin/mcp",
      "args": [
        "run",
        "/home/setevoy/Scripts/Python/MCP/my-mcp-server/mcp_server.py"
      ]
    }
  }
}

Повертаємо до Settings, клікаємо Refresh – і маємо отримати наш новий сервер, у якого є один tool – add:

І він жеж має з’явитись у вікні чату:

Пробуємо його використати:

Йой! It works!

LLM (у випадку з Windsurf дефолтна буде Cascade) сама визначила, що в неї є доступ до MCP-серверу, який може виконати математичну операцію add, і використала його.

Найс.

В наступному пості – напишемо власний MCP-сервер для роботи з VictoriaLogs – просто, аби детальніше подивитись як воно працює, бо команда VictoriaMetrics вже робить власний сервер (ще не випустили, але я вже помацаю 🙂 ).

Див. наступну частину по MCP – AI: пишемо MCP-сервер для VictoriaLogs.

Корисні посилання

Loading

Python: знайомство з Celery та його моніторинг
0 (0)

15 Квітня 2025

Якщо дуже просто, то Celery – це щось, за допомогою чого ми можемо виконувати задачі поза нашим основним сервісом.

Наприклад, є Backend API, який має якийсь ендпоінт, на який мобілочки відправляють інформацію про те, що юзер створив новий whatever в застосунку. Задача бекенда – додати whatever в базі даних.

Можна це виконати прямо в інстансі самого API відразу при отриманні івента на ендпоінт, а можна, якщо нам не горить виконання whatever в базі даних, створити паралельну відкладену задачу, яка буде виконана через 1-5-20-60 секунд.

Власне, це і робить Celery:

  • основний код сервісу створює task
  • Celery-клієнт в коді цю задачу відправляє в MQ Broker (Message Queue Broker, як-от RabbitMQ, Redis або мать його єті AWS SQS, див повний список на Broker Overview)
  • Celery Worker отримує меседж з черги
  • Worker запускає якусь функцію, як робить whatever в базі даних
  • profit!

Власне в цьому пості ми не будемо заглиблюватись в деталі реалізації всього цього щастя.

Все, що мені цікаво – це як з цим працювати, тобто – як я можу створити новий task, аби Worker цю задачу виконав.

В ідеалі – ще й перевірити, що задача дійсно була виконана – але тут є проблеми з AWS SQS. Далі подивимось на це детальніше.

Запуск Celery

Зробимо все швиденько локально з Python PiP та Docker, потім ще глянемо на AWS SQS, Kubernetes та моніторинг.

Створення проекту

Встановлюємо сам Celery та залежності для роботи з Redis:

$ mkdir celery
$ cd celery/
$ python -m venv .venv
$ . ./.venv/bin/activate
$ pip install celery
$ pip install -U "celery[redis]"

Запуск Redis

В ролі MQ буде Redis, бо його легко запустити локально і він легенький в плані ресурсів.

Для results backend – теж Redis, але це розглянемо трохи пізніше.

Запускаємо контейнер з Redis:

$ docker run --rm -p 6379:6379 --name redis -e REDIS_ARGS="--bind 0.0.0.0" redis

Заходимо в нього:

$ docker exec -ti redis bash
root@78326cab3d4b:/data#

Перевіряємо:

root@78326cab3d4b:/data# redis-cli ping
PONG

Запуск Celery

Параметри для брокера – див. Broker Settings.

IDK чому в документації параметр називається “broker” а не “broker_url“, бо “broker” наче депрікейтед, а документація “describes the current stable version of Celery (5.4)” (с). Чи, може, --broker – це параметр для командної строки, а broker_url – для конфігу?

Весь код можна просто робити в одному файлі типу tasks.py, як це описано в Getting Started документації, але я відразу розіб’ю на кілька окремих модулів, аби було більше “production way”, тим більше воно вже так зроблено у нас в Production, тому хочеться і під час тестування мати більш схожий сетап.

Створюємо основний модуль для Селері – celery_app.py:

from celery import Celery

app = Celery(__name__, 
                 broker_url='redis://localhost:6379/0',
                 include=["celery_tasks"]
             )

Тут, власне, broker_url – адреса Redis, а в include ми підключаємо наші майбутні таски. Також є опція autodiscover_tasks, але не пробував і у нас не використовується.

Якщо таски не заімпорчені – то будуть помилки типу:

Received unregistered task of type ‘celery_tasks.test_task’.

Створюємо модуль для Celery Tasks – celery_tasks.py:

from celery_app import app

@app.task
def test_task(arg):
    return "OK: " + arg

Власне таска – це просто якась функція, яка має в бекграунді основної системи виконати якусь задачу.

Як в нашому випадку – у нас є API, на який приходяться повідомлення від клієнтів, що юзер створив новий запис у себе в мобільній апці.

Наш API через Celery створює таску, яка їде в RDS, і оновлює табличку з цим юзером, додаючи якісь нові records.

Пишемо наш “API сервіс” – основний код, який буде викликати Celery.

Через метод delay() додаємо створення задачі:

#!/usr/bin/env python

from celery_tasks import test_task
    
test_task.delay("Hello, comrade!")

Запускаємо вже власне Celery Worker – це окремий процес Python (в Kubernetes у нас для цього окремі Pods).

Тобто, Celery-клієнт – це інстанс Celery, який створюється під час запуску API і через який ми створюємо нові задачі в брокері, а Worker – це окремий процес, який займається збором повідомлень і виконанням задач.

Запустити можна просто з термінала:

$ celery -A celery_app worker --loglevel=INFO
...
- ** ---------- [config]
- ** ---------- .> app:         celery_app:0x7d2bb7830980
- ** ---------- .> transport:   redis://localhost:6379/0
- ** ---------- .> results:     disabled://
...
 -------------- [queues]
                .> celery           exchange=celery(direct) key=celery
...

Вже можна глянути ключі в Redis – тут поки нічого особливого, але далі подивимось що взагалі тут створюється:

root@61eff8635cb1:/data# redis-cli keys *
1) "_kombu.binding.celery.pidbox"
2) "_kombu.binding.celery"
3) "_kombu.binding.celeryev"

Так як у нас Redis, то це будуть саме ключі. Але для Celery – це черги, і ключі створюються з типом SET, тобто можуть мати послідовність. Хоча нам зараз такі нюанси не дуже важливі.

Запускаємо наш “API” аби він викликав створення задачі (не забуваємо про activate venv, якщо робимо в окремому терміналі, бо треба імпортити Celery libs):

$ chmod +x my_api_app.py
$ ./my_api_app.py 

Перевіряємо логи Celery Worker – таска отримана, таска оброблена:

...
[2025-03-19 12:48:06,285: INFO/MainProcess] Task celery_tasks.test_task[edbdc0aa-673c-490f-a18f-0b7665db2ff7] received
[2025-03-19 12:48:06,287: INFO/ForkPoolWorker-15] Task celery_tasks.test_task[edbdc0aa-673c-490f-a18f-0b7665db2ff7] succeeded in 0.0003573799040168524s: 'OK: Hello, comrade!'

Default Celery Broker keys

Швиденько глянемо розберемо що Celery створює в чергах і для чого, бо в SQS будемо мати проблеми з деякими з них, тому треба розуміти чому і від чого.

Як вже говорили вище, в Redis це KEYS, але з типом SET (в SQS були б окремі черги):

root@a0c65a5e7bfb:/data# redis-cli type _kombu.binding.celeryev
set

Тут:

  • _kombu.binding.celeryev: використовується Celery Events для надсилання подій про стан воркерів (наприклад, коли воркер запускається, виконує задачу або завершує роботу)
    • використовується для моніторингу через celery events або Flower, ми їх далі подивимось
  • _kombu.binding.celery: головна черга завдань Celery за замовчуванням
    • сюди надсилаються задачі, які потім обробляються Celery Workers
  • _kombu.binding.celery.pidbox: використовується для pidbox messaging, тобто обміну командами між воркерами, наприклад, celery inspect, celery control – і в SQS це теж працювати не буде
    • через нього Celery може надсилати команди воркерам, щоб перевірити їхній стан, змінити рівень логування тощо

Чому _kombu в іменах – бо під капотом Celery використовує бібліотеку Kombu.

Глянемо, що в ключах.

В дефолтній черзі – виконуємо SMEMBERS, бо це тип SET:

root@a06f25448034:/data# redis-cli SMEMBERS _kombu.binding.celery
1) "celery\x06\x16\x06\x16celery"

\x06 та \x16 – це ACK та SYN, які додаються Kombo.

Так як наша задача була виконана – то у нас в _kombu.binding.celery пусто.

Ну і pidbox – інформація про наявний воркер celery@setevoy-wrk-laptop:

root@8d4de6fb1bc6:/data# redis-cli SMEMBERS _kombu.binding.celery.pidbox
1) "\x06\x16\x06\[email protected]"

Можна запустити redis-cli monitor, і побачити все, що відбувається в Redis.

Окей.

Все наче працює.

Що далі?

Додавання result_backend

Без наявного result_backend ми не можемо перевіряти статус виконання тасок, бо Celery просто ніде не зберігає цю інформацію. Див. Keeping Results.

Тобто, якщо ми потім захочемо отримати стан задачі з response = result.get() (далі це зробимо) – то без result_backend отримаємо помилки типу:

│ File “/usr/local/lib/python3.12/site-packages/celery/backends/base.py”, line 1104, in _is_disabled │
│ raise NotImplementedError(E_NO_BACKEND.strip())

Давайте конфіг Celery винесемо теж окремим модулем, celery_config.py, і додамо параметр result_backend з Redis:

broker_url='redis://localhost:6379/0'
result_backend='redis://localhost:6379/0'

include=[
    "celery_tasks"
]

Оновлюємо код celery_app.py – додаємо імпорт конфігу і виклик config_from_object():

import celery_config

from celery import Celery

#app = Celery(__name__, 
#                 broker_url='redis://localhost:6379/0',
#                 include=["celery_tasks"]
#             )

app = Celery(__name__)
app.config_from_object("celery_config", force=True)

Перезапускаємо Celery Worker, і тепер в “results” замість Disabled маємо адресу нашого Redis:

$ celery -A celery_app:app worker --loglevel=INFO
...
- ** ---------- [config]
- ** ---------- .> app:         celery_app:0x78f451ae8980
- ** ---------- .> transport:   redis://localhost:6379/0
- ** ---------- .> results:     redis://localhost:6379/0
...

Оновлюємо код основного сервісу – додамо отримання результату виконання задачі через get():

#!/usr/bin/env python

from celery_tasks import test_task

    
result = test_task.delay("Hello, comrade!")

print(result.get())

Запускаємо наш “API”:

$ ./my_api_app.py 
OK: Hello, comrade!

І в print(result.get()) маємо значення, яке повертає функція test_task() – тобто return "OK" + переданий аргумент.

Окей.

Виглядає, наче тут все класно працює.

А тепер давайте спробуємо використати AWS SQS.

Використання Celery з AWS SQS

Документація – Using Amazon SQS.

Встановлюємо залежності:

$ pip install "celery[sqs]"

Створення SQS

Залишаємо дефолтний тип, Standart:

DLQ нам зараз не потрібна.

Зберігаємо, копіюємо URL – він нам буде потрібний для Celery:

Налаштування Celery з SQS

Редагуємо наш celery_app.py – додаємо AWS ACCESS/SECRET ключі і чергу.

Але спочатку давайте глянемо на доступні опції:

  • broker_url: тут міняємо на sqs
  • broker_transport_options:
    • predefined_queues: варто додати, бо інакше Celery буде шукати доступні SQS з ListQueues, що довго і може бути дорого
      • дефолтна черга може бути задана з task_default_queue
        • якщо task_default_queue не задана, то Celery (мабуть) буде шукати чергу за URL https://sqs.us-east-1.amazonaws.com/492***148/celery
      • чергу також можна передати під час створення таски – @app.task(queue="my_custom_queue")
  • task_create_missing_queues: якщо потрібна черга не знайдена, то Celery спробує її створити – що в SQS нам точно не треба

Тепер конфіг може виглядати так – result_backend поки відключаємо, бо SQS його не підтримує, див. Results:

from kombu.utils.url import safequote

#broker_url='redis://localhost:6379/0'
#result_backend='redis://localhost:6379/0'

aws_access_key = safequote("AKI***B7A")
aws_secret_key = safequote("pAu***2gW")

broker_url = "sqs://{aws_access_key}:{aws_secret_key}@".format(
    aws_access_key=aws_access_key, aws_secret_key=aws_secret_key,
)
broker_transport_options = {
    "region": "us-east-1",
    "predefined_queues": {
        "arseny_test": {
            "url": "https://sqs.us-east-1.amazonaws.com/492***148/arseny-celery-test",
        }
    }
}

task_create_missing_queues = False
task_default_queue = "arseny_test"

include=[
    "celery_tasks"
]

Перезапускаємо воркер:

$ celery -A celery_app worker --loglevel=INFO
...
- ** ---------- [config]
- ** ---------- .> app:         celery_app:0x7d9631ef8980
- ** ---------- .> transport:   sqs://AKI***B7A:**@localhost//
- ** ---------- .> results:     disabled://
- *** --- * --- .> concurrency: 16 (prefork)
-- ******* ---- .> task events: OFF (enable -E to monitor tasks in this worker)
--- ***** ----- 
 -------------- [queues]
                .> arseny_test      exchange=arseny_test(direct) key=arseny_test

[tasks]
  . celery_tasks.test_task
...

Цікаво, що transport @localhost… Але ок.

Перевіряємо вкладку Моніторинг в SQS:

Меседжі пройшли, ОК.

Що далі?

А далі ми спробуємо додати трохи води моніторингу.

Моніторинг Celery в AWS SQS

Власне, як я дійшов до жизні такой до цього посту: є Kubernetes Pod, для якого хочеться мати простий Liveness Probe.

Я за 10 хвилин нагуглив пару методів Celery, оновив Deployment, і вже хотів мержити PR, як виявилось, що…

Отже, в чому зараз проблема: SQS не підтримує кілька корисних нам речей:

  • SQS doesn’t yet support worker remote control commands.
  • SQS doesn’t yet support events, and so cannot be used with celery eventscelerymon, or the Django Admin monitor.

Тобто, якщо ми спробуємо виконати celery inspect ping – то отримаємо помилки. Як мінімум тому, бо для цього потрібна черга pidbox, яка не підтримується в SQS.

Давайте спочатку на ці помилки глянемо.

get() та “No result backend is configured”

Помилку з get() ми вже бачили – якщо спробувати зробити таке без result_backend:

result = test_task.delay("Hello, comrade!")
print(result.get())

То отримаємо NotImplementedError(E_NO_BACKEND.strip()):

...
  File "/home/setevoy/Scripts/Python/celery/.venv/lib/python3.13/site-packages/celery/backends/base.py", line 1104, in _is_disabled
    raise NotImplementedError(E_NO_BACKEND.strip())
NotImplementedError: No result backend is configured.

Окей…

Але ж мабуть така серйозна бібліотека як Celery має власні механізми для перевірки воркерів?

Так – має.

Але…

Celery control inspect

Взагалі, celery.app.control класна штука, і якщо у вас RabbitMQ чи Redis – то з нею можна отримати багато корисної інформації.

Але у нас SQS, тому control працювати не буде.

Пробуємо перевірити таски для воркерів:

$ celery -A celery_app inspect registered
...
  File "/home/setevoy/Scripts/Python/celery/.venv/lib/python3.13/site-packages/kombu/transport/SQS.py", line 381, in _resolve_queue_url
    raise UndefinedQueueException((
    ...<2 lines>...
    ).format(sqs_qname))
kombu.transport.SQS.UndefinedQueueException: Queue with name '0f41e5d5-49e1-38bc-bc9b-c1efbc4f9a3e-reply-celery-pidbox' must be defined in 'predefined_queues'.

Або можемо спробувати пінганути воркери з app.control.ping() – отримаємо ту ж саму помилку з “pidbox must be defined in ‘predefined_queues’“:

@app.task
def celery_health_check():
    response = app.control.ping(timeout=2)
    return response

Ну і теж саме для celery_app.control.inspect().

Є дуже стара GitHub issue – celery ping doesn’t work when using SQS.

І варіанти того, як цю проблему обійти в Kubernetes Liveness probes – просто… Відключити перевірки взагалі. Наприклад – тут>>>.

Можливе рішення: окремий result_backend

Отже, що я зараз намагаюсь зробити – це просто додати result_backend з другим контейнером Redis до Kubernetes Pod з Celery. Ресурсів Redis потребує копійки, тому в принципі якимось оверхедом це не буде.

Тобто, ми маємо:

  • SQS для меседжів
  • Redis для зберігання статусів обробки цих меседжів

Тоді з get() можемо отримати результат виконання тестової таски, і впевнитись, що воркери працюють.

Задаємо result_backend з Redis знов:

...
result_backend='redis://localhost:6379/0'
...

Додаємо нову таску в celery_tasks.py:

@app.task
def celery_health_check():
    return "OK"

Додаємо “моніторинг” в наш “API”, my_api_app.py:

#!/usr/bin/env python

import sys

from celery_tasks import test_task, celery_health_check_task

def celery_health_check():
    try:
        result = celery_health_check_task.apply_async()
        response = result.get(timeout=5)

        print ("Result:", result)
        print ("Result state:", result.state)
        print ("Respose:", response)

        if response != "OK":
            raise RuntimeError("Celery health check task returned unexpected response!")

        print("Celery is running")

    except Exception as e:
        print("Celery health check failed")
        print({"status": "error", "message": str(e)})
        sys.exit(1)

celery_health_check()

delay() – самий простий метод без додаткових параметрів, apply_async() вміє в різні опції. Нам зараз в принципі не важливо, але delay() ми вже використовували, тут давайте з apply_async().

Перезапускаємо Celery Worker, запускаємо наш головний скрипт:

$ ./my_api_app.py 
Result: 2d32805b-3c55-412d-8fc4-4b893f222202
Result state: SUCCESS
Respose: OK
Celery is running

Гуд.

Що ми можемо ще?

Celery та FastAPI

Окрім виклику Celery через імпорти, ми можемо створити FastAPI сервіс, і все робити через TCP.

Встановлюємо fastapi та uvicorn:

$ pip install fastapi uvicorn

Створюємо файл celery_api.py, описуємо FastAPI app:

from fastapi import FastAPI, HTTPException

from celery_tasks import celery_health_check_task

app = FastAPI()


@app.get("/celery-healthz")
def celery_healthcheck():
    try:
        result = celery_health_check_task.apply_async()
        response = result.get(timeout=5)

        if response != "OK":
            raise RuntimeError("Celery health check task returned unexpected response!")

        return {"status": "success", "message": "Celery is running"}

    except Exception as e:
        raise HTTPException(status_code=500, detail={"status": "error", "message": str(e)})

Запускаємо з uvicorn:

$ uvicorn celery_api:app --host 0.0.0.0 --port 8000 --reload

І перевіряємо:

$ curl localhost:8000/celery-healthz
{"status":"success","message":"Celery is running"}

Looks good…

Flower для моніторингу Celery

Flower – популярне рішення для моніторингу Celery, але не буде працювати з SQS з тих самих причин:

  • Flower використовує celery events (celeryev), в SQS не працює
  • список воркерів у Flower використовує Celery inspect(), що, як ми бачили вище, теж не буде працювати з SQS

Якщо мати окремий result_backend, як ми вище робили – то буде працювати частково – можна буде побачити список тасок.

Тому, аби побачити можливості Flower – давайте повернемо Redis в celery_config.py:

broker_url='redis://localhost:6379/0'
result_backend='redis://localhost:6379/0'
...

Встановлюємо Flower:

$ pip install flower

Запускаємо Flower з нашим інстансом Celery та його конфігом:

$ celery -A celery_app flower
[I 250320 13:49:48 command:168] Visit me at http://0.0.0.0:5555
[I 250320 13:49:48 command:176] Broker: redis://localhost:6379/0
[I 250320 13:49:48 command:177] Registered tasks: 
    ['celery.accumulate',
     'celery.backend_cleanup',
     'celery.chain',
     'celery.chord',
     'celery.chord_unlock',
     'celery.chunks',
     'celery.group',
     'celery.map',
     'celery.starmap',
     'celery_tasks.celery_health_check_task',
     'celery_tasks.test_task']
[I 250320 13:49:48 mixins:228] Connected to redis://localhost:6379/0

І відкриваємо в браузері http://localhost:5555:

Можемо використати Flower API для моніторингу:

$ curl -s localhost:5555/api/workers | jq
{
  "celery@setevoy-wrk-laptop": {
    "scheduled": [],
    "timestamp": 1742471544.7675385,
    "active": [],
    "reserved": [],
    ...

Документація по API – API Reference.

Власне, це все.

Celery запустили, як створити таски – подивились, як можна моніторити їх виконання – розібрались.

Залишилось це реалізувати в Production.

Loading

Python: знайомство з декораторами на прикладі FastAPI
0 (0)

18 Березня 2025

В останнє декоратори в Python трогав ще років 10 тому, в Python 2, хочеться трохи оновити пам’ять, бо зараз почав доволі активно ними користуватись, ну і ще раз подивитись як жеж воно працює під капотом, і що воно таке взагалі.

Пост вийшов трохи… дивний? Бо перша половина – в стилі “у нас є одне яблуко, і ми до нього додаємо ще одне”, а друга половина – якісь інтеграли. Але anyway – особисто в мене в голові картинка склалась, розуміння з’явилось, тому най буде так.

Отже, якщо коротко – Python decorator являє собою просто функцію, яка в аргументах приймає іншу функцію, і “додає” до неї якийсь новий функціонал.

Спочатку зробимо власний декоратор, подивимось як все це діло виглядає в пам’яті системи, а потім розберемо FaspAPI та його додавання роутів через app.get("/path").

В кінці будуть кілька корисних посилань, де більше детально розглядається теорія про функції і декоратори в Python, а тут буде суто практична частина.

Простий приклад Python decorator

Описуємо функцію, яка буде нашим декоратором, і нашу “робочу” функцію:

#!/usr/bin/env python

# a decorator function, which accetps another function as an argument
def decorator(func):
  # extend the gotten function with a new feature
  def do_domething():
    print("I'm sothing")
    # execute the function, passed in the argument
    func()
  # return the "featured" functionality
  return do_domething


# just a common function 
def just_a_func():
  print("Just a text")

# run it
just_a_func()

Тут функція decorator() приймає аргументом будь-яку іншу функцію, а just_a_func() – наша “основна” функція, яка робить для нас якісь дії:

$ ./example_decorators.py 
Just a text

Тепер ми можемо зробити такий фінт – створимо змінну $decorated, яка буде посиланням на decorator(), аргументом до decorator() передамо нашу just_a_func(), і викличемо $decorated як функцію:

...
# run it
#just_a_func()

# create a variable pointed to the decorator(), and pass the just_a_func() in the argument
decorated = decorator(just_a_func)
# call the function from the 'decorated' object
decorated()

Результат – у нас виконається і “внутрішня” функція do_domething(), бо вона є в return функції decorator(), і функція just_a_func(), яку ми передали в аргументах – бо в decorator.do_domething() є її виклик:

$ ./example_decorators.py 
I'm sothing
Just a text

А тепер замість того аби створювати змінну і їй призначати функцію decorator() з аргументом – ми можемо зробити те саме, але через виклик декоратора як @decorator перед нашою робочою функцією:

#!/usr/bin/env python

# a decorator function, which accetps another function as an argument
def decorator(func):
  # extend the gotten function with a new feature
  def do_domething():
    print("I'm sothing")
    # execute the function, passed in the argument
    func()
  # return the "featured" functionality
  return do_domething


# just a common function 
#def just_a_func():
#  print("Just a text")

# run it
#just_a_func()

# create a variable pointed to the decorator(), and pass the just_a_func() in the argument
#decorated = decorator(just_a_func)
# call the function from the 'decorated' object
#decorated()

@decorator
def just_a_func():
  print("Just a text")

just_a_func()

І отримаємо той самий результат:

$ ./example_decorators.py 
I'm sothing
Just a text

Як працюють декоратори?

Знаєте, чому з інфраструктурою простіше, ніж з програмуванням? Бо при роботі з серверами-мережами-кубернетесом у нас є якісь умовно-фізичні об’єкти, які ми можемо помацати руками і побачити очима. А в програмуванні – це все треба тримати в голові. Але є дуже дієвий лайф-хак: просто дивись на карту пам’яті процесу.

Давайте розберемо, що відбувається “під капотом”, коли ми використовуємо декоратори:

  • def decorator(func): в пам’яті створюється об’єкт функції decorator()
  • def just_a_func(): аналогічно, створюється об’єкт для функції just_a_func()
  • decorated = decorator(just_a_func): створюється третій об’єкт – змінна decorated:
    • decorated в собі містить посилання на функцію decorator()
    • аргументом до decorator() передається посилання на адресу, де знаходиться just_a_func()
    • функція decorator() створює новий об’єкт – do_domething(), бо вона є в return у decorator()
      • do_domething() виконує якісь додаткові дії, і викликає функцію, яка передана в func

В результаті, при виклику decorated як функції (тобто, з ()) – виконається функція do_domething(), а потім функція, яку передали аргументом, бо в аргументі func є посилання на функцію just_a_func().

Все це можна побачити в консолі:

>>> from example_decorators import *
>>> decorator # check the decorator() address
<function decorator at 0x7668b8eef2e0>
>>> just_a_func # check the just_a_func() address
<function just_a_func at 0x7668b8eef380>
>>> decorated # check the decorated variable address
<function decorator.<locals>.do_domething at 0x7668b8eef420>

Так як в decorated = decorator() ми створили посилання на функцію decorator() яка повертає свою внутрішню функцію do_domething(), то тепер decorated – це функція decorator.do_domething().

А у func ми будемо мати адресу just_a_func.

Для кращого розуміння – давайте просто глянемо на адреси пам’яті з функцією id():

#!/usr/bin/env python

# a decorator function, which accetps another function as an argument
def decorator(func):
  # extend the gotten function with a new feature
  def do_domething():
    #print("I'm sothing")
    print(f"Address of the do_domething() function: {id(do_domething)}")
    # execute the function, passed in the argument
    func()
    print(f"Address of the 'func' argument: {id(func)}")
  # return the "featured" functionality
  return do_domething


# just a common function 
def just_a_func():
  return None
  #print("Just a text")

print(f"Address of the decorator() function object: {id(decorator)}")
print(f"Address of the just_a_func() function object (before decoration): {id(just_a_func)}")

# run it
#just_a_func()

# create a variable pointed to the decorator(), and pass the just_a_func() in the argument
decorated = decorator(just_a_func)
decorated()

print(f"Address of the just_a_func() function object (after decoration): {id(just_a_func)}")
print(f"Address of the 'decorated' variable: {id(decorated)}")

Виконуємо скрипт, і маємо такий результат:

$ ./example_decorators.py 
Address of the decorator() function object: 130166777561632
Address of the just_a_func() function object (before decoration): 130166777574272
Address of the do_domething() function: 130166777574432
Address of the 'func' argument: 130166777574272
Address of the just_a_func() function object (after decoration): 130166777574272
Address of the 'decorated' variable: 130166777574432

Тут:

  • decorator(): об’єкт функції за адресою 130166777561632 (створюється під час запуску програми)
  • just_a_func(): другий об’єкт функції за адресою 130166777574272 (створюється під час запуску програми)
  • виклик decorator() в decorated() створює об’єкт функцій do_domething(), який знаходиться за адресою 130166777574432 (створюється під час виконання decorator())
  • в аргументі func передається адреса об’єкту just_a_func()130166777574272
  • сама функція just_a_func() не змінюється, і знаходиться там жеж – 130166777574272
  • і змінна decorated тепер “відправляє” нас до функції do_domething() за адресою 130166777574432, бо decorator() виконує retrun значення do_domething()

Реальний приклад з FastAPI

Ну і давайте глянемо як це використовується в реальному житті.

Наприклад, я до цього посту прийшов, бо робив нові роути для FastAPI, і мені стало цікаво – як жеж FastAPI app.get("/path") додає роути?

Створимо файл fastapi_routes.py з двома роутами:

#!/usr/bin/env python

from fastapi import FastAPI

app = FastAPI()

# main route
@app.get("/")
def home():
    return {"message": "default route"}

# new route
@app.get("/ping")
def new_route():
    return {"message": "pong"}

Що тут відбувається:

  • створюємо інстанс класу FastAPI()
  • через декоратор @app.get("/") додаємо запуск функції home() при виклику path “/
  • аналогічно робимо для запиту при виклику app з path/ping

Встановлюємо fastapi та uvicorn:

$ python3 -m venv .venv
$ . ./.venv/bin/activate
$ pip install fastapi uvicorn

Запускаємо нашу програму з uvicorn:

$ uvicorn fastapi_routes:app --reload --port 8082
INFO:     Will watch for changes in these directories: ['/home/setevoy/Scripts/Python/decorators']
INFO:     Uvicorn running on http://127.0.0.1:8082 (Press CTRL+C to quit)
INFO:     Started reloader process [2700158] using StatReload
INFO:     Started server process [2700161]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
...

Перевіряємо:

$ curl localhost:8082/    
{"message":"default route"}

$ curl localhost:8082/ping
{"message":"pong"}

Як працює FastAPI get()?

Як це працює?

Сама функція get() не є декоратором, але вона повертає декоратор – див. applications.py#L1460:

..
-> Callable[[DecoratedCallable], DecoratedCallable]:
...
  return self.router.get(...)

Тут:

  • ->: return type annotation (анотація типу поверненого значення), тобто get() повертає якийсь тип даних
    • Callable[...]: повертається тип Callable (функція)
      • Callable[[DecoratedCallable], DecoratedCallable]: функція, яка повертається, приймає аргументом тип DecoratedCallable, і повертає теж тип DecoratedCallable
        • тип DecoratedCallable описаний в types.py: DecoratedCallable = TypeVar("DecoratedCallable", bound=Callable[..., Any]):
          • bound=Callable вказує, що типом даних може бути тільки функція (callable-об’єкт)
          • ця функція може приймати будь-які аргументи – ...,
          • і може повертати будь-які дані – Any
  • виклик app.get() повертає метод self.router.get()
    • а self.router.get() – це метод APIRouter, який описаний в routing.py#:1366, і який повертає метод self.api_route():
      • а функція  api_route(), яка описана в тому ж routing.py#L963 повертає функцію-декоратор decorator(func: DecoratedCallable)
        • а функція decorator() викликає метод add_api_route() – в тому ж routing.py#L994:
          • а add_api_route першим аргументом приймає path, а другим – функцію func, яку треба зв’язати з цим роутом
          • потім add_api_route() повертає func
        • а api_route() повертає decorator()
      • router.get() повертає api_route()
    • app.get() повертає router.get()
...
    def api_route(
        self,
        path: str,
        ...
        ),
    ) -> Callable[[DecoratedCallable], DecoratedCallable]:
        def decorator(func: DecoratedCallable) -> DecoratedCallable:
            self.add_api_route(
                path,
                func,
                ...
            )
            return func

        return decorator
...

Ми могли б переписати цей код так – залишимо додавання “/” через app.get(), а для “/ping” зробимо аналогічно тому, як робили в нашому першому прикладі – через створення змінної.

Тільки тут треба робити два об’єкти – спершу для app.get(), а потім вже викликати decorator() і передавати нашу функцію:

#!/usr/bin/env python

from fastapi import FastAPI

app = FastAPI()
  
# main route
@app.get("/")
def home():
    return {"message": "default route"}

# new route
def new_route():
    return {"message": "pong"}

# create 'decorator' variable pointed to the app.get() function
# the 'decorator' then will return another function, the decorator() itself
decorator = app.get("/ping")

# create another variable using the decorator() returned by the get() above, and pass our function
decorated = decorator(new_route)

Результат буде аналогічним в обох випадках – і для “/“, і для “/ping“.

Для більшої ясності – давайте це знову зробимо в консолі:

>>> from fastapi import FastAPI
>>> app = FastAPI()
>>> def new_route():
...     return {"message": "pong"}
...     
>>> decorator = app.get("/ping")
>>> decorated = decorator(new_route)

І перевіримо типи об’єктів та адреси пам’яті:

>>> app
<fastapi.applications.FastAPI object at 0x7381bb521940>
>>> app.get("/ping")
<function APIRouter.api_route.<locals>.decorator at 0x7381bb5a2480>
>>> decorator
<function APIRouter.api_route.<locals>.decorator at 0x7381bb5a2200>
>>> new_route
<function new_route at 0x7381bb5a22a0>
>>> decorated
<function new_route at 0x7381bb5a22a0>

Або навіть можемо просто використати метод add_api_route() напряму, прибравши виклик @app.get:

#!/usr/bin/env python

from fastapi import FastAPI

app = FastAPI()
  
# main route
#@app.get("/")
def home():
    return {"message": "default route"}
    
app.add_api_route("/", home)

# new route 
#@app.get("/ping")
def new_route():
    return {"message": "pong"}

app.add_api_route("/ping", new_route)

Власне, це все, що треба знати про використання get() як декоратор в FastAPI.

Корисні посилання

Loading

Kubernetes: знайти каталог з mounted volume в Pod на хості
0 (0)

10 Березня 2025

Маємо AWS Elastic Kubernetes Service, на якому розгорнуто стек VictoriaMetrics (див. VictoriaMetrics: створення Kubernetes monitoring stack з власним Helm-чартом).

Треба перенести дані зі старого поду VMSingle на новий, на новому кластері, а для цього треба знайти ці дані на EC2.

Note: щодо міграції даних VMSingle, то для неї є утиліта vmctl, десь в чернетках лежить пост, як буду робити наступну міграцію – то допишу

Перевірка VMSingle Kubernetes Pod

Перевіряємо дані VMSingle Kubernetes Pod – знаходимо його EC2-інстанс, відповідний Container ID та Mounts:

$ kk describe pod vmsingle-vm-k8s-stack-67d585c9cd-jt4f7
Name:             vmsingle-vm-k8s-stack-67d585c9cd-jt4f7
...
Node:             ip-10-0-46-247.ec2.internal/10.0.46.247
...
Containers:
  vmsingle:
    Container ID:  containerd://57398c3184cd229be564b140f32a9214b38a507137522904eab6ae38b676432a
...
    Mounts:
      /var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-5xmmq (ro)
      /victoria-metrics-data from data (rw)
...

Підключаємось на сервер (див. AWS: Karpenter та SSH для Kubernetes WorkerNodes):

$ ssh -i .ssh/hOS/atlas-eks-ec2 [email protected]
[ec2-user@ip-10-0-46-247 ~]$ sudo -s
[root@ip-10-0-46-247 ec2-user]#

Але звичного docker CLI тут нема, бо з версії 1.24 у вже ContainerD замість dockershim (див. All you need to know about moving to containerd on Amazon EKS):

[root@ip-10-0-46-247 ec2-user]# docker
bash: docker: command not found

Для роботи з containerd маємо утиліту crictl (Container Runtime Interface CTL):

[root@ip-10-0-46-247 ec2-user]# crictl 
NAME:
   crictl - client for CRI

USAGE:
   crictl [global options] command [command options] [arguments...]

COMMANDS:
   attach              Attach to a running container
   create              Create a new container
   exec                Run a command in a running container
   version             Display runtime version information
   images, image, img  List images
   inspect             Display the status of one or more containers
   inspecti            Return the status of one or more images
   ...

Варіант 1: використання crictl inspect та hostPath

Використовуючи Container ID із kubectl describe pod отримаємо інформацію про цей контейнер на хості і про його mounts:

[root@ip-10-0-46-247 ec2-user]# crictl inspect 57398c3184cd229be564b140f32a9214b38a507137522904eab6ae38b676432a
...
    "mounts": [
      {
        "containerPath": "/victoria-metrics-data",
        "gidMappings": [],
        "hostPath": "/var/lib/kubelet/pods/7b2b0205-8c7e-430f-995b-a45cd79ecb9f/volumes/kubernetes.io~csi/pvc-ed3831bc-56a2-4660-9aef-b47cd252edac/mount",
...

Перевіряємо каталог з hostPath за EC2:

[root@ip-10-0-46-247 ec2-user]# ll /var/lib/kubelet/pods/7b2b0205-8c7e-430f-995b-a45cd79ecb9f/volumes/kubernetes.io~csi/pvc-ed3831bc-56a2-4660-9aef-b47cd252edac/mount
total 40
drwxr-xr-x 6 root root  4096 Oct  1 00:51 cache
drwxr-xr-x 4 root root  4096 Dec  4  2023 data
-rw-r--r-- 1 root root     0 Oct  1 00:52 flock.lock
drwxr-xr-x 6 root root  4096 Sep 29 04:00 indexdb
drwx------ 2 root root 16384 Dec  4  2023 lost+found
drwxr-xr-x 2 root root  4096 Dec  4  2023 metadata
drwxr-xr-x 2 root root  4096 Dec  4  2023 snapshots
drwxr-xr-x 3 root root  4096 Oct  1 00:52 tmp

Варіант 2: з /proc/PID/root

Інший варіант – через PID процесу який ми теж бачили в crictl inspect – в данному випадку це буде 57398c3184cd229be564b140f32a9214b38a507137522904eab6ae38b676432a:

...
  "info": {
    ...
    "pid": 6933,
    ...
    "config": {
      "metadata": {
        "name": "vmsingle"
      },
...

Тоді на хості можемо перевірити /proc/<PID>/root:

[root@ip-10-0-46-247 ec2-user]# ll /proc/6933/root/victoria-metrics-data/
total 40
drwxr-xr-x 6 root root  4096 Oct  1 00:51 cache
drwxr-xr-x 4 root root  4096 Dec  4  2023 data
-rw-r--r-- 1 root root     0 Oct  1 00:52 flock.lock
drwxr-xr-x 6 root root  4096 Sep 29 04:00 indexdb
drwx------ 2 root root 16384 Dec  4  2023 lost+found
drwxr-xr-x 2 root root  4096 Dec  4  2023 metadata
drwxr-xr-x 2 root root  4096 Dec  4  2023 snapshots
drwxr-xr-x 3 root root  4096 Oct  1 00:52 tmp

Готово. Тепер можна зробити rsync цього каталогу на новий Kubernetes WorkerNode.

Loading

Nexus: налаштування Docker proxy repository та ContainerD в Kubernetes
0 (0)

5 Березня 2025

Про запуск Nexus писав в пості Nexus: запуск в Kubernetes та налаштування PyPi caching repository, тепер до PyPi хочеться додати кешування Docker images, тим більш Docker Hub з 1-го квітня 2025 вводить нові ліміти – див. Docker Hub usage and limits (дяка @Anatolii).

Робити будемо як завжди – спочатку вручну локально на робочій машині, подивимось, як воно працює, а потім додамо конфіг для Helm-чарту, задеплоїмо в Kubernetes, і подивимось, як налаштувати ContainerD для використання цього mirror.

Запуск Sonatype Nexus локально з Docker

Створюємо локальний каталог для nexus data, аби дані зберігались при рестарті Docker, міняємо юзера, бо будемо ловити помилки типу:

...
mkdir: cannot create directory '../sonatype-work/nexus3/log': Permission denied
mkdir: cannot create directory '../sonatype-work/nexus3/tmp': Permission denied
...

Виконуємо:

$ mkdir /home/setevoy/Temp/nexus3-data/
$ sudo chown -R 200:200 /home/setevoy/Temp/nexus3-data/

Запускаємо Nexus з цією директорією, і додаємо порти для доступу до самого Nexus та для Docker registry, який створимо далі:

$ docker run  -p 8080:8081 -p 8092:8092 --name nexus3 --restart=always -v /home/setevoy/Temp/nexus3-data:/nexus-data sonatype/nexus3

Чекаємо, поки все запуститься, і отримуємо пароль для admin:

$ docker exec -ti nexus3 cat /nexus-data/admin.password
d549658c-f57a-4339-a589-1f244d4dd21b

Заходимо в браузері на http://localhost:8080, логінимось в систему:

Setup wizard можна пропустити, або швиденько проклікати “Next” і задати новий пароль адміну.

Створення Docker cache repository

Переходимо в Administration > Repository > Repositories:

Клікаємо Create repository:

Вибираємо тип docker (proxy):

Задаємо ім’я, HTTP-порт, на якому будуть прийматись конекти від docker-daemon, і дозволяємо anonymous docker pull:

Далі задаємо адресу, з якої будемо пулити образи – https://registry-1.docker.io, решту параметрів поки можна залишити без змін:

Окремо варто згадати можливість створення docker (group), де налаштовується єдиний конектор для кількох репозиторіїв в Nexus. Але мені це поки не потрібно, хоча в майбутньому – можливо.

Див. Grouping Docker Repositories та Using Nexus OSS as a proxy/cache for Docker images.

Включення Docker Security Realm

Хоча ми і не використовуємо аутентифікацію, але реалм треба включити.

Переходимо в Security > Realms, додаємо Docker Bearer Token Realm:

Перевірка Docker mirror

Знаходимо IP контейнера, в якому запущено Nexus:

$ docker inspect nexus3
...
        "NetworkSettings": {
           ..
            "Networks": {
              ...
                    "IPAddress": "172.17.0.2",
...

Порт для Docker cache в Nexus ми задавали 8092.

На робочій машині редагуємо файл /etc/docker/daemon.json, задаємо registry-mirrors та insecure-registries, бо у нас нема SSL:

{
        "insecure-registries": ["http://172.17.0.2:8092"],
        "registry-mirrors": ["http://172.17.0.2:8092"]
}

Ребутаємо локальний Docker service:

$ systemctl restart docker

Виконуємо docker info, перевіряємо, що зміни застосовані:

$ docker info
...
 Insecure Registries:
  172.17.0.2:8092
  ::1/128
  127.0.0.0/8
 Registry Mirrors:
  http://172.17.0.2:8092/

Виконуємо docker pull nginx – запит має піти через Nexus, і там зберегти копії даних:

Якщо дані не з’являються – то скоріш за все проблема з аутентифікацією.

Для перевірки до /etc/docker/daemon.json додаємо debug=true:

{
        "insecure-registries": ["http://172.17.0.2:8092"],
        "registry-mirrors": ["http://172.17.0.2:8092"],
        "debug": true
}

Рестартимо локальний Docker, виконуємо docker pull і дивимось логи с journalctl -u docker:

$ sudo journalctl -u docker --no-pager -f
...
level=debug msg="Trying to pull rabbitmq from http://172.17.0.2:8092/"
level=info msg="Attempting next endpoint for pull after error: Head \"http://172.17.0.2:8092/v2/library/rabbitmq/manifests/latest\": unauthorized: "
level=debug msg="Trying to pull rabbitmq from https://registry-1.docker.io"
...

Першого разу я забув включити Docker Bearer Token Realm.

А другого разу в мене в ~/.docker/config.json був збережений токен для https://index.docker.io, і Docker намагався використати його. В такому випадку можна просто видалити/перемістити config.json, і виконати pull ще раз.

Окей.

А що там с ContainerD? Бо в AWS Elastic Kubenretes Service у нас не Docker.

ContainerD та registry mirrors

Чесно кажучи, з containerd болі було більше, ніж з Nexus. Тут і його TOML для конфігів, і різні версії самого ContainerD та конфігурації, і deprecated параметри.

В мене просто очі болять від такого формату:

[plugins]
  [plugins.'io.containerd.cri.v1.runtime']
    [plugins.'io.containerd.cri.v1.runtime'.containerd]
      [plugins.'io.containerd.cri.v1.runtime'.containerd.runtimes]
        [plugins.'io.containerd.cri.v1.runtime'.containerd.runtimes.runc]
          [plugins.'io.containerd.cri.v1.runtime'.containerd.runtimes.runc.options]

Anyway, воно все ж запрацювало, тому поїхали.

Давайте спочатку теж зробимо локально, потім вже будемо налаштовувати в Kubernetes.

На Arch Linux встановлюємо з pacman:

$ sudo pacman -S containerd crictl

Генеруємо дефолтний конфіг для containerd:

$ sudo mkdir /etc/containerd/
$ containerd config default | sudo tee /etc/containerd/config.toml

В файл /etc/containerd/config.toml додаємо параметри для mirrors:

...
[plugins]
  [plugins.'io.containerd.cri.v1.images']
...
    [plugins.'io.containerd.cri.v1.images'.registry]
      [plugins.'io.containerd.cri.v1.images'.registry.mirrors."docker.io"]
        endpoint = ["http://172.17.0.2:8092"]
...

Тут:

  • plugins.'io.containerd.cri.v1.images: параметри для image service, управління образами
    • registry: налаштування registry для images service
      • mirrors."docker.io": дзеркала для docker.io
        • endpoint: куди звертатись, коли треба спулити образ з docker.io

Перезапускаємо containerd:

$ sudo systemctl restart containerd

Перевіряємо, що нові параметри застосовані:

$ containerd config dump | grep -A 1 mirrors
      [plugins.'io.containerd.cri.v1.images'.registry.mirrors]
        [plugins.'io.containerd.cri.v1.images'.registry.mirrors.'docker.io']
          endpoint = ['http://172.17.0.2:8092']

Виконуємо crictl pull:

$ sudo crictl pull ubuntu

І перевіряємо Nexus:

З’явився образ Ubuntu.

Тут наче все працює – давайте спробуємо це все діло налаштувати в Kubernetes.

Nexus Helm chart values та Kubernetes

В частині Додавання репозиторію в Nexus через Helm chart values трохи писав про те, як і які values додавались для запуску з Nexus Helm chart в Kubernetes для кешу PyPi.

Трохи їх оновимо:

  • додамо окремий blob store: підключимо окремий persistentVolume, бо в дефолтному лише 8 гіг, і якщо для PyPi цього більш-менш достатньо, то для Docker images буде замало
  • додамо additionalPorts: тут задаємо порт, на якому буде Docker cache
  • включимо Ingress

Всі values – values.yaml.

В мене деплоїться з Terraform під час налаштування Kubernetes-кластеру.

Все разом, з PyPi, в мене зараз виглядає так:

resource "helm_release" "nexus" {
  namespace        = "ops-nexus-ns"
  create_namespace = true

  name                = "nexus3"
  repository          = "https://stevehipwell.github.io/helm-charts/"
  #repository_username = data.aws_ecrpublic_authorization_token.token.user_name
  #repository_password = data.aws_ecrpublic_authorization_token.token.password
  chart               = "nexus3"
  version             = "5.7.2"
  # also:
  #  Environment:
  #  INSTALL4J_ADD_VM_PARAMS:          -Djava.util.prefs.userRoot=${NEXUS_DATA}/javaprefs -Xms1024m -Xmx1024m -XX:MaxDirectMemorySize=2048m
  values = [
    <<-EOT
      # use existing Kubernetes Secret with admin's password
      rootPassword:
        secret: nexus-root-password
        key: password

      # enable storage
      persistence:
        enabled: true
        storageClass: gp2-retain

      # create additional PersistentVolume to store Docker cached data
      extraVolumes:
        - name: nexus-docker-volume
          persistentVolumeClaim:
            claimName: nexus-docker-pvc

      # mount the PersistentVolume into the Nexus' Pod
      extraVolumeMounts:
        - name: nexus-docker-volume
          mountPath: /data/nexus/docker-cache

      resources:
        requests:
          cpu: 100m
          memory: 2000Mi
        limits:
          cpu: 500m
          memory: 3000Mi

      # enable to collect Nexus metrics to VictoriaMetrics/Prometheus
      metrics:
        enabled: true
        serviceMonitor:
          enabled: true

      # use dedicated ServiceAccount
      # still, EKS Pod Identity isn't working (yet?)
      serviceAccount:
        create: true
        name: nexus3
        automountToken: true

      # add additional TCP port for the Docker caching listener
      service:
        additionalPorts:
          - port: 8082
            name: docker-proxy
            containerPort: 8082
            hosts:
              - nexus-docker.ops.example.co

      # to be able to connect from Kubernetes WorkerNodes, we have to have a dedicated AWS LoadBalancer, not only Kubernetes Service with ClusterIP
      ingress:
        enabled: true
        annotations:
          alb.ingress.kubernetes.io/group.name: ops-1-30-internal-alb
          alb.ingress.kubernetes.io/target-type: ip
        ingressClassName: alb
        hosts:
        - nexus.ops.example.co

      # define the Nexus configuration
      config:
        enabled: true
        anonymous:
          enabled: true

        blobStores:

          # local EBS storage; 8 GB total default size ('persistence' config above)
          # is attached to a repository in the 'repos.pip-cache' below
          - name: default
            type: file
            path: /nexus-data/blobs/default
            softQuota:
              type: spaceRemainingQuota
              limit: 500

          # dedicated sorage for PyPi caching
          - name: PyPILocalStore
            type: file
            path: /nexus-data/blobs/pypi
            softQuota:
              type: spaceRemainingQuota
              limit: 500              

          # dedicated sorage for Docker caching
          - name: DockerCacheLocalStore
            type: file
            path: /data/nexus/docker-cache
            softQuota:
              type: spaceRemainingQuota
              limit: 500

        # enable Docker Bearer Token Realm
        realms:
          enabled: true
          values:
            - NexusAuthenticatingRealm
            - DockerToken

        # cleanup policies for Blob Storages
        # is attached to epositories below
        cleanup:
          - name: CleanupAll
            notes: "Cleanup content that hasn't been updated in 14 days downloaded in 28 days."
            format: ALL_FORMATS
            mode: delete
            criteria:
              isPrerelease:
              lastBlobUpdated: "1209600"
              lastDownloaded: "2419200"

        repos:

          - name: pip-cache
            format: pypi
            type: proxy
            online: true
            negativeCache:
              enabled: true
              timeToLive: 1440
            proxy:
              remoteUrl: https://pypi.org
              metadataMaxAge: 1440
              contentMaxAge: 1440
            httpClient:
              blocked: false
              autoBlock: true
              connection:
              retries: 0
              useTrustStore: false
            storage:
              blobStoreName: default
              strictContentTypeValidation: false
            cleanup:
              policyNames:
                - CleanupAll

          - name: docker-cache
            format: docker
            type: proxy
            online: true
            negativeCache:
              enabled: true
              timeToLive: 1440
            proxy:
              remoteUrl: https://registry-1.docker.io
              metadataMaxAge: 1440
              contentMaxAge: 1440
            httpClient:
              blocked: false
              autoBlock: true
              connection:
              retries: 0
              useTrustStore: false
            storage:
              blobStoreName: DockerCacheLocalStore
              strictContentTypeValidation: false
            cleanup:
              policyNames:
                - CleanupAll
            docker:
              v1Enabled: false
              forceBasicAuth: false
              httpPort: 8082
            dockerProxy:
              indexType: "REGISTRY"
              cacheForeignLayers: "true"
    EOT
  ]
}

Деплоїмо, відкриваємо порт:

$ kk -n ops-nexus-ns port-forward svc/nexus3 8081

Перевіряємо Realm:

Перевіряємо сам Docker repository:

Гуд.

Ingress/ALB для Nexus Docker cache

Так як ContainerD на EC2 не відноситься до Kubernetes, то і доступу до Kubernetes Service з ClusterIP в нього нема. Відповідно, він не зможе виконати pull образів з порта 8082 на nexus3.ops-nexus-ns.svc.cluster.local.

В Helm chart є можливість створити окремий Ingress, в якому задаємо всі параметри:

...
      # to be able to connect from Kubernetes WorkerNodes, we have to have a dedicated AWS LoadBalancer, not only Kubernetes Service with ClusterIP
      ingress:
        enabled: true
        annotations:
          alb.ingress.kubernetes.io/group.name: ops-1-30-internal-alb
          alb.ingress.kubernetes.io/target-type: ip
        ingressClassName: alb
        hosts:
        - nexus.ops.example.co
...

В мене використовується анотація alb.ingress.kubernetes.io/group.name для обєднання кількох Kubernetes Ingress через один AWS LoadBalancer, див. Kubernetes: єдиний AWS Load Balancer для різних Kubernetes Ingress.

Важливий нюанс тут: в параметрах Ingress не треба додавати порти і хости, які задані в Service.

Тобто, для:

...
      # add additional TCP port for the Docker caching listener
      service:
        additionalPorts:
          - port: 8082
            name: docker-proxy
            containerPort: 8082
            hosts:
              - nexus-docker.ops.example.co
...

В Helm-чарті автоматично створиться роут на Ingress:

$ kk -n ops-nexus-ns get ingress nexus3 -o yaml
...
spec:
  ingressClassName: alb
  rules:
  - host: nexus.ops.example.co
    http:
      paths:
      - backend:
          service:
            name: nexus3
            port:
              name: http
        path: /
        pathType: Prefix
  - host: nexus-docker.ops.example.co
    http:
      paths:
      - backend:
          service:
            name: nexus3
            port:
              name: docker-proxy
        path: /
        pathType: Prefix

Див. ingress.yaml.

Го далі.

Налаштування ContainerD mirror на Kubernetes WorkerNode

Вже бачили локально, в AWS EKS в принципі все теж саме.

Єдине, що локально у нас версія v2.0.3, а в AWS EKS – 1.7.25, тому формат конфігу буде трохи різний.

На AWS EKS WorkerNode/EC2 перевіряємо файл /etc/containerd/config.toml:

...

[plugins."io.containerd.grpc.v1.cri".registry]
config_path = "/etc/containerd/certs.d:/etc/docker/certs.d"
...

Поки руками додаємо сюди нове дзеркало – тут і є трохи відмінності від того, що ми робили локально. Див. приклади в Configure Registry Credentials Example – GCR with Service Account Key Authentication.

Тобто, для containerd версії 1 – версія конфігу == 2, а для containerd версії 2 – версія конфігу == 3…? Okay, man… 

На EC2 конфіг буде виглядати так:

[plugins."io.containerd.grpc.v1.cri".registry]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
      endpoint = ["http://nexus-docker.ops.example.co"]

Порт не задаємо, бо на AWS ALB це розрулиться через hostname, який зароутить запит на потрібний Listener.

Рестартимо сервіс:

[root@ip-10-0-32-218 ec2-user]# systemctl restart containerd

Виконуємо pull якогось образу:

[root@ip-10-0-46-186 ec2-user]# crictl pull nginx

Перевіряємо Nexus:

Все є.

Залишилось додати налаштування ContainerD при створенні сервері з Karpenter.

Karpenter та конфіг для ContainerD

В мене EC2NodeClass для Karpenter створюються в Terraform, див. Terraform: створення EKS, частина 3 – установка Karpenter.

Звістно, всі ці операції краще виконувати на тестовому оточенні, або створити окремий NodeClass та NodePool.

Зараз там через AWS EC2 UserData конфігуриться ~ec2-user/.ssh/authorized_keys для SSH (див. AWS: Karpenter та SSH для Kubernetes WorkerNodes), і сюди ж можемо додати створення файлу для ContainerD mirror.

В дефолтному варіанті ми бачили, що containerd буде перевіряти такі каталоги:

...
[plugins."io.containerd.grpc.v1.cri".registry] 
  config_path = "/etc/containerd/certs.d:/etc/docker/certs.d"
...

Отже, в них можемо додати новий файл.

Але пам’ятаєте, як в тому анекдоті – “А тепер забудьте все, чому вас вчили в університеті”?

Ну, от – забудьте все, що ми робили з конфігами containerd вище, бо це вже deprecated way. Тепер стільно-модно-молодьожно робити з Registry Host Namespace.

Ідея в тому, що в /etc/containerd/certs.d створюється каталог для registry, в ньому файл hosts.toml, а вже в ньому – описується налаштування registry.

В нашому випадку виглядати це буде так:

[root@ip-10-0-45-117 ec2-user]# tree /etc/containerd/certs.d/
/etc/containerd/certs.d/
└── docker.io
    └── hosts.toml

І в hosts.toml:

server = "https://docker.io"

[host."http://nexus-docker.ops.example.co"]
  capabilities = ["pull", "resolve"]

Окей. Описуємо це все діло в UserData нашого тестового EC2NodeClass.

Так тут наш “улюблений” YAML – то приведу весь конфіг, аби не мати проблем з відступами, бо трохи погемороївся:

resource "kubectl_manifest" "karpenter_node_class_test_latest" {
  yaml_body = <<-YAML
    apiVersion: karpenter.k8s.aws/v1
    kind: EC2NodeClass
    metadata:
      name: class-test-latest
    spec:
      kubelet:
        maxPods: 110
      blockDeviceMappings:
        - deviceName: /dev/xvda
          ebs:
            volumeSize: 40Gi
            volumeType: gp3
      amiSelectorTerms:
        - alias: al2@latest
      role: ${module.eks.eks_managed_node_groups["${local.env_name_short}-default"].iam_role_name}
      subnetSelectorTerms:
        - tags:
            karpenter.sh/discovery: "atlas-vpc-${var.aws_environment}-private"
      securityGroupSelectorTerms:
        - tags:
            karpenter.sh/discovery: ${var.env_name}
      tags:
        Name: ${local.env_name_short}-karpenter
        nodeclass: test
        environment: ${var.eks_environment}
        created-by: "karpenter"
        karpenter.sh/discovery: ${module.eks.cluster_name}
      userData: |
        #!/bin/bash
        set -e

        mkdir -p ~ec2-user/.ssh/
        touch ~ec2-user/.ssh/authorized_keys
        echo "${var.karpenter_nodeclass_ssh}" >> ~ec2-user/.ssh/authorized_keys
        chmod 600 ~ec2-user/.ssh/authorized_keys
        chown -R ec2-user:ec2-user ~ec2-user/.ssh/

        mkdir -p /etc/containerd/certs.d/docker.io

        cat <<EOF | tee /etc/containerd/certs.d/docker.io/hosts.toml

        server = "https://docker.io"

        [host."http://nexus-docker.ops.example.co"]
          capabilities = ["pull", "resolve"]
        EOF

        systemctl restart containerd
  YAML

  depends_on = [
    helm_release.karpenter
  ]
}

Для створення EC2 маю окремий тестовий Pod, який має tolerations і nodeAffinity (див. Kubernetes: Pods та WorkerNodes – контроль розміщення подів на нодах), через які Karpenter має створити EC2 саме з “class-test-latest” EC2NodeClass:

apiVersion: v1
kind: Pod
metadata:
  name: test-pod
spec:
  containers:
    - name: nginx
      image: nginx
      command: ['sleep', '36000']
  restartPolicy: Never
  tolerations:
    - key: "TestOnly"
      effect: "NoSchedule"  
      operator: "Exists"
  affinity:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
          - matchExpressions:
              - key: component
                operator: In
                values:
                  - test

Деплоїмо зміни, деплоїмо Pod, логінимось на EC2 та перевіряємо конфіг:

[root@ip-10-0-45-117 ec2-user]# cat /etc/containerd/certs.d/docker.io/hosts.toml 

server = "https://docker.io"

[host."http://nexus-docker.ops.example.co"]
  capabilities = ["pull", "resolve"]

Ще раз виконуємо pull якого-небудь PHP:

[root@ip-10-0-43-82 ec2-user]# crictl pull php

І перевіряємо Nexus:

Готово.

Корисні посилання

Loading

Arch Linux: підключення розділів LVM та запуск mkinitcpio
0 (0)

4 Березня 2025

Не часто, але іноді виникає потреба завантажити систему з usb, і перезібрати initramfs-linux.img.

Цей пост – скоріш просто невеликий нотаток для себе як, що, і куди маунтити на робочому ноуті, аби запустити mkinitcpio, бо в мене є розділи LVM, є окремі розділи на диску під /boot та swap.

iwctl та WiFi 

Отже, завантажуємось з флешки, і налаштовуємо WiFi, аби далі всі команди робити з іншого компа, де можна копіпастити з RTFM:

[root@archiso ~]# iwctl
# station wlan0 connect setevoy-linksys-5-0

Задаємо пароль root:

[root@archiso ~]# passwd root

Отримуємо IP:

[root@archiso ~]# ip a s wlan0
3: wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
    inet 192.168.3.114/24 brd 192.168.3.255 scope global dynamic noprefixroute wlan0

І підключаємо з іншого ноута:

[setevoy@setevoy-home-laptop ~] $ ssh [email protected]

Підключення розділів LVM

Знаходимо volume group:

[root@archiso ~]# vgscan
  Found volume group "vg_arch" using metadata type lvm2

Активуємо його:

[root@archiso ~]# vgchange -ay
  2 logical volume(s) in volume group "vg_arch" now active

Згадуємо, які в системі є logical volumes, в мене їх два – один корневий під систему, інший під $HOME:

[root@archiso ~]# lvdisplay
  --- Logical volume ---
  LV Path                /dev/vg_arch/root
...
   
  --- Logical volume ---
  LV Path                /dev/vg_arch/home
...

Маунтимо /dev/vg_arch/root до /mnt:

[root@archiso ~]# mount /dev/vg_arch/root /mnt/

Підключення /boot

Глянемо решту дисків і розділів:

[root@archiso ~]# lsblk 
NAME             MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
loop0              7:0    0 820.6M  1 loop /run/archiso/airootfs
sda                8:0    1  28.9G  0 disk 
└─sda1             8:1    1  28.9G  0 part 
nvme0n1          259:0    0 465.8G  0 disk 
├─nvme0n1p1      259:1    0   512M  0 part 
├─nvme0n1p2      259:2    0     1G  0 part 
├─nvme0n1p3      259:3    0    32G  0 part 
└─nvme0n1p4      259:4    0 432.3G  0 part 
  ├─vg_arch-root 254:0    0   100G  0 lvm  /mnt
  └─vg_arch-home 254:1    0 332.3G  0 lvm

Оце саме та трохи tricky part, де я постійно забуваю що і як в мене маунтиться – але у нас є fstab, де все описано.

Наприклад, я колись витратив багато часу перезбираючи initramfs-образ, але система все одно не завантажувалась.

І лише через деякий час я згадав, що в мене і /boot на окремому розділі:

[root@archiso ~]# cat /mnt/etc/fstab 
# /dev/mapper/vg_arch-root
UUID=8569a65c-d848-427d-bcd0-5046d0e07f2b       /               ext4            rw,relatime     0 1

# /dev/mapper/vg_arch-home
UUID=0ae5ba43-3bb3-4826-8570-8918a82bf27f       /home           ext4            rw,relatime     0 2

# /dev/nvme0n1p1
UUID=54C4-1990          /boot/EFI       vfat            rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=iso8859-1,shortname=mixed,utf8,errors=remount-ro       0 2

# /dev/nvme0n1p2
UUID=6a42ffb4-6811-4176-b26e-873f49aea3b0       /boot           ext2            rw,relatime     0 2

# /dev/nvme0n1p3
UUID=08d2ae9d-28fa-4d20-9d06-72d1b7fdc21d       none            swap            defaults        0 0

Маунтимо /dev/nvme0n1p2 в /mnt/boot/:

[root@archiso ~]# mount /dev/nvme0n1p2 /mnt/boot/

Глянемо, що там зараз – а зараз нічого нема, бо під час апдейту не вистачило місця в /tmp, і не зібрався новий initramfs-linux.img:

[root@archiso ~]# ls -l /mnt/boot/
total 24
drwxr-xr-x 2 root root  4096 Dec  7  2020 EFI
drwxr-xr-x 6 root root  4096 Dec  7  2020 grub
drwx------ 2 root root 16384 Dec  7  2020 lost+found

Ну і власне тепер можна збирати систему.

Запуск mkinitcpio

Тут вже все просто – встановлюємо пакети в /mnt:

[root@archiso ~]# pacstrap /mnt base linux linux-firmware

Виконуємо chroot, і запускаємо mkinitcpio:

[root@archiso ~]# arch-chroot /mnt/
11:27:22 [root@archiso /]  # mkinitcpio -p linux
==> Building image from preset: /etc/mkinitcpio.d/linux.preset: 'default'
==> Using configuration file: '/etc/mkinitcpio.conf'
  -> -k /boot/vmlinuz-linux -c /etc/mkinitcpio.conf -g /boot/initramfs-linux.img
...

Перевіряємо /boot ще раз – тепер все на місці:

11:28:48 [root@archiso /]  # ls -l /boot/
total 68000
drwxr-xr-x 2 root root     4096 Dec  7  2020 EFI
drwxr-xr-x 6 root root     4096 Dec  7  2020 grub
-rw------- 1 root root 41323222 Mar  3 11:28 initramfs-linux-fallback.img
-rw------- 1 root root 14137751 Mar  3 11:28 initramfs-linux.img
drwx------ 2 root root    16384 Dec  7  2020 lost+found
-rw-r--r-- 1 root root 14053888 Mar  3 11:26 vmlinuz-linux

Готово – перезавантажуємось в основну систему.

Loading

PostgreSQL: використання EXPLAIN та налаштування “auto_explain” в AWS RDS
0 (0)

12 Лютого 2025

Вже згадував про можливості EXPLAIN в пості PostgreSQL: AWS RDS Performance and monitoring, але це настільки цікава і корисна штука, що варто про неї поговорити окремо.

До того ж, в AWS RDS для PostgreSQL є можливість включити логування Execution Plans з EXPLAIN, що теж корисно для моніторингу і дебагу, тому подивимось як це включити і які параметри для цього є.

PostgreSQL EXPLAIN

Отже, що таке EXPLAIN? див. також Using EXPLAIN.

Explain відобразить нам Execution Plan. А аби краще розуміти що таке Execution Plan – глянемо на те, як взагалі виглядає процес виконання запитів.

Що таке Execution Plan в PostgreSQL

Коли ми відправляємо запит до PostgreSQL, то:

  • запит проходить через лексичний (Lexing) та синтаксичний (Parsing) аналіз
    • Lexing: розділення на токени (оператори) – SELECT, FROM, WHERE тощо
    • Parsing: перевірка синтаксису та створення дерева синтаксичного аналізу (Parse Tree)
  • далі відбувається аналіз (Analysis/Binding)
    • перевірка існування таблиць, колонок та функцій, прав доступу
    • створюється схематична інформація (schema information) – мета-дані про структуру таблиць, індекси, привілегії тощо
  • створюється логічний план (Logical Plan Generation)
    • на основі дерева синтаксичного аналізу (Parse Tree) формується логічний план запиту, в якому визначаються операції, які треба виконати – JOIN, AGREGATE etc
  • виконується оптимізація запиту (Query Optimization)
    • визначаються найкращі алгоритми JOIN (Nested Loop, Hash Join, Merge Join)
    • вирішується, чи використовувати індекси (Index Scan, Bitmap Index Scan) або повний перегляд таблиці (Seq Scan)
  • генерується фізичний план (Execution Plan Generation)
    • логічний план перетворюється у конкретний набір операцій для виконання (Seq Scan, Index Scan, Hash Join тощо)
    • визначається, як буде використовуватися оперативна пам’ять, кеш і тимчасові файли на диску (саме тому фізичний план – бо вже враховуються фізичні ресурси системи)
  • і нарешті відбувається виконання запиту (Execution)
    • отримуємо дані з диску, змінюємо дані в пам’яті тощо
    • якщо це SELECT – дані відправляються клієнту
    • якщо виконується INSERT/UPDATE/DELETE – дані фізично змінюються на диску
  • завершення операції (Commit або Rollback)
    • COMMIT (підтвердження транзакції) – зміни фіксуються в базі даних, і стають доступні іншим клієнтам
    • ROLLBACK (скасування транзакції) – зміни повертаються до стану, який був до BEGIN

Використання EXPLAIN

Отже, з EXPLAIN ми можемо отримати Execution Plan – тобто, побачити те, які операції будуть виконуватись, і скільки даних і ресурсів вони торкнуться.

Найпростіший приклад може виглядати так:

EXPLAIN SELECT * FROM table_name;

Execution Plan являє собою дерево фізичних операцій, де Nodes – це окрема операція, така як Seq Scan, Index Scan, Sort, Join, Aggregate тощо, а стрілочки – зв’язки між вузлами і передача даних між операціями.

Візуалізація EXPLAIN

Є можливість візуалізувати результати Explain, наприклад онлайн з https://www.pgexplain.dev:

Або https://explain.depesz.com:

Опції EXPLAIN

Загальний синтаксис:

EXPLAIN (options) statement

Основні Options такі:

  • ANALYZE: коли ми просто викликаємо EXPLAIN, то реальні дії не виконуються; додавання ANALYZE запускає виконання запиту, і потім відображає статистику
    • default: FALSE
  • VERBOSE: включає в результат додаткову інформацію (імена колонок, функцій тощо)
    • default: FALSE
  • COSTS: відображення “вартості” виконання операції – умовна одиниця вимірювання витрат на виконання запиту з врахування затрат CPU та IO
    • default: TRUE
  • BUFFERS: відображення використання буферів пам’яті (тільки якщо ANALYZE=TRUE) – скільки даних знайдено в кеші, скільки буде зчитано з диску, записано на диск тощо
    • default: FALSE
  • FORMAT: в якому форматі вивести результат – TEXT, XML, JSON, YAML
    • default: TEXT

Результати EXPLAIN

Давайте глянемо, що у нас було в результаті виконання такого запиту:

EXPLAIN (ANALYZE, VERBOSE, BUFFERS, FORMAT YAML)  SELECT * FROM foster_home;

Що цікавого ми тут маємо:

  • основний план і загальна інформація:
    • Node Type: "Seq Scan": операція послідовного сканування (Sequential Scan), без використання індексів
    • Parallel Aware: false: запит буде виконано без паралелізації
    • Async Capable: false: запит не може бути виконано асинхронно
    • Relation Name: "foster_home": ім’я таблиці, над якою виконуються дії
    • Schema: "public": ім’я схеми, в якій знаходиться таблиця
  • оцінка вартості (COSTS):
    • Startup Cost: 0.00: операція починається миттєво, оскільки це послідовне читання
    • Total Cost: 16242.01: оцінка вартості всієї операції (не час, а умовні одиниці)
    • Plan Rows: 35801: планується повернути в результаті запита 35801 рядків
    • Plan Width: 1330: середній очікуваний розмір рядка в байтах
  • фактичне виконання запиту (ANALYZE):
    • Actual Startup Time: 0.018: час на початок виконання запиту
    • Actual Total Time: 638.911: скільки всього часу зайняло виконання
    • Actual Rows: 35801: скільки рядків було повернуто в результаті виконання
  • вихідні дані (Output):
    • список колонок, які були повернуті в результаті запиту (всі, бо виконуємо SELECT *)
  • буфери пам’яті (BUFFERS):
    • Shared Hit Blocks: 455: в shared_buffers було знайдено 455 блоків з існуючими даними
    • Shared Read Blocks: 15429: 15429 блоків довелось читати з диску
    • Shared Dirtied Blocks: 0 та Shared Written Blocks: 0: в результаті виконання запиту ніякі дані не змінювались
    • Temp Read Blocks: 0 та Temp Written Blocks: 0 – тимчасові файли не використовувались (temp_blks_read в pg_stat_statements)
  • операції введення/виведення (I/O)
    • I/O Read Time: 599.188: скільки часу витратили на читання з диску
    • I/O Write Time: 0.000: нічого не писали
    • Temp I/O Read Time: 0.000 та Temp I/O Write Time: 0.000: знов-таки, тимчасові файли не використовувались

EXPLAIN та використання пам’яті

Що найбільш цікаве для мене, бо до цього всього ми прийшли саме тому, що розбирались з питанням “що з’їло всю пам’ять на сервері” – це скільки пам’яті буде використано при виконання різних запитів.

Використання shared_buffers

Отже, в результатах EXPLAIN ми бачили, що оцінка була:

  • Plan Rows: 35801: планується повернути в результаті запита 35801 строк
  • Plan Width: 1330: і кожен рядок займе 1330 байт у пам’яті

Тобто, в результаті виконання запиту SELECT * FROM foster_home очікується отримати 35801 рядків, в середньому кожен розміром в 1330 байт.

Відповідно, в shared_buffers на час виконання запиту планується мати:

35801*1330/1024/1024
45

45 мегабайт.

Але реальний розмір після виконання вказано в Shared Hit Blocks + Shared Read Blocks: 455 блоків даних по 8 КБ вже було в пам’яті, і 15429 блоків було зчитано з диску.

Враховуючи, що кожен блок це 8КБ, то маємо:

(455+15429)*8/1024
124

Порівняємо з розміром самої таблиці:

dev_kraken_db=> SELECT pg_size_pretty(pg_relation_size('foster_home'));
 pg_size_pretty 
----------------
 124 MB

Отже, в результаті виконання SELECT * FROM foster_home ми в shared_buffers будемо мати 124 мегабайти (3640 байти там вже були, і 123432 буде додатково зчитано з диску).

При тому, що під shared_buffers на Dev-сервері всього виділено:

dev_kraken_db=> SHOW shared_buffers;
 shared_buffers 
----------------
 190496kB

~186 мегабайт.

Різниця в Plan Width і Shared Read Blocks

Чому в плані ми бачили ~45 мегабайт, а після виконання – 124 MB?

Бо Plan Width відображає дані по середньому розміру рядка, а Shared Read Blocks – скільки фізичних блоків даних було прочитано з диску.

Для значень в Plan Width PostgreSQL використовує дані з view pg_stats.avg_width.

Колонки в нашій таблиці:

dev_kraken_db=> \d foster_home
                  Table "public.foster_home"
       Column        | Type  | Collation | Nullable | Default 
---------------------+-------+-----------+----------+---------
 challenge_id        | text  |           |          | 
 type                | text  |           |          | 
 parent_challenge_id | text  |           |          | 
 source_challenge_id | text  |           |          | 
 base_challenge_id   | text  |           |          | 
 bio_parent_id       | text  |           |          | 
 matched_by          | text  |           |          | 
 title               | text  |           |          | 
 challenge           | jsonb |           |          | 
 user_id             | text  |           |          | 
Indexes:
    "foster_home_challenge_id" btree (challenge_id)

І їх розмір в pg_stats:

dev_kraken_db=> SELECT attname, avg_width 
FROM pg_stats 
WHERE tablename = 'foster_home';
       attname       | avg_width 
---------------------+-----------
 type                |         7
 bio_parent_id       |        37
 matched_by          |        18
 challenge_id        |        37
 parent_challenge_id |        37
 title               |        27
 user_id             |        37
 source_challenge_id |        37
 base_challenge_id   |        37
 challenge           |      1056

Що дає нам ті самі 1330 байт:

1056+37+37+37+27+37+37+18+37+7
1330

Отже, планується отримати 35801 строк, і кожна приблизно ~1330 байт.

Але реальний їх розмір ми можемо дізнатись з pg_column_size():

dev_kraken_db=> SELECT pg_size_pretty(avg(pg_column_size(t))) 
FROM foster_home t;
       pg_size_pretty        
-----------------------------
 1424.0065081980950253 bytes

Або:

1424*35801/1024/1024
48

48 мегабайт.

Але ж все одно не 124 мегабайти, які були прочитані з диска? Чому так?

Бо:

  • дані з диску читаються блоками по 8 КБ, а не окремими рядками:
    • тобто, навіть якщо треба отримати кілька рядків в пару кілобайт, то для їх отримання доведеться зчитати 8 КБ блоку, в якому вони знаходяться
  • таблиця може бути фрагментованою:
    • тобто рядки можуть знаходиться в різних блоках даних на диску, і читати доведеться кожен блок
  • виконується Seq Scan (повне сканування таблиці), а не використовується індекс:
    • через це з диску читається вся таблиця
  • частина даних може зберігатись поза основною таблицею в TOAST-таблиці:
    • але в SELECT pg_size_pretty(pg_relation_size('foster_home')); ми вже маємо розмір без TOAST та індексів – 124 мегабайти
    • отримати весь розмір можна з SELECT pg_size_pretty(pg_total_relation_size('foster_home'));

Відносно індексу – як виглядає різниця в читані даних, коли індекс є, і коли нема.

Наприклад, подивимось EXPLAIN SELECT по полю user_id, для якого нема індексу:

dev_kraken_db=> EXPLAIN (ANALYZE, VERBOSE, BUFFERS, FORMAT YAML)  SELECT user_id FROM foster_home;
...
     Node Type: "Seq Scan"               +
     ...
     Total Cost: 16242.01                +
     Plan Rows: 35801                    +
     Plan Width: 37                      +
     ...
     Actual Rows: 35801                  +
     ...
     Output:                             +
       - "user_id"                       +
     Shared Hit Blocks: 715              +
     Shared Read Blocks: 15169           +
...

Знов маємо Node Type: "Seq Scan", тобто вичитування всієї таблиці з диску і, відповідно, багато Shared Read Blocks.

Тоді як для challenge_id, для кого індекс є, це було б:

dev_kraken_db=> EXPLAIN (ANALYZE, VERBOSE, BUFFERS, FORMAT YAML) SELECT challenge_id FROM foster_home;
                 QUERY PLAN                 
--------------------------------------------
 - Plan:                                   +
     Node Type: "Index Only Scan"          +
     ...
     Total Cost: 1629.43                   +
     Plan Rows: 35801                      +
     Plan Width: 37                        +
     ...
     Actual Rows: 35801                    +
     ...
     Output:                               +
       - "challenge_id"                    +
     Heap Fetches: 0                       +
     Shared Hit Blocks: 271                +
     Shared Read Blocks: 0                 +
...

Тут всі дані з нашого індексу вже є в shared_buffers, тому з диску взагалі нічого не читалось.

Перевірити shared_bufers для індексу foster_home_challenge_id можемо так:

dev_kraken_db=> SELECT count(*) AS cached_pages,
       pg_size_pretty(count(*) * 8192) AS cached_size
FROM pg_buffercache
WHERE relfilenode = (SELECT relfilenode FROM pg_class WHERE relname = 'foster_home_challenge_id');
 cached_pages | cached_size 
--------------+-------------
          271 | 2168 kB

Окей – тут наче розібрались?

Але окрім shared_buffers під час виконання запиту може ще використовуватись і work_mem.

Використання work_mem

work_mem використовується, якщо в запиті є ORDER BY, HASH JOIN.

Див. Resource Consumption.

При цьому якщо в одному запиті є кілька таких операцій – то під кожну буде виділено свою область work_mem:

Query Plan:
   Sort (work_mem = 4MB)
     -> Nested Loop
         -> Sort (work_mem = 4MB)
         -> Hash Join (work_mem = 4MB)

Крім того, окремий work_mem виділяється кожному Worker, тобто додатковому процесу при виконанні запиту – див. How Parallel Query Works:

...
   ->  Sort  (cost=25736.77..25774.06 rows=14917 width=1330) (actual time=1286.099..1352.484 rows=11934 loops=3)
         ...
         Worker 0:  actual time=1279.232..1338.547 rows=10752 loops=1
           ...
         Worker 1:  actual time=1281.125..1358.600 rows=12929 loops=1
           ...
...

Перевірити, скільки work_mem споживає запит, і чи достатньо дефолтних 4 мегабайт можемо так:

dev_kraken_db=> EXPLAIN (ANALYZE, VERBOSE, BUFFERS, FORMAT YAML)
dev_kraken_db-> SELECT * FROM foster_home ORDER BY title;
                 QUERY PLAN                 
--------------------------------------------
 - Plan:                                   +
     Node Type: "Gather Merge"             +
     ...
     Temp Read Blocks: 5497                +
     Temp Written Blocks: 5507             +
     ...
     Temp I/O Read Time: 192.337           +
     Temp I/O Write Time: 117.445          +
     ...
     Plans:                                +
       - Node Type: "Sort" 
         ...
         Sort Key:                         +
           - "foster_home.title"           +
         Sort Method: "external merge"     +
         Sort Space Used: 17048            +
         Sort Space Type: "Disk"           +
...

Тут ми бачимо, що:

  • Temp Read та Written Blocks: використовувались тимчасові блоки
  • Temp I/O Read та Write Time: був витрачений час на роботу з диском
  • Sort Method: "external merge" та Sort Space Type: "Disk": для сортування використовувався диск, а не "Memory", бо в work_mem весь результат не вмістився
  • Sort Space Used: 17048: для сортування знадобилось 17048 кілобайт (16 мегабайт)

Перевірити поточне значення для work_mem можемо так:

dev_kraken_db=> SHOW work_mem;
 work_mem 
----------
 4MB

Саме тому для сортування знадобилось створювати temp files.

Якщо ж ми збільшимо work_mem (через SET для поточної сесії, або через Parameters Group для RDS аби зміни були постійними):

dev_kraken_db=> SET work_mem = '20MB';
SET

То тепер будемо бачити іншу картину:

...
     Temp Written Blocks: 0                 +
     ...
     Temp I/O Write Time: 0.000             +
...
         Sort Key:                          +
           - "foster_home.title"            +
         Sort Method: "quicksort"           +
         Sort Space Used: 17454             +
         Sort Space Type: "Memory"          +

...

Отже, як резюме: з EXPLAIN ANALYZE ми можемо отримати інформацію про те, скільки даних при виконанні запиту буде зчитано з диску в shared_buffers, і скільки даних буде використано в work_mem або temp files

Як нам це може допомогти моніторити “важкі” запити в AWS RDS?

AWS RDS PostgreSQL та auto_explain

В RDS ми можемо включити auto_explain, який буде записувати в лог результат EXPLAIN для подальшого аналізу.

Документація – auto_explain — log execution plans of slow queries. Код самого модуля – auto_explain.c.

Аби включити auto_explain в RDS, його треба додати в shared_preload_libraries:

Після чого ребутаємо інстанс RDS.

Далі налаштовуємо такі параметри:

  • auto_explain.log_min_duration: скільки часу має виконуватись запит, аби бути записаним в лог з EXPLAIN (в мілісекундах)
  • auto_explain.log_analyze: виконувати ANALIZE, а не просто EXPLAIN (може впливати на навантаження RDS)
  • auto_explain.log_buffers: додавати інформацію по BUFFERS
  • auto_explain.log_verbose: VERBOSE для EXPLAIN
  • auto_explain.log_format: в якому форматі пишемо лог

Зберігаємо параметри, і перевіряємо лог:

Готово.

Корисні посилання

Loading

PostgreSQL: AWS RDS Performance and monitoring
0 (0)

7 Лютого 2025

Мігруємо наш Backend API з DynamoDB на AWS RDS PostgreSQL, і кілька раз RDS падав.

Власне, враховуючи те, що ми задля економії взяли db.t3.small з двома vCPU і двома гігабайтами пам’яті – то доволі очікувано, але стало цікаво чому ж саме все падало.

Через кілька днів почав цю тему дебажити, і хоча причини поки не знайшли – але з’явилась непогана чернетка того, як можна поінвестигейтити проблеми з перформансом в RDS PostgreSQL.

Пост – не звичайний “як зробити”, а скоріше просто записати для себе – куди і на що наступного разу дивитись, і які зміни в моніторингу можна зробити, аби наступного разу побачити проблему раніше, ніж вона стане критичною.

The Issue

Отже, як все починалось.

Backend API запущений в AWS Elastic Kubernetes Service, і в якийсь момент посипались алерти по 503 помилкам:

З’явились алерти на використання Swap на Production RDS:

В Sentry з’явились помилки про проблеми з підключенням до серверу баз даних:

Починаємо перевіряти моніторинг RDS, і бачимо, що в якийсь момент Freeable Memory впала до 50 мегабайт:

Коли сервер впав, ми його перезапустили – але проблема тут же виникла знов.

Тому вирішили поки що переїхати на db.m5.large – на графіку видно, як вільна пам’ять стала 7.25 GB.

Ну і давайте глянемо, що цікавого ми можемо побачити з всієї цієї історії.

Set “Application Name”

В Performance Insights можна відобразити статистику по окремим Applications:

У нас цього зроблено не було, але, думаю, є сенс налаштувати окремі Applications для підключень експортерів моніторингу та з сервісів Backend API.

Є кілька варіантів, як це зробити – або передавати параметрами в connection strings:

"postgresql://user:password@host:port/database?application_name=MyApp"

Або виконувати прямо з коду при ініціалізації підключень:

with engine.connect() as conn: 
  conn.execute("SET application_name TO 'MyApp'")

Другий варіант виглядає привабливішим, бо connection string до Backend API передається змінною оточення з AWS Secret Store, і робити окремий URL тільки заради одного параметру application_name для кожного сервісу API виглядає трохи костильно.

Тому краще в кожній апці бекенду задавати власний параметр при створенні підключення.

Корисні PostgreSQL Extentions

По ходу діла додавав кілька PostgreSQL Extentions, які прям дуже корисні в таких справах для моніторингу і інвестігейту.

Включення pg_stat_statements

Теж на жаль не було включено на момент проблеми, але в цілому прямо must have штука.

Документація – pg_stat_statements — track statistics of SQL planning and execution та SQL statistics for RDS PostgreSQL.

В RDS PostgreSQL версій 11 і вище бібліотека включена по дефолту, тому все, що треба зробити – це створити EXTENSION, див. CREATE EXTENSION.

Перевіряємо, чи є extention зараз:

dev_kraken_db=> SELECT * 
FROM pg_available_extensions 
WHERE 
    name = 'pg_stat_statements' and 
    installed_version is not null;
 name | default_version | installed_version | comment 
------+-----------------+-------------------+---------
(0 rows)

(0 rows) – ок, пусто.

Створюємо його:

dev_kraken_db=> CREATE EXTENSION pg_stat_statements;
CREATE EXTENSION

Перевіряємо ще раз:

dev_kraken_db=> SELECT *                            
FROM pg_available_extensions 
WHERE 
    name = 'pg_stat_statements' and 
    installed_version is not null;
        name        | default_version | installed_version |                                comment                                 
--------------------+-----------------+-------------------+------------------------------------------------------------------------
 pg_stat_statements | 1.10            | 1.10              | track planning and execution statistics of all SQL statements executed
(1 row)

І спробуємо отримати якусь інформацію з pg_stat_statements і таким запитом:

SELECT query 
FROM pg_stat_statements
ORDER BY total_exec_time DESC
LIMIT 10;

 

Далі в цьому пості будуть ще приклади того, яку інформацію з pg_stat_statements можемо отримати.

Включення pg_stat_activity

Окрім pg_stat_statements, корисну інформацію по поточній активності можна отримати з pg_stat_activity, включена по дефолту.

Обидві являють собою views, хоча в різних схемах бази:

dev_kraken_db=> \dv *.pg_stat_(statements|activity)
                 List of relations
   Schema   |        Name        | Type |  Owner   
------------+--------------------+------+----------
 pg_catalog | pg_stat_activity   | view | rdsadmin
 public     | pg_stat_statements | view | rdsadmi

Різниця між pg_stat_activity та pg_stat_statements у PostgreSQL

Обидві допомагають аналізувати запити, але pg_stat_activity – це поточна активність, а pg_stat_statements – “історична”:

Параметр pg_stat_activity pg_stat_statements
Що показує? Поточні активні сесії та їхній стан. Історія виконаних SQL-запитів зі статистикою.
Дані в режимі реального часу? Так, тільки активні процеси. Ні, це накопичена статистика по всіх запитах.
Які запити видно? Тільки ті, що виконуються прямо зараз. Запити, які виконувались раніше (навіть якщо вже завершилися).
Чи зберігає історію? Ні, дані зникають після завершення запиту. Так, PostgreSQL збирає та агрегує статистику.
Що можна дізнатися? Який запит зараз працює, скільки він триває, на що він чекає (CPU, I/O, Locks). Середній, мінімальний, максимальний час виконання запитів, кількість викликів.
Основне використання Аналіз продуктивності в режимі реального часу, пошук проблемних запитів зараз. Пошук “важких” запитів, які створюють навантаження в довгостроковій перспективі.

Включення pg_buffercache

Ще один корисний extension – це pg_buffercache, який може відобразити інформацію по стану пам’яті в PosgtreSQL.

Включається аналогічно до pg_stat_statements:

CREATE EXTENSION IF NOT EXISTS pg_buffercache;

Далі теж подивимось на цікаві запити для перевірки стану пам’яті в PostgreSQL.

Окей. Повертаємось на нашої проблеми.

CPU utilization та DBLoad

Перше, на що звернули увагу – це навантаження на CPU.

В Performance Isights це виглядало так:

А в Monitoring самого інстансу – так:

DBLoad (Database Load)

Документація по DBLoad в CloudWatch – тут>>>.

У PostgreSQL кожна клієнтська сесія створює окремий процес (backend process).

DBLoad – це метрика AWS RDS PostgreSQL, яка відображає значення активних сесій, які виконуються або очікують на ресурси – CPU, disk I/O, Locks. Не враховуються сесії в статусі idle, але враховуються сесії в статусі active, idle in transaction або waiting.

DBLoad схожий на Load Average у Linux, але враховує тільки PostgreSQL-сесії:

  • У Linux Load Average показує кількість процесів на Linux-сервері, які або використовують CPU, або чекають на нього чи на I/O
  • У RDS DBLoad відображає середню кількість активних сесій на сервері PostgreSQL, які або працюють, або чекають ресурси

Тобто в ідеалі кожен backend-процес, який виконує запити від підключеного клієнта, має мати доступ до “власного” ядра vCPU, отже DBLoad має бути ~= кількості vCPU або менше.

Якщо ж DBLoad значно перевищує кількість доступних ядер – то це показник, що система перевантажена і процеси (сесії) очікують в черзі на CPU або інші ресурси.

DBLoad включає в себе ще два показники:

  • DBLoadCPU: сесії, які знаходяться саме в очікуванні вільного CPU
  • DBLoadNonCPU: сесії, які знаходяться в очікуванні диску, database table locks, networking, etc

Перевірити сесії, які будуть вважатись активними і будуть включені в DBLoad можемо так:

SELECT pid, usename, state, wait_event, backend_type, query
FROM pg_stat_activity
WHERE state != 'idle'

Нормальне значення для DBLoad

DBLoad має бути приблизно рівним або нижче кількості доступних vCPU.

DBLoad vs CPU Utilization

Чому на першому скріні ми бачимо “100%”, а на другому просто кількість в 17.5?

  • CPU Utilization: відсоток використання CPU від загальної доступної потужності
  • DBLoad: кількість активних сесій

Враховуючи, що на сервері в той момент було 2 доступних vCPU, і при цьому 17 активних сесій – то маємо 100% використання процесорного часу.

Окремо варто завернути увагу на DBLoadRelativeToNumVCPUs – це DBLoad поділений на кількість доступних vCPU, тобто середнє навантаження на кожне ядро CPU.

DBLoadCPU (Database Load on CPU Wait)

DBLoadCPU відображає кількість активних сесій, які очікують на CPU, тобто процеси, які не можуть виконуватись, бо всі доступні CPU зайняті.

В ідеалі має бути близько нуля – тобто, на сервері не має бути процесів, які очікують CPU.

Якщо DBLoadCPU має значення близько DBLoad, то RDS не встигає обробити всі запити – не вистачає CPU time, і вони стають в чергу.

Перевірити можемо тим самим запитом з pg_stat_activity, як вище: якщо в wait_event = "CPU", то це процеси, які чекають вільного CPU.

Нормальне значення для DBLoadCPU

DBLoadCPU має бути якнайнижчим (близьким до нуля).

Якщо DBLoadCPU майже дорівнює DBLoad, то:

  • основне навантаження саме на процесор
  • сесії не блокуються через Table Locks або повільний диск (I/O), а просто чекають CPU

DBLoadNonCPU (Database Load on Non-CPU)

DBLoadNonCPU, власне, відображає інформацію очікування ресурсів, не пов’язаних з CPU.

Це можуть бути:

  • блокування (Locks): очікування доступу до таблиці або рядка
  • I/O очікування (I/O Wait): повільне читання або запис через дискові обмеження
  • Network Wait: затримки через мережеві операції (наприклад, реплікація або передача даних)
  • Other Wait Events: інші очікування, такі як процеси фонового обслуговування

Перевірити такі сесії можемо аналогічно до попередніх запитів з pg_stat_activity, але додамо виборку wait_event_type та wait_event:

SELECT pid, usename, state, wait_event_type, wait_event, query
FROM pg_stat_activity
WHERE state != 'idle'
ORDER BY query_start;

Тут wait_event_type вказує на тип ресурсу, на який очікує процес (CPU, IO, Lock, WAL, Client), а wait_event деталізує яку конкретно операцію процес очікує.

Наприклад, wait_event_type може бути “IO“, тоді в wait_event_type можуть бути значення “DataFileRead” (очікування читання з диска) або “DataFileWrite” – очікування запису на диск.

Або, якщо wait_event_type == Client, тоді wait_event_type може бути “ClientRead“, “ClientWrite“, “ClientSocket“.

Див. RDS for PostgreSQL wait events.

Повернемось до наших графіків:

  • CPU Utilization 100%: система перенавантажена
  • DBLoad 17.5: при двох vCPU – маємо багато активних сесій, процесор не встигає обробити всі запити
  • DBLoadCPU 13.9: багато сесій очікують на доступний CPU
  • DBLoadNonCPU 3.59: частина запитів очікували диск, блокування, або якісь мережеві запити

Operating System CPU utilization

Окрім метрик DBLoad, які відносяться саме до RDS та PostgreSQL, у нас ще є інформація по самій операційній системі, де маємо інформацію і по диску, і по пам’яті, і по CPU.

Власне в CPU utilization ми маємо графік у відсотках з використання CPU, який складається з кількох метрик, кожна з яких відображає окремий режим:

  • os.cpuUtilization.steal.avg (Steal Time): очікування фізичного CPU, якщо AWS виділила його іншому інстансу на цьому фізичному сервері, або якщо CPU Credits використано, і AWS обмежує ваш інстанс
  • os.cpuUtilization.guest.avg (Guest Time): CPU, який “з’їла” гостьова операційна система – якщо на сервері є Virtual Machine або Docker, але не про RDS
  • os.cpuUtilization.irq.avg (Interrupt Requests, IRQ Time): очікування Interrupt Requests, IRQ Time – обробка апаратних переривань (мережеві запити або диск), може бути пов’язана з високим IOPS на EBS
  • os.cpuUtilization.wait.avg (I/O Wait Time): час I/O Wait Time, дискові операції, наприклад – зчитування файлів
  • os.cpuUtilization.user.avg (User Time): час на юзер-процеси, в даному випадку це можуть бути обробка запитів PostgreSQL
  • os.cpuUtilization.system.avg (System Time): робота ядра операційної системи (обробка процесів з user space, дискові операції, операції з пам’яттю)
  • os.cpuUtilization.nice.avg (Nice Time): час на процеси з пріоритетом nice – низькопріоритетні фонові завдання

Схожі дані ми маємо в Linux top:

Tasks: 611 total, 7 running, 603 sleep, 1 d-sleep, 0 stopped, 0 zombie
%Cpu(s):  5.9 us,  3.6 sy,  0.0 ni, 89.8 id,  0.2 wa,  0.0 hi,  0.5 si,  0.0 st 
...

Тут ususer, sysystem, ninice, ididle і так далі.

З нашого графіку в RDS Performance Insights ми маємо найбільшу частину саме по wait – і в той час є спайки по EBS IO operations:

Тобто, “прилетів” якийсь запит, який почав активно вичитувати з диска:

І поки CPU чекав на завершення операцій з диском – решта запитів виконувались повільніше.

В той самий час маємо “провал” по Freeable memory – бо дані з диска записувались в пам’ять.

І хоча саме значення в 460 IOPS не виглядає якимось зависоким, але схоже, що саме в цей момент ми “з’їли” доступну пам’ять.

На що нам в даному випадку може вказувати високий os.cpuUtilization.wait.avg?

  • повільний EBS: все ж не наш кейс, бо маємо швидкість до 3000 IOPS; хоча очікування читання з диску в пам’ять могло спричинити ріст I/O Waits на CPU
  • блокування/Locks: як варіант, але у нас є метрика db.Transactions.blocked_transactions.avg – і там все було добре, тобто PostgreSQL не чекав на звільнення locks – на транзакції теж зараз глянемо
  • мало оперативної пам’яті: читання нових даних з диску в пам’ять витіснило існуючі там дані в Swap, і потім вичитувало їх звідти назад, при цьому скидуючи дані з пам’яті обратно в Swap, аби завантажити зі swap нові  (swap storm)

Використання Swap в цей час теж виросло:

До Swap і ReadIOPS зараз перейдемо, але спочатку давайте глянемо на транзакції.

Transactions

Ще з цікавого – активність транзакцій:


Бачимо, що як тільки почались проблеми з CPU – у нас xact_commit та xact_rollback (графік зліва) впали до нуля, і в той же час кількість active_transactions виросла до ~20, але при цьому blocked_transactions було 0.

Вже не можу зробити скрін, але ще був спайк по “idle in transaction” – тобто, транзакції починались (BEGIN), але не завершувались (не виконали COMMIT або ROLLBACK).

Але як так може бути? Навіть при високому CPU Waits хоча б частина транзакцій мали б завершитись.

  • зависокий Read IOPS: система не могла отримати дані з диску?
    • ні – ReadIOPS виріс, але не прям настільки критично
    • однак через те, що FreeableMemory був занизьким, дані з shared_buffers могли бути скинуті до swap, що викликало ще більші затримки у процесів, які ці дані очікували
  • зависокий Write IOPS: система не могла виконати запис WAL (Write Ahead Logs, будемо розбирати далі), якого потребує завершення транзакцій
    • але ми бачили, що Write IOPS був в нормі
  • багато table locks, і процеси очікували вивільнення ресурсів?
    • теж ні, бо ми бачили, що blocked_transactions було на нулі
  • робота autovacuum або ANALYZE, які могли заблокувати транзакції?
    • але знов-таки – db.Transactions.blocked_transactions.avg був на нулі
  • Swap storm: оце вже більше схоже на правду:
    • читання з диску витіснило активні дані на Swap (впав показник FreeableMemory)
    • Swap Usage виріс майже до 3-х гігабайт
    • PostgreSQL не міг отримати сторінки з shared_buffers, бо вони були в SWAP (про пам’ять теж далі буде)
    • через це транзакції “зависли” в очікуванні читання з диска, замість того щоб працювати у RAM

Що ми можемо перевірити в таких випадках?

I/O Waits або Blocks

SELECT pid, usename, query, wait_event_type, wait_event, state 
FROM pg_stat_activity 
WHERE state = 'active';

Якщо в wait_event маємо “I/O” або “Locks” – то причина може бути тут.

WAL – Write Ahead Logs

  • при кожній операції DML (Data Manipulation Language), наприклад при INSERT, UPDATE або DELETE, дані спочатку змінюються в пам’яті (shared_buffers – будемо далі про них говорити), де створюється “контекст операції”
  • одночасно ця операція заноситься у WAL-буфер (wal_buffers – буфер пам’яті)
  • коли wal_buffers заповнюється, або коли транзакція завершена, PostgreSQL-процес wal_writer за допомогою системного виклику fsync() записує дані з буфера у wal-файл (директорія pg_wal/) – це журнал всіх змін, що відбулися перед COMMIT
  • клієнт, який запустив виконання запиту отримує повідомлення COMMIT – операція успішно завершена
    • якщо параметр synchronous_commit = on, PostgreSQL чекає завершення fsync() перед відправкою COMMIT
    • якщо synchronous_commit = off, PostgreSQL не чекає fsync() і COMMIT відбувається швидше, але з ризиком втрати даних
    • при неможливості виконати транзакцію – клієнт отримає помилку “could not commit transaction
  • дані з shared_buffers записуються до файлів самої бази даних (каталог base/) – цим займається процес checkpointer, який записує модифіковані в пам’яті дані (dirty pages) на диск
    • це відбувається  за допомогою процесу CHECKPOINT не одразу після COMMIT, а періодично
    • після виконання CHECKPOINT – PostgreSQL виконує архівацію або видалення WAL-файлів

Дуже класний матеріал на тему WAL, memory та checkpoint – PostgreSQL: What is a checkpoint?

Отже, якщо EBS був перенавантажений з Write IOPS – то WAL міг перестати писатись, і це могло призвести до зупинки виконання транзакцій.

Але в нашому випадку ми бачимо, що і db.Transactions.xact_rollback.avg був на нулі, а він не залежить від WAL і Write-операцій на диску.

В PostgreSQL Exporter є кілька корисних метрик, які відображаються активність WAL:

  • pg_stat_archiver_archived_count: загальна кількість успішно заархівованих WAL-файлів (що скаже нам, що WAL працює коректно)
  • pg_stat_archiver_failed_count: кількість невдалих спроб архівування WAL-файлів
  • pg_stat_bgwriter_checkpoint_time: час, витрачений на виконання CHECKPOINTs

Ще можна зробити такий запит:

SELECT * FROM pg_stat_wal;

Якщо wal_buffers_full високий і росте, то, можливо, транзакції чекають на виконання fsync(), або що значення wal_buffers замале, і його треба збільшити аби зменшити частоту примусових записів WAL на диск.

В PostgreSQL такої метрики наче нема, але можемо зробити власну з custom.yaml:

pg_stat_wal:
  query: "SELECT wal_buffers_full FROM pg_stat_wal;"
  metrics:
    - wal_buffers_full:
        usage: "COUNTER"
        description: "Number of times the WAL buffers were completely full, causing WAL data to be written to disk."

Read IOPS та Swap

Добре.

Давайте повернемось до питання з Read IOPS та Swap.

Що тут могло відбутись:

  • якийсь запит почав активно зчитувати дані з диску
  • вони заносились в shared_buffers, в пам’яті не вистачило місця, і дані, які там були до цього були винесені в Swap
  • запити в PostgreSQL продовжують виконуватись, але тепер замість того, аби просто взяти дані з пам’яті – PostgreSQL має йти до Swap, і тому маємо високий ReadIOPS та CPU I/O Waits – тобто CPU чекає, поки дані будуть зчитані з диску

Але тоді наче мало б бути спайк по db.IO.blks_read.avg, раз читаємо з диска?

Але ні, бо db.IO.blks_read – це запити від самого PostgreSQL на читання данних.

Коли ж він оперує зі свапом – він все одно вважає, що працює з оперативною пам’яттю.

А от метрика ReadIOPS – це вже від самої операційної системи/EBS, і вона як раз показує всі операції читання, а не тільки від процесів PostgreSQL.

Що цікаво, що в момент проблеми у нас db.Cache.blks_hit впав до нуля. Про що це каже? Зазвичай, що backend-процеси (сесії) не знаходили дані в shared_buffers.

Але знаючи, що у нас взагалі всі транзакції зупинились, а db.IO.blks_read теж впав до нуля – то скоріш PostgreSQL просто перестав звертатись до кешу взагалі, бо всі чекали на вільний CPU.

Окей, гугл…

А що зі свапом?

SWAP та Enhanced monitoring

Що у нас є на графіках?

Тут нам буде корисний Enhanced monitoring:

Вибираємо там Swap (Manage graphs), і бачимо цікаву картину:

  • Free Memory падає
  • Free Swap падає
  • але Swaps in та Swaps out без змін

Тобто виглядає так, наче пам’ять закінчується – система скидає дані з RAM у Swap – але при цьому саме операції Swaps in/out “не було”.

Виглядає наче цікаво, і варто було б тут копнути далі – але AWS Console на цих графіках постійно падає:

Див. OS metrics in Enhanced Monitoring.

Втім, хоча ми не можемо отримати метрики з Enhanced monitoring напряму, але – сюрпрайз! вони пишуться до CloudWatch Logs! А вже з логів ми можемо нагенерити собі будь-які метрики з VictoriaLogs або Loki:

І вже в логах бачимо, що Swap In/Out таки відбувався. Тільки простих графіків вже не побачити. Але в майбутньому зробити собі якихось метрик з цих логів було б корисно.

В Log Groups шукаємо RDSOSMetrics, а потім вибираємо лог по RDS ID:

Operating system process list

Ще дуже корисним може бути список процесів:

Якщо починає падати вільна пам’ять – йдемо сюди, дивимось Resident memory, знаходимо PID процесу який жере пам’ять – і дивимось, що саме там за запит:

prod_kraken_db=> SELECT user, pid, query FROM pg_stat_activity WHERE pid = '26421';
       user       |  pid  |  query   
------------------+-------+----------
 prod_kraken_user | 26421 | ROLLBACK

Всі ці процеси ми також маємо в логах, про які згадував вище – але це краще перевіряти в момент, коли виникає проблема, аби знайти який саме виконувався.

Бо так, ми можемо включити slow queries logs – але в тих логах ми не побачимо PID, і не зможемо дізнатись скільки пам’яті цей запит використав.

Пам’ять в PostgreSQL

Давайте трохи копнемо в те, що взагалі в пам’яті PostgreSQL.

Див. RDS for PostgreSQL memory та Tuning memory parameters.

Пам’ять в PostgreSQL ділиться на два основні типи – це “shared memory, та “local memory” – пам’ять кожного бекенд-процесу (сесії).

В shared memory ми маємо:

  • shared_buffers: основна пам’ять, де PostgreSQL тримає кеш даних, які він зчитує з диску при обробці запитів – кешування сторінок таблиць та індексів
    • аналог Heap Memory (Java Heap)
    • shared_buffers за замовчуванням становить 25% від загальної RAM, але можна змінити
  • wal_buffers: вже бачили вище – використовується для тимчасового зберігання WAL-записів для буферизації транзакції перед записом у WAL-файл

Із shared_buffers змінені дані (dirty pages) записуються на диск двома процесами:

  • Background Writer (bgwriter): працює в фоні, поступово записує дані на диск
  • Checkpointer (checkpoint): примусово записує всі сторінки під час CHECKPOINT

Пам’ять процесів має:

  • work_mem: виділяється запитам, які виконують сортувань (ORDER BY), хеш-операцій (HASH JOIN) та агрегацій
    • кожен запит отримує свою копію work_mem, тому при великій кількості одночасних запитів пам’ять може швидко закінчитись
    • якщо work_mem процесу не вистачає – PostgreSQL починає записувати тимчасові файли на диск (temp_blks_written), що уповільнює виконання запитів
  • maintenance_work_mem: власне, maintenance operations – операції по vacuuming, створення індексів, додавання foreign keys
  • temp_buffers: виділяється для тимчасових таблиць (CREATE TEMP TABLE).

Ми можемо отримати всі дані з pg_settings так:

SELECT 
    name, 
    setting, 
    unit,
    CASE 
        WHEN unit = '8kB' THEN setting::bigint * 8 
        WHEN unit = 'kB' THEN setting::bigint 
        ELSE NULL 
    END AS total_kb,
    pg_size_pretty(
        CASE 
            WHEN unit = '8kB' THEN setting::bigint * 8 * 1024
            WHEN unit = 'kB' THEN setting::bigint * 1024
            ELSE NULL 
        END
    ) AS total_pretty
FROM pg_settings
WHERE name IN ('shared_buffers', 'work_mem', 'temp_buffers', 'wal_buffers');

Маємо 238967 shared_buffers, кожен по 8КБ, разом ~1.9 GB.

Але це вже зараз, на db.m5.large.

Перевірка shared_buffers

Cache hit ratio покаже скільки даних було отримано з пам’яті, а скільки з самого диску – хоча у нас це є в метриках db.IO.blks_read.avg та db.Cache.blks_hit.avg (або метрики pg_stat_database_blks_hit та pg_stat_database_blks_read в PostgreSQL Exporter):

SELECT 
    blks_read, blks_hit, 
    ROUND(blks_hit::numeric / NULLIF(blks_hit + blks_read, 0), 4) AS cache_hit_ratio
FROM pg_stat_database
WHERE datname = current_database();

Якщо cache_hit_ratio < 0.9, значить, кеш PostgreSQL не ефективний, і забагато даних читається з диска замість кеша.

Побачити скільки з виділених shared_buffers зараз використані (активні), а скільки вільні – тут нам знадобиться extention pg_buffercache.

Запит:

SELECT
    COUNT(*) AS total_buffers,
    SUM(CASE WHEN isdirty THEN 1 ELSE 0 END) AS dirty_buffers,
    SUM(CASE WHEN relfilenode IS NULL THEN 1 ELSE 0 END) AS free_buffers,
    SUM(CASE WHEN relfilenode IS NOT NULL THEN 1 ELSE 0 END) AS used_buffers,
    ROUND(100.0 * SUM(CASE WHEN relfilenode IS NOT NULL THEN 1 ELSE 0 END) / COUNT(*), 2) AS used_percent,
    ROUND(100.0 * SUM(CASE WHEN relfilenode IS NULL THEN 1 ELSE 0 END) / COUNT(*), 2) AS free_percent
FROM pg_buffercache;

Маємо 238967 буферів загалом, з яких використано лише 12280, або 5%.

Або інший варіант – подивитись, скільки всього сторінок зараз в shared_buffers:

prod_kraken_db=> SELECT 
    count(*) AS cached_pages,
    pg_size_pretty(count(*) * 8192) AS cached_size
FROM pg_buffercache;
 cached_pages | cached_size 
--------------+-------------
       117495 | 918 MB

При тому, що всього під shared_buffers виділено:

prod_kraken_db=> SHOW shared_buffers;
 shared_buffers 
----------------
 939960kB

918 мегабайт.

Але чому тоді в попередньому запиті ми бачили, що “зайнято 5%”?

Бо в результаті з pg_buffercache в полях used_buffers та used_percent враховуються тільки активні сторінки (used), тобто ті, які або мають прив’язку до файлу (relfilenode), або були нещодавно використані.

Використання EXPLAIN ANALYZE

Див. EXPLAIN.

EXPLAIN (ANALYZE, BUFFERS) покаже нам скільки даних в буферах зараз, скільки даних буде прочитано з диску:

Тут:

  • shared hit: скільки сторінок було прочитано з кешу (shared_buffers)
  • shared read: скільки сторінок було прочитано з диска (завантажено в shared_buffers)
  • shared dirtied: скільки сторінок було модифіковано

Тема Explain доволі цікава і дає нам багато цікавої інформації, тому написав про неї окремо – PostgreSQL: використання EXPLAIN та налаштування “auto_explain” в AWS RDS.

Подивитись зміст shared_buffers

Отримати кількість буферів по всім таблицям:

SELECT
c.relname, count(*) AS buffers
FROM
pg_buffercache b
INNER JOIN pg_class c ON b.relfilenode = pg_relation_filenode(c.oid)
AND
b.reldatabase IN (0, (SELECT oid FROM pg_database
WHERE
datname = current_database()))
GROUP BY c.relname
ORDER BY 2 DESC
LIMIT 10;

Тут для challenge_progress використано 1636 буферів, що дає нам:

1636*8/1024
12

12 мегабайт.

Або можна отримати з pg_relation_size() – див. System Administration Functions та pg_relation_size():

prod_kraken_db=> SELECT pg_size_pretty(pg_relation_size('challenge_progress'));
 pg_size_pretty 
----------------
 13 MB

Перевірка work_mem

Якщо у нас падає FreeableMemory, то, можливо, використовується забагато work_mem.

Перевірити скільки виділяється на кожен процес:

dev_kraken_db=> SHOW work_mem;
 work_mem 
----------
 4MB

Перевірити чи вистачає процесам цього значення work_mem можна зі значення temp_blks_written, бо коли пам’ять в work_mem закінчується, то процес починає виносити дані в тимчасові таблиці:

Ну і, власне, на цьому, мабуть, все.

Якісь висновки? Складно робити. Ясно, що db.t3.small з двома гігабайтами нам було замало.

Є підозра який саме запит тоді викликав цю “цепну реакцію”, в slow queries logs побачили “некрасивий” SELECT, і девелопери його наче оптимізували.

Спробуємо зменшити тип інстансу до 4 гігабайт пам’яті, і подивимось, чи виникне проблема знов.

Monitoring summary

Замість висновків – кілька ідей того, що треба моніторити, і що в моніторингу можна покращити.

Наші алерти

Накидаю трохи алертів, які у нас вже є зараз.

CloudWatch метрики

Метрики CloudWatch. Збираємо до VictoriaMetrics з YACE-експортером.

CPUUtilization

Алерт:

- alert: HighCPUUtilization
  expr: avg(aws_rds_cpuutilization_average{dimension_DBInstanceIdentifier!="", dimension_DBInstanceIdentifier!~"kraken-ops-rds-.*"}[5m]) by (dimension_DBInstanceIdentifier) > 80
  for: 5m
  labels:
    severity: warning
    component: devops
    environment: ops
  annotations:
    summary: "High CPU utilization on RDS instance"
    description: "CPU utilization is above 80% for more than 5 minutes on RDS instance {{ "{{" }} $labels.instance }}."

DBLoadRelativeToNumVCPUs

Алерт:

- alert: HighCPULoadPerVCPUWarningAll
  expr: avg(aws_rds_dbload_relative_to_num_vcpus_average{dimension_DBInstanceIdentifier!="", dimension_DBInstanceIdentifier!~"kraken-ops-rds-.*"}[5m]) by (dimension_DBInstanceIdentifier) > 0.8
  for: 5m
  labels:
    severity: warning
    component: devops
    environment: ops
  annotations:
    summary: "High per-core CPU utilization on RDS instance"
    description: |
      CPU utilization is above 80% for more than 5 minutes on RDS instance {{ "{{" }} $labels.instance }}
      *DB instance*: `{{ "{{" }} $labels.dimension_DBInstanceIdentifier }}`
      *Per-vCPU load*: `{{ "{{" }} $value | humanize }}`

FreeStorageSpace

Не дуже актуально, якщо маємо динамічний storage, але може бути корисним.

Алерт:

- record: aws:rds:free_storage:gigabytes
  expr: sum(aws_rds_free_storage_space_average{dimension_DBInstanceIdentifier!=""}) by (dimension_DBInstanceIdentifier) / 1073741824

# ALL
- alert: LowFreeStorageSpaceCriticalAll
  expr: aws:rds:free_storage:gigabytes < 5
  for: 5m
  labels:
    severity: warning
    component: devops
    environment: ops        
  annotations:
    summary: "Low Disk Space on an RDS instance"
    description: |-
      Free storage below 5 GB
      *DB instance*: `{{ "{{" }} $labels.dimension_DBInstanceIdentifier }}`
      *Free storage*: `{{ "{{" }} $value | humanize }}`

FreeableMemory

Алерт:

- alert: LowFreeableMemoryDev
  expr: avg(aws_rds_freeable_memory_average{dimension_DBInstanceIdentifier="kraken-ops-rds-dev"}[5m]*0.000001) by (dimension_DBInstanceIdentifier) < 20
  for: 5m
  labels:
    severity: warning
    component: backend
    environment: dev       
  annotations:
    summary: "High memory usage on RDS instance"
    description: |-
      Freeable memory is less than 100mb
      *DB instance*: `{{ "{{" }} $labels.dimension_DBInstanceIdentifier }}`
      *Free memory*: `{{ "{{" }} $value | humanize }}`

ReadLatency, ReadIOPS та WriteLatency і WriteIOPS

Схожі метрики, корисно моніторити.

Алерт:

- alert: HighDiskReadLatencyKrakenStaging
  expr: sum(aws_rds_read_latency_average{dimension_DBInstanceIdentifier="kraken-ops-rds-dev"}) by (dimension_DBInstanceIdentifier) > 0.1
  for: 1s
  labels:
    severity: warning
    component: backend
    environment: dev
  annotations:
    summary: "High Disk Read Latency on RDS instance"
    description: |-
      Reads from a storage are too slow
      *DB instance*: `{{ "{{" }} $labels.dimension_DBInstanceIdentifier }}`
      *Read Latency*: `{{ "{{" }} $value | humanize }}`

SwapUsage

Теж must have метрика.

Алерт:

- record: aws:rds:swap_used:gigabytes
  expr: sum(aws_rds_swap_usage_average{dimension_DBInstanceIdentifier!=""}) by (dimension_DBInstanceIdentifier) / 1073741824

# ALL
- alert: SwapUsedAllWarning
  expr: sum(aws:rds:swap_used:gigabytes{dimension_DBInstanceIdentifier!="", dimension_DBInstanceIdentifier!~"kraken-ops-rds-.*"}) by (dimension_DBInstanceIdentifier) > 0.8
  for: 1s
  labels:
    severity: warning
    component: devops
    environment: ops
  annotations:
    summary: "Swap space use is too high on an RDS instance"
    description: |-
      The RDS instance is using more than *0.8 GB* of swap space
      *DB instance*: `{{ "{{" }} $labels.dimension_DBInstanceIdentifier }}`
      *Swap used GB*: `{{ "{{" }} $value | humanize }}`

DatabaseConnections

Є метрика CloudWatch, але вона нам повертає просто кількість конектів – а ліміт може бути різним для різних типів інстансів.

Тому приклад алерта тут покажу, але далі буде інший – з метрик PostgreSQL Exporter:

# db.t3.micro - 112 max_connections (Backend Dev)
# db.t3.small - 225 max_connections (Backend Prod)
# db.t3.medium - 450 max_connections
# db.t3.large - 901 max_connections

# ALL
- alert: HighConnectionCountWarning
  expr: avg(aws_rds_database_connections_average{dimension_DBInstanceIdentifier!="", dimension_DBInstanceIdentifier!~".*kraken.*"}[5m]) by (dimension_DBInstanceIdentifier) > 50
  for: 1m
  labels:
    severity: warning
    component: devops
    environment: ops
  annotations:
    summary: "High number of connections on RDS instance"
    description: |-
      An RDS instance Connections Pool is almost full. New connections may be rejected.
      *DB instance*: `{{ "{{" }} $labels.dimension_DBInstanceIdentifier }}`
      *Instance type*: `db.t3.micro`
      *Max connections*: `112`
      *Current connections*: `{{ "{{" }} $value | humanize }}`

Loki Recording Rules metrics

Пару метрик генеримо з логів нашого Backend API, наприклад:

- record: aws:rds:backend:connection_failed:sum:rate:5m
  expr: |
    sum(
        rate(
            {app=~"backend-.*"} 
            != "token_email" 
            |= "sqlalchemy.exc.OperationalError" 
            | regexp `.*OperationalError\) (?P<message>connection to server at "(?P<db_server>[^"]+)".*$)`
            [5m]
        )
    ) by (message, db_server)

І потім з них створюємо алерти:

- alert: BackendRDSConnectionFailed
  expr: sum(aws:rds:backend:connection_failed:sum:rate:5m{db_server="dev.db.kraken.ops.example.co"}) by (db_server, message) > 0
  for: 1s
  labels:
    severity: critical
    component: backend
    environment: dev
  annotations:
    summary: "Connection to RDS server failed"
    description: |-
      Backend Pods can't connect to an RDS instance
      *Database server:*: {{ "{{" }} $labels.db_server }}
      *Error message*: {{ "{{" }} $labels.message }}

PostgreSQL Exporter metrcis

pg_stat_database_numbackends

Тут як раз про Connections: в експортері ми маємо метрику pg_settings_max_connections, яка вказує на максимальну кількість конектів в залежності від типу інстансу, і pg_stat_database_numbackends – кількість активних сесій (конектів).

Відповідно можемо порахувати % від max connections.

Єдина проблема, що ці метрики мають різні лейбли, і я забив робити якісь label_replace – тому просто додав три record, на кожен environemnt:

# 'pg_stat_database_numbackends' and 'pg_settings_max_connections' have no common labels
# don't want to waste time with 'label_replace' or similar
# thus just create different 'records' for Prod and Staging
- record: aws:rds:kraken_dev:max_connections_used:percent
  expr: |
    (
      sum(pg_stat_database_numbackends{datname=~"dev_kraken_db", job="atlas-victoriametrics-postgres-exporter-kraken-dev"})
      /
      sum(pg_settings_max_connections{container=~".*kraken-dev"})
    ) * 100

- alert: ExporterHighConnectionPercentBackendDevWarning
  expr: aws:rds:kraken_dev:max_connections_used:percent > 40
  for: 1s
  labels:
    severity: warning
    component: backend
    environment: dev
  annotations:
    summary: "High number of connections on the Backend RDS instance"
    description: |-
      RDS instance Connections Pool is almost full. New connections may be rejected.
      *DB instance*: `kraken-ops-rds-dev`
      *Connections pool use*: `{{ "{{" }} $value | humanize }}%`
    grafana_rds_overview_url: 'https://{{ .Values.monitoring.root_url }}/d/ceao6muzwos1sa/kraken-rds?orgId=1&from=now-1h&to=now&timezone=browser&var-query0=&var-db_name=kraken-ops-rds-dev'

pg_stat_activity_max_tx_duration

Алерти, коли якісь транзакції виконуються надто довго.

Не сказати, що дуже корисна метрика, бо не маємо PID і кількості пам’яті, але поки що хоч так.

Потім можна буде подумати над кастомними метриками.

Зараз алерт такий:

- alert: ExporterTransactionExecutionTimeBackendDevWarning
  expr: sum(rate(pg_stat_activity_max_tx_duration{datname="dev_kraken_db"}[5m])) by (state, datname) > 0.1
  for: 1m
  labels:
    severity: warning
    component: backend
    environment: dev
  annotations:
    summary: "RDS transactions running too long"
    description: |-
      Too long duration in seconds active transaction has been running
      *Database name*: `{{ "{{" }} $labels.datname }}`
      *State*: `{{ "{{" }} $labels.state }}`
      *Duration*: `{{ "{{" }} printf "%.2f" $value }}` seconds
    grafana_rds_overview_url: 'https://{{ .Values.monitoring.root_url }}/d/ceao6muzwos1sa/kraken-rds?orgId=1&from=now-1h&to=now&timezone=browser&var-query0=&var-db_name={{ "{{" }} $labels.datname }}'

Варто додати

Ну, тут прям дуже багато всього.

PostgreSQL Exporter custom metrics

Основне, десь вище вже згадував – в PostgreSQL Exporter ми можемо створювати кастомні метрики з результатами запитів до PostgreSQL, використовуючи config.queries.

Див. Create Prometheus integrated Postgres custom metrics.

Хоча ця фіча наче deprecated.

Але навіть якщо її вимкнуть – то можна заморочитись, і написати власний експортер. Див. Prometheus: створення Custom Prometheus Exporter на Python та Prometheus: GitHub Exporter – пишемо власний експортер для GitHub API.

CloudWatch Logs та Enhanced Monitoring

Теж вже згадував, було б дуже корисно мати власні метрики по тому ж Swap, або мати PID процесів і їхню resident memory.

How can I filter Enhanced Monitoring CloudWatch logs to generate automated custom metrics for Amazon RDS?

Моніторинг Transactions

В мене це зараз є на Grafana dashboard:

Але можливо додам окремими алертами – по кількості active transactions, або по idle in transaction.

Основні метрики з PostgreSQL Exporter:

  • pg_stat_database_xact_commit та pg_stat_database_xact_rollback: як бачили в нашому випадку – якщо значення падає, то маємо проблеми – запити не завершуються
  • pg_stat_activity: по лейблі state маємо два основні:
    • active: загальна кількість активних запитів
    • idle in transaction: теж бачили в нашому випадку, що багато запитів зависли в очікуванні завершення
  • pg_locks: кількість блоків (див. pg_locks та Concurrency Control)

Моніторинг WAL

Теж згадував кілька метрик, які є в PotsgreSQL Exporter, можливо, додам по ним або алертів, або графіків до Grafana:

  • pg_stat_archiver_archived_count: загальна кількість успішно заархівованих WAL-файлів (що скаже нам, що WAL працює коректно)
  • pg_stat_archiver_failed_count: кількість невдалих спроб архівування WAL-файлів
  • pg_stat_bgwriter_checkpoint_time: час, витрачений на виконання CHECKPOINT

В самому сервері можемо перевірити з view pg_stat_wal:

SELECT * FROM pg_stat_wal;

Основні тут:

  • wal_records: кількість записаних WAL-записів (операцій INSERT, UPDATE, DELETE)
  • wal_bytes: загальний обсяг даних (у байтах), записаних у WAL
  • wal_buffers_full: скільки разів WAL-буфери були повністю заповнені, змушуючи бекенд-процеси писати напряму в WAL-файл
  • wal_write: кількість разів, коли PostgreSQL записував WAL у файл
  • wal_write_time: загальний час у мілісекундах, витрачений на записи WAL
  • wal_sync_time: загальний час (у мілісекундах), витрачений на fsync() (гарантований запис на диск)

Моніторинг shared_buffers

Тут треба ще подумати, які б метрики можна було генерити, і які графіки або алерти придумати.

З того, що приходить в голову:

  • моніторити shared hit та read: скільки даних було знайдено в кеші, а скільки довелось зчитувати з диску
  • buffers_backend: скільки буферів записали безпосередньо бекенд-процеси
    • в нормальній ситуації всі дані з dirty pages мають записуватись bgwriter або checkpoint
    • якщо shared_buffers зайняті, а bgwriter, wal_writer або checkpointer не встигає переносити з них дані на диск – то backend-процеси клієнтів змушені переносити дані самі, що уповільнює виконання їх запитів

Перевіряємо з:

SELECT buffers_backend, buffers_checkpoint, buffers_alloc FROM pg_stat_bgwriter;

Тут:

  • buffers_backend: скільки буферів записали безпосередньо бекенд-процеси
  • buffers_checkpoint: скільки буферів записано під час CHECKPOINT
    • якщо маємо високе значення:
      • то чекпоінти відбуваються рідко, і одразу записують багато сторінок
      • або bgwriter не встигає виконувати записи, і CHECKPOINT записує все відразу
  • buffers_alloc: скільки нових буферів виділено у shared_buffers
    • якщо маємо високе значення – то кеш постійно витісняється, і PostgreSQL змушений завантажувати сторінки з диска

Моніторинг Checkpointer

Також сенс приглядати за Checkpointer:

SELECT checkpoint_write_time, checkpoint_sync_time FROM pg_stat_bgwriter;

Тут:

  • checkpoint_write_time: час, витрачений на запис змінених сторінок (dirty pages) з shared_buffers у файлову систему; якщо значення велике – то:
    • занадто великий shared_buffers – при чекпоінті доводиться записувати забагато сторінок одразу
    • багато операцій (UPDATE, DELETE), що призводить до великої кількості “брудних” сторінок (dirty pages).
    • або checkpoint_timeout занадто великий, тому при чекпоінті записується багато змін одразу.
  • checkpoint_sync_time: час, витрачений на примусовий запис (виконання fsync()) змінених сторінок на фізичний диск; якщо значення велике – то:
    • можливі проблеми з диском – повільно записуються дані

Моніторинг work_mem

Теж є сенс дивитись сюди.

Якщо work_mem недостатньо – то процеси починають писати temp_blks_written, що, по-перше, уповільнює виконання запитів, по-друге – створює додаткове навантаження на диск.

Перевіряємо з:

SELECT temp_files, temp_bytes FROM pg_stat_database WHERE datname = current_database();

Корисні посилення

Loading