Здравейте! Напоследък излязоха много страхотни инструменти за автоматизация както за създаване на Docker изображения, така и за внедряване в Kubernetes. В тази връзка реших да се поиграя с GitLab, да разгледам възможностите му и, разбира се, да настроя пайплайн.

Вдъхновението за тази работа е уебсайтът kubernetes.io, който се генерира от изходни кодове автоматично, а за всяко внесено искане за изтегляне, роботът автоматично генерира предварителна версия на сайта с вашите промени и предоставя линк за преглед.

Опитах се да изградя подобен процес от нулата, напълно базиран на GitLab CI и свободни инструменти, които съм свикнал да използвам за внедряване на приложения в Kubernetes. Днес, накрая, ще ви разкажа за тях по-подробно.

В статията ще бъдат разгледани следните инструменти:
Hugo, qbec, kaniko, git-crypt и GitLab CI създаване на динамични среди.

Съдържание

1. Запознаване с Hugo
2. Подготовка на Dockerfile
3. Запознаване с kaniko
4. Запознаване с qbec
5. Тестване на GitLab-runner с Kubernetes-executor
6. Внедряване на Helm-чарти с qbec
7. Запознаване с git-crypt
8. Създаване на образ на инструментариум
9. Нашият първи пайплайн и сборка на изображения по тагове
10. Автоматизация на внедряването
11. Артефакти и сборка при push в master
12. Динамички средини
13. Прегледни приложения

1. Запознаване с Hugo

Като пример за нашия проект, ще се опитаме да създадем сайт за публикуване на документация, базиран на Hugo. Hugo е статичен генератор на съдържание.

За тези, които не са запознати със статичните генератори, ще разкажа малко повече за тях. В отличие от обикновените уеб платформи с база данни и PHP, които генерират страници на лето при заявка от потребителя, статичните генератори работят малко по-различно. Те позволяват да се вземат изходни файлове, обикновено набор от файлове в Markdown формат и шаблони, след което да се компилират в напълно готов сайт.

Тоест, на изхода ще получите структура от директории и набор от генерирани HTML файлове, които можете просто да качите на всякакъв евтин хостинг и да получите работещ сайт.

Hugo може да бъде инсталиран локално и да се опита в действие:

Инициализираме нов сайт:

hugo new site docs.example.org

И едновременно с това и Git репозиторий:

cd docs.example.org
git init

В момента нашият сайт е напълно чист и, за да се появи нещо на него, първо трябва да свържем тема, темата е просто набор от шаблони и зададени правила, по които се генерира нашият сайт.

Темата, която ще използваме, е Learn, която, според мен, е най-подходяща за сайт с документация.

Отделно внимание заслужава фактът, че не е необходимо да запазваме файловете на темата в репозитория на нашия проект; вместо това можем просто да я свържем, използвайки git submodule:

git submodule add https://github.com/matcornic/hugo-theme-learn themes/learn

По този начин в нашия репозиторий ще се намират само файловете, които са пряко свързани с нашия проект, а свързаната тема ще остане като линк към конкретен репозиторий и комит в него, тоест винаги ще може да бъде изтеглена от оригиналния източник без риск от несъвместими промени.

Нека променим конфигурацията config.toml:

baseURL = "http://docs.example.org/"
languageCode = "en-us"
title = "My Docs Site"
theme = "learn"

На този етап можем да стартираме:

hugo server

И на адрес http://localhost:1313/ можем да проверим нашия новосъздаден сайт, всички промени, направени в директорията, автоматично обновяват отворената страница в браузъра, много удобно!

Нека опитаме да създадем заглавна страница в content/_index.md:

# My docs site

## Welcome to the docs!

You will be very smart :-)

Скриншот на току-що създадената страница

За генериране на сайта е достатъчно да стартираме:

hugo

Съдържанието на директорията public/ ще представлява вашия сайт.
Да, между другото, нека веднага я добавим в .gitignore:

echo /public > .gitignore

Не забравяйте да комитнем нашите промени:

git add .
git commit -m "New site created"

2. Подготовка на Dockerfile

Време е да определим структурата на нашия репозиторий. Обикновено използвам нещо подобно:

.
├── deploy
│   ├── app1
│   └── app2
└── dockerfiles
    ├── image1
    └── image2

• dockerfiles/ съдържа директории с Dockerfiles и всичко необходимо за изграждане на нашите docker-образи.
• deploy/ съдържа директории за деплой на нашите приложения в Kubernetes.

По този начин нашият първи Dockerfile ще създадем по пътя dockerfiles/website/Dockerfile

FROM alpine:3.11 as builder
ARG HUGO_VERSION=0.62.0
RUN wget -O- https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-64bit.tar.gz | tar -xz -C /usr/local/bin
ADD . /src
RUN hugo -s /src

FROM alpine:3.11
RUN apk add --no-cache darkhttpd
COPY --from=builder /src/public /var/www
ENTRYPOINT [ "/usr/bin/darkhttpd" ]
CMD [ "/var/www" ]

Както може да забележите, Dockerfile съдържа два FROM, тази възможност се нарича multi-stage build и позволява изключването на всичко ненужно от финалния docker-образ.
По този начин финалният образ ще съдържа само darkhttpd (лек HTTP-сервер) и public/ съдържанието на нашия статично генериран сайт.

Не забравяйте да комитнем нашите промени:

git add dockerfiles/website
git commit -m "Add Dockerfile for website"

3. Запознаване с kaniko

Като сборщик на docker образи реших да използвам kaniko, тъй като за работата му не е необходим docker демон, а самата сборка може да се извършва на всяка машина и кешът може да се съхранява директно в регистратурата, като по този начин се избягва необходимостта от пълноценен персистентен склад.

За да построите образ, е достатъчно да стартирате контейнера с kaniko executor и да му предадете текущия контекст на сборката, това може да се направи и локално, чрез docker:

docker run -ti --rm 
  -v $PWD:/workspace 
  -v ~/\.docker/config.json:/kaniko/.docker/config.json:ro 
  gcr.io/kaniko-project/executor:v0.15.0 
  --cache 
  --dockerfile=dockerfiles/website/Dockerfile 
  --destination=registry.gitlab.com/kvaps/docs.example.org/website:v0.0.1

Къде registry.gitlab.com/kvaps/docs.example.org/website — името на вашия docker образ, след сборката той ще бъде автоматично качен в docker регистратурата.

Параметър —cache позволява кеширане на слоеве в docker регистратурата, за приведения пример те ще бъдат запазени в registry.gitlab.com/kvaps/docs.example.org/website/cache, но можете да посочите и друг път с помощта на параметъра —cache-repo.

Скриншот на docker-registry

4. Запознаване с qbec

Qbec — е инструмент за разгръщане, който позволява декларативно да описвате манифестите на вашето приложение и да ги разгръщате в Kubernetes. Използването на Jsonnet като основен синтаксис позволява значително опростяване на описанието на различията за няколко среди и почти напълно избягва повторяемостта на кода.

Това може да е особено актуално в случаите, когато трябва да разгръщате приложение в няколко клъстера с различни параметри и искате декларативно да ги опишете в Git.

Qbec също така позволява рендериране на Helm-чарти, предавайки им необходимите параметри и след това да се работи с тях точно като с обикновени манифести, включително възможността за налагане на различни мутации, а това, от своя страна, позволява да се избегне необходимостта от използване на ChartMuseum. Тоест, можете да съхранявате и рендерирате чартове директно от git, където им е и мястото.

Както споменах по-рано, всички разгръщания ще бъдат съхранявани в директорията deploy/:

mkdir deploy
cd deploy

Нека инициализираме нашето първо приложение:

qbec init website
cd website

Сега структурата на нашето приложение изглежда така:

.
├── components
├── environments
│   ├── base.libsonnet
│   └── default.libsonnet
├── params.libsonnet
└── qbec.yaml

Да разгледаме файла qbec.yaml:

apiVersion: qbec.io/v1alpha1
kind: App
metadata:
  name: website
spec:
  environments:
    default:
      defaultNamespace: docs
      server: https://kubernetes.example.org:8443
  vars: {}

Тук ни интересува в предимствени ред spec.environments, qbec вече е създал за нас подразбиращата се среда и е взел адреса на сървъра, както и namespace от нашия текущ kubeconfig.
Сега при деплой в по подразбиране среда, qbec винаги ще деплойва само в указан Kubernetes клъстер и в указан namespace, тоест вие вече няма да трябва да превключвате между контексти и namespaces, за да осъществите деплой.
В случай на необходимост, винаги можете да актуализирате настройките в този файл.

Всички ваши среди са описани в qbec.yaml, и в файла params.libsonnet, където е посочено от къде да се вземат параметрите за тях.

По-нататък виждаме две директории:

• components/ — тук ще се съхраняват всички манифести за нашето приложение, те могат да бъдат описани както в jsonnet, така и с обикновени yaml файлове
• environments/ — тук ще описваме всички променливи (параметри) за нашите среди.

По подразбиране имаме два файла:

• environments/base.libsonnet — той ще съдържа общи параметри за всички среди
• environments/default.libsonnet — съдържа параметри, преопределени за средата по подразбиране

Нека да отворим environments/base.libsonnet и добавим там параметри за нашия първи компонент:

{
  components: {
    website: {
      name: 'example-docs',
      image: 'registry.gitlab.com/kvaps/docs.example.org/website:v0.0.1',
      replicas: 1,
      containerPort: 80,
      servicePort: 80,
      nodeSelector: {},
      tolerations: [],
      ingressClass: 'nginx',
      domain: 'docs.example.org',
    },
  },
}

Създаваме също и нашия първи компонент components/website.jsonnet:

local env = {
  name: std.extVar('qbec.io\/env'),
  namespace: std.extVar('qbec.io\/defaultNs'),
};
local p = import '..\/params.libsonnet';
local params = p.components.website;

