Backstage IDP
У "Підручниках з розробки Backstage" ми будемо говорити про розробку Backstage. Він має багато стандартних частин, які ми можемо використовувати, а також багато частин, які можна розширювати. Ось список підручників на даний момент:
- як створити модуль і користувацькі дії
- як створити плагін для бекенду
- Додати сервіс до основних сервісів Backstage
- Налаштування LDAP або Active Directory для організаційних даних у Backstage
У цій частині ми розглянемо поради та хитрощі з Backstage, тобто речі, які я дізнався після 5 місяців розробки Backstage для моєї компанії. Ось список цих порад:
- неправильне завантаження CSS для Techdocs
- використання dotenv для зчитування змінних середовища
- покращення Docker-образу для розгортання на серверах без підключення до інтернету
- для кожного плагіна створюється окремі бази даних, а не для кожного модуля
- деякі інші менш важливі поради
Неправильне завантаження CSS для Techdocs
Коли я розгортав Docker-образ на наших серверах, ми стикнулися з проблемою: коли я відкривав будь-який документ у плагіні Docs, він не відображався правильно. Після перевірки я зрозумів, що CSS-файл не завантажується. Тому я вирішив проблему таким чином. Я відкрив інспектор у браузері і зберіг файл, коли працював з Backstage у режимі розробки (CSS-файл має однаковий вміст для різних документів, але різні імена для кожного документу), зберіг його і зберіг в місці, яке доступне для мого Nginx. У конфігурації Nginx (або Ingress, якщо розгорнуто на Kubernetes) додайте цей код вище за розділ Backstage:
location ~ ^/api/techdocs/static/docs/default/(component|system|api|resource|template)/[a-zA-Z0-9_-]+/assets/stylesheets/main\..*\.css$ {
alias /usr/share/nginx/html/main.min.css;
# Фейкові заголовки
add_header Content-Security-Policy "default-src 'self';base-uri 'self';font-src 'self' https: data:;frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self' 'unsafe-eval';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests;connect-src 'self' http: https:";
add_header Referrer-Policy "no-referrer";
add_header Strict-Transport-Security "max-age=15552000; includeSubDomains";
add_header X-Content-Type-Options "nosniff";
add_header X-DNS-Prefetch-Control "off";
add_header X-Download-Options "noopen";
add_header X-Frame-Options "SAMEORIGIN";
add_header X-Permitted-Cross-Domain-Policies "none";
add_header X-XSS-Protection "0";
add_header Cache-Control "public, max-age=0";
add_header Vary "Accept-Encoding";
# Переконатися, що Content-Type та кодування співпадають
default_type "text/css; charset=utf-8";
gzip on;
gzip_types text/css;
# Обслуговування вмісту з відповідними заголовками модифікації
add_header Last-Modified "Tue, 24 Sep 2024 09:07:33 GMT";
add_header ETag 'W/"20ec5-192234934db"';
}
Таким чином, файл обслуговуватиметься через Nginx, а не через Backstage.
Використання dotenv для зчитування змінних середовища
Файли конфігурації Backstage мають такий формат:
database:
client: pg
connection:
host: ${POSTGRES_HOST}
user: ${POSTGRES_USER}
password: ${POSTGRES_PASSWORD}
port: ${POSTGRES_PORT}
який заповнює змінні з системних змінних середовища. Один з простих способів передати ці змінні до системи — це записати їх у текстовий файл (який називається .env) і використовувати пакет node.js під назвою dotenv. Встановіть його і активуйте, додавши це на початок файлу /packages/backend/src/index.ts:
import dotenv from 'dotenv';
dotenv.config({ path: '../../.env' });
Таким чином, нам не потрібно передавати змінні середовища одну за одною.
також у середовищі Kubernetes ми можемо завантажити цей файл як конфігураційну мапу (Config Map) і передати її в поди.
Покращення Docker-образу
Стандартний Dockerfile для backstage доволі довгий, тому розбиття його може заощадити час. Ми можемо виділити першу частину, щоб вона виконувалась лише один раз і не впливала на інші частини:
FROM node:18-bookworm-slim
# Встановлення залежностей для isolate-vm, необхідних для плагіна @backstage/plugin-scaffolder-backend.
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
--mount=type=cache,target=/var/lib/apt,sharing=locked \
apt-get update && \
apt-get install -y --no-install-recommends python3 g++ build-essential && \
yarn config set python /usr/bin/python3
# Встановлення залежностей для TechDocs
RUN apt-get update && apt-get install -y python3 python3-pip python3-venv
ENV VIRTUAL_ENV=/opt/venv
RUN python3 -m venv $VIRTUAL_ENV
ENV PATH="$VIRTUAL_ENV/bin:$PATH"
RUN pip3 install mkdocs-techdocs-core
# Встановлення curl, ping, telnet для перевірки підключення
RUN apt-get update && apt-get install -y curl iputils-ping telnet ldap-utils
RUN curl -O https://nodejs.org/download/release/v18.20.5/node-v18.20.5-headers.tar.gz && \
yarn config set tarball /node-v18.20.5-headers.tar.gz
Тепер ми можемо використовувати цей образ як базовий для Backstage. Є кілька моментів, які роблять його кращим для розгортання на ізольованих серверах (наприклад, на виробничих серверах компанії).
Я додав пакети telnet, ping, ldap, щоб у разі потреби діагностувати загальні проблеми з підключенням, ми мали достатньо інструментів на наших контейнерах.
Також я додав заголовочні файли для node.js (в мене версія node 18), що необхідно при встановленні пакунків на серверах без підключення до інтернету.
Зберіть образ і позначте його значущою назвою, потім створіть другу частину Dockerfile:
FROM your-company-image-server/backstage-base:latest
USER node
WORKDIR /app
ENV NODE_ENV=production
COPY --chown=node:node .yarnrc yarn.lock package.json packages/backend/dist/skeleton.tar.gz ./
RUN tar xzf skeleton.tar.gz && rm skeleton.tar.gz
RUN --mount=type=cache,target=/home/node/.cache/yarn,sharing=locked,uid=1000,gid=1000 \
yarn install --frozen-lockfile --production --network-timeout 300000
COPY --chown=node:node packages/backend/dist/bundle.tar.gz app-config*.yaml ./
RUN tar xzf bundle.tar.gz && rm bundle.tar.gz
CMD ["node", "packages/backend", "--config", "app-config.yaml", "--config", "app-config.production.yaml"]
Тепер ви отримаєте коротший час побудови, і більшість з цього не потребуватиме підключення до інтернету, окрім yarn packages.
Для встановлення пакунків через yarn, потрібно зробити таке:
Створіть файл .yarnrc:
yarn-offline-mirror ".yarn-cache/"
yarn-offline-mirror-pruning true
Якщо ви запустите yarn install на сервері з підключенням до мережі, він кешуватиме стиснуті файли залежностей у директорії .yarn-cache всередині вашого проєкту; якщо ви це збережете у репозиторії, він використовуватиме цей кеш наступного разу, і підключення до інтернету вже не буде потрібне.
Створюються окремі бази даних для кожного плагіна, а не для кожного модуля
Якщо подивитися на базу даних, до якої підключений ваш Backstage, ви побачите, що для кожного плагіна створена окрема база даних. Навіть якщо ви створюєте новий плагін, він матиме свою власну базу даних, і ви не зможете отримати доступ до бази даних іншого плагіна, використовуючи сервіс knex, доступний для вашого плагіна.
Отже, коли ви створюєте свої власні плагіни, вам потрібно створювати міграції для них, щоб створювати необхідні таблиці.
Для міграцій вам знадобиться файл knexfile.js у корені вашого плагіна:
// Оновіть налаштування вашої конфігурації.
/**
* @type { Object. }
*/
module.exports = {
migrations: {
tableName: 'migrations',
},
};
і виконувач міграцій:
import {
DatabaseService,
resolvePackagePath,
} from '@backstage/backend-plugin-api';
export async function applyDatabaseMigrations(
db: DatabaseService,
): Promise {
const knex = await db.getClient();
const migrationsDir = resolvePackagePath(
'@internal/backstage-plugin-pluginname-backend',
'migrations',
);
await knex.migrate.latest({
directory: migrationsDir,
});
}
Тепер викликайте це десь у коді (наприклад, всередині функції registerInit).
Тепер ви можете створювати міграції за допомогою:
yarn knex migrate:make migrationName
Декілька дрібних порад
- Не забувайте вимкнути гостя (guest) автентифікацію
Backstage має провайдера гостя (guest provider), який є стандартним, коли ви створюєте новий проєкт Backstage. Але не забувайте видалити його з обох пакетів — backend і frontend. В іншому випадку у вашій конфігурації виникне очевидна проблема з безпекою.
- Модулі використовують базу даних плагінів
Інший момент полягає в тому, що якщо ви хочете отримати доступ до бази даних у модулі, який ви пишете, ви можете отримати доступ лише до бази даних плагіна, що відповідає цьому модулю; наприклад, у модулі з назвою scaffolder-backend-module-foo ви маєте доступ лише до бази даних плагіна scaffolder.
Це були деякі проблеми, з якими я зіткнувся під час роботи з Backstage. Сподіваюся, це допоможе вирішити деякі з ваших проблем. І на цьому все.
Перекладено з: Backstage tips and tricks