12.01.2020 17:15
kvaps 2 3200 Источник

В продолжение предыдущей статьи про инструменты деплоя в Kubernetes, хочу рассказать вам про то как можно использовать Jsonnet для упрощения описания джоб в вашем .gitlab-ci.yml



Дано


Есть монорепа, в которой:


  • 10 Dockerfiles
  • 30 описанных деплоев
  • 3 окружения: devel, staging и production

Задача


Настроить пайплайн:


  • Сборка Docker-образов должна производиться по добавлении git-тэга с версией.
  • Каждая операция деплоя должна выполняться при пуше в ветку окружения и только по изменении файлов в конкретной директории
  • В каждом окружении установлен свой gitlab-runner с отдельным тэгом, который выполняет деплой только в своём окружении.
  • Не все приложения должны быть задеплоены в каждое из окружений, мы должны описать пайплайн так, чтобы иметь возможность делать исключения.
  • Некоторые деплойменты используют git submodule и должны запускаться с установленной переменной GIT_SUBMODULE_STRATEGY=normal

Описать это всё может показаться настоящим адом, но мы не отчаиваемся и вооружившись Jsonnet сделаем это легко и непринуждённо.


Решение


gitlab-ci.yml имеет встроенные возможности по сокращению описания повторяющихся джоб, например можно использовать extends или include, но он не предоставляет полноценный темплейтинг, что не позволяет описать джобы наиболее кратко и эфективно.


Для решения этой задачи я предлагаю использовать jsonnet, который позволяет почти полностью избавиться от повторения кода при описании любых структур данных.


При работе с jsonnet очень советую установить вам плагин для вашего редактора

К примеру для vim есть плагин vim-jsonnet, который включает подсветку синтаксиса и автоматически выполняет jsonnet fmt при каждом сохранении (требует наличия установленно jsonnet).

Посмотрим на структуру нашего репозитория:


.
+-- deploy
¦   +-- analyse
¦   +-- basin
¦   +-- brush
¦   +-- copper
¦   +-- dinner
¦   +-- dirty
¦   +-- drab
¦   +-- drunk
¦   +-- education
¦   +-- fanatical
¦   +-- faulty
¦   +-- guarantee
¦   +-- guitar
¦   +-- hall
¦   +-- harmonious
¦   +-- history
¦   +-- iron
¦   +-- maniacal
¦   +-- mist
¦   +-- nine
¦   +-- pleasant
¦   +-- polish
¦   +-- receipt
¦   +-- shop
¦   +-- smelly
¦   +-- solid
¦   +-- stroke
¦   +-- thunder
¦   +-- ultra
¦   L-- yarn
L-- dockerfiles
    +-- dinner
    +-- drunk
    +-- fanatical
    +-- guarantee
    +-- guitar
    +-- harmonious
    +-- shop
    +-- smelly
    +-- thunder
    L-- yarn

Сборка docker-образов будет производиться с помощью kaniko


Деплой приложений в кластер будет производится с помощью qbec. Каждое приложение описано для трёх разных окружений, чтобы применить изменения в кластер достаточно выполнить: 


qbec apply <environment> --root deploy/<app> --yes

где:


  • <app> — название нашего приложения
  • <environment> — одно из наших окружений: devel, stage или prod.

В конечном итоге наши джобы должны выглядeть так:


Сборка:


build:{{ image }}:
  stage: build
  tags:
    - build
  image:
    name: gcr.io/kaniko-project/executor:debug
    entrypoint: [""]
  script:
    - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json
    - /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/dockerfiles/{{ image }}/Dockerfile --destination $CI_REGISTRY_IMAGE/{{ image }}:$CI_COMMIT_TAG
  only:
    refs:
      - tags

Где вместо {{ image }}, будет подставляться имя директории из dockerfiles


Деплой:


deploy:{{ environment }}:{{ app }}:
  stage: deploy
  tags:
    - {{ environment }}
  script:
    - qbec apply {{ environment }} --root deploy/{{ app }} --force:k8s-context __incluster__ --wait --yes
  only:
    changes:
      - deploy/{{ app }}/**/*
    refs:
      - {{ environment }}

Где вместо {{ app }}, будет подставляться имя директории из deploy,
а вместо {{ environment }} — имя окружения в которое нужно произвести деплой.


Давайте опишем прототипы наших джоб в виде объектов в отдельной либе lib/jobs.jsonnet


