diff --git a/docs/pages_en/usage/integration_with_ci_cd_systems/ci_cd_workflow_basics.md b/docs/pages_en/usage/integration_with_ci_cd_systems/ci_cd_workflow_basics.md index e835f09e6d..01aaab854e 100644 --- a/docs/pages_en/usage/integration_with_ci_cd_systems/ci_cd_workflow_basics.md +++ b/docs/pages_en/usage/integration_with_ci_cd_systems/ci_cd_workflow_basics.md @@ -15,29 +15,28 @@ We also recommend you to read one the following guides about configuring the spe ## Basics -> NOTICE: In the text below, the term "git" can be interpreted as a common name for any version control system. However, werf supports only the Git version control system. We suppose our readers are familiar with the following git-related terms: branch, tag, master, commit, merge, rebase, fast-forward merge, and the git push-force procedure. To fully appreciate this article, readers are advised to get a good understanding of these terms. - -### Environment +### Environments #### Production Generally, end users interact with an application in the production environment. It is also the target environment for all application code changes made by application developers. -Also, there are so-called _production-like_ environments. Production-like environments are separate from production but have the same hardware and software configuration, network infrastructure, operating system, software versions, etc. In the real world, there may be some differences, though. Still, each project defines its acceptable risks related to the difference between production-like and production environments. Examples of production-like environments – [staging](#staging) and [testing](#testing) – are provided below. +#### Production-like -#### Staging +Production-like environments are separate from production but have the same hardware and software configuration, network infrastructure, operating system, software versions, etc. In the real world, there may be some differences, though. Still, each project defines its acceptable risks related to the difference between production-like and production environments. +##### Staging -Staging is a [production-like environment](#production) serving as a playground to examine your application before deploying it to production. Also, staging is the place to test new business functionality by managers, testers, and customers. End users do not interact with the staging environment in any way. +Staging is an environment serving as a playground to examine your application before deploying it to production. Also, staging is the place to test new business functionality by managers, testers, and customers. End users do not interact with the staging environment in any way. If your application uses some external services, then staging is the only environment typically (besides the production itself) that uses the same set of external services APIs and versions. -#### Testing +##### Testing -Testing is a [production-like environment](#production) with the following goal: to reveal problems with the new version of an application that may arise in the production environment. Some long-running application tests may use this environment to perform full-fledged application testing in a production-like environment. The higher the difference between testing and production environments, the higher the risk of deploying a buggy application to the production environment. That's why we recommend making a production-like environment as close as possible to a production one (same software versions, libraries, operating system, IP-addresses and ports, hardware, etc.). +Testing is an environment with the following goal: to reveal problems with the new version of an application that may arise in the production environment. Some long-running application tests may use this environment to perform full-fledged application testing in a production-like environment. The higher the difference between testing and production environments, the higher the risk of deploying a buggy application to the production environment. That's why we recommend making a production-like environment as close as possible to a production one (same software versions, libraries, operating system, IP-addresses and ports, hardware, etc.). #### Review -Review is a dynamic (temporary) environment used by application developers to test newly written code and conduct experiments not allowed in [production-like environments](#production). +Review is a dynamic (temporary) environment used by application developers to test newly written code and conduct experiments not allowed in [production-like environments](#production-like). It is possible to dynamically create an arbitrary number of review environments (as resources permit). Application developer usually creates and terminates such an environment using a CI/CD system. Also, a review environment could be automatically removed after a period of inactivity. @@ -78,17 +77,9 @@ You can run a pipeline manually by one of the following methods: - By assigning a label in a CI/CD system (e.g., GitLab CI/CD or GitHub Actions). A label is usually assigned to/withdrawn from the pull request by the user or automatically by the CI/CD system while the pipeline is running. - For example, the user assigns the "run tests" label to his pull request, and the CI/CD system automatically triggers the corresponding pipeline. While this pipeline is running, the "run tests" label is revoked from the pull request. Then the user can assign this label again to restart the process, and so on. - Label serves as an alternative to buttons or is used in cases when the CI/CD system does not support buttons (e.g., GitHub Actions). - For review environments, assigning a label by the user is a signal to activate the review environment, and removing it (manually or automatically) is a signal to deactivate it. This option will be discussed in more detail (later) (#automatically-deploy-to-review-using-a-pull-request-manual-triggering). + For review environments, assigning a label by the user is a signal to activate the review environment, and removing it (manually or automatically) is a signal to deactivate it. - By sending a request to the API of the CI/CD system (for example, via HTTP at a specific url in GitHub Actions). ### The testing stage To implement a proper CI/CD, it is critical to automatically get instant feedback when making changes to the project codebase. The testing stage can be divided into two nominal stages: during the primary stage, tests run fast and cover most of the functions; during the secondary stage, tests can run for a prolonged time and verify more aspects of the application. Generally, primary tests are run automatically, and passing them is a prerequisite for changes to be released. - -## Further reading - -We recommend you to read the guide for your specific CI/CD system: - - The [GitLab CI/CD]({{ "how_to/integration_with_ci_cd_systems/gitlab_ci_cd/workflows.html" | true_relative_url }}) guide. - - The [GitHub Actions]({{ "how_to/integration_with_ci_cd_systems/github_actions/workflows.html" | true_relative_url }}) guide. - -If you want to learn more about how to create a workflow, or no instructions exist for your particular CI/CD system, then you can read the following sections where the [workflow components](#workflow-components-for-various-environments) and [ready-made workflow configurations](#ready-made-workflow-configurations) are defined. After reading them, you will be able to choose a ready-made configuration (or create your own) and implement it for your CI/CD system using werf. diff --git a/docs/pages_ru/usage/integration_with_ci_cd_systems/ci_cd_workflow_basics.md b/docs/pages_ru/usage/integration_with_ci_cd_systems/ci_cd_workflow_basics.md index 73c6c535d2..fe957aad33 100644 --- a/docs/pages_ru/usage/integration_with_ci_cd_systems/ci_cd_workflow_basics.md +++ b/docs/pages_ru/usage/integration_with_ci_cd_systems/ci_cd_workflow_basics.md @@ -11,80 +11,74 @@ permalink: usage/integration_with_ci_cd_systems/ci_cd_workflow_basics.html - Инструкция для [GitLab CI/CD]({{ "how_to/integration_with_ci_cd_systems/gitlab_ci_cd/workflows.html" | true_relative_url }}). - Инструкция для [Github Actions]({{ "how_to/integration_with_ci_cd_systems/github_actions/workflows.html" | true_relative_url }}). -## Pipeline +## Основы -С помощью git пользователь вносит изменения в кодовую базу проекта. Каждый коммит в гит активирует так называемый **pipeline** со стороны CI/CD системы. Pipeline разбит на стадии, которые могут запускаться последовательно или параллельно. - -Главное назначение pipeline — донести внесённое в гит изменение до некоторого окружения. В случае непрохождения какой-то стадии pipeline прерывается и пользователь тем самым получает обратную связь. Коммит, который успешно проходит по всем необходимым стадиям попадает на некоторый контур/окружение. +### Окружение -Бывают следующие основные типы стадий: - - Build-and-Publish — сборка образов приложения и их публикация в хранилище образов. - - Deploy — непосредственно выкат приложения на контур. - - Cleanup — очистка неиспользуемых образов и связанного кеша из хранилища. +#### Production -### Pull request - -Пользователь вносит изменения в кодовую базу путём создания коммитов в git и pull request-ов в CI/CD системе. Обычно pull request — это сущность, которая связывает коммит в git и pipeline (а также позволяет делать review, оставлять комментарии и пр.). В разных CI/CD системах pull request может называться по-разному (Merge Request в GitLab CI) или вообще отсутствовать (Jenkins). - -### Workflow +В этом окружении работает разрабатываемая система, это целевое окружение для всех изменений, которые делают разработчики системы. Этим окружением пользуются реальные пользователи в процессе эксплуатации системы. -Pipeline-ы и стадии внутри pipeline-ов могут быть активированы как автоматически, так и вручную. Способы активации pipeline-ов, их устройство, связь с гит, требуемые действия со стороны пользователя — всё это будет определяться так называемым workflow. -Возможно множество вариантов workflow для достижения одной и той же цели. Далее мы рассмотрим те варианты, которые можно реализовать с использованием werf. +#### Production-like -### Варианты ручного запуска pipeline +Конфигурация выделенных для окружения ресурсов (инфраструктура, конфигурация железа, версии софта, операционная система, сетевая организация), а также внешние сервисы — по максимуму насколько возможно совпадают с production окружением. Есть нюансы, из-за которых различия могут быть, но в каждом конкретном _production-like_ окружении определяются свои допустимые риски связанные с различием с production окружением. -Ручной запуск pipeline предполагает: - - Нажатие кнопки в CI/CD системе (например Gitlab CI). - - Назначение label в CI/CD системе (например Gitlab CI или Github Actions). Label обычно назначается на pull request и снимается с pull request пользователем или автоматически CI/CD системой во время работы pipeline. - - Например, пользователь назначает label "run tests" на его pull request и CI/CD система автоматически запускает соответствующий pipeline. Во время работы этого pipeline label "run tests" снимается с pull request. Далее для перезапуска пользователь может опять назначить этот label. И т.д. - - Label используется как альтернатива кнопкам, либо в случаях когда кнопки не поддерживаются CI/CD системой (например, Github Actions). -Для review окружений назначение пользователем label является сигналом к активации review окружения, а его снятие (вручную/автоматом) — к деактивации. Вариант будет подробнее рассмотрен (далее)(#автоматом-для-pull-request-после-ручной-активации). - - Запрос через API CI/CD системы (например через HTTP по определённому url в Github Actions). +##### Staging -## Релизы и CI/CD +Staging — это окружение, в котором происходит финальная проверка перед выкатом на [production](#production). Staging даёт возможность полнее протестировать бизнес-функции приложения и обычно это то место, куда идут менеджеры, тестировщики, заказчики. -**Релиз** — это оформленная версия приложения с какими-то изменениями с момента предыдущего релиза. +В случае, если приложение связано с какими либо внешними сервисами, staging — это единственное окружение помимо [production](#production), где можно проверить как новая версия работает в связке с реальными версиями внешних систем. -В каскадном (или водопадном) подходе к разработке софта релизы обычно делаются редко и содержат множество изменений. Доставка таких релизов в окружения также происходит редко, но в этот момент все усилия команды тратятся на слежение за новой версией, исправление ошибок, проверку что всё прошло успешно. Обычно это отдельный и очень ответственный этап разработки, и пока он длится, новых изменений никто не делает (а если и делает, то пока нет возможности доставить их пользователю до нового релиза). Новая версия ещё не была проверена в реальной жизни, или была проверена тестами, но этого всё равно может быть недостаточно — с этим связаны большие риски, что новая версия приложения не заработает. +##### Testing -В CI/CD подходе релизы делаются часто, и релизы могут содержать мало изменений. Поощряется, чтобы разработчики разбивали новые фичи на такие куски, которые можно сразу обкатать на production-like или production окружениях. Более того, разработчики, которые прониклись таким подходом, сами хотят как можно быстрее пустить новый код в работу и получить обратную связь — после этого опираясь на проверенный код проще делаются новые изменения. До конца доделанным можно считать лишь тот код, который не только написан, но и задействован в production. +Testing — это окружение, цель которого: выявить возникшие у приложения проблемы на [production](#production) окружении. В данном окружении могут работать "долгие" автоматизированные тесты приложения, которые проверяют множество аспектов его работы. Чем больше различий между testing и production, тем больше рисков получить нерабочее приложение после очередного выката, поэтому рекомендуется максимально повторять production окружение (одинаковый софт, версии, библиотеки, IP-адреса и порты, железо и т.д.). -В дальнейших разделах мы определим возможные варианты конфигураций workflow и насколько каждый из них соответствует подходам CI/CD. +#### Review -## Окружения +Динамический (временный) контур, используемый разработчиками при разработке для оценки работоспособности написанного кода, первичной оценки работоспособности приложения и проведения таких экспериментов, которые нельзя делать на [production-like окружениях](#production-like). -### Production +Особенность review-окружений в том, что их можно создавать динамически в любых количествах (в разумных пределах, насколько позволяют ресурсы). Как правило, создание и удаление такого окружения инициируется разработчиком через CI/CD систему, также такое окружение может быть удалено автоматически после отсутствия активности в течение некоторого времени. -В этом окружении работает разрабатываемая система, это целевое окружение для всех изменений, которые делают разработчики системы. Этим окружением пользуются реальные пользователи в процессе эксплуатации системы. +### Релизы и CI/CD -Существуют также так называемые _production-like_ окружения, особенность которых в том, что конфигурация выделенных для окружения ресурсов (инфраструктура, конфигурация железа, версии софта, операционная система, сетевая организация), а также внешние сервисы — по максимуму насколько возможно совпадают с production окружением. Есть нюансы, из-за которых различия могут быть, но в каждом конкретном _production-like_ окружении определяются свои допустимые риски связанные с различием с production окружением. Примеры таких окружений: [staging](#staging) и [testing](#testing) — рассмотрены далее. +**Релиз** — это оформленная версия приложения с какими-то изменениями с момента предыдущего релиза. -### Staging +В каскадном (или водопадном) подходе к разработке софта релизы обычно делаются редко и содержат множество изменений. Доставка таких релизов в окружения также происходит редко, но в этот момент все усилия команды тратятся на слежение за новой версией, исправление ошибок, проверку, что всё прошло успешно. Обычно это отдельный и очень ответственный этап разработки, и пока он длится, новых изменений никто не делает (а если и делает, то пока нет возможности доставить их пользователю до нового релиза). Новая версия ещё не была проверена в реальной жизни, или была проверена тестами, но этого всё равно может быть недостаточно — с этим связаны большие риски, что новая версия приложения не заработает. -Staging — это [production-like окружение](#production), в котором происходит финальная проверка перед выкатом на [production](#production). Staging даёт возможность полнее протестировать бизнес-функции приложения и обычно это то место, куда идут менеджеры, тестировщики, заказчики. +В CI/CD подходе релизы делаются часто, и релизы могут содержать мало изменений. Поощряется, чтобы разработчики разбивали новые фичи на такие куски, которые можно сразу обкатать на production-like или production окружениях. Более того, разработчики, которые прониклись таким подходом, сами хотят как можно быстрее пустить новый код в работу и получить обратную связь — после этого опираясь на проверенный код проще делаются новые изменения. До конца доделанным можно считать лишь тот код, который не только написан, но и задействован в production. -В случае, если приложение связано с какими либо внешними сервисами, staging — это единственное окружение помимо [production](#production), где можно проверить как новая версия работает в связке с реальными версиями внешних систем. +В дальнейших разделах мы определим возможные варианты конфигураций workflow и насколько каждый из них соответствует подходам CI/CD. -### Testing +### Что такое pipeline и workflow -Testing — это [production-like окружение](#production), цель которого: выявить возникшие у приложения проблемы на [production](#production) окружении. В данном окружении могут работать "долгие" автоматизированные тесты приложения, которые проверяют множество аспектов его работы. Чем больше различий между testing и production, тем больше рисков получить нерабочее приложение после очередного выката, поэтому рекомендуется максимально повторять production окружение (одинаковый софт, версии, библиотеки, IP-адреса и порты, железо и т.д.). +С помощью git пользователь вносит изменения в кодовую базу проекта. Каждый коммит в гит активирует так называемый **pipeline** со стороны CI/CD системы. Pipeline разбит на стадии, которые могут запускаться последовательно или параллельно. -### Review +Главное назначение pipeline — донести внесённое в гит изменение до некоторого окружения. В случае непрохождения какой-то стадии pipeline прерывается и пользователь тем самым получает обратную связь. Коммит, который успешно проходит по всем необходимым стадиям попадает на некоторый контур/окружение. -Динамический (временный) контур, используемый разработчиками при разработке для оценки работоспособности написанного кода, первичной оценки работоспособности приложения и проведения таких экспериментов, которые нельзя делать на [production-like окружениях](#production). +Бывают следующие основные типы стадий: + - Build-and-Publish — сборка образов приложения и их публикация в хранилище образов. + - Deploy — непосредственно выкат приложения на контур. + - Cleanup — очистка неиспользуемых образов и связанного кеша из хранилища. -Особенность review-окружений в том, что их можно создавать динамически в любых количествах (в разумных пределах, насколько позволяют ресурсы). Как правило, создание и удаление такого окружения инициируется разработчиком через CI/CD систему, также такое окружение может быть удалено автоматически после отсутствия активности в течение некоторого времени. +#### Pull request -## Стадия тестирования +Пользователь вносит изменения в кодовую базу путём создания коммитов в git и pull request-ов в CI/CD системе. Обычно pull request — это сущность, которая связывает коммит в git и pipeline (а также позволяет делать review, оставлять комментарии и пр.). В разных CI/CD системах pull request может называться по-разному (Merge Request в GitLab CI) или вообще отсутствовать (Jenkins). -Для правильной организации CI/CD критично во время внесения изменений в кодовую базу проекта получать быструю обратную связь в автоматическом режиме с помощью тестов. Причём стадию тестирования можно разбить на 2 условных этапа: на первичном этапе тесты проходят быстро и покрывают большую часть функций, на вторичном этапе тесты могут работать долго и проверять больше аспектов приложение. Первичные тесты обычно запускаются автоматически и их прохождение является обязательным условием для допуска изменений к релизу. +#### Workflow -## Что читать дальше +Pipeline-ы и стадии внутри pipeline-ов могут быть активированы как автоматически, так и вручную. Способы активации pipeline-ов, их устройство, связь с гит, требуемые действия со стороны пользователя — всё это будет определяться так называемым workflow. +Возможно множество вариантов workflow для достижения одной и той же цели. Далее мы рассмотрим те варианты, которые можно реализовать с использованием werf. -Дальше рекомендуется ознакомиться с инструкцией по вашей CI/CD системе: - - Инструкция для [GitLab CI/CD]({{ "how_to/integration_with_ci_cd_systems/gitlab_ci_cd/workflows.html" | true_relative_url }}). - - Инструкция для [Github Actions]({{ "how_to/integration_with_ci_cd_systems/github_actions/workflows.html" | true_relative_url }}). +### Варианты ручного запуска pipeline -Если вы хотите узнать больше подробностей по методике составления workflow или для вашей CI/CD системы не нашлось инструкции, тогда можно ознакомится с дальнейшими разделами где определяются [составляющие workflow](#составляющие-workflow-для-отдельных-окружений) и [готовые конфигурации workflow](#готовые-конфигурации-workflow). После этого вы будете готовы выбрать готовую конфигурацию или составить свою и реализовать её для вашей CI/CD системы с использованием werf. +Ручной запуск pipeline предполагает: + - Нажатие кнопки в CI/CD системе (например Gitlab CI). + - Назначение label в CI/CD системе (например Gitlab CI или Github Actions). Label обычно назначается на pull request и снимается с pull request пользователем или автоматически CI/CD системой во время работы pipeline. + - Например, пользователь назначает label "run tests" на его pull request и CI/CD система автоматически запускает соответствующий pipeline. Во время работы этого pipeline label "run tests" снимается с pull request. Далее для перезапуска пользователь может опять назначить этот label. И т.д. + - Label используется как альтернатива кнопкам, либо в случаях когда кнопки не поддерживаются CI/CD системой (например, Github Actions). +Для review окружений назначение пользователем label является сигналом к активации review окружения, а его снятие (вручную/автоматом) — к деактивации. + - Запрос через API CI/CD системы (например через HTTP по определённому url в Github Actions). +### Стадия тестирования +Для правильной организации CI/CD критично во время внесения изменений в кодовую базу проекта получать быструю обратную связь в автоматическом режиме с помощью тестов. Причём стадию тестирования можно разбить на 2 условных этапа: на первичном этапе тесты проходят быстро и покрывают большую часть функций, на вторичном этапе тесты могут работать долго и проверять больше аспектов приложение. Первичные тесты обычно запускаются автоматически и их прохождение является обязательным условием для допуска изменений к релизу.