Skip to main content

Создать компонент-сервис

info

Вы можете менять порядок полей и сущностей в файле.

Если у вас монорепозиторий:

  • может быть несколько файлов .YML с компонентами-сервисами;
  • эти файлы можно разложить по разным папкам репозитория;
  • заполните spec.path.

Шаг 1. Добавьте файл в репозиторий​

  1. Скачайте файл service.yml.
  2. Перенесите файл в любой каталог репозитория.

Шаг 2. Заполните информацию о сервисе​

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

Впишите в ваш файл service.yml информацию о сервисе по примерам ниже. Чтобы он появился в каталоге, в нём должны быть поля:

  • metadata.name;
  • spec.type.

Пример конфигурации для каталога ПО​

Примеры для отображения в каталоге ПО
service.yml
---
apiVersion: devplatform.tcsbank.ru/v1
kind: Service
metadata:
  name: tenant-manager
  description: Spirit IAM core component
  labels:
    go: "1.18"
spec:
  supportTeam: Devplatform_PaaS
  developers:
    groups:
      - devplatform-devs
  links:
    Dashboard: https://...
    Grafana: https://...
    User Docs: https://...
    Wiki: https://...
    SLA: https://...
    Runbooks: https://....
    Jira: https://...
  type: backend
  criticalLevel: MC
  provides:
    - users-api
  consumes:
    - name: service-provider-1
      tenant: test-cicd-images
      description: описание связи
  dependsOn:
    - tenant-manager-db
Чтобы сущность не отображалась в каталоге

Если вы создаёте сущность в каталоге для теста и не хотите, чтобы она использовалась в каталоге, добавьте annotations: service-catalog/processing.skip: "true".

Пример:

apiVersion: devplatform.tcsbank.ru/v1
kind: Service
metadata:
  name: tenant-manager-test
  annotations: service-catalog/processing.skip: "true"

Примеры для конфигурации Spirit Deploy​

Примеры конфигурации для деплоя на HTTP, TCP и GRPC
apiVersion: devplatform.tcsbank.ru/v1
kind: Service
metadata:
  description: Сервис для демонстрации функций DaaS
  name: demo-application
spec:
  developers:
    groups:
    - k8s-admins
  type: backend
  imageStream: "acr.polygon.tcsgroup.io/k8s/demo-application2"    # acr.polygon.tcsgroup.io/<tenant>/<repo_name>
  runtimeParams:
    metrics:
      port: 8080
      path: /metrics

Общие данные​

Основное​

metadata:
  name: tenant-manager
  description: Spirit IAM core component
  labels:
    go: "1.18"
    environment: production
    app: nginx
spec:
  type: backend
  criticalLevel: MC

metadata.name — уникальный в рамках тенанта идентификатор сервиса. Напишите в формате регулярных выражений: \^\[a-zA-Z0-9\_.\]\[a-zA-Z0-9\_\\-.\]\*\$\.


metadata.description — понятное описание сервиса.


metadata.labels — произвольный набор ключ-значение с важными для пользователя характеристиками. Логика по примеру лейблов Kubernetes.


spec.type — тип сервиса — backend или frontend.


spec.criticalLevel — уровень критичности сервиса. Например, MC, BC, BO или OP (Mission Critical, Business Critical, Business Operational или Office Productivity соответсвенно).

Ответственные​

spec:
  supportTeam: Devplatform_PaaS
  developers:
    groups:
      - devplatform-devs

spec.supportTeam — имя группы ответственных SRE в OnCall.


spec.developers — разработчики сервиса, можно указывать только группы пользователей Spirit.

  • spec.developers.groups[] — список названий групп, которые отвечают за этот Service.

Ссылки​

spec:
  links:
    Jira: https://jira...
    Runbooks: https://...
    SLA: https://...
    Wiki: https://wiki...
    Dashboard: https://.../grafana/...
    Grafana: https://.../grafana/...
    User Docs: https://wiki....

spec.links — ссылки ресурсов, связанные с сервисом. Укажите Sage, Jira, Runbooks, SLA и Wiki. Чтобы добавить другие ресурсы, укажите их в формате LinkLabel: linkURL.


spec.path — относительный путь до сервиса внутри репозитория. Для монорепозиториев.


Контракты и ресурсы​

spec:
  provides:
    - users-api // если Contract и Service в одном тенанте, название строкой
  consumes:
    - name: service-provider-1 // Contract и Service в разных тенантах, поэтому указаны все поля
      tenant: test-cicd-images
      description: описание связи
  dependsOn:
    - tenant-manager-db

spec.provides — список поставляемых контрактов API. Если Contract и Service в одном тенанте, укажите имя контракта строкой. Если нет, пропишите:

  • spec.provides.[].name — поставляемый сервисом Contract name.
  • spec.provides.[].tenant — поставляемый сервисом Contract tenant

spec.consumes — список потребляемых контрактов. Если Contract и Service в одном тенанте, укажите имя контракта строкой. Если нет, пропишите:

  • spec.consumes.[].name — потребляемые сервисом Contract name
  • spec.consumes.[].tenant — потребляемые сервисом Contract tenant
  • spec.consumes.[].description — произвольное описание связи. Необязательный атрибут.