{
  // Задание на сборку docker-образа
  dockerImage(name):: {
    tags: ['build'],
    stage: 'build',
    image: {
      name: 'gcr.io/kaniko-project/executor:debug-v0.15.0',
      entrypoint: [''],
    },
    script: [
      'echo "{\\"auths\\":{\\"$CI_REGISTRY\\":{\\"username\\":\\"$CI_REGISTRY_USER\\",\\"password\\":\\"$CI_REGISTRY_PASSWORD\\"}}}" > /kaniko/.docker/config.json',
      '/kaniko/executor --cache --context $CI_PROJECT_DIR/dockerfiles/' + name + ' --dockerfile $CI_PROJECT_DIR/dockerfiles/' + name + '/Dockerfile --destination $CI_REGISTRY_IMAGE/' + name + ':$CI_COMMIT_TAG --build-arg VERSION=$CI_COMMIT_TAG',
    ],
  },
  // Задание на деплой qbec-приложения
  qbecApp(name): {
    stage: 'deploy',
    script: [
      'qbec apply $CI_COMMIT_REF_NAME --root deploy/' + name + ' --force:k8s-context __incluster__ --wait --yes',
    ],
    only: {
      changes: [
        'deploy/' + name + '/**/*',
      ],
    },
  },
}

Обратите внимание я намеренно не стал указывать refs и tags чтобы сделать нашу либу более гибкой и в полной мере продемонстрировать вам возможности jsonnet, их мы добавим позже уже из основного файла.


Теперь опишем наш .gitlab-ci.jsonnet:


// Импортируем нашу либу
local jobs = import 'lib/jobs.libsonnet';

// Определяем функции модификаторы
local ref(x) = { only+: { refs: [x] } };
local tag(x) = { tags: [x] };
local submodule(x) = { variables+: { GIT_SUBMODULE_STRATEGY: x } };

{
  // Cборка docker-образов
  ['build:' + x]: jobs.dockerImage(x) + tag('build') + ref('tags')
  for x in [
    'dinner',
    'drunk',
    'fanatical',
    'guarantee',
    'guitar',
    'harmonious',
    'shop',
    'smelly',
    'thunder',
    'yarn',
  ]
}
+
{
  // Деплой приложений которые должны быть развёрнуты только в 'prod'
  ['deploy:prod:' + x]: jobs.qbecApp(x) + tag('prod') + ref('prod')
  for x in [
    'dinner',
    'hall',
  ]
}
+
{
  // Деплой с git-submodule
  ['deploy:' + env + ':' + app]: jobs.qbecApp(app) + tag(env) + ref(env) + submodule('normal')
  for env in ['devel', 'stage', 'prod']
  for app in [
    'brush',
    'fanatical',
    'history',
    'shop',
  ]
}
+
{
  // Деплой всего остального
  ['deploy:' + env + ':' + app]: jobs.qbecApp(app) + tag(env) + ref(env)
  for env in ['devel', 'stage', 'prod']
  for app in [
    'analyse',
    'basin',
    'copper',
    'dirty',
    'drab',
    'drunk',
    'education',
    'faulty',
    'guarantee',
    'guitar',
    'harmonious',
    'iron',
    'maniacal',
    'mist',
    'nine',
    'pleasant',
    'polish',
    'receipt',
    'smelly',
    'solid',
    'stroke',
    'thunder',
    'ultra',
    'yarn',
  ]
}

Обратите внимание на функции ref, tag и submodule вначале файла, они позволяют сформировать переопределяющий объект.


Небольшое пояснение: использование "+:" вместо ":" для override-объектов позволяет добавить значение к уже существующему объекту или списку.


Например ":" для refs:


local job = {
  script: ['echo 123'],
  only: { refs: ['tags'] },
};
local ref(x) = { only+: { refs: [x] } };

job + ref('prod')

вернёт:


{
   "only": { "refs": [ "prod" ] },
   "script": [ "echo 123" ]
}

А вот "+:" для refs:


local job = {
  script: ['echo 123'],
  only: { refs: ['tags'] },
};
local ref(x) = { only+: { refs+: [x] } };

job + ref('prod')

вернёт:


{
   "only": { "refs": [ "prod", "tags" ] },
   "script": [ "echo 123" ]
}

Как видите, использование Jsonnet позволяет очень эффективно описывать и проводить слияние ваших объектов, на выходе вы всегда получаете готовый JSON, который мы сразу же можем записать в наш .gitlab-ci.yml файл:


jsonnet .gitlab-ci.jsonnet > .gitlab-ci.yml

Проверим количество строк:


# wc -l .gitlab-ci.jsonnet lib/jobs.libsonnet .gitlab-ci.yml
   77 .gitlab-ci.jsonnet
   24 lib/jobs.libsonnet
 1710 .gitlab-ci.yml

На мой взгляд очень неплохо!


Посмотреть больше примеров и пощупать Jsonnet можно прямо на официальном сайте: jsonnet.org
Если вам, как и мне, нравится Jsonnet то вступайте в нашу группу в телеграме t.me/jsonnet_ru