From 79d6f811e1a3bc37f3debd8ccc014bfb5f086028 Mon Sep 17 00:00:00 2001 From: Timofey Kirillov Date: Tue, 13 Dec 2022 19:59:33 +0300 Subject: [PATCH] feat(docs): build chapter: overview and configuration articles (lang:ru) Also added new articles into sidebar for lang:ru and lang:en. Translation to lang:en will be in separate PR. Signed-off-by: Timofey Kirillov --- docs/_data/sidebars/_documentation.yml | 12 + docs/pages_en/usage/build_draft/images.md | 2 +- docs/pages_en/usage/build_draft/overview.md | 2 +- docs/pages_ru/usage/build_draft/images.md | 354 +++++++++++++++++++- docs/pages_ru/usage/build_draft/overview.md | 19 +- 5 files changed, 385 insertions(+), 4 deletions(-) diff --git a/docs/_data/sidebars/_documentation.yml b/docs/_data/sidebars/_documentation.yml index 8156d6d0ac..6adb1d7a5c 100644 --- a/docs/_data/sidebars/_documentation.yml +++ b/docs/_data/sidebars/_documentation.yml @@ -17,6 +17,12 @@ entries: - title: Build f: + - title: Overview (NEW) + url: /usage/build_draft/overview.html + + - title: Images configuration (NEW) + url: /usage/build_draft/images.html + - title: Build process url: /usage/build/build_process.html @@ -208,6 +214,12 @@ entries: - title: Сборка f: + - title: Обзор (НОВИНКА) + url: /usage/build_draft/overview.html + + - title: Конфигурация образов (НОВИНКА) + url: /usage/build_draft/images.html + - title: Процесс сборки url: /usage/build/build_process.html diff --git a/docs/pages_en/usage/build_draft/images.md b/docs/pages_en/usage/build_draft/images.md index 45c3b9f083..039ca924d2 100644 --- a/docs/pages_en/usage/build_draft/images.md +++ b/docs/pages_en/usage/build_draft/images.md @@ -3,4 +3,4 @@ title: Images configuration permalink: usage/build_draft/images.html --- - + diff --git a/docs/pages_en/usage/build_draft/overview.md b/docs/pages_en/usage/build_draft/overview.md index c4df5cc4e9..e917c84781 100644 --- a/docs/pages_en/usage/build_draft/overview.md +++ b/docs/pages_en/usage/build_draft/overview.md @@ -3,4 +3,4 @@ title: Overview permalink: usage/build_draft/overview.html --- - + diff --git a/docs/pages_ru/usage/build_draft/images.md b/docs/pages_ru/usage/build_draft/images.md index 53b0e6438c..3da652b311 100644 --- a/docs/pages_ru/usage/build_draft/images.md +++ b/docs/pages_ru/usage/build_draft/images.md @@ -3,4 +3,356 @@ title: Конфигурация образов permalink: usage/build_draft/images.html --- - + + +Чтобы включить сборку своих образов требуется добавить описание образов в werf.yaml проекта. Каждый образ добавляется директивой `image` с указанием имени образа: + +```yaml +image: frontend +--- +image: backend +--- +image: database +``` + +Имя образа — это короткое символьное имя, на которое мы будем ссылаться в других местах конфигурации и при вызове команд werf. Например, когда нам потребуется либо получить полное имя образа опубликованного в container registry, либо при запуске команд внутри собранного образа через `werf kube-run` и т.п. Если в файле конфигурации описывается более одного образа, то **каждый образ** должен иметь собственное имя. + +Далее для каждого образа в `werf.yaml` необходимо определить сборочные инструкции [с помощью Dockerfile](#сборщик-dockerfile) или [stapel](#сборщик-stapel). + +## Сборщик Dockerfile + + + +Для описания сборочных инструкций образа поддерживается стандартный Dockerfile. Следующие ресурсы помогут написать Dockerfile: + +* [Dockerfile Reference](https://docs.docker.com/engine/reference/builder/). +* [Best practices for writing Dockerfiles](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/). + +Минимальная конфигурация для сборки Dockerfile выглядит следующим образом: + +```Dockerfile +# Dockerfile +FROM node +WORKDIR /app +COPY package*.json /app/ +RUN npm ci +COPY . . +CMD ["node", "server.js"] +``` + +```yaml +# werf.yaml +image: backend +dockerfile: Dockerfile +``` + +Также, вы можете описывать несколько целевых образов из разных стадий одного и того же Dockerfile: + +```Dockerfile +# Dockerfile + +FROM node as backend +WORKDIR /app +COPY package*.json /app/ +RUN npm ci +COPY . . +CMD ["node", "server.js"] + +FROM python as frontend +WORKDIR /app +COPY requirements.txt /app/ +RUN pip install -r requirements.txt +COPY . . +CMD ["gunicorn", "app:app", "-b", "0.0.0.0:80", "--log-file", "-"] +``` + +```yaml +# werf.yaml +image: backend +dockerfile: Dockerfile +target: backend +--- +image: frontend +dockerfile: Dockerfile +target: frontend +``` + +И конечно, вы можете описывать образы, основанные на разных Dockerfile: + +```yaml +# werf.yaml +image: backend +dockerfile: dockerfiles/Dockerfile.backend +--- +image: frontend +dockerfile: dockerfiles/Dockerfile.frontend +``` + +Чтобы указать сборочный контекст используется директива `context`. **Важно:** в этом случае путь до dockerfile указывается относительно директории контекста: + +```yaml +image: docs +context: docs +dockerfile: Dockerfile +--- +image: service +context: service +dockerfile: Dockerfile +``` + +— для образа `docs` будет использоваться dockerfile по пути `docs/Dockerfile`, а для `service` — `service/Dockerfile`. + +### contextAddFiles + +По умолчанию контекст сборки Dockerfile-образа включает только файлы из текущего коммита репозитория проекта. Файлы не добавленные в git или некоммитнутые изменения не попадают в сборочный контекст. Такая логика действует в соответствии с настройками [гитерминизма]({{ "/usage/project_configuration/giterminism.html" | true_relative_url }}) по умолчанию. + +Чтобы добавить в сборочный контекст файлы, которые не хранятся в git, нужна директива `contextAddFiles` в `werf.yaml` а также нужно разрешить использование директивы `contextAddFiles` в `werf-giterminism.yaml` (подробнее [про гитерминизм]({{ "/usage/project_configuration/giterminism.html#contextaddfiles" | true_relative_url }})): + +```yaml +# werf.yaml +image: app +context: app +contextAddFiles: +- file1 +- dir1/ +- dir2/file2.out +``` + +```yaml +# werf-giterminism.yaml +giterminismConfigVersion: 1 +config: + dockerfile: + allowContextAddFiles: + - file1 + - dir1/ + - dir2/file2.out +``` + +В данной конфигурации контекст сборки будет состоять из следующих файлов: + +- `app/**/*` из текущего коммита репозитория проекта; +- Файлы `app/file1`, `app/dir2/file2.out` и директория `dir1`, которые находятся в директории проекта. + +## Сборщик Stapel + +В werf встроен альтернативный синтаксис описания сборочных инструкций называемый Stapel, который даёт следующие возможности: + +1. Удобство поддержки и параметризации комплексной конфигурации, возможность переиспользовать общие куски и генерировать конфигурацию однотипных образов за счет использования YAML-формата и шаблонизации. +2. Специальные инструкции для интеграции с git, позволяющие задействовать инкрементальную пересборку с учетом истории git-репозитория. +3. Наследование образов и импортирование файлов из образов (аналог multi-stage для Dockerfile). +4. Запуск произвольных сборочных инструкций, опции монтирования директорий и другие инструменты продвинутого уровня для сборки образов. +5. Более эффективная механика кеширования слоёв (сейчас в pre-альфа аналогичная схема поддерживается и для слоёв Dockerfile при сборке с Buildah). + + + +Пример минимальной конфигурации stapel образа в werf.yaml: + +```yaml +image: app +from: ubuntu:22.04 +``` + +Добавим исходники из git в наш образ: + +```yaml +image: app +from: ubuntu:22.04 +git: +- add: / + to: /app +``` + +Доступно 4 стадии для описания произвольных shell-инструкций, а также директива `git.stageDependencies` для настройки триггеров пересборки этих стадий при изменении соответствующих стадий (см. [подробнее]({{ "/usage/build/building_images_with_stapel/assembly_instructions.html#зависимость-от-изменений-в-git-репозитории" | true_relative_url }})): + +```yaml +image: app +from: ubuntu:22.04 +git: +- add: / + to: /app + stageDependencies: + install: + - package-lock.json + - Gemfile.lock + beforeSetup: + - app/webpack/ + - app/assets/ + setup: + - config/templates/ +shell: + beforeInstall: + - apt update -q + - apt install -y libmysqlclient-dev mysql-client g++ + install: + - bundle install + - npm install + beforeSetup: + - bundle exec rails assets:precompile + setup: + - rake generate:configs +``` + +Поддерживаются вспомогательные образы, из которых можно импортировать файлы в целевой образ (аналог `COPY --from=STAGE` в multi-stage Dockerfile), а также golang-шаблонизация: + +```yaml +{{ $_ := set . "BaseImage" "ubuntu:22.04" }} + +{{ define "package:build-tools" }} + - apt update -q + - apt install -y gcc g++ build-essential make +{{ end }} + +image: builder +from: {{ .BaseImage }} +shell: + beforeInstall: +{{ include "package:build-tools" }} + install: + - cd /app + - make build +--- +image: app +from: alpine:latest +import: +- image: builder + add: /app/build/app + to: /usr/local/bin/app + after: install +``` + +Подробная документация по написанию доступна [в разделе stapel]({{ "usage/build/building_images_with_stapel/base_image.html" | true_relative_url }}). + +## Наследование образов и импортирование файлов + +При написании одного Dockerfile в нашем распоряжении имеется механизм multi-stage. Он позволяет объявить в Dockerfile отдельный образ-стадию и использовать её в качестве базового для другого образа, либо скопировать из неё отдельные файлы. + +werf позволяет реализовать это не только в рамках одного Dockerfile, но и между произвольными образами, определяемыми в `werf.yaml`, в том числе собираемыми из разных Dockerfile-ов, либо собираемыми сборщиком Stapel. Всю оркестрацию и выстраивание зависимостей werf возьмёт на себя и произведёт сборку за один шаг (вызов `werf build`). + +Пример использования образа собранного из `base.Dockerfile` в качестве базового для образа из `Dockerfile`: + +```Dockerfile +# base.Dockerfile +FROM ubuntu:22.04 +RUN apt update -q && apt install -y gcc g++ build-essential make curl python3 +``` + +```Dockerfile +# Dockerfile +ARG BASE_IMAGE +FROM ${BASE_IMAGE} +WORKDIR /app +COPY . . +CMD [ "/app/server", "start" ] +``` + +```yaml +# werf.yaml +image: base +dockerfile: base.Dockerfile +--- +image: app +dockerfile: Dockerfile +dependencies: +- image: base + imports: + - type: ImageName + targetBuildArg: BASE_IMAGE +``` + +В следующем примере рассмотрено импортирование файлов из образа Stapel в образ Dockerfile: + +```yaml +# werf.yaml +image: builder +from: golang +git: +- add: / + to: /app +shell: + install: + - cd /app + - go build -o /app/bin/server +--- +image: app +dockerfile: Dockerfile +dependencies: +- image: builder + imports: + - type: ImageName + targetBuildArg: BUILDER_IMAGE +``` + +```Dockerfile +# Dockerfile +FROM alpine +ARG BUILDER_IMAGE +COPY --from=${BUILDER_IMAGE} /app/bin /app/bin +CMD [ "/app/bin/server", "server" ] +``` + +## Передача информации о собранном образе в другой образ + +werf позволяет получить информацию о собранном образе при сборке другого образа. Например если в сборочных инструкциях образа `app` требуются имена и digest-ы образов `auth` и `controlplane`, опубликованных в container registry, то конфигурация могла бы выглядеть так: + +```Dockerfile +# modules/auth/Dockerfile +FROM alpine +WORKDIR /app +COPY . . +RUN ./build.sh +``` + +```Dockerfile +# modules/controlplane/Dockerfile +FROM alpine +WORKDIR /app +COPY . . +RUN ./build.sh +``` + +```Dockerfile +# Dockerfile +FROM alpine +WORKDIR /app +COPY . . + +ARG AUTH_IMAGE_NAME +ARG AUTH_IMAGE_DIGEST +ARG CONTROLPLANE_IMAGE_NAME +ARG CONTROLPLANE_IMAGE_DIGEST + +RUN echo AUTH_IMAGE_NAME=${AUTH_IMAGE_NAME} >> modules_images.env +RUN echo AUTH_IMAGE_DIGEST=${AUTH_IMAGE_DIGEST} >> modules_images.env +RUN echo CONTROLPLANE_IMAGE_NAME=${CONTROLPLANE_IMAGE_NAME} >> modules_images.env +RUN echo CONTROLPLANE_IMAGE_DIGEST=${CONTROLPLANE_IMAGE_DIGEST} >> modules_images.env +``` + +```yaml +# werf.yaml +image: auth +dockerfile: Dockerfile +context: modules/auth/ +--- +image: controlplane +dockerfile: Dockerfile +context: modules/controlplane/ +--- +image: app +dockerfile: Dockerfile +dependencies: +- image: auth + imports: + - type: ImageName + targetBuildArg: AUTH_IMAGE_NAME + - type: ImageID + targetBuildArg: AUTH_IMAGE_DIGEST +- image: controlplane + imports: + - type: ImageName + targetBuildArg: CONTROLPLANE_IMAGE_NAME + - type: ImageID + targetBuildArg: CONTROLPLANE_IMAGE_DIGEST +``` + +В процессе сборки werf автоматически подставит в указанные build-arguments соответствующие имена и идентификаторы. Всю оркестрацию и выстраивание зависимостей werf возьмёт на себя и произведёт сборку за один шаг (вызов `werf build`). diff --git a/docs/pages_ru/usage/build_draft/overview.md b/docs/pages_ru/usage/build_draft/overview.md index 20ffc2b759..b4b0644ebe 100644 --- a/docs/pages_ru/usage/build_draft/overview.md +++ b/docs/pages_ru/usage/build_draft/overview.md @@ -3,4 +3,21 @@ title: Обзор permalink: usage/build_draft/overview.html --- - +Чтобы доставить приложение в kubernetes как правило нужно собрать один или несколько образов приложения. + +В случае если в вашем проекте не требуется сборка своих образов, этот раздел можно пропустить. + +От пользователя требуется предоставить сборочные инструкции в виде Dockerfile или альтернативного сборочного синтаксиса stapel. + +Одна особенность сборки через werf заключается в том, что процесс сборки образов и их публикация в container registry — это один неразрывный шаг. Главная задача сборочного процесса в werf: обеспечить, чтобы для текущего коммита в container registry появились собранные образы и не пересобирать те образы, которые уже опубликованы. + +При сборке werf из коробки без специальной конфигурации берёт на себя всю работу по сборке, предоставляя следующие фичи: + +* оркестрация одновременной/параллельной сборки всех образов приложения; +* общий кеш промежуточных слоёв и образов в Container Registry, доступный с любых раннеров; +* оптимальная схема тегирования, основанная на содержимом образа, предотвращающая лишние пересборки и downtime приложения при дальнейшем выкате; +* система обеспечения воспроизводимости и неизменности образов для коммита: однажды собранные образы для коммита более не будут пересобраны (в рамках политик очистки — см. очистка). + +Предоставляется простой интерфейс для встараивания в CI/CD pipeline или для локального использования: команда `werf build [--repo REPO]`. Также сборку автоматически осуществляют команды `werf converge`, `werf kube-run` и `werf render`. + +После прочтения данного раздела пользователь узнает как описать инструкции сборки образов, как работает механизм сборки, какие есть варианты конфигурации сборочного механизма и варианты организации хранилища под нужды проекта.