[
  {
    apiVersion: 'apps\/v1',
    kind: 'Deployment',
    metadata: {
      labels: { app: params.name },
      name: params.name,
    },
    spec: {
      replicas: params.replicas,
      selector: {
        matchLabels: {
          app: params.name,
        },
      },
      template: {
        metadata: {
          labels: { app: params.name },
        },
        spec: {
          containers: [
            {
              name: 'darkhttpd',
              image: params.image,
              ports: [
                {
                  containerPort: params.containerPort,
                },
              ],
            },
          ],
          nodeSelector: params.nodeSelector,
          tolerations: params.tolerations,
          imagePullSecrets: [{ name: 'regsecret' }],
        },
      },
    },
  },
  {
    apiVersion: 'v1',
    kind: 'Service',
    metadata: {
      labels: { app: params.name },
      name: params.name,
    },
    spec: {
      selector: {
        app: params.name,
      },
      ports: [
        {
          port: params.servicePort,
          targetPort: params.containerPort,
        },
      ],
    },
  },
  {
    apiVersion: 'extensions\/v1beta1',
    kind: 'Ingress',
    metadata: {
      annotations: {
        'kubernetes.io\/ingress.class': params.ingressClass,
      },
      labels: { app: params.name },
      name: params.name,
    },
    spec: {
      rules: [
        {
          host: params.domain,
          http: {
            paths: [
              {
                backend: {
                  serviceName: params.name,
                  servicePort: params.servicePort,
                },
              },
            ],
          },
        },
      ],
    },
  },
]

В този файл описахме три Kubernetes ресурса: Deployment, Услуга и IngressПо желание, можехме да ги изнесем в различни компоненти, но на този етап ни стига и един.

Синтаксис jsonnet много наподобява обикновен json, в принципе обикновеният json вече е валиден jsonnet, така че в началото вероятно ще бъде по-лесно да ползвате онлайн услуги като yaml2json за да конвертирате познатия ви yaml в json, или, ако вашите компоненти не съдържат никакви променливи, спокойно можете да ги опишете в обикновен yaml.

При работа с jsonnet силам ви да инсталирате плъгин за вашия редактор.

Например, за vim има плъгин vim-jsonnet, който включва подсветка на синтаксиса и автоматично изпълнява jsonnet fmt при всяко запазване (изисква инсталиран jsonnet).

Всичко е готово, сега можем да започнем деплой:

За да видим какво сме получили, изпълняваме:

qbec show default

На изхода ще видите рендерирани yaml манифести, които ще бъдат приложени в кластера default.

Страхотно, сега прилагаме:

qbec apply default

На изхода винаги ще видите какво ще се извърши във вашия кластер, qbec ще ви помоли да се съгласите с промените, като напишете y можете да потвърдите намерението си.

Готово! Сега нашето приложение е разположено!

Ако направите промени, винаги можете да изпълните:

qbec diff default

за да видите как тези промени ще се отразят на текущото разполагане

Не забравяйте да комитнем нашите промени:

cd ..\/..\ngit add deploy\/website\ngit commit -m "Добави разполагане за уебсайта"

5. Пробваме Gitlab-runner с Kubernetes-executor

До неотдавна използвах само обикновен gitlab-runner на предварително подготвена машина (LXC-контейнер) с shell- или docker-executor. Първоначално имахме няколко такива раннера глобално определени в нашия GitLab. Те събираха docker-образи за всички проекти.

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

За щастие, това не е никакъв проблем, тъй като сега ще разполагаме gitlab-runner директно като част от нашия проект, направо в Kubernetes.

GitLab предоставя готов helm-чарт за разполагане на gitlab-runner в Kubernetes. Така че всичко, от което имате нужда, е да разберете registration token за нашия проект в Settings —> CI \/ CD —> Runners и да го предадете на helm:

helm repo add gitlab https:\/\/charts.gitlab.io\n\nhelm install gitlab-runner \n  --set gitlabUrl=https:\/\/gitlab.com \n  --set runnerRegistrationToken=yga8y-jdCusVDn_t4Wxc \n  --set rbac.create=true \n  gitlab\/gitlab-runner

Където:

• https://gitlab.com — адресът на вашия GitLab-сървър.
• yga8y-jdCusVDn_t4Wxc — registration token за вашия проект.
• rbac.create=true — предоставя на раннера необходимото количество привилегии, за да може да създава подове за изпълнение на задачите ни с помощта на kubernetes-executor.

Ако всичко е направено правилно, трябва да видите регистриран раннер в секцията Runners, в настройките на вашия проект.

Скриншот на добавения раннер

Толкова ли е лесно? — да, така е! Повече никакви притеснения с ръчната регистрация на раннерите, от този момент нататък, раннерите ще бъдат създавани и унищожавани автоматично.

6. Разполагане на Helm-чарти с QBEC

Тъй като решихме да считаме gitlab-runner част от нашия проект, време е да го опишем в нашето Git-репозиторий.

Можехме да го опишем като отделен компонент website, но в бъдеще планираме да разполагаме различни копия website много често, в отличие gitlab-runner, който ще бъде разположен само веднъж на всеки Kubernetes-клъстер. Така че да инициализираме отделно приложение за него:

cd deploy\nqbec init gitlab-runner\ncd gitlab-runner

Този път няма да описваме Kubernetes-съществата на ръка, а ще използваме готов Helm чарт. Едно от предимствата на qbec е възможността да рендерираме Helm чартове директно от Git репозиторий.

Нека го свържем, използвайки git submodule:

git submodule add https://gitlab.com/gitlab-org/charts/gitlab-runner vendor/gitlab-runner

Сега директорията vendor/gitlab-runner съдържа репозитория с чарт за gitlab-runner.

По подобен начин можем да свързваме и други репозитории, например и целия репозиторий с официални чарпове. https://github.com/helm/charts

Нека опишем компонента components/gitlab-runner.jsonnet:

local env = {
  name: std.extVar('qbec.io/env'),
  namespace: std.extVar('qbec.io/defaultNs'),
};
local p = import '.. /params.libsonnet';
local params = p.components.gitlabRunner;

std.native('expandHelmTemplate')(
  '.. /vendor/gitlab-runner',
  params.values,
  {
    nameTemplate: params.name,
    namespace: env.namespace,
    thisFile: std.thisFile,
    verbose: true,
  }
)

Първият аргумент на expandHelmTemplate предаваме пътя до чарта, след това params.values, който ще вземем от параметрите на околната среда, следва обект с

• nameTemplate — името на релиза
• namespace — неймспейсът, предаван на Helm
• thisFile — задължителен параметър, предаващ пътя до текущия файл
• verbose — показва командата helm template с всички аргументи при рендериране на чарта.

Сега нека опишем параметрите за нашия компонент в environments/base.libsonnet:

local secrets = import '.. /secrets/base.libsonnet';

{
  components: {
    gitlabRunner: {
      name: 'gitlab-runner',
      values: {
        gitlabUrl: 'https://gitlab.com/',
        rbac: {
          create: true,
        },
        runnerRegistrationToken: secrets.runnerRegistrationToken,
      },
    },
  },
}

Обърнете внимание runnerRegistrationToken взимаме от външния файл secrets/base.libsonnet, нека го създадем:

{
  runnerRegistrationToken: 'yga8y-jdCusVDn_t4Wxc',
}

Нека проверим дали всичко работи:

qbec show default

ако всичко е наред, можем да изтрием нашия предишен релиз, деплоизиран чрез Helm:

helm uninstall gitlab-runner

и да го деплоизираме отново, но вече чрез qbec:

qbec apply default

7. Запознаване с git-crypt

Git-crypt е инструмент, който позволява настройването на прозрачно криптиране за вашия репозиторий.

В момента структурата на нашата директория за gitlab-runner изглежда така:

.
├── components
│   ├── gitlab-runner.jsonnet
├── environments
│   ├── base.libsonnet
│   └── default.libsonnet
├── params.libsonnet
├── qbec.yaml
├── secrets
│   └── base.libsonnet
└── vendor
    └── gitlab-runner (submodule)

Но съхранението на тайни в Git не е безопасно, нали? Така че трябва да ги криптираме правилно.

Обикновено за една единствена променлива това не винаги има смисъл. Можете да предавате тайни в qbec и чрез променливи на околната среда на вашата CI система.
Но е важно да се отбележи, че има и по-сложни проекти, които могат да съдържат значително повече секрети, и предаването им всичките чрез променливи на средата би било крайно затруднително.

Освен това, в такъв случай нямаше да мога да ви разкажа за този чудесен инструмент, наречен git-crypt.

git-crypt който е удобен, защото позволява да съхраните цялата история на секретите, както и да сравнявате, обединявате и разрешавате конфликти, както сме свикнали да правим с Git.

Първото нещо след инсталирането git-crypt е да генерираме ключове за нашето хранилище:

git crypt init

Ако имате PGP ключ, можете веднага да се добавите като сътрудник на този проект:

git-crypt add-gpg-user kvapss@gmail.com

По този начин винаги ще можете да декриптирате това хранилище, използвайки своя частен ключ.

Ако нямате PGP ключ и не предвиждате такъв, можете да поемете по друг път и да експортирате ключа на проекта:

git crypt export-key /path/to/keyfile

Така всеки, който притежава експортирания keyfile ще може да декриптира вашето хранилище.

Време е да настроим нашия първи секрет.
Напомням, че все още сме в директорията deploy/gitlab-runner/, където имаме директория secrets/, нека да криптираме всичките файлове в нея, за целта ще създадем файл secrets/.gitattributes с такова съдържание:

* filter=git-crypt diff=git-crypt
.gitattributes !filter !diff

Както е видно от съдържанието, всички файлове по маска * ще преминават през git-crypt, с изключение на самия .gitattributes

Можем да проверим това, като стартираме:

git crypt status -e

На изхода ще получим списък на всички файлове в хранилището, за които е активирано криптиране.

Вот и всичко, сега можем смело да комитнем нашите промени:

cd ../../
git add .
git commit -m "Add deploy for gitlab-runner"

За да заключите хранилището, е достатъчно да изпълните:

git crypt lock

и веднага всички криптирани файлове ще се превърнат в бинарно нещо, което ще бъде невъзможно да се прочете.
За да декриптирате хранилището, изпълнете:

git crypt unlock

8. Създаваме toolbox-образ

Toolbox-образ е образ с всички инструменти, които ще използваме за разполагане на нашия проект. Той ще бъде използван от gitlab-ранера за изпълнение на типични задачи за разполагане.

Тук всичко е просто, създаваме нов dockerfiles/toolbox/Dockerfile с такова съдържание:

ОТ alpine:3.11

RUN apk add --no-cache git git-crypt

RUN QBEC_VER=0.10.3 
 && wget -O- https://github.com/splunk/qbec/releases/download/v${QBEC_VER}/qbec-linux-amd64.tar.gz 
     | tar -C /tmp -xzf - 
 && mv /tmp/qbec /tmp/jsonnet-qbec /usr/local/bin/

RUN KUBECTL_VER=1.17.0 
 && wget -O /usr/local/bin/kubectl 
      https://storage.googleapis.com/kubernetes-release/release/v${KUBECTL_VER}/bin/linux/amd64/kubectl 
 && chmod +x /usr/local/bin/kubectl

RUN HELM_VER=3.0.2 
 && wget -O- https://get.helm.sh/helm-v${HELM_VER}-linux-amd64.tar.gz 
     | tar -C /tmp -zxf - 
 && mv /tmp/linux-amd64/helm /usr/local/bin/helm

Как можете заметить, в этом образе мы устанавливаем все утилиты, которые использовались для развертывания нашего приложения. Нам не нужен здесь разве что kubectl, но возможно вы захотите поэкспериментировать с ним на этапе настройки пайплайна.

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

Для этого перейдем в директорию с gitlab-runner’ом:

cd deploy/gitlab-runner

и добавим новый компонент components/rbac.jsonnet:

local env = {
  name: std.extVar('qbec.io/env'),
  namespace: std.extVar('qbec.io/defaultNs'),
};
local p = import '../params.libsonnet';
local params = p.components.rbac;

[
  {
    apiVersion: 'v1',
    kind: 'ServiceAccount',
    metadata: {
      labels: {
        app: params.name,
      },
      name: params.name,
    },
  },
  {
    apiVersion: 'rbac.authorization.k8s.io/v1',
    kind: 'Role',
    metadata: {
      labels: {
        app: params.name,
      },
      name: params.name,
    },
    rules: [
      {
        apiGroups: [
          '*',
        ],
        resources: [
          '*',
        ],
        verbs: [
          '*',
        ],
      },
    ],
  },
  {
    apiVersion: 'rbac.authorization.k8s.io/v1',
    kind: 'RoleBinding',
    metadata: {
      labels: {
        app: params.name,
      },
      name: params.name,
    },
    roleRef: {
      apiGroup: 'rbac.authorization.k8s.io',
      kind: 'Role',
      name: params.name,
    },
    subjects: [
      {
        kind: 'ServiceAccount',
        name: params.name,
        namespace: env.namespace,
      },
    ],
  },
]

Также опишем новые параметры в environments/base.libsonnet, который теперь выглядит так:

local secrets = import '../secrets/base.libsonnet';

{
  components: {
    gitlabRunner: {
      name: 'gitlab-runner',
      values: {
        gitlabUrl: 'https://gitlab.com/',
        rbac: {
          create: true,
        },
        runnerRegistrationToken: secrets.runnerRegistrationToken,
        runners: {
          serviceAccountName: $.components.rbac.name,
          image: 'registry.gitlab.com/kvaps/docs.example.org/toolbox:v0.0.1',
        },
      },
    },
    rbac: {
      name: 'gitlab-runner-deploy',
    },
  },
}

Обърнете внимание $.components.rbac.name ссылается на name для компонента rbac

Давайте проверим, что изменилось:

qbec diff default

и применим наши изменения в Kubernetes:

qbec apply default

Также не забываем закоммитить наши изменения в git:

cd ../..
git add dockerfiles/toolbox
git commit -m "Добавить Dockerfile для toolbox"
git add deploy/gitlab-runner
git commit -m "Настроить gitlab-runner для использования toolbox"

9. Наш первый пайплайн и сборка образов по тегам

В корне проекта мы создадим .gitlab-ci.yml с такова съдържание:

.build_docker_image:
  stage: build
  image:
    name: gcr.io/kaniko-project/executor:debug-v0.15.0
    entrypoint: [""]
  before_script:
    - echo "{"auths":{"$CI_REGISTRY":{"username":"$CI_REGISTRY_USER","password":"$CI_REGISTRY_PASSWORD"}}}" > /kaniko/.docker/config.json

build_toolbox:
  extends: .build_docker_image
  script:
    - /kaniko/executor --cache --context $CI_PROJECT_DIR/dockerfiles/toolbox --dockerfile $CI_PROJECT_DIR/dockerfiles/toolbox/Dockerfile --destination $CI_REGISTRY_IMAGE/toolbox:$CI_COMMIT_TAG
  only:
    refs:
      - tags

build_website:
  extends: .build_docker_image
  variables:
    GIT_SUBMODULE_STRATEGY: normal
  script:
    - /kaniko/executor --cache --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/dockerfiles/website/Dockerfile --destination $CI_REGISTRY_IMAGE/website:$CI_COMMIT_TAG
  only:
    refs:
      - tags

Обърнете внимание, ние използваме GIT_SUBMODULE_STRATEGY: normal за тези джобове, където е необходимо явно инициализиране на сабмодулите преди изпълнението.

Не забравяйте да комитнем нашите промени:

git add .gitlab-ci.yml
git commit -m "Автоматизиране на Docker строеж"

Мисля, че можем смело да наречем това версия v0.0.1 и да поставим таг:

git tag v0.0.1

Ще поставяме тагове всеки път, когато трябва да пуснем нова версия. Таговете в Docker изображенията ще бъдат свързани с Git таговете. Всеки push с нов таг ще инициализира строеж на изображения с този таг.

Изпълняваме git push —tags, и ще видим нашия първи пайплайн:

Снимка на първия пайплайн

Важно е да обърнете внимание, че строежът по тагове е подходящ за строеж на Docker изображения, но не е подходящ за деплой на приложение в Kubernetes. Понеже нови тагове могат да бъдат назначавани и за стари комити, в този случай инициализацията на пайплайна за тях ще доведе до деплой на стара версия.

За да решим този проблем, обикновено строежът на Docker изображенията е свързан с таговете, а деплой на приложението с клон master, в който са зададени версиите на събраните изображения. Само в този случай ще можете да инициализирате rollback с прост revert master-клона.

10. Автоматизация на деплоя

За да може Gitlab-runner да разкодира нашите тайни, ще трябва да експортираме ключа на репозитория и да го добавим в променливите на средата на нашата CI:

git crypt export-key /tmp/docs-repo.key
base64 -w0 /tmp/docs-repo.key; echo

получената строка ще запазим в Gitlab, затова ще отидем в настройките на нашия проект:
Настройки → CI / CD → Променливи

И ще създадем нова променлива:

Type
Ключ
Стойност
Защитена
Скривана
Обхват

File
GITCRYPT_KEY
<your string>
истинно (по време на обучението може и неверно)
истинно
Всички среди

Снимка на добавената променлива

Сега ще обновим нашия .gitlab-ci.yml добавяйки в него:

.deploy_qbec_app:
  stage: deploy
  only:
    refs:
      - master

deploy_gitlab_runner:
  extends: .deploy_qbec_app
  variables:
    GIT_SUBMODULE_STRATEGY: normal
  before_script:
    - base64 -d "$GITCRYPT_KEY" | git-crypt unlock -
  script:
    - qbec apply default --root deploy/gitlab-runner --force:k8s-context __incluster__ --wait --yes

deploy_website:
  extends: .deploy_qbec_app
  script:
    - qbec apply default --root deploy/website --force:k8s-context __incluster__ --wait --yes

Тук сме използвали няколко нови опции за qbec:

• —root some/app — позволява да се определи директорията на конкретно приложение
• —force:k8s-context __incluster__ — това е магическа променлива, която казва, че деплойментът ще се случи в същия клъстер, в който е стартиран gitlab-runner. Това е необходимо, защото в противен случай qbec ще се опита да намери подходящ Kubernetes сървър в kubeconfig-а ви.
• —wait — принуждава qbec да изчака, докато създадените ресурси преминат в състояние Ready и само след това завършва с успешен exit-code.
• —yes — просто деактивира интерактивния шел. Сигурни ли сте? при деплоймента.

Не забравяйте да комитнем нашите промени:

git add .gitlab-ci.yml
git commit -m "Автоматизиране на деплой"

И след това git push ще видим как приложенията ни са били деплоинирани:

Скриншот на втория пайплайн

11. Артефакти и сборка при push в master

Обикновено гореспоменатите стъпки са напълно достатъчни за изграждане и доставка на почти всяка микрослужба, но не искаме да слагаме таг всеки път, когато трябва да обновим сайта. Затова ще поемем по-динамичен маршрут и ще настроим деплой по digest в master-ветката.

Идеята е проста: образът на нашия website ще бъде пересъбиран всеки път при push в master, а след това автоматично ще се деплойва в Kubernetes.

Нека актуализираме тези две задачи в нашия .gitlab-ci.yml:

build_website:
  extends: .build_docker_image
  variables:
    GIT_SUBMODULE_STRATEGY: normal
  script:
    - mkdir -p $CI_PROJECT_DIR/artifacts
    - /kaniko/executor --cache --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/dockerfiles/website/Dockerfile --destination $CI_REGISTRY_IMAGE/website:$CI_COMMIT_REF_NAME --digest-file $CI_PROJECT_DIR/artifacts/website.digest
  artifacts:
    paths:
      - artifacts/
  only:
    refs:
      - master
      - tags

deploy_website:
  extends: .deploy_qbec_app
  script:
    - DIGEST="$(cat artifacts/website.digest)"
    - qbec apply default --root deploy/website --force:k8s-context __incluster__ --wait --yes --vm:ext-str digest="$DIGEST"

Обърнете внимание, добавихме бранша master к refs за задачата build_website и сега използваме $CI_COMMIT_REF_NAME вместо $CI_COMMIT_TAG, така че се откъсваме от таговете в Git и сега ще пускаме образа с името на бранша на комита, инициирал пайплайна. Важно е да се отбележи, че това също ще работи и с тагове, което ще ни позволи да запазваме снимки на сайта с определена версия в docker-registry.

Когато името на docker-тага за новата версия на сайта може да остане едно и също, все пак трябва да описваме промените за Kubernetes, в противен случай той просто няма да извърши повторно разгръщане на приложението от новия образ, тъй като няма да забележи никакви промени в манифеста на разгръщането.

Опция —vm:ext-str digest=" $DIGEST " за qbec — позволява предаване на външна променлива в jsonnet. Искаме, при всяко издание на нашето приложение, то да се разгръща в кластера. Да използваме име на таг, което може да остане едно и също, вече не можем, тъй като трябва да се свържем с конкретна версия на образа и да задействаме разгръщането при нейното изменение.

Тук ще ни помогне възможността на Kaniko да запази digest на образа в файл (опция —digest-file)
След това този файл ще предадем и прочетем в момента на разгръщането.

Актуализираме параметрите за нашия deploy/website/environments/base.libsonnet който сега ще изглежда така:

{
  components: {
    website: {
      name: 'example-docs',
      image: 'registry.gitlab.com/kvaps/docs.example.org/website@' + std.extVar('digest'),
      replicas: 1,
      containerPort: 80,
      servicePort: 80,
      nodeSelector: {},
      tolerations: [],
      ingressClass: 'nginx',
      domain: 'docs.example.org',
    },
  },
}

Готово, сега всеки комит в master инициализира изграждането на docker-образа за website, а след това неговото разгръщане в Kubernetes.

Не забравяйте да комитнем нашите промени:

git add .
git commit -m "Configure dynamic build"

Проверяваме, след git push трябва да видим нещо подобно:

Скриншот на пайплайна за master

В принципе не е необходимо да разгръщаме gitlab-runner при всяко push, стига, разбира се, нищо да не се е променило в неговата конфигурация, нека да поправим това в .gitlab-ci.yml:

deploy_gitlab_runner:
  extends: .deploy_qbec_app
  variables:
    GIT_SUBMODULE_STRATEGY: normal
  before_script:
    - base64 -d "$GITCRYPT_KEY" | git-crypt unlock -
  script:
    - qbec apply default --root deploy/gitlab-runner --force:k8s-context __incluster__ --wait --yes
  only:
    changes:
      - deploy/gitlab-runner/**/*

changes ще следи за изменения в deploy/gitlab-runner/ и ще задейства нашата работа само при наличие на такива

Не забравяйте да комитнем нашите промени:

git add .gitlab-ci.yml
git commit -m "Reduce gitlab-runner deploy"

git push, така е по-добре:

Скриншот на актуализирания пайплайн

12. Динамични среди

Време е да разнообразим нашия пайплайн с динамични среди.

Първо актуализираме работата build_website в нашия .gitlab-ci.yml, премахвайки блока only, което ще накара Gitlab да я задейства при всеки комит в всяка клон:

build_website:
  extends: .build_docker_image
  variables:
    GIT_SUBMODULE_STRATEGY: normal
  script:
    - mkdir -p $CI_PROJECT_DIR/artifacts
    - /kaniko/executor --cache --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/dockerfiles/website/Dockerfile --destination $CI_REGISTRY_IMAGE/website:$CI_COMMIT_REF_NAME --digest-file $CI_PROJECT_DIR/artifacts/website.digest
  artifacts:
    paths:
      - artifacts/

След това актуализираме работата deploy_website, ще добавим там блок среда:

deploy_website:
  extends: .deploy_qbec_app
  environment:
    name: prod
    url: https://docs.example.org
  script:
    - DIGEST="$(cat artifacts/website.digest)"
    - qbec apply default --root deploy/website --force:k8s-context __incluster__ --wait --yes --vm:ext-str digest="$DIGEST"

Това ще позволи на Gitlab да асоциира работното място с prod окружението и да извежда правилната връзка за него.

Сега добавим още две работни места:

deploy_website:
  extends: .deploy_qbec_app
  environment:
    name: prod
    url: https://docs.example.org
  script:
    - DIGEST="$(cat artifacts/website.digest)"
    - qbec apply default --root deploy/website --force:k8s-context __incluster__ --wait --yes --vm:ext-str digest="$DIGEST"

deploy_review:
  extends: .deploy_qbec_app
  environment:
    name: review/$CI_COMMIT_REF_NAME
    url: http://$CI_ENVIRONMENT_SLUG.docs.example.org
    on_stop: stop_review
  script:
    - DIGEST="$(cat artifacts/website.digest)"
    - qbec apply review --root deploy/website --force:k8s-context __incluster__ --wait --yes --vm:ext-str digest="$DIGEST" --vm:ext-str subdomain="$CI_ENVIRONMENT_SLUG" --app-tag "$CI_ENVIRONMENT_SLUG"
  only:
    refs:
    - branches
  except:
    refs:
      - master

stop_review:
  extends: .deploy_qbec_app
  environment:
    name: review/$CI_COMMIT_REF_NAME
    action: stop
  stage: deploy
  before_script:
    - git clone "$CI_REPOSITORY_URL" master
    - cd master
  script:
    - qbec delete review --root deploy/website --force:k8s-context __incluster__ --yes --vm:ext-str digest="$DIGEST" --vm:ext-str subdomain="$CI_ENVIRONMENT_SLUG" --app-tag "$CI_ENVIRONMENT_SLUG"
  variables:
    GIT_STRATEGY: none
  only:
    refs:
    - branches
  except:
    refs:
      - master
  when: manual

Те ще бъдат стартирани при push в каквито и да е клонове освен master и ще деплоят прегледна версия на сайта.

Виждаме нова опция за qbec: —app-tag — тя позволява да се етикетират деплоитираните версии на приложението и да се работи само в рамките на тази таг, когато се създават и унищожават ресурси в Kubernetes qbec ще оперира само с тях.
По този начин можем да не създаваме отделно окружение за всяко ревю, а просто да повторно използваме същото.

Тук също използваме qbec apply review, вместо qbec apply default — това точно е моментът, когато ще се опитаме да опишем разликите за нашите среди (review и default):

Добавим review окружение в deploy/website/qbec.yaml

spec:
  environments:
    review:
      defaultNamespace: docs
      server: https://kubernetes.example.org:8443

След това ще го обявим в deploy/website/params.libsonnet:

local env = std.extVar('qbec.io/env');
local paramsMap = {
  _: import './environments/base.libsonnet',
  default: import './environments/default.libsonnet',
  review: import './environments/review.libsonnet',
};

if std.objectHas(paramsMap, env) then paramsMap[env] else error 'environment ' + env + ' not defined in ' + std.thisFile

И ще запишем персонализирани параметри за него в deploy/website/environments/review.libsonnet:

// this file has the param overrides for the default environment
local base = import './base.libsonnet';
local slug = std.extVar('qbec.io/tag');
local subdomain = std.extVar('subdomain');

base {
  components+: {
    website+: {
      name: 'example-docs-' + slug,
      domain: subdomain + '.docs.example.org',
    },
  },
}

Нека също така да се вгледаме по-внимателно в работното място stop_review, то ще сработва при изтриване на клон и за да не се опитва gitlab да направи checkout на него, се използва GIT_STRATEGY: none, след това клонираме master-клона и премахваме прегледа през него.
Малко сложно, но не съм намерил по-красив начин досега.
Алтернативният вариант може да бъде деплоя на всеки преглед в отделно пространство, което винаги може да бъде премахнато изцяло.

Не забравяйте да комитнем нашите промени:

git add .
git commit -m "Активиране на автоматичен преглед"

git push, git checkout -b тест, git push origin тест, проверяваме:

Скриншот на създадените среди в Gitlab

Всичко работи? — отлично, изтриваме нашия тестови клон: git checkout master, git push origin :тест, проверяваме дали задачите за премахване на средата са изпълнени без грешки.

Тук веднага искам да уточня, че всякакви разработчици в проекта могат да създават клони, те също могат да променят .gitlab-ci.yml файла и да получат достъп до секретни променливи.
Затова настоателно се препоръчва да разрешите тяхното използване само за защитени клони, например в master, или да създадете отделен набор от променливи за всяка среда.

13. Приложения за преглед

Прегледни приложения това е възможността на GitLab, която позволява за всеки файл в репозиторият да добавите бутон за бързо преглеждане в разположената среда.

За да се появят тези бутони, е необходимо да се създаде файл .gitlab/route-map.yml и да се опишат в него всички трансформации на пътищата, в нашия случай това ще бъде много просто:

# Indices
- source: /content/(.+?)_index.(md|html)/ 
  public: '1'

# Pages
- source: /content/(.+?).(md|html)/ 
  public: '1/'

Не забравяйте да комитнем нашите промени:

git add .gitlab/
git commit -m "Активиране на приложения за преглед"

git push, и проверяваме:

Скриншот на бутона Приложение за преглед

Задачата е завършена!

Изходния код на проекта:

• в Gitlab: https://gitlab.com/kvaps/docs.example.org
• в GitHub: https://github.com/kvaps/docs.example.org

Благодаря за вниманието, надявам се да ви е харесало

Източник: habr.com