spec.dependsOn — список используемых ресурсов. Если Resource и Service в одном тенанте, укажите имя Resource строкой. Если нет, пропишите:

  • spec.dependsOn.[].name — имя Resource;
  • spec.dependsOn.[].tenant — тенант Resource.

Параметры Runtime​

Обычно эти поля заполняют не сразу, а когда хотят задеплоить приложение с помощью Spirit Deploy.

spec:
  imageStream: "acr.polygon.tcsgroup.io/k8s/demo-application2"
  runtimeParams:
    command:
      - "node"
    args:
      - "--start"
    ports:
      - containerPort: 8080
        name: metrics
      - containerPort: 8081
        name: app
    probes:
      liveness:
        http:
          port: 8080
          path: "/livez"
      readiness:
        http:
          port: 8080
          path: "/readyz"

imageStream — путь до образа в хранилище образов. Тип данных: string.

command — массив параметров для CMD внутри Docker-образа для запуска конкретного бинаря. Тип данных: string[].


args — аргументы для запуска приложения. Тип данных: string[].


ports — массив объектов с описанием портов, необходимых к открытию в приложения. Тип данных: string[].

  • containerPort — номер порта в контейнере. Тип: string.
  • name — имя порта. Тип: string.

probes — объект с описанием конфигураций всех проб: startup, readiness или liveness.

Под каждым из значений можно прописать тип конфигурации пробы:

Деплой приложения​

Обычно эти поля заполняют не сразу, а когда хотят задеплоить приложение с помощью Spirit Deploy.

spec:
  envs:
    - DB_CONNECTION
    - DB_CONNECTION_INTERVAL
    - PORT
    - DEMO_ENV_1
    - DEMO_ENV_2
    - SYSTEM
    - ENV
  configMountDir: /tmp
  configPresets:
    - presetName: dev
        files:
        - targetName: devConfig.yaml
        $ref: configs/devConfig.yaml
        - presetName: prod
        files:
        - targetName: prodConfig.yaml
        $ref: configs/prodConfig.yaml

envs — секреты для запуска образа. Тип данных: string[].


configMountDir — директория для монтирования файла внутри пода приложения. Тип данных: string.


configPresets — массив пресетов с конфигами приложения. Поля:

  • обязательное — presetName — название в формате string;
  • files — файлы конфигурации внутри репозитория, где находится service.yaml. Обязательные поля:
    • targetName — имя файла при монтировании в контейнер. Тип: string.
    • $ref — путь до файла внутри репозитория, где находится service.yaml. Тип: string.

Шаг 3. Заполните контракты API​

Что такое контракты API

API, через который сервисы связываются друг с другом — plaintext-описание контракта.

Сейчас contract definition может храниться только внутри сущности Contract в файле service-catalog.yml.

Чтобы модели отображались в новом формате в API, передавайте заголовок версии Accept: [application/service-catalog.v2+json].

apiVersion: devplatform.tcsbank.ru/v1
kind: Contract
metadata:
  name: users-api
  description: contract description 2
spec:
  protocol: "HTTP"
  serialization: "JSON"
  definition:
    version: "0.0.1"
    content: |
      openapi: "3.0.0"
      paths:
        /api/v2/users:
          get:
            summary: List all users

metadata.name — уникальный идентификатор Contract. Пишите в формате регулярных выражений: ^[a-zA-Z0-9_.][a-zA-Z0-9_\-.]*$.

metadata.description — описание контракта. Пишите так, чтобы вам и коллегам было понятно что это и зачем.

spec.definition.version — версия контракта.

spec.definition.content — содержимое definition Contract.

Шаг 4. Заполните зависимости​

Что такое зависимости

В рамках одного файла можно определить несколько сущностей одного типа. Их имена уникальны в пределах одного тенанта. Если появится дубль, данные не сохранятся.

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

Сам по себе Resource не указывает на конкректный экземпляр зависимости, представляя из себя интерфейс.

Файл из примера: resource.yml

apiVersion: devplatform.tcsbank.ru/v1
kind: Resource
metadata:
  name: tenant-manager-db
  description: Tenant manager DB
spec:
  type: Postgres

metadata.name — уникальный идентификатор. Пишите в формате регулярных выражений: ^[a-zA-Z0-9_.][a-zA-Z0-9_\-.]*$.

metadata.description — описание. Пишите так, чтобы вам и коллегам было понятно что это и зачем.

spec.type — тип инфраструктурной зависимости. Значения: Postgres, Cassandra, KafkaTopic, Redis, ExternalAPI, S3Bucket.

Шаг 5. Запушьте изменения​

Вы не можете проверить целостность логических связей до push master.

  1. Залейте изменения и докатите их в ветку master.

  2. Проверьте, корректные ли данные в интерфейсе Spirit.

    Ошибки целостности связей отображаются в UI Spirit на странице сервиса: