From 8d3858e119402caa6c04a281127296a507cdc9c0 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Tue, 6 Aug 2024 18:22:16 +0300 Subject: [PATCH 01/61] Create promotion-flow.md --- _docs/promotions/promotion-flow.md | 118 +++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 _docs/promotions/promotion-flow.md diff --git a/_docs/promotions/promotion-flow.md b/_docs/promotions/promotion-flow.md new file mode 100644 index 000000000..4b40884a8 --- /dev/null +++ b/_docs/promotions/promotion-flow.md @@ -0,0 +1,118 @@ +--- +title: "Promotion orchestration" +description: "Create flows to orchestrate promotion for products across environments" +group: deployments +toc: true +--- + + + + +PromotionFlow selection is based on a product selector and a release to an environment. +Products “Billing” is deployed to the first env, “dev” +Allow grouping of environments in order to create complex logic of promotion after multiple environments are healthy +Define Rollback Logic for Rollouts, when rollout fails and creates a rollback on env us-east, rollback eu and asia as they have the same version. Potentially rollback asia-2 as well +Asia-2 promotion starts depends on multiple envs +define release windows + + + + + + +Configure Promotion Flows + + +A Promotion Flow is a structured sequence of actions that automates the promotion of changes in products through various stages of development and deployment. It ensures that code changes are automatically, systematically, and consistently moved, from development to production environments, enhancing the reliability and efficiency of deployments. + +Benefits of Promotion Flows +Consistency: Automates repetitive tasks, ensuring uniformity across deployments. +Efficiency: Reduces manual effort and accelerates the deployment process. +Control: Allows precise control over the conditions under which changes are promoted. +Visibility: Provides clear insights into the progress and status of changes across environments. +Contribution to Deployments +Promotion flows streamline the process of moving code changes through different stages, such as testing, staging, and production. By defining specific criteria for promotion, they help maintain the integrity of the software and reduce the likelihood of introducing bugs into production. + +## Promotion Flow configuration +Similar to most entities, and to all promotion-entities, Promotion Workflows through the Flow Builder, a graphical interface, or through a YAML Custom Resource Definition (CRD). + +### Flow Builder +The Flow Builder provides an intuitive interface for creating and managing promotion flows. +You can visually design the flow by selecting environments, promotion workflows, setting trigger conditions, and defining dependencies. And even add environments and promotion workflows on-the-fly when doing so. + + +YAML Custom Resource Definition (CRD) + a more technical approach, promotion flows can be defined using YAML CRD. This method allows for precise control and customization of the flow by editing a YAML file that describes the flow's actions, triggers, and dependencies. + + + + + + + +Types of Flows + + Parallel and Sequential +Promotion flows can be designed to run actions in parallel or sequentially, depending on the desired workflow and dependencies. + +a. Parallel Flows +In a Parallel Flow, multiple actions are executed simultaneously. This approach is useful when actions are independent of each other and can run concurrently, thereby reducing the overall time required for promotion. + +Example Use Case: Running tests and building a container image at the same time. +b. Sequential Flows +A Sequential Flow involves executing actions in a specific order. This is essential when actions have dependencies or need to be completed before the next action can begin. + +Example Use Case: Running a build process, followed by testing, and then deploying to a staging environment. +4. Applying Promotion Flows +Promotion flows are not tied to any specific product or technology stack, making them versatile tools for managing deployments across various platforms. They can be applied to: + +Continuous Integration/Continuous Deployment (CI/CD) Pipelines: Automating the movement of code changes through different pipeline stages. +Release Management: Ensuring that releases are properly validated and approved before reaching production. +Environment Management: Controlling the promotion of changes across development, staging, and production environments. +Promotion flows can be customized to suit the unique requirements of any deployment process, providing a powerful way to automate and manage the lifecycle of software changes. + +## Promotion Flow components + +Promotion flows consist of several components, each serving a specific role in the deployment process. +Before creating Promotion Flows + +Trigger Environment (Required) +The trigger environment is where a change initiates the promotion flow. The change in the trigger environment is a manual user commit or pull request actio, and not an automated promotion action as in other environments. +You can configure a trigger workflow (akin to a Post-Action Workflow) to automate specific actions. + +Promotion Workflows (Optional) +Promotion workflows, categorized as Pre-Action and Post-Action workflows, validate the environment's readiness for promotion: +* Pre-Action Workflow: Executes before committing changes to ensure the environment meets predefined criteria. +* Post-Action Workflow: Executes after committing changes to verify the environment's stability and functionality post-deployment. +While optional, it is highly recommended to add these workflows to environments and enhance deployment reliability and consistency. + +Inter-Environment Dependencies +In both sequential and parallel promotion flows, adding a new environment automatically establishes a dependency on the previous environment. This ensures changes progress through stages in a controlled manner. + +For parallel flows, you can add multiple environments as dependencies simultaneously. This means that the changes are promoted conncurrently to each of the environments and only when successfully deployed across all dependent environments are they promoted to the next environment in the flow. + + + + + +## Create Promotion Flow with Flow Builder + + +1. 1. In the Codefresh UI, on the toolbar, click the **Settings** icon, and then from the sidebar, select **Promotion Flows**. +1. Click **Add Promotion Flow**. +1. Select the trigger environment: + 1. Click ?? to see the list of available environments. + 1. Do one of the following: + * To add an existing environment, select it and click **Add**. Continue from step ?? + * To create a new environment, click **Add New Environment**. To +1. Select the next environment to promote to: + 1. Mouse over the right of the current environment and click ??. + 1. Repeat step 3 to add an existing or a new environment. +1. Add Pre- and Post-Action Workflows: + 1. Mouse over the connector between the two environments. + 1. To add a Pre-Action Workflow, click the top ??? icon. + 1. To add a Post-Action Workflow, click the lower ??? icon. + 1. From the list displayed, do one of the following: + * To add an existing Pre- or Post-Action Workflow, select it and click **Add**. Continue from step ?? + * To add a new Workflow, click **Add New Workflow**. To +1. Add inter-environment dependencies: From cdd1c23a9ff7c296d57dfdee81b357757914dc74 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Wed, 7 Aug 2024 11:21:40 +0300 Subject: [PATCH 02/61] Update promotion-flow.md --- _docs/promotions/promotion-flow.md | 108 ++++++++++++++++------------- 1 file changed, 60 insertions(+), 48 deletions(-) diff --git a/_docs/promotions/promotion-flow.md b/_docs/promotions/promotion-flow.md index 4b40884a8..1fd6727a9 100644 --- a/_docs/promotions/promotion-flow.md +++ b/_docs/promotions/promotion-flow.md @@ -10,7 +10,7 @@ toc: true PromotionFlow selection is based on a product selector and a release to an environment. Products “Billing” is deployed to the first env, “dev” -Allow grouping of environments in order to create complex logic of promotion after multiple environments are healthy + Define Rollback Logic for Rollouts, when rollout fails and creates a rollback on env us-east, rollback eu and asia as they have the same version. Potentially rollback asia-2 as well Asia-2 promotion starts depends on multiple envs define release windows @@ -23,96 +23,108 @@ define release windows Configure Promotion Flows -A Promotion Flow is a structured sequence of actions that automates the promotion of changes in products through various stages of development and deployment. It ensures that code changes are automatically, systematically, and consistently moved, from development to production environments, enhancing the reliability and efficiency of deployments. +A Promotion Flow is a structured sequence of actions that automates the promotion of changes in products through various environments until deployment. It ensures that code changes are automatically, systematically, and consistently moved, from development to production environments, enhancing the reliability and efficiency of deployments. Benefits of Promotion Flows -Consistency: Automates repetitive tasks, ensuring uniformity across deployments. -Efficiency: Reduces manual effort and accelerates the deployment process. -Control: Allows precise control over the conditions under which changes are promoted. -Visibility: Provides clear insights into the progress and status of changes across environments. -Contribution to Deployments -Promotion flows streamline the process of moving code changes through different stages, such as testing, staging, and production. By defining specific criteria for promotion, they help maintain the integrity of the software and reduce the likelihood of introducing bugs into production. +Simplicity -## Promotion Flow configuration -Similar to most entities, and to all promotion-entities, Promotion Workflows through the Flow Builder, a graphical interface, or through a YAML Custom Resource Definition (CRD). +Automated deployment processes -### Flow Builder -The Flow Builder provides an intuitive interface for creating and managing promotion flows. -You can visually design the flow by selecting environments, promotion workflows, setting trigger conditions, and defining dependencies. And even add environments and promotion workflows on-the-fly when doing so. +Simple vs. complex promotion logic -YAML Custom Resource Definition (CRD) - a more technical approach, promotion flows can be defined using YAML CRD. This method allows for precise control and customization of the flow by editing a YAML file that describes the flow's actions, triggers, and dependencies. +Product-agnostic +4. Applying Promotion Flows +Promotion flows are not tied to any specific product or technology stack, making them versatile tools for managing deployments across various platforms. They can be applied to: +Consistency: Automates repetitive tasks, ensuring uniformity across deployments. +Efficiency: Reduces manual effort and accelerates the deployment process. +Control: Allows precise control over the conditions under which changes are promoted. +Visibility: Provides clear insights into the progress and status of changes across environments. +Contribution to Deployments +Promotion flows streamline the process of moving code changes through different stages, such as testing, staging, and production. By defining specific criteria for promotion, they help maintain the integrity of the software and reduce the likelihood of introducing bugs into production. +## Flow Builder vs. YAML +Similar to most entities, and to all promotion-entities, you can create Promotion Workflows through the Flow Builder, a graphical interface, or through a YAML Custom Resource Definition (CRD). You can switch seamlessly between both when creating Promotion Flows. +## Sequential vs. parallel flows -Types of Flows +Promotion flows can be designed to run sequentially or in parallel to suit the unique requirements of any deployment process. - Parallel and Sequential -Promotion flows can be designed to run actions in parallel or sequentially, depending on the desired workflow and dependencies. +Sequential flows +Sequential flows are linear, where changes are promoted from the previous to the next environment in the order in which they are defined. +This is the more common and traditional flow where you start the flow from the dev environment as the trigger environment, and then promote to testing, staging, and finally production. -a. Parallel Flows -In a Parallel Flow, multiple actions are executed simultaneously. This approach is useful when actions are independent of each other and can run concurrently, thereby reducing the overall time required for promotion. +Parallel flows +In a parallel flow, changes are promoted across multiple environments simultaneously. This promotion logic groups environments to create promotions after multiple environments are healthy. -Example Use Case: Running tests and building a container image at the same time. -b. Sequential Flows -A Sequential Flow involves executing actions in a specific order. This is essential when actions have dependencies or need to be completed before the next action can begin. -Example Use Case: Running a build process, followed by testing, and then deploying to a staging environment. -4. Applying Promotion Flows -Promotion flows are not tied to any specific product or technology stack, making them versatile tools for managing deployments across various platforms. They can be applied to: -Continuous Integration/Continuous Deployment (CI/CD) Pipelines: Automating the movement of code changes through different pipeline stages. -Release Management: Ensuring that releases are properly validated and approved before reaching production. -Environment Management: Controlling the promotion of changes across development, staging, and production environments. -Promotion flows can be customized to suit the unique requirements of any deployment process, providing a powerful way to automate and manage the lifecycle of software changes. ## Promotion Flow components -Promotion flows consist of several components, each serving a specific role in the deployment process. -Before creating Promotion Flows +A Promotion Flow comprises several components, optional and required, each serving a specific role in the deployment process. +Before creating Promotion Flows it is advisable to understand the role of the components and the -Trigger Environment (Required) -The trigger environment is where a change initiates the promotion flow. The change in the trigger environment is a manual user commit or pull request actio, and not an automated promotion action as in other environments. -You can configure a trigger workflow (akin to a Post-Action Workflow) to automate specific actions. +* Trigger Environment (required) + The trigger environment is where a change initiates the promotion flow. The change in the trigger environment is a manual user commit or pull request action, and not an automated promotion action as in the other environments defined in the Promotion Flow. + To automate specific actions after the change, you can configure a trigger workflow (akin to a Post-Action Workflow). -Promotion Workflows (Optional) -Promotion workflows, categorized as Pre-Action and Post-Action workflows, validate the environment's readiness for promotion: -* Pre-Action Workflow: Executes before committing changes to ensure the environment meets predefined criteria. -* Post-Action Workflow: Executes after committing changes to verify the environment's stability and functionality post-deployment. -While optional, it is highly recommended to add these workflows to environments and enhance deployment reliability and consistency. +* Promotion Workflows (optional) + Promotion workflows, categorized as Pre-Action and Post-Action workflows, validate the environment's readiness for promotion: + * Pre-Action Workflow: Executes before changes are committed to ensure the environment meets predefined criteria. + * Post-Action Workflow: Executes after changes are committed to verify the environment's stability and functionality post-deployment. + While optional, we highly recommend adding these workflows to environments to enhance deployment reliability and consistency. + You can select from available Promotion Workflows or create a new Pre- or Post-Action Workflow as needed. -Inter-Environment Dependencies -In both sequential and parallel promotion flows, adding a new environment automatically establishes a dependency on the previous environment. This ensures changes progress through stages in a controlled manner. +* Inter-environment dependencies + In both sequential and parallel flows, adding a new environment automatically establishes a dependency on the previous environment. This ensures that changes are promoted in a controlled manner. -For parallel flows, you can add multiple environments as dependencies simultaneously. This means that the changes are promoted conncurrently to each of the environments and only when successfully deployed across all dependent environments are they promoted to the next environment in the flow. + For parallel flows, you can add multiple environments as simultaneous dependencies on new environments. This means that the changes from the previous environment are promoted concurrently to each of the dependent environments, and only when successfully deployed across all environments are they promoted to the next environment in the flow. ## Create Promotion Flow with Flow Builder +Visually design and create the flow by selecting environments, promotion workflows, setting trigger conditions, and defining dependencies through the Flow Builder. If needed add new environments and promotion workflows on-the-fly when doing so. +##### Before you begin +* Review +* -1. 1. In the Codefresh UI, on the toolbar, click the **Settings** icon, and then from the sidebar, select **Promotion Flows**. +##### How to +1. In the Codefresh UI, on the toolbar, click the **Settings** icon, and then from the sidebar, select **Promotion Flows**. 1. Click **Add Promotion Flow**. 1. Select the trigger environment: 1. Click ?? to see the list of available environments. 1. Do one of the following: * To add an existing environment, select it and click **Add**. Continue from step ?? - * To create a new environment, click **Add New Environment**. To + * To create a new environment, click **Add New Environment**. 1. Select the next environment to promote to: 1. Mouse over the right of the current environment and click ??. - 1. Repeat step 3 to add an existing or a new environment. + 1. Do one of the following: + * To add an existing environment, select it and click **Add**. Continue from step ?? + * To create a new environment, click **Add New Environment**. + The Create Environment form is displayed. See ???? + A notification alerts you that are unsaved changes to the Promotion Flow. 1. Add Pre- and Post-Action Workflows: 1. Mouse over the connector between the two environments. 1. To add a Pre-Action Workflow, click the top ??? icon. 1. To add a Post-Action Workflow, click the lower ??? icon. 1. From the list displayed, do one of the following: * To add an existing Pre- or Post-Action Workflow, select it and click **Add**. Continue from step ?? - * To add a new Workflow, click **Add New Workflow**. To -1. Add inter-environment dependencies: + * To add a new Workflow, click **Add New Workflow**. + The Add Promotion Workflows form is displayed. See ???? + A notification alerts you that are unsaved changes to the Promotion Flow. +1. If needed, create dependencies on the next environment: + 1. Mouse over the current environment. + 1. From the **Depends on** list, select the environment and click **Update dependency**. + The environment is added below the existing environment, and a link is added between it and the next environment to indicate a dependency. +1. Click **Save Promotion Flow** to commit changes. + + + From 0a1bcff4cb6c641c23496334a0afb2f0ccddeafe Mon Sep 17 00:00:00 2001 From: NimRegev Date: Thu, 8 Aug 2024 14:57:54 +0300 Subject: [PATCH 03/61] Update promotion-flow.md Add more content to promotion flow topic --- _docs/promotions/promotion-flow.md | 176 ++++++++++++++++++++--------- 1 file changed, 122 insertions(+), 54 deletions(-) diff --git a/_docs/promotions/promotion-flow.md b/_docs/promotions/promotion-flow.md index 1fd6727a9..42cc2ed0b 100644 --- a/_docs/promotions/promotion-flow.md +++ b/_docs/promotions/promotion-flow.md @@ -6,34 +6,17 @@ toc: true --- - - -PromotionFlow selection is based on a product selector and a release to an environment. -Products “Billing” is deployed to the first env, “dev” - -Define Rollback Logic for Rollouts, when rollout fails and creates a rollback on env us-east, rollback eu and asia as they have the same version. Potentially rollback asia-2 as well -Asia-2 promotion starts depends on multiple envs -define release windows - - - - - - -Configure Promotion Flows - - A Promotion Flow is a structured sequence of actions that automates the promotion of changes in products through various environments until deployment. It ensures that code changes are automatically, systematically, and consistently moved, from development to production environments, enhancing the reliability and efficiency of deployments. Benefits of Promotion Flows Simplicity -Automated deployment processes +Automated deployment + +Promotion logic -Simple vs. complex promotion logic -Product-agnostic @@ -47,7 +30,7 @@ Contribution to Deployments Promotion flows streamline the process of moving code changes through different stages, such as testing, staging, and production. By defining specific criteria for promotion, they help maintain the integrity of the software and reduce the likelihood of introducing bugs into production. ## Flow Builder vs. YAML -Similar to most entities, and to all promotion-entities, you can create Promotion Workflows through the Flow Builder, a graphical interface, or through a YAML Custom Resource Definition (CRD). You can switch seamlessly between both when creating Promotion Flows. +You can create Promotion Workflows through the Flow Builder, a graphical interface, or through a YAML Custom Resource Definition (CRD). You can switch seamlessly between both when creating Promotion Flows.Similar to most entities, and all promotion-entities, ## Sequential vs. parallel flows @@ -64,26 +47,44 @@ In a parallel flow, changes are promoted across multiple environments simultaneo -## Promotion Flow components +## Promotion Flow building blocks -A Promotion Flow comprises several components, optional and required, each serving a specific role in the deployment process. -Before creating Promotion Flows it is advisable to understand the role of the components and the +A Promotion Flow comprises several building blocks, optional and required, each serving a specific role in the deployment process. +Before creating Promotion Flows it is advisable to understand the role of these building blocks. -* Trigger Environment (required) - The trigger environment is where a change initiates the promotion flow. The change in the trigger environment is a manual user commit or pull request action, and not an automated promotion action as in the other environments defined in the Promotion Flow. - To automate specific actions after the change, you can configure a trigger workflow (akin to a Post-Action Workflow). +* Environments (required) + + * Trigger environment + The trigger environment is where a change initiates the promotion flow. The change in the trigger environment is a manual user commit or pull request action, and not an automated promotion action as in the other environments defined in the Promotion Flow. + To automate specific actions after the change, you can configure a trigger workflow (akin to a Post-Action Workflow). + + * Target environments + Any environment apart from the trigger environment are target environments in the promotion flow. A Promotion Flow requires at least one target environment. + Target environments can linear or parallel. + * Promotion Workflows (optional) Promotion workflows, categorized as Pre-Action and Post-Action workflows, validate the environment's readiness for promotion: - * Pre-Action Workflow: Executes before changes are committed to ensure the environment meets predefined criteria. + * Pre-Action Workflow: Executes before changes are committed to ensure the target environment meets predefined criteria. * Post-Action Workflow: Executes after changes are committed to verify the environment's stability and functionality post-deployment. While optional, we highly recommend adding these workflows to environments to enhance deployment reliability and consistency. You can select from available Promotion Workflows or create a new Pre- or Post-Action Workflow as needed. -* Inter-environment dependencies +* Promotion Action (required) + The Promotion Action is the action that activates and propagates the changes to the current environment, and can be Commit, Pull Request, or No Action. The Action is generally defined as part of the Promotion Policy. You can also select an action on-the-fly + +* Product (optional) + Instead of manually applying Pre-Action, Post-Action, and Action for each environment, you can select a Product to apply the Promotion Policy defined for it to all environments defined, excluding the trigger environment. + + The promotion policy defined for the Product dictates the Pre-Action, Post-Action, and Action for each environment. You retain the flexibility to configure parts of the Promotion Policy not defined in the Product. + This allows you to customize specific steps or workflows as needed, while still leveraging the overall Product policy. + + + +Inter-environment dependencies In both sequential and parallel flows, adding a new environment automatically establishes a dependency on the previous environment. This ensures that changes are promoted in a controlled manner. - For parallel flows, you can add multiple environments as simultaneous dependencies on new environments. This means that the changes from the previous environment are promoted concurrently to each of the dependent environments, and only when successfully deployed across all environments are they promoted to the next environment in the flow. + For parallel flows, you can add multiple environments as simultaneous dependencies on new environments. This means that the changes from the previous environment are first promoted concurrently to each of the dependent environments, and only when successfully deployed across all environments are they promoted to the next environment in the flow. @@ -92,39 +93,106 @@ Before creating Promotion Flows it is advisable to understand the role of the co ## Create Promotion Flow with Flow Builder Visually design and create the flow by selecting environments, promotion workflows, setting trigger conditions, and defining dependencies through the Flow Builder. If needed add new environments and promotion workflows on-the-fly when doing so. -##### Before you begin +### Before you begin * Review * -##### How to +### Step 1: Add a Promotion Flow +Add the Promotion Flow to 1. In the Codefresh UI, on the toolbar, click the **Settings** icon, and then from the sidebar, select **Promotion Flows**. 1. Click **Add Promotion Flow**. -1. Select the trigger environment: - 1. Click ?? to see the list of available environments. - 1. Do one of the following: - * To add an existing environment, select it and click **Add**. Continue from step ?? - * To create a new environment, click **Add New Environment**. -1. Select the next environment to promote to: - 1. Mouse over the right of the current environment and click ??. - 1. Do one of the following: - * To add an existing environment, select it and click **Add**. Continue from step ?? - * To create a new environment, click **Add New Environment**. - The Create Environment form is displayed. See ???? - A notification alerts you that are unsaved changes to the Promotion Flow. -1. Add Pre- and Post-Action Workflows: - 1. Mouse over the connector between the two environments. - 1. To add a Pre-Action Workflow, click the top ??? icon. - 1. To add a Post-Action Workflow, click the lower ??? icon. - 1. From the list displayed, do one of the following: - * To add an existing Pre- or Post-Action Workflow, select it and click **Add**. Continue from step ?? - * To add a new Workflow, click **Add New Workflow**. - The Add Promotion Workflows form is displayed. See ???? + +### Step 2: Select Trigger Environment +Evry Promotion Flow starts from a Trigger Environment where the change is first made. +You can either select a predefined environment or create a new environment and then return to the Promotion Flow and select the environment. + + +1. Click ?? to see the list of available environments. +1. Do one of the following: +1. To add an existing environment, select it and click **Add**. Continue from step ?? +1. To create a new environment, click **Add New Environment**. + * You are taken to the Environments page and the Create Environment form is displayed. See ???? + * A notification alerts you that are unsaved changes to the Promotion Flow. + This notification remains as long as you are unsaved changes and you are in different UI. +1. To return to the Promotion Flow and continue, click **Go to Promotion Flow**. + You ccan now pick up from where you left off. + + + + +### Step 3: Select environment to promote to +Add the environment to promote to from the trigger environment. Again, you can select a predefined environment or create a new environment and then return to the Promotion Flow and select the environment. + + + +1. Mouse over the right of the current environment and click ??. +1. To add an existing environment, select it and click **Add**. Continue from step ?? +1. To create a new environment, click **Add New Environment**. + * You are taken to the Environments page and the Create Environment form is displayed. See ???? + * A notification alerts you that are unsaved changes to the Promotion Flow. + This notification remains as long as you have unsaved changes and you are in different UI. +1. To return to the Promotion Flow and continue, click **Go to Promotion Flow**. + You can now pick up from where you left off. +1. To + +### Step 4: (Optional) Select a Product to apply Promotion Policy +Select a product to automatically apply its Promotion Policy to all environments defined, excluding the trigger environment. +This is an alternative to manually applying Pre-Action, Post-Action, and Action for each environment (described in Steps 5 and 6). + +Promotion Policy ??? + +1. From the list of Products, select the product with the Promotion Policy to apply. + The Pre-Action, Post-Action, and Action defined for the Policy are assigned to all the environments. + Mouse over the Pre-Action, Post-Action, and Action icons to see the Workflows and the Promotion Action assigned. + + If the Policy does not match an environment, it will not apply any of the Policy components. + +1. If any component is not defined for the Policy, click the corresponding icon and assign a Workflow or an Action. + + +### Step 5: Select Promotion Action + + The See ???? A notification alerts you that are unsaved changes to the Promotion Flow. -1. If needed, create dependencies on the next environment: + + Inline not defined = Undefined + +### Step 6: (Optional) Add Pre- and Post-Action Workflows +1. Mouse over the connector on the left between the two environments. +1. To add a Pre-Action Workflow, click the top ??? icon. +1. To add a Post-Action Workflow, click the lower ??? icon. +1. To add an existing Pre- or Post-Action Workflow, select it and click **Add**. Continue from step ?? +1. To add a new Workflow, click **Add New Workflow**. + * You are taken to the Promotion Workflows page and the Add Promotion Workflows form is displayed. See ???? + * A notification alerts you that are unsaved changes to the Promotion Flow. + This notification remains as long as you have unsaved changes and you are in different locations in the UI. +1. To return to the Promotion Flow and continue, click **Go to Promotion Flow**. + You can now pick up from where you left off. + + + + + +### Step 7: Add additional environments + +1. Mouse over the right of the current environment and click ??. +1. To add environments for parallel Flows creating dependencies on the next environment: 1. Mouse over the current environment. 1. From the **Depends on** list, select the environment and click **Update dependency**. - The environment is added below the existing environment, and a link is added between it and the next environment to indicate a dependency. + The environment is added below the existing environment, and a link is added between it and the next environment to indicate a dependency. +1. Repeat step 1 and step 2 as needed. + +### Step 8: Save changes and commit flow 1. Click **Save Promotion Flow** to commit changes. + + +## Manually trigger a Promotion Flow + + + + +## Troubleshooting Promotion Flow creation + From f1982c1c2ad5519dd74b05366ef0a6a34cbf1eda Mon Sep 17 00:00:00 2001 From: NimRegev Date: Mon, 12 Aug 2024 14:26:18 +0300 Subject: [PATCH 04/61] Create manually-trigger-promotion.md --- _docs/promotions/manually-trigger-promotion.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 _docs/promotions/manually-trigger-promotion.md diff --git a/_docs/promotions/manually-trigger-promotion.md b/_docs/promotions/manually-trigger-promotion.md new file mode 100644 index 000000000..12565cf5c --- /dev/null +++ b/_docs/promotions/manually-trigger-promotion.md @@ -0,0 +1,6 @@ +--- +title: "Manually trigger promotions" +description: "Manually trigger a promotion flow to initiate deployments " +group: promotions +toc: true +--- \ No newline at end of file From b9bfdafc6458db581d4331988c1cc7eb67cc3ab1 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Thu, 22 Aug 2024 13:05:08 +0300 Subject: [PATCH 05/61] Add promotion outline --- _docs/promotions/promotion-components.md | 124 +++++++++++++++++++++++ _docs/promotions/promotion-flow.md | 109 +++++++++++++++++++- 2 files changed, 228 insertions(+), 5 deletions(-) create mode 100644 _docs/promotions/promotion-components.md diff --git a/_docs/promotions/promotion-components.md b/_docs/promotions/promotion-components.md new file mode 100644 index 000000000..5fbebace3 --- /dev/null +++ b/_docs/promotions/promotion-components.md @@ -0,0 +1,124 @@ + + + + + + + +The table describes the entities involved in the promotion process, starting with the core entities and those entities wh + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EntityRole in promotionsCreated byLearn more
Core entities
These entities define the structure of your deployment.
Environments (Required)Environments are where your applications live and promotions happen. Typically, environments reflect your software lifecycle and deployment stages. You need at least two environments: +
    +
  • Trigger environment: Where a change starts the promotion flow, initiated by a manual commit or pull request.
    • +
  • Target environments: The environments where changes are promoted after the trigger environment.
    • +
+ 		Users with ABAC permissionsLink
Product (Optional)A Product in GitOps groups related applications into a single entity. This simplifies promotions by allowing you to promote the entire Product and all its applications across different environments, rather than managing applications individually.Users with ABAC permissionsLink
ApplicationsApplications are the core units around which promotions revolve. Each application can be promoted individually or as part of a product.Users with ABAC permissionsLink
Promotion Building Blocks
These entities define how promotions are orchestrated, what gets promoted, and under what conditions.
Promotion FlowsPromotion flows orchestrate the movement of applications through environments, ensuring a controlled and automated promotion process.Account administratorsLink
Promotion SettingsPromotion settings specify what gets promoted across environments. If using a Product, these settings can be defined within the Product’s configuration or in a YAML CRD.Users with ABAC permissionsLink
Promotion PolicyA Promotion Policy outlines the actions taken when changes are promoted. It ensures that the target environment is ready for promotion, with workflows to validate the environment both before and after the promotion action, like commits or pull requests.Account administratorsLink
+ +## Promotion entites and GitOps Runtimes + +All promotion entities are stored as part of GitOps Runtimes in the Shared Configuration Repository. Depending on wheyjr are required across all runtimes and clusters or specific runtimes and clusters. + +{: .table .table-bordered .table-hover} +| Entity | Location | Toekn +| -------------- | -------------- | +| Environments |- | | +| Product |user-isc/resources/configuration/products | | +| Applications |Git Source associated with Runtime | | +| Promotion Workflows |isc/resources/all-runtimes-all-clusters/promotion-workflows |should be covered by ABAC, and commit done via Runtime Token.reason for having to be stored in the ISC is that is needs to be in all clusters and run | +| Promotion Template |isc/configuration/promotion-templates| | +| Promotion Policy |isc/configuration/promotion-policies| | +| Promotion Flow |isc/configuration/promotion-flows| | + +## Promotion entities & creation modes + +UI form YAML + +## Promotion sequence guide +prereq +GitOps runtime as configuration runtime +Admin permissios + +1. Create environments + +1. Create product + + +1. Create applications + +1. Create promotion workflows + +1. Create promotion templates + +1. Create promotion policy + +1. Create promotion flow + +1. Configure settings for product + +1. Trigger promotion flow + +1. Track deployment for product + +## Promotion process +What happens when a promotion flow is triggerred automatically? +Manually through drag-n-drop + + + diff --git a/_docs/promotions/promotion-flow.md b/_docs/promotions/promotion-flow.md index 42cc2ed0b..d18ee8b3c 100644 --- a/_docs/promotions/promotion-flow.md +++ b/_docs/promotions/promotion-flow.md @@ -61,7 +61,21 @@ Before creating Promotion Flows it is advisable to understand the role of these * Target environments Any environment apart from the trigger environment are target environments in the promotion flow. A Promotion Flow requires at least one target environment. Target environments can linear or parallel. - + +* Product (optional) + Instead of manually applying Pre-Action, Post-Action, and Action for each environment, you can select a Product to apply the Promotion Policy defined for it to all environments defined, excluding the trigger environment. + + The promotion policy defined for the Product dictates the Pre-Action, Post-Action, and Action for each environment. You retain the flexibility to configure parts of the Promotion Policy not defined in the Product. + This allows you to customize specific steps or workflows as needed, while still leveraging the overall Product policy. + +* Applications + + +* Promotion Settings + + +* Promotion Policy + * Promotion Workflows (optional) Promotion workflows, categorized as Pre-Action and Post-Action workflows, validate the environment's readiness for promotion: @@ -73,12 +87,97 @@ Before creating Promotion Flows it is advisable to understand the role of these * Promotion Action (required) The Promotion Action is the action that activates and propagates the changes to the current environment, and can be Commit, Pull Request, or No Action. The Action is generally defined as part of the Promotion Policy. You can also select an action on-the-fly -* Product (optional) - Instead of manually applying Pre-Action, Post-Action, and Action for each environment, you can select a Product to apply the Promotion Policy defined for it to all environments defined, excluding the trigger environment. - The promotion policy defined for the Product dictates the Pre-Action, Post-Action, and Action for each environment. You retain the flexibility to configure parts of the Promotion Policy not defined in the Product. - This allows you to customize specific steps or workflows as needed, while still leveraging the overall Product policy. + + +| **Entity** | **How does i ** | **Where and When** | **By Whom** | **Learn more** | +|----------------------|---------------------------|--------------------|-------------| +| **Environments (required)** | Environments are where your applicatios live and promotions happen. Typically environments reflect your software lifecyle and deployment lifecyle. Create environments. You need at least two: Trigger environment: The trigger environment is where a change initiates the promotion flow. The change in the trigger environment is a manual user commit or pull request action.
Target environments: Any environment apart from the trigger environment are target environments in the promotion flow. A Promotion Flow requires at least one target environment. | First step in promotion | Users with ABAC | +| **Product (optional)** | A Product is a specialized entity in Codefresh GitOps which groups related applications and treats them a single cohesdive entity. Why is this important for promotions? With product instead of promoting individual applocations you can promote the productand all applications within it across different environments. | Defining a Porduct allows you to configure several settings connected to promotions in a single location. | Users with ABAC | Link?? +| **Applications** | Applications are the smallest entity around which promotions revolve. | | | +| **Promotion Flows** | Promotion flows orchestrate the promotion of a product through different environments according t | | | +| **Promotion Settings** | Promotion settings define exactly what gets promoted in the different applicatins and across what environments. if you have created a product, you can define promotion settings as part of the product's settings. You can also define it in the CRD. | | | +| **Promotion Policy** | Defines what is done in the next environment when there is a change that initiates promotion. It validates that th environment is ready for the promotion through promotion workflows and promotion action. The promotion action is the action through a commit or a PR or a predefined mechanism that propagates the changes defined by promotion settings to the target environment. Promotion workflows are what ensures that the target environment - these can be verifying predefined criteria before the promotion changes are implemented, and verifing the environment's stability and functionality post-promotion action. | | | + + + + +| **Component** | **Role in Promotion Process** | **Where and When** | **Who Can Create** | **Additional Resources** | +|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|---------------------------|---------------------------| +| **Environments (Required)** | Environments are where your applications live and promotions happen. Typically, environments reflect your software lifecycle and deployment stages. You need at least two environments:
- **Trigger Environment**: Where a change starts the promotion flow, initiated by a manual commit or pull request.
- **Target Environments**: The environments where changes are promoted after the trigger environment. | First step in the promotion process | Users with ABAC permissions | [Link] | +| **Product (Optional)** | A Product in Codefresh GitOps groups related applications into a single entity. This simplifies promotions by allowing you to promote the entire Product and all its applications across different environments, rather than managing them individually. | Centralized promotion settings | Users with ABAC permissions | [Link] | +| **Applications** | Applications are the core units around which promotions revolve. Each application can be promoted individually or as part of a Product. | Part of each environment | Users with ABAC permissions | [Link] | +| **Promotion Flows** | Promotion flows orchestrate the movement of changes through environments, ensuring a controlled and automated promotion process. | Defined in the Promotion Flow UI | Users with ABAC permissions | [Link] | +| **Promotion Settings** | Promotion settings specify what gets promoted across environments. If using a Product, these settings can be defined within the Product’s configuration or in a YAML CRD. | Defined during product setup | Users with ABAC permissions | [Link] | +| **Promotion Policy** | A Promotion Policy outlines the actions taken when changes are promoted. It ensures that the target environment is ready for promotion, with workflows to validate the environment both before and after the promotion action, like commits or pull requests. | Applied during the promotion process | Users with ABAC permissions | [Link] | + +The table describes the entities involved in the promotion process, starting with the core entities and those entities wh + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EntityRole in promotionsCreated byLearn more
Core entities
These entities define the structure of your deployment.
Environments (Required)Environments are where your applications live and promotions happen. Typically, environments reflect your software lifecycle and deployment stages. You need at least two environments: +
    +
  • Trigger environment: Where a change starts the promotion flow, initiated by a manual commit or pull request.
    • +
  • Target environments: The environments where changes are promoted after the trigger environment.
    • +
+ 		Users with ABAC permissionsLink
Product (Optional)A Product in Codefresh GitOps groups related applications into a single entity. This simplifies promotions by allowing you to promote the entire Product and all its applications across different environments, rather than managing applications individually.Users with ABAC permissionsLink
ApplicationsApplications are the core units around which promotions revolve. Each application can be promoted individually or as part of a product.Users with ABAC permissionsLink
Promotion Building Blocks
These entities define how promotions are orchestrated, what gets promoted, and under what conditions.
Promotion FlowsPromotion flows orchestrate the movement of applications through environments, ensuring a controlled and automated promotion process.Account administratorsLink
Promotion SettingsPromotion settings specify what gets promoted across environments. If using a Product, these settings can be defined within the Product’s configuration or in a YAML CRD.Users with ABAC permissionsLink
Promotion PolicyA Promotion Policy outlines the actions taken when changes are promoted. It ensures that the target environment is ready for promotion, with workflows to validate the environment both before and after the promotion action, like commits or pull requests.Account administratorsLink
+ + Inter-environment dependencies From ca6937bbdaae982bd42995cc46e013d0efd59d36 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Sun, 25 Aug 2024 15:49:43 +0300 Subject: [PATCH 06/61] Update promotion-components.md Fleshed out high-level flow for promotion sequence --- _docs/promotions/promotion-components.md | 83 ++++++++++++++++++------ 1 file changed, 63 insertions(+), 20 deletions(-) diff --git a/_docs/promotions/promotion-components.md b/_docs/promotions/promotion-components.md index 5fbebace3..7c239dbcb 100644 --- a/_docs/promotions/promotion-components.md +++ b/_docs/promotions/promotion-components.md @@ -5,7 +5,7 @@ -The table describes the entities involved in the promotion process, starting with the core entities and those entities wh +The table describes the entities involved in the promotion process, starting with the core entities, followed by the dedicated promotion-specific entities @@ -24,7 +24,7 @@ The table describes the entities involved in the promotion process, starting wit @@ -33,7 +33,7 @@ The table describes the entities involved in the promotion process, starting wit - + @@ -46,26 +46,26 @@ The table describes the entities involved in the promotion process, starting wit - + - + - + - + @@ -73,7 +73,7 @@ The table describes the entities involved in the promotion process, starting wit ## Promotion entites and GitOps Runtimes -All promotion entities are stored as part of GitOps Runtimes in the Shared Configuration Repository. Depending on wheyjr are required across all runtimes and clusters or specific runtimes and clusters. +All promotion entities are stored as CRDs in the Shared Configuration Repository of the GitOps Runtime designated as the Configuration Runtime. If you have more than one Configuration Runtime, Codefresh automatically consolidates the settings into a single set of promotion CRDs. {: .table .table-bordered .table-hover} | Entity | Location | Toekn @@ -90,31 +90,74 @@ All promotion entities are stored as part of GitOps Runtimes in the Shared Confi UI form YAML -## Promotion sequence guide -prereq -GitOps runtime as configuration runtime -Admin permissios +## Create a promotion sequence +The guide provides the steps required to create a promotion sequence. Follow the steps in the order in which they are listed. Each step is followed by a brief description of its purpose and objective in the promotion sequence. For detailed information, click the step title. -1. Create environments -1. Create product +### Prerequisites +1. Configuration Runtime + At least one GitOps Runtime must be designated as the Cofiguration Runtime to store the settings of the different promotion entities. + If no GitOps Runtime has been designated as such, Codefresh assigns one of the existing Runtimes. + +1. Admin permissions + Only account admins can create promotion entities such as Promotion Policies and Promotion Flows. +1. User permissions + Users need the required ABAC permissions to create Promotion Workflows and configure product settings. +### How to +1. Create environments + Environments define the starting and the end points of promotions. + For a promotion sequence, you need at least two environments: the trigger environment, which is the source of the changes to promote, and the target environment, to which the changes need to be promoted. + 1. Create applications + Applications represent the components or services to promote and deploy. They are the smallest unit of deployment within a promotion sequence. + Create a Argo CD application in Form or YAML mode. + +1. Create products + Products connect related applications and group them as a single entity. Being able to apply promotion settings at the level of the product, across multiple applications simplifies promotion flows and management. -1. Create promotion workflows + Create a product and connect related applications to it, either manually or declaratively. -1. Create promotion templates -1. Create promotion policy +1. Create workflows + Promotion Workflows consist of steps to validate and verify readiness of target environments in the promotion sequence. + Create Promotion Workflows tailored to different environments, and integrate them into Promotion Policies to enforce checks before and after promotions. + +1. Configure properties to be promoted + Promotion Templates define which files and attributes within those files to promote across the applications in the product. + Instead of doing a manual diff and deciding which changes to promote, or promoting entire applications, configure the precise changes to promote, ensuring consistency and reducing errors. + +1. Create validations for environments + Promotion Policies define the rules that validate the target environments before and after changes are promoted, along with the action that promotes the changes. These Policies ensure that promotions do not break or destabilize environments. + Create a Promotion Policy by product or type of environment, specifying the promotion action (mandatory), and any Promotion Workflows to run before and after the promotion action (optional). + +1. Create flows for promotions + Promotion Flows orchestrate the sequence of actions that move changes through the deifned environments. + Create a Promotion Flow to integrate environments, products and applications, promotion workflows, and policies, ensuring that changes are promoted in a controlled and predictable manner. + -1. Create promotion flow +1. Configure promotion settings for product + After setting up the core entities and building blocks, configure settings for your product. + These settings can include the attributes to be promoted across the product's applications (Promotion Templates), the promotion flows valid for the product and flow-specific trigger conditions (Promotion Flows). -1. Configure settings for product +1. Trigger promotion flow + Implement the changes to initiate the promotion sequence. + The change, made to an application in the trigger environment, starts the process of moving changes from the trigger environment through the defined sequence of environments, following the defined Promotion Policies and Settings. + + If the flow is not triggered automatically through the trigger conditions, or trigger a Flow manually by clicking the Trigger button, or by dragging and dropping a single application with the changes to a different environment. -1. Trigger promotion flow 1. Track deployment for product + Monitor the deployment progress for the product as it moves through the promotion sequence. + Use the Releases feature to track and ensure successful deployments across environments. + + + + + + + ## Promotion process What happens when a promotion flow is triggerred automatically? From bf6570f9a147b7213cc3fa5634b8209a01043870 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Mon, 9 Sep 2024 10:12:22 +0300 Subject: [PATCH 07/61] Update promotion content Content updates for promotion flow creation, end-to-end guide to create and deploy, and promotion components --- _docs/promotions/create-promotion-sequence.md | 75 ++++ _docs/promotions/promotion-components.md | 120 +++--- _docs/promotions/promotion-flow.md | 371 ++++++++---------- ...ger-promotion.md => trigger-promotions.md} | 0 images/icons/delete-red.png | Bin 0 -> 414 bytes images/icons/flow-builder-add-workflow.png | Bin 0 -> 4562 bytes 6 files changed, 295 insertions(+), 271 deletions(-) create mode 100644 _docs/promotions/create-promotion-sequence.md rename _docs/promotions/{manually-trigger-promotion.md => trigger-promotions.md} (100%) create mode 100644 images/icons/delete-red.png create mode 100644 images/icons/flow-builder-add-workflow.png diff --git a/_docs/promotions/create-promotion-sequence.md b/_docs/promotions/create-promotion-sequence.md new file mode 100644 index 000000000..4d35a295b --- /dev/null +++ b/_docs/promotions/create-promotion-sequence.md @@ -0,0 +1,75 @@ +--- +title: "Promotion sequences" +description: "Step-by-step guide to creating promotions" +group: promotions +toc: true +--- + + +This step-by-step guide lists the steps required to create a promotion sequence. Follow the steps in the order in which they are listed. Each step is followed by a brief description of its purpose and objective in the promotion sequence. For detailed information, click the step title. + + +## Prerequisites +1. [Configuration Runtime]({{site.baseurl}}/docs/installation/gitops/monitor-manage-runtimes/#designating-configuration-runtimes) + The Configuration Runtime is a GitOps Runtime that stores the manifests of the promotion entities. + Designate at least one GitOps Runtime as the Cofiguration Runtime. + If no GitOps Runtime has been designated as such, Codefresh assigns one of the existing Runtimes. + +1. Admin permissions + Only account admins can create promotion entities such as Promotion Policies and Promotion Flows. + +1. [User permissions]({{site.baseurl}}/docs/administration/account-user-management/gitops-abac/) + Users need the required ABAC permissions to create Promotion Workflows and configure product settings. + +## How to: Step-by-step +1. [Create environments]({{site.baseurl}}/docs/dashboards/gitops-environments/#create-environments) + Environments define the starting and the end points of promotions. + For a promotion sequence, you need at least two environments: the trigger environment, which is the source of the changes to promote, and the target environment, to which the changes need to be promoted. + +1. [Create applications]({{site.baseurl}}//docs/deployments/gitops/create-application/#create-an-argo-cd-application) + Applications represent the components or services to promote and deploy. They are the smallest unit of deployment within a promotion sequence. + Create a Argo CD application in Form or YAML mode. + +1. [Create products]({{site.baseurl}}/docs/products/create-product/) + Products connect related applications and group them as a single entity. + Being able to apply promotion settings at the level of the product, and being able to promote the product with all its applications, simplifies promotion management. + + Create a product and connect related applications to it, either manually or declaratively. + + +1. [Create workflows]({{site.baseurl}}/docs/promotions/promotion-workflows/) + Before promoting changes across environments, it's customary to run tests and validations that match the requirements of the target environments in the promotion sequence. + Promotion Workflows allow you to create steps and testing different environments, and enforce checks before and after promoting changes. + +1. [Configure properties to be promoted] + Instead of doing a manual diff and deciding which changes to promote, or promoting entire applications, configure the precise changes to promote, ensuring consistency and reducing errors. + Promotion Templates define which files and attributes within those files to promote across the applications in the product. + + +1. [Create promotion policies for environments]({{site.baseurl}}/docs/promotions/promotion-policy/) + Define the conditions to validate that the target environments are ready for promotion: workflows to run before and after changes are promoted, along with the action that promotes the changes. Enforcing these conditions ensure that promotions do not break or destabilize environments. + + Promotion Policies define the products or type of environments with the promotion action (mandatory), and any Promotion Workflows to run before and after the promotion action (optional). + +1. [Create flows to orchestrate promotions]({{site.baseurl}}/docs/promotions/promotion-flow/) + Orchestrate the sequence of actions to move and deploy changes through the required environments, from the trigger environment to the final target environment. + Promotion Flows ensure that changes are promoted in a controlled and predictable manner by integrating environments, products and applications, promotion workflows, and policies. + + +1. Configure [promotion settings]({{site.baseurl}}/docs/products/configure-product-settings/#configure-promotion-settings) and [flows]({{site.baseurl}}/products/configure-product-settings/#configure-promotion-flows) for product + After setting up the core entities and building blocks, configure settings for your product. + These settings can include the attributes to be promoted across the product's applications (Product Promotion Templates), the promotion flows valid for the product and flow-specific trigger conditions (Promotion Flows). + +1. [Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/) + Implement the changes to initiate the promotion sequence. + The change, made to an application in the trigger environment, starts the process of moving changes from the trigger environment through the defined sequence of environments, following the defined Promotion Policies and Settings. + TBD + + +1. [Track deployments for products]({{site.baseurl}}/docs/promotions/releases/) + Monitor the deployment progress for the product as it moves through the promotion sequence. + Use the Releases feature to track and ensure successful deployments across environments. + + +## Related articles + diff --git a/_docs/promotions/promotion-components.md b/_docs/promotions/promotion-components.md index 7c239dbcb..0e67f3af0 100644 --- a/_docs/promotions/promotion-components.md +++ b/_docs/promotions/promotion-components.md @@ -2,10 +2,39 @@ +Promotion flows are not tied to any specific product or technology stack, making them versatile tools for managing deployments across various platforms. They can be applied to: +Consistency: Automates repetitive tasks, ensuring uniformity across deployments. +Efficiency: Reduces manual effort and accelerates the deployment process. +Control: Allows precise control over the conditions under which changes are promoted. +Visibility: Provides clear insights into the progress and status of changes across environments. +Contribution to Deployments +Promotion flows streamline the process of moving code changes through different stages, such as testing, staging, and production. By defining specific criteria for promotion, they help maintain the integrity of the software and reduce the likelihood of introducing bugs into production. +## Flow Builder vs. YAML +You can create Promotion Workflows through the Flow Builder, a graphical interface, or through a YAML Custom Resource Definition (CRD). You can switch seamlessly between both when creating Promotion Flows. -The table describes the entities involved in the promotion process, starting with the core entities, followed by the dedicated promotion-specific entities +## Sequential vs. parallel promotions + +Promotion Flows can be designed to run sequentially or in parallel to suit the unique requirements of any deployment process. + +Sequential flows +Sequential flows are linear, where changes are promoted from the previous to the next environment in the order in which they are defined. +This is the more common and traditional kind of Promotion Flow where you start the flow from the development environment as the trigger environment, and then promote to the testing, staging, and finally to the production environments. + +Parallel flows +In a parallel flow, changes are promoted across multiple environments simultaneously. This promotion logic groups environments to create promotions after multiple environments are healthy. + + + + +## Promotion building blocks + +A promotion sequence comprises several building blocks, optional and required, each serving a specific role in the promotion and deployment process. +Before creating promotion flows or sequences it is advisable to understand the role of these building blocks. + + +The table describes the entities involved in the promotion process, starting with the core entities and those entities wh
Environments are where your applications live and promotions happen. Typically, environments reflect your software lifecycle and deployment stages. You need at least two environments:
  • Trigger environment: Where a change starts the promotion flow, initiated by a manual commit or pull request.
    • -
  • Target environments: The environments where changes are promoted after the trigger environment.
    • +
  • Target environments: The environments to which changes are promoted from the trigger environment.
 Users with ABAC permissions
Product (Optional)A Product in GitOps groups related applications into a single entity. This simplifies promotions by allowing you to promote the entire Product and all its applications across different environments, rather than managing applications individually.By grouping related applications, products simplify promotions by allowing you to promote the entire product and all its applications across different environments. Users with ABAC permissions Link
Promotion Building Blocks
These entities define how promotions are orchestrated, what gets promoted, and under what conditions.		Promotion entities
These dedicated entities are the building blocks of promotions, defining how promotions are orchestrated, what gets promoted, and under what conditions.
Promotion FlowsPromotion flows orchestrate the movement of applications through environments, ensuring a controlled and automated promotion process.Promotion Flows orchestrate the movement of applications in products through environments, ensuring a controlled and automated promotion process. Account administrators Link
Promotion SettingsPromotion settings specify what gets promoted across environments. If using a Product, these settings can be defined within the Product’s configuration or in a YAML CRD.Promotion Settings specify what gets promoted across environments. If using a product, these settings can be defined within the product’s configuration or in a YAML CRD. Users with ABAC permissions Link
Promotion PolicyA Promotion Policy outlines the actions taken when changes are promoted. It ensures that the target environment is ready for promotion, with workflows to validate the environment both before and after the promotion action, like commits or pull requests.Promotion Policies outline the actions taken when changes are promoted for products or by environments. The Promotion Policy ensures that the target environment is ready for promotion, with workflows to validate the environment both before and after the promotion action, like commits or pull requests. Account administrators Link
@@ -24,7 +53,7 @@ The table describes the entities involved in the promotion process, starting wit @@ -33,7 +62,7 @@ The table describes the entities involved in the promotion process, starting wit - + @@ -46,34 +75,49 @@ The table describes the entities involved in the promotion process, starting wit - + - + - + - +
Environments are where your applications live and promotions happen. Typically, environments reflect your software lifecycle and deployment stages. You need at least two environments:
  • Trigger environment: Where a change starts the promotion flow, initiated by a manual commit or pull request.
    • -
  • Target environments: The environments to which changes are promoted from the trigger environment.
    • +
  • Target environments: The environments where changes are promoted after the trigger environment.
 Users with ABAC permissions
Product (Optional)By grouping related applications, products simplify promotions by allowing you to promote the entire product and all its applications across different environments.A Product in Codefresh GitOps groups related applications into a single entity. This simplifies promotions by allowing you to promote the entire Product and all its applications across different environments, rather than managing applications individually. Users with ABAC permissions Link
Promotion entities
These dedicated entities are the building blocks of promotions, defining how promotions are orchestrated, what gets promoted, and under what conditions.		Promotion Building Blocks
These entities define how promotions are orchestrated, what gets promoted, and under what conditions.
Promotion FlowsPromotion Flows orchestrate the movement of applications in products through environments, ensuring a controlled and automated promotion process.Promotion flows orchestrate the movement of applications through environments, ensuring a controlled and automated promotion process. Account administrators Link
Promotion SettingsPromotion Settings specify what gets promoted across environments. If using a product, these settings can be defined within the product’s configuration or in a YAML CRD.Promotion settings specify what gets promoted across environments. If using a Product, these settings can be defined within the Product’s configuration or in a YAML CRD. Users with ABAC permissions Link
Promotion PolicyPromotion Policies outline the actions taken when changes are promoted for products or by environments. The Promotion Policy ensures that the target environment is ready for promotion, with workflows to validate the environment both before and after the promotion action, like commits or pull requests.A Promotion Policy outlines the actions taken when changes are promoted. It ensures that the target environment is ready for promotion, with workflows to validate the environment both before and after the promotion action, like commits or pull requests. Account administrators Link
+ + + +Inter-environment dependencies + In both sequential and parallel flows, adding a new environment automatically establishes a dependency on the previous environment. This ensures that changes are promoted in a controlled manner. + + For parallel flows, you can add multiple environments as simultaneous dependencies on new environments. This means that the changes from the previous environment are first promoted concurrently to each of the dependent environments, and only when successfully deployed across all environments are they promoted to the next environment in the flow. + + + + + + + ## Promotion entites and GitOps Runtimes -All promotion entities are stored as CRDs in the Shared Configuration Repository of the GitOps Runtime designated as the Configuration Runtime. If you have more than one Configuration Runtime, Codefresh automatically consolidates the settings into a single set of promotion CRDs. +All promotion entities are stored as manifests in the Shared Configuration Repository of the GitOps Runtime designated as the Configuration Runtime. +If you have more than one Configuration Runtime, Codefresh automatically consolidates the settings into a single set of promotion manifests. {: .table .table-bordered .table-hover} | Entity | Location | Toekn @@ -90,67 +134,7 @@ All promotion entities are stored as CRDs in the Shared Configuration Repository UI form YAML -## Create a promotion sequence -The guide provides the steps required to create a promotion sequence. Follow the steps in the order in which they are listed. Each step is followed by a brief description of its purpose and objective in the promotion sequence. For detailed information, click the step title. - - -### Prerequisites -1. Configuration Runtime - At least one GitOps Runtime must be designated as the Cofiguration Runtime to store the settings of the different promotion entities. - If no GitOps Runtime has been designated as such, Codefresh assigns one of the existing Runtimes. - -1. Admin permissions - Only account admins can create promotion entities such as Promotion Policies and Promotion Flows. - -1. User permissions - Users need the required ABAC permissions to create Promotion Workflows and configure product settings. - -### How to -1. Create environments - Environments define the starting and the end points of promotions. - For a promotion sequence, you need at least two environments: the trigger environment, which is the source of the changes to promote, and the target environment, to which the changes need to be promoted. - -1. Create applications - Applications represent the components or services to promote and deploy. They are the smallest unit of deployment within a promotion sequence. - Create a Argo CD application in Form or YAML mode. - -1. Create products - Products connect related applications and group them as a single entity. Being able to apply promotion settings at the level of the product, across multiple applications simplifies promotion flows and management. - - Create a product and connect related applications to it, either manually or declaratively. - - -1. Create workflows - Promotion Workflows consist of steps to validate and verify readiness of target environments in the promotion sequence. - Create Promotion Workflows tailored to different environments, and integrate them into Promotion Policies to enforce checks before and after promotions. - -1. Configure properties to be promoted - Promotion Templates define which files and attributes within those files to promote across the applications in the product. - Instead of doing a manual diff and deciding which changes to promote, or promoting entire applications, configure the precise changes to promote, ensuring consistency and reducing errors. - -1. Create validations for environments - Promotion Policies define the rules that validate the target environments before and after changes are promoted, along with the action that promotes the changes. These Policies ensure that promotions do not break or destabilize environments. - Create a Promotion Policy by product or type of environment, specifying the promotion action (mandatory), and any Promotion Workflows to run before and after the promotion action (optional). - -1. Create flows for promotions - Promotion Flows orchestrate the sequence of actions that move changes through the deifned environments. - Create a Promotion Flow to integrate environments, products and applications, promotion workflows, and policies, ensuring that changes are promoted in a controlled and predictable manner. - - -1. Configure promotion settings for product - After setting up the core entities and building blocks, configure settings for your product. - These settings can include the attributes to be promoted across the product's applications (Promotion Templates), the promotion flows valid for the product and flow-specific trigger conditions (Promotion Flows). - -1. Trigger promotion flow - Implement the changes to initiate the promotion sequence. - The change, made to an application in the trigger environment, starts the process of moving changes from the trigger environment through the defined sequence of environments, following the defined Promotion Policies and Settings. - - If the flow is not triggered automatically through the trigger conditions, or trigger a Flow manually by clicking the Trigger button, or by dragging and dropping a single application with the changes to a different environment. - -1. Track deployment for product - Monitor the deployment progress for the product as it moves through the promotion sequence. - Use the Releases feature to track and ensure successful deployments across environments. diff --git a/_docs/promotions/promotion-flow.md b/_docs/promotions/promotion-flow.md index d18ee8b3c..245d9859a 100644 --- a/_docs/promotions/promotion-flow.md +++ b/_docs/promotions/promotion-flow.md @@ -1,297 +1,262 @@ --- -title: "Promotion orchestration" -description: "Create flows to orchestrate promotion for products across environments" -group: deployments +title: "Creating Promotion Flows" +description: "Create Promotion Flows to orchestrate promotion for products across environments" +group: promotions toc: true --- A Promotion Flow is a structured sequence of actions that automates the promotion of changes in products through various environments until deployment. It ensures that code changes are automatically, systematically, and consistently moved, from development to production environments, enhancing the reliability and efficiency of deployments. -Benefits of Promotion Flows -Simplicity +Our Flow Builder visually guides you through creating any type of Promotion Flow. See [Create a Promotion Flow](#create-a-promotion-flow). +As with other entities, you can toggle between YAML and chart modes while in the Flow Builder. -Automated deployment +Before creating promotion flows, review [our notes on Promotion Flows](#notes-on-promotion-flows) which highlights key factors to be aware of in promotion flow behavior. -Promotion logic + -4. Applying Promotion Flows -Promotion flows are not tied to any specific product or technology stack, making them versatile tools for managing deployments across various platforms. They can be applied to: -Consistency: Automates repetitive tasks, ensuring uniformity across deployments. -Efficiency: Reduces manual effort and accelerates the deployment process. -Control: Allows precise control over the conditions under which changes are promoted. -Visibility: Provides clear insights into the progress and status of changes across environments. -Contribution to Deployments -Promotion flows streamline the process of moving code changes through different stages, such as testing, staging, and production. By defining specific criteria for promotion, they help maintain the integrity of the software and reduce the likelihood of introducing bugs into production. -## Flow Builder vs. YAML -You can create Promotion Workflows through the Flow Builder, a graphical interface, or through a YAML Custom Resource Definition (CRD). You can switch seamlessly between both when creating Promotion Flows.Similar to most entities, and all promotion-entities, +## Notes on Promotion Flows +Here are a few key factors to be aware of when creating Promotion Flows. +### Trigger and target environments +You can create and assign environments for the Promotion Flow, starting with the Trigger Environment, where the change initiates the flow, and the other target environments required for promotion. You need at least one target environment for promotions. -## Sequential vs. parallel flows +* Adding environments + When adding an environment, you can select from the list of available environments, or create a new one that takes you to the Environments page for defining settings. At this point, the Promotion Flow remains unsaved, allowing to return to the flow later. -Promotion flows can be designed to run sequentially or in parallel to suit the unique requirements of any deployment process. +* Removing environments + You can remove an environment from the Promotion Flow, and decide how to reconnect next environments to previous environments. -Sequential flows -Sequential flows are linear, where changes are promoted from the previous to the next environment in the order in which they are defined. -This is the more common and traditional flow where you start the flow from the dev environment as the trigger environment, and then promote to testing, staging, and finally production. + Reconnecting environments is only relevant when there is one or more environments in the flow _following_ the one being removed. If the environment you’re removing, for example `staging` is the final environment in the flow, you can remove it directly without needing to reconnect. -Parallel flows -In a parallel flow, changes are promoted across multiple environments simultaneously. This promotion logic groups environments to create promotions after multiple environments are healthy. +### Inline versus automated Promotion Policy settings +For each environment, you can explicitly set the Promotion Policy, including the Promotion Action (required), and the optional Pre- and Post-Action Workflows. +##### Inline Promotion Policy settings +The Flow Builder displays available settings for the Promotion Policy. If you manually select these settings, this _inline_ selection overides any automated Promotion Policy settings that match the product/environment when the flow is triggered. -## Promotion Flow building blocks +##### Automated Promotion Policy settings +If no inline settings are defined, the system applies automated Promotion Policy settings based on predefined priorities. See TBD -A Promotion Flow comprises several building blocks, optional and required, each serving a specific role in the deployment process. -Before creating Promotion Flows it is advisable to understand the role of these building blocks. +### Previewing Promotion Policies by Product +Instead of waiting for the Promotion Flow to be triggered, you can preview Promotion Policy settings for any product to ensure that the environment and product have the desired policies. +Previewing Policies by product confirms if the automated Policies that will be applied for the product are the correct ones for it. Preview is also useful to identify environments and products without matching Policies or Policies that are missing required settings such as the Promotion Action. +Note that only those settings without inline values are populated by the preview. -* Environments (required) - - * Trigger environment - The trigger environment is where a change initiates the promotion flow. The change in the trigger environment is a manual user commit or pull request action, and not an automated promotion action as in the other environments defined in the Promotion Flow. - To automate specific actions after the change, you can configure a trigger workflow (akin to a Post-Action Workflow). - - * Target environments - Any environment apart from the trigger environment are target environments in the promotion flow. A Promotion Flow requires at least one target environment. - Target environments can linear or parallel. +## Create a Promotion Flow +Visually design and create the flow by selecting environments, Promotion Actions and Workflows, and defining dependencies through the Flow Builder. If needed create new environments and promotion workflows on-the-fly when doing so. -* Product (optional) - Instead of manually applying Pre-Action, Post-Action, and Action for each environment, you can select a Product to apply the Promotion Policy defined for it to all environments defined, excluding the trigger environment. +### Before you begin +* Review [Create a promotion sequence]({{site.baseurl}}/docs/promotions/create-promotion-sequence/) - The promotion policy defined for the Product dictates the Pre-Action, Post-Action, and Action for each environment. You retain the flexibility to configure parts of the Promotion Policy not defined in the Product. - This allows you to customize specific steps or workflows as needed, while still leveraging the overall Product policy. -* Applications +### Step 1: Add a Promotion Flow +Open the Flow Builder to add a Promotion Flow. +1. In the Codefresh UI, on the toolbar, click the **Settings** icon, and then from the sidebar, select **Promotion Flows**. +1. Click **Add Promotion Flow**. +SCREENSHOT -* Promotion Settings +{:start="3"} +1. Continue with [Step 2: Select Trigger Environment](#step-2-select-trigger-environment). -* Promotion Policy +### Step 2: Select Trigger Environment +Every Promotion Flow starts from a Trigger Environment where the change is made that triggers the flow. +Select a predefined environment, or create a new environment and then return to the Promotion Flow and select the new environment. -* Promotion Workflows (optional) - Promotion workflows, categorized as Pre-Action and Post-Action workflows, validate the environment's readiness for promotion: - * Pre-Action Workflow: Executes before changes are committed to ensure the target environment meets predefined criteria. - * Post-Action Workflow: Executes after changes are committed to verify the environment's stability and functionality post-deployment. - While optional, we highly recommend adding these workflows to environments to enhance deployment reliability and consistency. - You can select from available Promotion Workflows or create a new Pre- or Post-Action Workflow as needed. -* Promotion Action (required) - The Promotion Action is the action that activates and propagates the changes to the current environment, and can be Commit, Pull Request, or No Action. The Action is generally defined as part of the Promotion Policy. You can also select an action on-the-fly +1. Click ?? in **Select Trigger Environment** to see the list of available environments. +SCREENSHOT +{:start="2"} +1. Do one of the following: + * To add an existing environment, select it and click **Add**. Continue from step ?? + * To create a new environment, click **Add New Environment**. + * You are taken to the Environments page and the Create Environment form is displayed. See ???? + * A notification alerts you that there are unsaved changes to the Promotion Flow. + This notification remains as long as you have unsaved changes in the Promotion Flow. +1. If needed, to return to the Promotion Flow and continue, click **Go to Promotion Flow**. + You can now pick up from where you left off. +1. Continue with [Step 3: (Optional) Add Trigger Workflow to Trigger Environment](#step-3-optional-add-post-action-workflow-to-trigger-environment). -| **Entity** | **How does i ** | **Where and When** | **By Whom** | **Learn more** | -|----------------------|---------------------------|--------------------|-------------| -| **Environments (required)** | Environments are where your applicatios live and promotions happen. Typically environments reflect your software lifecyle and deployment lifecyle. Create environments. You need at least two: Trigger environment: The trigger environment is where a change initiates the promotion flow. The change in the trigger environment is a manual user commit or pull request action.
Target environments: Any environment apart from the trigger environment are target environments in the promotion flow. A Promotion Flow requires at least one target environment. | First step in promotion | Users with ABAC | -| **Product (optional)** | A Product is a specialized entity in Codefresh GitOps which groups related applications and treats them a single cohesdive entity. Why is this important for promotions? With product instead of promoting individual applocations you can promote the productand all applications within it across different environments. | Defining a Porduct allows you to configure several settings connected to promotions in a single location. | Users with ABAC | Link?? -| **Applications** | Applications are the smallest entity around which promotions revolve. | | | -| **Promotion Flows** | Promotion flows orchestrate the promotion of a product through different environments according t | | | -| **Promotion Settings** | Promotion settings define exactly what gets promoted in the different applicatins and across what environments. if you have created a product, you can define promotion settings as part of the product's settings. You can also define it in the CRD. | | | -| **Promotion Policy** | Defines what is done in the next environment when there is a change that initiates promotion. It validates that th environment is ready for the promotion through promotion workflows and promotion action. The promotion action is the action through a commit or a PR or a predefined mechanism that propagates the changes defined by promotion settings to the target environment. Promotion workflows are what ensures that the target environment - these can be verifying predefined criteria before the promotion changes are implemented, and verifing the environment's stability and functionality post-promotion action. | | | +### Step 3: (Optional) Add Trigger Workflow to Trigger Environment +If required, add a Trigger Workflow to validate the readiness of the trigger environment after the change and commit action. +TBD purpose of doing it +1. Click {::nomarkdown}{:/}. +SCREENSHOT +{:start="2"} +1. Do one of the following: + * To review the manifest of an inline Trigger Workflow, click ??? and then select the required workflow. Continue from _step 2_. + * To apply a Trigger Workflow from automated Promotion Policy settings, click **Automated Promotion Policy**. Continue from _step 2_. + * To add a new Promotion Workflow, click **Add New Workflow**. + * You are taken to the Add Promotion Workflow page where you can define the settings. See TBD???? + * A notification alerts you that there are unsaved changes to the Promotion Flow. + This notification remains as long as you have unsaved changes in the Promotion Flow. +1. If needed, to return to the Promotion Flow and continue, click **Go to Promotion Flow**. +1. Continue with [Step 4: Add target environment to promote to](#step-4-add-target-environment-to-promote-to). -| **Component** | **Role in Promotion Process** | **Where and When** | **Who Can Create** | **Additional Resources** | -|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|---------------------------|---------------------------| -| **Environments (Required)** | Environments are where your applications live and promotions happen. Typically, environments reflect your software lifecycle and deployment stages. You need at least two environments:
- **Trigger Environment**: Where a change starts the promotion flow, initiated by a manual commit or pull request.
- **Target Environments**: The environments where changes are promoted after the trigger environment. | First step in the promotion process | Users with ABAC permissions | [Link] | -| **Product (Optional)** | A Product in Codefresh GitOps groups related applications into a single entity. This simplifies promotions by allowing you to promote the entire Product and all its applications across different environments, rather than managing them individually. | Centralized promotion settings | Users with ABAC permissions | [Link] | -| **Applications** | Applications are the core units around which promotions revolve. Each application can be promoted individually or as part of a Product. | Part of each environment | Users with ABAC permissions | [Link] | -| **Promotion Flows** | Promotion flows orchestrate the movement of changes through environments, ensuring a controlled and automated promotion process. | Defined in the Promotion Flow UI | Users with ABAC permissions | [Link] | -| **Promotion Settings** | Promotion settings specify what gets promoted across environments. If using a Product, these settings can be defined within the Product’s configuration or in a YAML CRD. | Defined during product setup | Users with ABAC permissions | [Link] | -| **Promotion Policy** | A Promotion Policy outlines the actions taken when changes are promoted. It ensures that the target environment is ready for promotion, with workflows to validate the environment both before and after the promotion action, like commits or pull requests. | Applied during the promotion process | Users with ABAC permissions | [Link] | -The table describes the entities involved in the promotion process, starting with the core entities and those entities wh +### Step 4: Add target environment to promote to +Add the environment to promote to from the trigger environment. You can add as many target environments as you need. +Again, you can select a predefined environment or create a new environment and then return to the Promotion Flow and select the new environment. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
EntityRole in promotionsCreated byLearn more
Core entities
These entities define the structure of your deployment.
Environments (Required)Environments are where your applications live and promotions happen. Typically, environments reflect your software lifecycle and deployment stages. You need at least two environments: -
    -
  • Trigger environment: Where a change starts the promotion flow, initiated by a manual commit or pull request.
    • -
  • Target environments: The environments where changes are promoted after the trigger environment.
    • -
- 		Users with ABAC permissionsLink
Product (Optional)A Product in Codefresh GitOps groups related applications into a single entity. This simplifies promotions by allowing you to promote the entire Product and all its applications across different environments, rather than managing applications individually.Users with ABAC permissionsLink
ApplicationsApplications are the core units around which promotions revolve. Each application can be promoted individually or as part of a product.Users with ABAC permissionsLink
Promotion Building Blocks
These entities define how promotions are orchestrated, what gets promoted, and under what conditions.
Promotion FlowsPromotion flows orchestrate the movement of applications through environments, ensuring a controlled and automated promotion process.Account administratorsLink
Promotion SettingsPromotion settings specify what gets promoted across environments. If using a Product, these settings can be defined within the Product’s configuration or in a YAML CRD.Users with ABAC permissionsLink
Promotion PolicyA Promotion Policy outlines the actions taken when changes are promoted. It ensures that the target environment is ready for promotion, with workflows to validate the environment both before and after the promotion action, like commits or pull requests.Account administratorsLink
+1. Mouse over the right of the current environment and click ??. +SCREENSHOT -Inter-environment dependencies - In both sequential and parallel flows, adding a new environment automatically establishes a dependency on the previous environment. This ensures that changes are promoted in a controlled manner. +{:start="2"} +1. To add an existing environment, select it and click **Add**. Continue from _step 3_. +1. To create a new environment, click **Add New Environment**. + * You are taken to the Create Environment page where you can define the settings. See TBD???? + * A notification alerts you that are unsaved changes to the Promotion Flow. + This notification remains as long as you have unsaved changes in the Promotion Flow. +1. To return to the Promotion Flow and continue, click **Go to Promotion Flow**. +1. To add more target environments, repeat _step 1_ through _step 3_. +1. Continue with [Step 5: (Optional) Add dependencies to target environment](#step-5-optional-add-dependencies-to-target-environment). - For parallel flows, you can add multiple environments as simultaneous dependencies on new environments. This means that the changes from the previous environment are first promoted concurrently to each of the dependent environments, and only when successfully deployed across all environments are they promoted to the next environment in the flow. +### Step 5: (Optional) Add dependencies to target environment +Promote changes from the previous environment concurrently to multiple environments by adding dependencies to the current target environment. When there are dependent environments, changes are promoted to the next environment in the flow only after they are successfully deployed across all dependent environments. +1. Mouse over the target environment. +1. From the **Depends on** list, select the environment and click **Update Dependency**. + The environment is added below the existing environment, and a link is added between it and the next environment to indicate a dependency. + SCREENSHOT +{:start="3"} +1. Repeat _step 2_ as needed to add other environments as dependencies. +1. Continue with [Step 6: Select Promotion Action for target environment](#step-6-select-promotion-action-for-target-environment). +### Step 6: Select Promotion Action for target environment -## Create Promotion Flow with Flow Builder -Visually design and create the flow by selecting environments, promotion workflows, setting trigger conditions, and defining dependencies through the Flow Builder. If needed add new environments and promotion workflows on-the-fly when doing so. +Select the Promotion Action to use for the target environment, either manually from the inline settings, or through automated Promotion Policies. +An inline Promotion Action when selected overrides the Promotion Actions in automated Promotion Policies that may match the product and the environment. If the system identifies that no inline Action is selected, and none of the matched Promotion Policies have an Action, it pops up an error message. -### Before you begin -* Review -* +{{site.data.callout.callout_tip}} +**TIP** +If you define the Promotion Action through automated Promotion Policies, you can preview the Promotion Action that will be applied for a Product. +See [Step 8: (Optional) Preview automated Promotion Policy settings by product](#step-8-optional-preview-automated-promotion-policy-settings-by-product). +{{site.data.callout.end}} -### Step 1: Add a Promotion Flow -Add the Promotion Flow to -1. In the Codefresh UI, on the toolbar, click the **Settings** icon, and then from the sidebar, select **Promotion Flows**. -1. Click **Add Promotion Flow**. -### Step 2: Select Trigger Environment -Evry Promotion Flow starts from a Trigger Environment where the change is first made. -You can either select a predefined environment or create a new environment and then return to the Promotion Flow and select the environment. +1. Mouse over the left of the target environment and click ??. + +SCREENSHOT + +{:start="2"} +1. To define an inline Promotion Action, select one from the list. +1. To define an Action from automated Promotion Policies, click **Automated Promotion Policies**. +1. Continue with [Step 7: (Optional) Add Pre- and Post-Action Workflows for target environment](#step-7-optional-add-pre--and-post-action-workflows-for-target-environment). -1. Click ?? to see the list of available environments. + + +### Step 7: (Optional) Add Pre- and Post-Action Workflows for target environment +Add Pre- or Post-Action Workflows to the target environment. +Either manually select an inline Workflow for the Promotion Flow, or leave it to the Automated Promotion Policy to apply and execute the appropriate Workflow. + +1. Mouse over the left of the target environment. 1. Do one of the following: -1. To add an existing environment, select it and click **Add**. Continue from step ?? -1. To create a new environment, click **Add New Environment**. - * You are taken to the Environments page and the Create Environment form is displayed. See ???? - * A notification alerts you that are unsaved changes to the Promotion Flow. - This notification remains as long as you are unsaved changes and you are in different UI. + * To add a Pre-Action Workflow, click the top ??? icon. + * To add a Post-Action Workflow, click the lower ??? icon. + +SCREENSHOT + +{:start="3"} +1. Define the Pre-/Post-Action Workflow: + * To add an inline Workflow, select it and click **Add**. Continue from step ?? + * To add a new Workflow, click **Add New Workflow**. + * You are taken to the Add Promotion Workflow page where you can define the settings. See ???? + * A notification alerts you that are unsaved changes to the Promotion Flow. + This notification remains as long as you have unsaved changes in the Flow. + * To apply an automated Promotion Policy, click Automated Promotion Policy. 1. To return to the Promotion Flow and continue, click **Go to Promotion Flow**. - You ccan now pick up from where you left off. - + You can now pick up from where you left off. +1. Continue with [Step 8: (Optional) Preview automated Promotion Policy settings by product](#step-8-optional-preview-automated-promotion-policy-settings-by-product). -### Step 3: Select environment to promote to -Add the environment to promote to from the trigger environment. Again, you can select a predefined environment or create a new environment and then return to the Promotion Flow and select the environment. -1. Mouse over the right of the current environment and click ??. -1. To add an existing environment, select it and click **Add**. Continue from step ?? -1. To create a new environment, click **Add New Environment**. - * You are taken to the Environments page and the Create Environment form is displayed. See ???? - * A notification alerts you that are unsaved changes to the Promotion Flow. - This notification remains as long as you have unsaved changes and you are in different UI. -1. To return to the Promotion Flow and continue, click **Go to Promotion Flow**. - You can now pick up from where you left off. -1. To -### Step 4: (Optional) Select a Product to apply Promotion Policy -Select a product to automatically apply its Promotion Policy to all environments defined, excluding the trigger environment. -This is an alternative to manually applying Pre-Action, Post-Action, and Action for each environment (described in Steps 5 and 6). -Promotion Policy ??? -1. From the list of Products, select the product with the Promotion Policy to apply. - The Pre-Action, Post-Action, and Action defined for the Policy are assigned to all the environments. - Mouse over the Pre-Action, Post-Action, and Action icons to see the Workflows and the Promotion Action assigned. - If the Policy does not match an environment, it will not apply any of the Policy components. - -1. If any component is not defined for the Policy, click the corresponding icon and assign a Workflow or an Action. +### Step 8: (Optional) Preview automated Promotion Policy settings by product +Select a product to preview settings that will be applied from automated Promotion Policies for all target environments without inline settings. +When there are no inline settings selected or defined for an environment's Promition Polocy, the system applies settings from all predefined or automated Promotion Policies that match the product and the environment according to priority. -### Step 5: Select Promotion Action - - The See ???? - A notification alerts you that are unsaved changes to the Promotion Flow. - - Inline not defined = Undefined - -### Step 6: (Optional) Add Pre- and Post-Action Workflows -1. Mouse over the connector on the left between the two environments. -1. To add a Pre-Action Workflow, click the top ??? icon. -1. To add a Post-Action Workflow, click the lower ??? icon. -1. To add an existing Pre- or Post-Action Workflow, select it and click **Add**. Continue from step ?? -1. To add a new Workflow, click **Add New Workflow**. - * You are taken to the Promotion Workflows page and the Add Promotion Workflows form is displayed. See ???? - * A notification alerts you that are unsaved changes to the Promotion Flow. - This notification remains as long as you have unsaved changes and you are in different locations in the UI. -1. To return to the Promotion Flow and continue, click **Go to Promotion Flow**. - You can now pick up from where you left off. - +Preview by product within a Promotion Flow shows you if there is a Promotion Policy that matches the product, and which settings will be applied. +>**NOTE** +This action is only a preview and does not impact the Promotion Flow. -### Step 7: Add additional environments -1. Mouse over the right of the current environment and click ??. -1. To add environments for parallel Flows creating dependencies on the next environment: - 1. Mouse over the current environment. - 1. From the **Depends on** list, select the environment and click **Update dependency**. - The environment is added below the existing environment, and a link is added between it and the next environment to indicate a dependency. -1. Repeat step 1 and step 2 as needed. +1. From the list of Products, select the product for which to evaluate or apply Promotion Policy settings. + The Promotion Action, Pre- and Post-Action Workflows that match are applied from the predefined or automated promotion policies and displayed for each environment. Mouse over the Pre-Action, Post-Action, and Action icons to see the Workflows and the Promotion Action assigned. + +SCREENSHOT + +1. If you get an error component is not defined for the Policy, click the corresponding icon and assign a Workflow or an Action. + + +### Step 9: Save changes and commit flow +As the final action in creating a Promotion Flow, save the settings and commit the changes. +TBD where are teh changes saved? -### Step 8: Save changes and commit flow 1. Click **Save Promotion Flow** to commit changes. +## Removing environments from Promotion Flows +Remove one or more environments from a Promotion Flow. TBD why would you want to remove an environment? What happens if the env is defined as part of the promotion policies? + +Removing an environment requires you to reconnect environments that are linked to the one being removed. +Reconnecting environments is only relevant when there is one or more environments in the flow _following_ the one being removed. If the environment you’re removing, for example `staging` is the final environment in the flow, you can remove it directly without needing to reconnect. -## Manually trigger a Promotion Flow +1. In the Codefresh UI, on the toolbar, click the **Settings** icon, and then from the sidebar, select **Promotion Flows**. +1. Select the Promotion Flow with the environment you want to remove. +1. Mouse over the environment node and then click {::nomarkdown}{:/}. + If the environment is linked to another one, you are prompted to select the reconnect behavior. +SCREENSHOT +1. Do one of the following: + * If you have environments in the flow linked to the environment you are removing, from the **Reconnect next environments to** list, select a preceding environment to reconnect to. + For example, consider a promotion flow with `dev`, `qa`, `staging`, and `prod` environments in that order. When removing the `qa` environment which is linked to `staging`, you need to reconnect `staging` to the preceding environment, `dev` in our example. + SCREENSHOT + + * To remove all connected environments, select **Remove all connected environments**. + This action removes all environments linked to and succeeding `qa`, which are `staging` and `prod` in our example. + + SCREENSHOT ## Troubleshooting Promotion Flow creation +TBD +## Related articles +[Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/) +[Promotions overview]({{site.baseurl}}/docs/promotions/promotion-components/) diff --git a/_docs/promotions/manually-trigger-promotion.md b/_docs/promotions/trigger-promotions.md similarity index 100% rename from _docs/promotions/manually-trigger-promotion.md rename to _docs/promotions/trigger-promotions.md diff --git a/images/icons/delete-red.png b/images/icons/delete-red.png new file mode 100644 index 0000000000000000000000000000000000000000..ae8061e9e8499e7d14552e490a18501ba50b800f GIT binary patch literal 414 zcmV;P0b%}$P)680OA+cJD6ag~$iHY= z?e5v?&3{?H3o)lJSpo+}g~**#P&{u+#)MUH+p%V%Q~W!80H;A?LSd1AO8@`>07*qo IM6N<$f-dEyr~m)} literal 0 HcmV?d00001 diff --git a/images/icons/flow-builder-add-workflow.png b/images/icons/flow-builder-add-workflow.png new file mode 100644 index 0000000000000000000000000000000000000000..4b80eecdefdacca885a2e4bbb3d216ad6ef3f2af GIT binary patch literal 4562 zcmV;@5iRbCP)OCVdj zi3w(6#iWdRkyN4yR;o;>lu1Pc7A9j*96*QRC39yO284OsdES}1xBKM#ojIpHx4AP& z<~Gh~|Eju9_vv%{@jGAt&i8%iT%rgOB1DJ~Awq-*5h6r*pTnZd3?W4Arz93aeW~qKe!6L2CC+_&#Yd7{B>G;$iK6bE05fUmexc<-agN@ToUh*m_ zx6G~Hva+nQwmM!&VWY%xXhmt|s*hIB*g_vfu+eRjmKUOwOn~+DLBn_2-)b4myeDLf zXU-&AXqq4|l7hgbCp}tQ;>0FwcXY6ywkM9ze;+$Y-#m4ky3!*#+o2xqP7M#yyTPg9 zRPEhw?%PDu0C@@R&yEZ?#w=Pjk#;xs_t1{^lk_)N)X>t>GHUGWp%=T)(jy?#;KWS7y~Q#Ye*gQ|n!TPSIYVbX+) zG1u&(pENA?hRRuT)A;`Bld`;_ayISY{hO<=Bo686hMBWyDS$~!%BMLI1xvjcx<*H6L2*e|U0q2z9qda=vOC$b ze{!~!AWI+{Ku0VsDWmVVpY(qN67{B!ffu{pru&*+`^2_w+iWH6CfOR7Jy{pTqzMoF%ZLd`#)esQ=(DwTQZ^o0v_jUy@Nczhi8GLSWK*~EZM&O_S+pCt2#WkMN>dt{v?3BcZ>5Q!{VVMjpCj+ zUJ=_)91{KM(JZpD^^cBlyOemS`E}9UpA>z33{pqA6HunpY1vNiW7EXn^F{-117h*H z`6TncBwu#~y(24{^vgzmj4mUJ9h*KmZ;_Oi&GVNKzUm7-4~yNxW+^v2+TWrFufB#x zDNRqam-BLG2fdLzPi;f}vi-Fc)pT`f1^xBhTKWfW=edHeyY4z?#xNF=@ipwAh3RB)r%U&a_Y`dn!Y2M%L}E%VOn|zR94QX(_Rt+KJlWeL0Ir8>;8<;278DMaPDE*Yz)3ozDFKoNZ5jp`f5ZTyez}-sa7l#o@z; zg|>DKnxr}b9iWc=N2QQ4X}9qHrdMD3eX{f74cVGt%{Nq5GnrNNmsRkwEBFnC^gKX# z17BxJ@eF!k!BX18R(q*r171A#@Y!wu`q(u7;KIFRC*nDL-r#tIyRWReOi9tVl7IK{y}Neq>MkiM zu^}r=x~+V2`8c`*0?(@xF`>xID?RFO?32@AI?V&8M>e8F zE^jQark|fa!O5rrnmnwE)UvvNDladW5!K?wi|wULmrARJo`Y;`J9qB1l-EjzrH3Xh zc}dTHInne3B$-TzKys;yr2^T)ukxT+-*${1= zJl;!avN`yX+s%8Qqo)3Dng~yR!p6Q>PZlcJY{F*fK7WgpPpX6dU_O))CFb5`_lY=H1gDTgfE=cyrSg$ci znpnpLe}ya{Of-gE8dO&4${+B|S(*wRHT7PI&7-|wwivxXGe@)68|Q-}UjR>L*; z0rx!FcKq?6v;-jn=~ai5Rug{4Ijrnb5+O{u!-0^^Uy=pi99j-5XDLAdBy%gKdngC< z5GOA38ruJ%dvI$_Y3jy}v#(lJY&%(&Zh9;lu5u?~*;-O+c%q?wc+hVHi_NlHx&%qd zxJ^)s%F0TMHQcJHsd47anUm@7@3#j6ja-c*oq|>%4?3cf@#xS)d zMS~x-b$EDqLw({%;wNWXX~@eR6lopTQKmlri^@5aFIc?;ze34_reN#FX0cC>!NX#o zT(;5fAU~(bd3@Wf`BcUe4wHuK zwTp+g?_~KPSa>RxlJAP>lgWmsBFyNMEu3=6O1>k`P|~wXuaiF(;z2$<@XYDN)}))h z`k${_C=*jA$=X}NKI*HAis_3VT0{SS^p$b1zxVuUx>%mc?(C^YH}e4L4}u&7xrjK~ z(g|dPbhwDPJ@nkXXm&O?f5^LqE3$n*mM!Op_bgbv@MvGp-D%G|2vUFB{Wcxo`At|p zycDhFx~z;B)0(o`eC!Tns_Mub9Zi^MfKmLun)wO)O_FtM_t+0eg zk1bl+n;cH{eg0rW!$?>1$P2yg6;xgMnM=7b^$mP4{$Ja_z~rX612fn-(oD1O?e_Ne zx^NAde4z$TKL8>%0g;2?yqb6zk}~FJ88a!c9JU|?81|ia-q|{P_Uy+`o;>;W!u|VY zqqS?-I>(P6kG)i0ZZlC1dlPXcCC;4@v$oxT+MajiXDDXRoA9nY6&gEr`g0>&pZGOL zG%m|WhIJc+d&`$Ehj-#};6p4agusU(l#H0OL8MDZzyj3>G3!=s6n! za^_x+_sOe;hefzQWu>h~>m$H~+p5GTZ8tVHTI@>Nyn$$k$+Eh;yW;}`12HBa@&s#l z)X#0T5##|H&7nK7E@$}nF1vk_aISaRqB9_S#*7(h-WL@W6&|F7EgtDw589206GWTK zD6p@VQ^;4yrT@*z8bJ1T=@6^?Puk&zLbJ0i1a(IQJFuUr*nqT_sm&F2Sn zYMkO)O0wlk0+PlpN@IJv}|do#=Az#6{u?0T1Rl@mnPymKrcM!C9p0 zcgT0d8A{-zee7I56|5Y(i4qo$I%p~%yDL|&^bQ?5{ER80gY-=gxIIJ3FDp zqimsa<8#srVe1{``ZUPrFTIGZ3S6f>v_+I`X$jK`Vl3DH`CL(mEFfgAPTE;MpTnY;L zuzH|0Uk3V(NnPy2vJ~0SbZE4fNF+cOvG#hfP_9d}&SL8v9ol1K zzh3@^I}HC2DA4!OYYg>1jV*z*&1Y1DWN0gFLyI&i+e);H<)=b*mQE2b2Qs!~-#14) zOd7Do%L_1h0)r-kmIDV4U_Bz_M3yWuF50rMEuMe=c|xFr-(ZkL7!S+VJ~zU7q-C+e zEi|p$%Kqm>UcD2IQ2vQb>OqaqRHc|@ZpFfYiJS&fqD;7_$wou?$84q2J%qe~Xp%8b zMiR^(3kFiba^jb&t!Qm+l{dryiHOo1AVE4@L1RIX??I^tG;=3Yd)D5Bk=D#Pw}}_U zU+qz=&Dcpgs&I9A~QLDoC}9kL7`e0uod8v3Dw0fpYxZIrJ10f<48 z^v$uO20uSwQK7l4hhBqh)S=WK2!4w?a{;G*9uZjNqw^Du01<5wO5`*keP5g3>$m8BC7Xikn zuLoJ*h14@OnrQ5+X|k;U3*`!G%r+A|OK4UeriBL~#;Y?2FLObTIuD|d$|e1m5yOv{ zb=tCx!7polx8659BN!j(uQ6;%c`uNaV=;Z<@!C+pr5tYyTx%lNF3Sz1_dCWT&-9CP z{GalIw!w3`{C%3(?+#^k)kL_QlHw!q*)O{caRZZ9+WQo5|PX0Gp~^=9thhF zoKnzMY9_gYmU}U)rQ8;;uSJ12WSpPgVSFBtle{2l=9WXRb9I*f{gl9zc@V>8)9$mb zCsl8@HB+g6JIna@2<3Ts!v_JmJP9jsE;uvuo(zQV3mDpdQ8P6pC~H4Lga{ELM2HX} wLWBqrB1DJ~Awq-*5h6s05FtW@2-6;a1Zv-6@iH$MqW}N^07*qoM6N<$g8uvNWB>pF literal 0 HcmV?d00001 From 0a06b31977d8edaeef63208a137403e332970612 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Tue, 10 Sep 2024 13:57:40 +0300 Subject: [PATCH 08/61] Update content Added more procs on triggering promotions --- _docs/promotions/create-promotion-sequence.md | 2 +- _docs/promotions/trigger-promotions.md | 117 +++++++++++++++++- 2 files changed, 115 insertions(+), 4 deletions(-) diff --git a/_docs/promotions/create-promotion-sequence.md b/_docs/promotions/create-promotion-sequence.md index 4d35a295b..12b9da87d 100644 --- a/_docs/promotions/create-promotion-sequence.md +++ b/_docs/promotions/create-promotion-sequence.md @@ -62,7 +62,7 @@ This step-by-step guide lists the steps required to create a promotion sequence. 1. [Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/) Implement the changes to initiate the promotion sequence. - The change, made to an application in the trigger environment, starts the process of moving changes from the trigger environment through the defined sequence of environments, following the defined Promotion Policies and Settings. + The change made to an application in the trigger environment starts the process of moving changes through the defined sequence of environments, following the defined Promotion Policies and Settings. TBD diff --git a/_docs/promotions/trigger-promotions.md b/_docs/promotions/trigger-promotions.md index 12565cf5c..0a40c6a7b 100644 --- a/_docs/promotions/trigger-promotions.md +++ b/_docs/promotions/trigger-promotions.md @@ -1,6 +1,117 @@ --- -title: "Manually trigger promotions" -description: "Manually trigger a promotion flow to initiate deployments " +title: "Trigger promotions" +description: "Orchestrate promotions automatically or manually trigger promotions" group: promotions toc: true ---- \ No newline at end of file +--- + + When you trigger a promotion + +## Automatically trigger promotions + + +## Manually trigger a Promotion Flow + +TBD prereqs for manual trigger. + + +1. In the Codefresh UI, on the toolbar, click the **Settings** icon, and then from the sidebar, select **Promotion Flows**. +1. Select the Promotion Flow to trigger manually. +1. On the toolbar, click **Trigger**. + + +{:start="4"} +1. From the list of products, select the product for which to trigger the Promotion Flow, and click **Next**. + +SCREENSHOT + +{:start="5"} +1. Select the application or applications to promote for the product. + +SCREENSHOT + +{:start="6"} +1. Click **Trigger**. + A release is created for the product, the Releases tab is displayed. + +SCREENSHOT + + +## Manually promote applications through drag-n-drop +Drag-and-drop an application from the trigger environment to the target environment to promote changes. + +This is one method to manually promote applications. To manually promote applications through Promotion Policies or Promotion Flows, see [Manually promote applications by Promotion Policies or Flows](#manually-promote-applications-through-promotion-policies-or-flows). + +##### Before you begin +* ??? + + +##### How to +1. From the sidebar in the Codefresh UI, do one of the following to drag-n-drop an application: + * Select **Products**, and then select the product with the application to promote. + * Select **Environments**, and then select the trigger environment with the product. +1. Drag the application/product from the trigger environment to the desired target environment. + +SCREENSHOT + +{:start="3"} +1. Select the Promotion Actions as **Commit** (automated) or **Pull Request** (may require manual approval based on organization policies). +1. Optional. Select the **Pre-Action Workflow** to run before the Promotion Action. +1. Optional. Select the **Post-Action Workflow** to run after the Promotion Action. +1. Review the files with the changes that are to be promoted. By default, the changes are displayed in the compact diff view. +1. Add information on the Promotion Action describing the reason and changes for it. +1. Click **Promote**. + +A release is created for the Product and the Release tab displays the ongoing deployment. + +SCREENSHOT +## Manually promote applications through Promotion Policies or Flows + +Manually promote an application in a product to a target environment either through a predefined Promotion Flow or by creating a custom Promotion Policy for the application. + +##### Before you begin +* Make sure you have permissions: + * To trigger Promotion Flows from Products + * To promote to environments + +##### How to +1. From the sidebar in the Codefresh UI, do one of the following: + * To promote an application from a product, select **Products**, and then select the product with the application to promote. + * To promote an application from an environment, select **Environments**. +1. Click the context menu of the application in the trigger environment, and select **Promote**. + +SCREENSHOT + +{:start="4"} +1. Do one of the following: + * To promote through a preconfigured Promotion Policy or by defining a custom one, select **Select target environment**. + Continue from _step 5_. + * To promote through a predefined Promotion Flow for the application's product, select **Trigger Promotion Flow**. Continue from _step 8_. + +SCREENSHOT + +{:start="5"} +1. To promote by Promotion Policies, do the following: + 1. From the list of environments, select the environment to promote to, and click **Next**. + 1. If needed, define the Policy settings: + * Select the Promotion Actions as **Commit** (automated) or **Pull Request** (may require manual approval based on organization policies). + * Optional. Select the **Pre-Action Workflow** to run before the Promotion Action. + * Optional. Select the **Post-Action Workflow** to run after the Promotion Action. + product with the application and the target environment does not match configured Promotion Policy settings, define the settings, as describe d. + 1. Review the files with the changes that are to be promoted. + 1. Add information on the Promotion Action describing the reason and changes for it. + 1. Click **Promote**. + + SCREENSHOT + +{:start="8"} +1. To promote through a Promotion Flow, do the following: + 1. Click **Next**. + 1. Select the Promotion Flow to use for promotion. + 1. In the Trigger Promotion Flow page, verify that there are no validation errors, and then click **Trigger**. + +SCREENSHOT + +A release is created for the Product and the Release tab displays the ongoing deployment. + +SCREENSHOT From f1970bb1adfa31b1022a1cc4894728ff1c76973e Mon Sep 17 00:00:00 2001 From: NimRegev Date: Tue, 17 Sep 2024 15:23:22 +0300 Subject: [PATCH 09/61] Update content for promotion flows --- _docs/promotions/create-promotion-sequence.md | 2 +- _docs/promotions/promotion-flow.md | 37 ++++++++++--- _docs/promotions/promotions-overview.md | 54 +++++++++++++++++++ 3 files changed, 84 insertions(+), 9 deletions(-) create mode 100644 _docs/promotions/promotions-overview.md diff --git a/_docs/promotions/create-promotion-sequence.md b/_docs/promotions/create-promotion-sequence.md index 12b9da87d..930b8d52c 100644 --- a/_docs/promotions/create-promotion-sequence.md +++ b/_docs/promotions/create-promotion-sequence.md @@ -6,7 +6,7 @@ toc: true --- -This step-by-step guide lists the steps required to create a promotion sequence. Follow the steps in the order in which they are listed. Each step is followed by a brief description of its purpose and objective in the promotion sequence. For detailed information, click the step title. +This guide lists the steps required to create a promotion sequence. Follow the steps in the order in which they are listed. Each step is followed by a brief description of its purpose and objective in the promotion sequence. For detailed information, click the step title. ## Prerequisites diff --git a/_docs/promotions/promotion-flow.md b/_docs/promotions/promotion-flow.md index 245d9859a..bf7478b51 100644 --- a/_docs/promotions/promotion-flow.md +++ b/_docs/promotions/promotion-flow.md @@ -8,6 +8,9 @@ toc: true A Promotion Flow is a structured sequence of actions that automates the promotion of changes in products through various environments until deployment. It ensures that code changes are automatically, systematically, and consistently moved, from development to production environments, enhancing the reliability and efficiency of deployments. + +Promotion Flows streamline the process of moving code changes through different stages, such as testing, staging, and production. They automate repetitive tasks, reducing manual efforts, ensuring uniformity across deployments. +By defining specific criteria for promotion, they help maintain the integrity of the software and reduce the likelihood of introducing bugs into production. Our Flow Builder visually guides you through creating any type of Promotion Flow. See [Create a Promotion Flow](#create-a-promotion-flow). As with other entities, you can toggle between YAML and chart modes while in the Flow Builder. @@ -17,12 +20,29 @@ Before creating promotion flows, review [our notes on Promotion Flows](#notes-on - +## Flow Builder vs. YAML +You can create Promotion Workflows through the Flow Builder, a graphical interface, or through a YAML Custom Resource Definition (CRD). You can switch seamlessly between both when creating Promotion Flows. +The Flow Builder visually guides you through creating any type of Promotion Flow. See [Create a Promotion Flow](#create-a-promotion-flow). + + +## Sequential vs. parallel promotions + +Promotion Flows can be designed to run sequentially or in parallel to suit the unique requirements of any deployment process. +Sequential flows +Sequential flows are linear, where changes are promoted from the previous to the next environment in the order in which they are defined. +This is the more common and traditional kind of Promotion Flow where you start the flow from the development environment as the trigger environment, and then promote to the testing, staging, and finally to the production environments. +Parallel flows +In a parallel flow, changes are promoted across multiple environments simultaneously. This promotion logic groups environments to create promotions after multiple environments are healthy. ## Notes on Promotion Flows -Here are a few key factors to be aware of when creating Promotion Flows. +Here are a few key factors to be aware of when creating Promotion Flows. + + + + + ### Trigger and target environments You can create and assign environments for the Promotion Flow, starting with the Trigger Environment, where the change initiates the flow, and the other target environments required for promotion. You need at least one target environment for promotions. @@ -35,18 +55,19 @@ You can create and assign environments for the Promotion Flow, starting with the Reconnecting environments is only relevant when there is one or more environments in the flow _following_ the one being removed. If the environment you’re removing, for example `staging` is the final environment in the flow, you can remove it directly without needing to reconnect. +### ## Dependencies -### Inline versus automated Promotion Policy settings +### Inline versus global Promotion Policy settings For each environment, you can explicitly set the Promotion Policy, including the Promotion Action (required), and the optional Pre- and Post-Action Workflows. ##### Inline Promotion Policy settings The Flow Builder displays available settings for the Promotion Policy. If you manually select these settings, this _inline_ selection overides any automated Promotion Policy settings that match the product/environment when the flow is triggered. -##### Automated Promotion Policy settings +##### Global Promotion Policy settings If no inline settings are defined, the system applies automated Promotion Policy settings based on predefined priorities. See TBD -### Previewing Promotion Policies by Product +## Previewing Promotion Policies by Product Instead of waiting for the Promotion Flow to be triggered, you can preview Promotion Policy settings for any product to ensure that the environment and product have the desired policies. Previewing Policies by product confirms if the automated Policies that will be applied for the product are the correct ones for it. Preview is also useful to identify environments and products without matching Policies or Policies that are missing required settings such as the Promotion Action. Note that only those settings without inline values are populated by the preview. @@ -102,7 +123,7 @@ SCREENSHOT {:start="2"} 1. Do one of the following: * To review the manifest of an inline Trigger Workflow, click ??? and then select the required workflow. Continue from _step 2_. - * To apply a Trigger Workflow from automated Promotion Policy settings, click **Automated Promotion Policy**. Continue from _step 2_. + * To apply a Trigger Workflow from global Promotion Policy settings, click **Automated Promotion Policy**. Continue from _step 2_. * To add a new Promotion Workflow, click **Add New Workflow**. * You are taken to the Add Promotion Workflow page where you can define the settings. See TBD???? * A notification alerts you that there are unsaved changes to the Promotion Flow. @@ -232,9 +253,9 @@ TBD where are teh changes saved? ## Removing environments from Promotion Flows Remove one or more environments from a Promotion Flow. TBD why would you want to remove an environment? What happens if the env is defined as part of the promotion policies? -Removing an environment requires you to reconnect environments that are linked to the one being removed. +Removing an environment requires you to reconnect environments linked to the one being removed to prevent orhpans. -Reconnecting environments is only relevant when there is one or more environments in the flow _following_ the one being removed. If the environment you’re removing, for example `staging` is the final environment in the flow, you can remove it directly without needing to reconnect. +Reconnecting environments is only relevant when there are one or more environments in the flow _following_ the one being removed. If the environment you’re removing, for example `staging` is the final environment in the flow, you can remove it directly without needing to reconnect. 1. In the Codefresh UI, on the toolbar, click the **Settings** icon, and then from the sidebar, select **Promotion Flows**. 1. Select the Promotion Flow with the environment you want to remove. diff --git a/_docs/promotions/promotions-overview.md b/_docs/promotions/promotions-overview.md new file mode 100644 index 000000000..37a1b7407 --- /dev/null +++ b/_docs/promotions/promotions-overview.md @@ -0,0 +1,54 @@ +--- +title: "Promotions" +description: "The power of promotions in Codefresh GitOps" +group: promotions +toc: true +--- + + +In the context of Continuous Delivery (CD), a promotion is the process of advancing an application version from one environment to another, from staging to production for example, based on predefined criteria or manual approval. Promotions ensure that only validated, reliable versions of your applications are deployed to production. + +The current is experiencing rapid evolution, with a significant emphasis on automation, security, and cloud compatibility, revolving around the central concet of Git as the single source of truth. + +Here's how promotions are typically implemented: + +Promotion policies: Rules and conditions, such as passing test suites or code quality checks, must be satisfied before promotion. +Automated workflows: Once the criteria are met, the system automatically promotes the application to the next environment. +Manual approvals: In some cases, a manual approval gate requires human intervention before the promotion is finalized. + + +##### What is the unique value proposition of GitOps promotions in Codefresh? +Codefresh builds on the power of GitOps by fully integrating promotions into its framework, giving you enhanced visibility, control, and automation. + +Here’s what makes our GitOps promotions stand out: + +* **Declarative and version-controlled** + Promotions are tracked in Git as code. Every promotion is tied to a Git commit, giving you full traceability and version control. This means teams can always see who approved or triggered a promotion and why. + + + +* **Context and visibility** + While Argo CD manages deployments as individual applications, Codefresh introduces **environments** and **products** for a more intuitive and cohesive view of your development and deployment system. + * Environments represent different stages helping teams manage applications as they progress through the software lifecycle. + * Products group related applications. Promoting a productInstead of individual applications, They simplify promotions as a applications are promoted as a unit instead of indTeams + * Releases, unique to Codefresh, give visibility to the deployment process for products, making it easy for any stakeholder to track the success and progress of application deployments. + +##### Promotion entities +Codefresh offers several specialized entities to streamline and automate the promotion process: +* Promotion Templates: Define which properties to promote. +* Promotion Policies: Define validation and readiness requirements for environments through workflows. +* Promotion Flows: Create promotion sequences, whether simple or complex, reducing manual steps and improving accuracy. + +As with other GitOps entities, you can create these promotion entities in our intuitive UI or directly in YAML. + + +By leveraging GitOps for promotions, Codefresh ensures that the promotion process is transparent, automated, and easily auditable, offering a robust solution for enterprise-grade CD pipelines. + + +##### How do you get started with promotions? + +To get started, explore [promotion components]({{site.baseurl}}/docs/promotions/promotion-components/) to understand the entities involved. + +For a step-by-step guide on creating and implementing a promotion and monitoring its deployment, see [Create a promotion sequence]({{site.baseurl}}/docs/promotions/create-promotion-sequence/). + From 5cfb5f0a8aae5eed94aeff79567dd4dd2cf041da Mon Sep 17 00:00:00 2001 From: NimRegev Date: Wed, 18 Sep 2024 11:25:07 +0300 Subject: [PATCH 10/61] Update promotion content Content updates for promotion topics --- _docs/promotions/create-promotion-sequence.md | 25 +++--- _docs/promotions/promotion-components.md | 84 +++++-------------- _docs/promotions/promotion-flow.md | 64 ++++++-------- _docs/promotions/promotions-overview.md | 31 +++---- _docs/promotions/trigger-promotions.md | 16 +++- 5 files changed, 84 insertions(+), 136 deletions(-) diff --git a/_docs/promotions/create-promotion-sequence.md b/_docs/promotions/create-promotion-sequence.md index 930b8d52c..94352efed 100644 --- a/_docs/promotions/create-promotion-sequence.md +++ b/_docs/promotions/create-promotion-sequence.md @@ -1,6 +1,6 @@ --- title: "Promotion sequences" -description: "Step-by-step guide to creating promotions" +description: "Step-by-step guide to creating, triggering, and monitoring promotions" group: promotions toc: true --- @@ -28,7 +28,7 @@ This guide lists the steps required to create a promotion sequence. Follow the s 1. [Create applications]({{site.baseurl}}//docs/deployments/gitops/create-application/#create-an-argo-cd-application) Applications represent the components or services to promote and deploy. They are the smallest unit of deployment within a promotion sequence. - Create a Argo CD application in Form or YAML mode. + Create an Argo CD application in Form or YAML mode. 1. [Create products]({{site.baseurl}}/docs/products/create-product/) Products connect related applications and group them as a single entity. @@ -39,14 +39,14 @@ This guide lists the steps required to create a promotion sequence. Follow the s 1. [Create workflows]({{site.baseurl}}/docs/promotions/promotion-workflows/) Before promoting changes across environments, it's customary to run tests and validations that match the requirements of the target environments in the promotion sequence. - Promotion Workflows allow you to create steps and testing different environments, and enforce checks before and after promoting changes. + Promotion Workflows allow you to create steps for testing different environments, and enforce checks before and after promoting changes. -1. [Configure properties to be promoted] + -1. [Create promotion policies for environments]({{site.baseurl}}/docs/promotions/promotion-policy/) +1. [Create policies for environment validation]({{site.baseurl}}/docs/promotions/promotion-policy/) Define the conditions to validate that the target environments are ready for promotion: workflows to run before and after changes are promoted, along with the action that promotes the changes. Enforcing these conditions ensure that promotions do not break or destabilize environments. Promotion Policies define the products or type of environments with the promotion action (mandatory), and any Promotion Workflows to run before and after the promotion action (optional). @@ -57,13 +57,12 @@ This guide lists the steps required to create a promotion sequence. Follow the s 1. Configure [promotion settings]({{site.baseurl}}/docs/products/configure-product-settings/#configure-promotion-settings) and [flows]({{site.baseurl}}/products/configure-product-settings/#configure-promotion-flows) for product - After setting up the core entities and building blocks, configure settings for your product. - These settings can include the attributes to be promoted across the product's applications (Product Promotion Templates), the promotion flows valid for the product and flow-specific trigger conditions (Promotion Flows). + After setting up the core and promotion-specific entities, configure additional promotion-specific settings for your product. + These settings include the attributes to be promoted across the product's applications (Product Promotion Templates), the promotion flows valid for the product and flow-specific trigger conditions (Promotion Flows). 1. [Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/) - Implement the changes to initiate the promotion sequence. - The change made to an application in the trigger environment starts the process of moving changes through the defined sequence of environments, following the defined Promotion Policies and Settings. - TBD + Implement the changes to initiate the promotion. + The change made to an application in the trigger environment starts the process of moving these changes through the defined sequence of environments, either automatically or manually. 1. [Track deployments for products]({{site.baseurl}}/docs/promotions/releases/) @@ -72,4 +71,6 @@ This guide lists the steps required to create a promotion sequence. Follow the s ## Related articles - +[About promotions]({{site.baseurl}}/docs/promotions/promotions-overview/) +[Promotion building blocks]({{site.baseurl}}/docs/promotions/promotion-components/) +[Trigger promotions]({{site.baseurl}}docs/promotions/trigger-promotions/) diff --git a/_docs/promotions/promotion-components.md b/_docs/promotions/promotion-components.md index 0e67f3af0..5dc037c34 100644 --- a/_docs/promotions/promotion-components.md +++ b/_docs/promotions/promotion-components.md @@ -1,40 +1,17 @@ +--- +title: "Promotion building blocks" +description: "Explore entities and their roles in the promotion process" +group: promotions +toc: true +--- - - - -Promotion flows are not tied to any specific product or technology stack, making them versatile tools for managing deployments across various platforms. They can be applied to: -Consistency: Automates repetitive tasks, ensuring uniformity across deployments. -Efficiency: Reduces manual effort and accelerates the deployment process. -Control: Allows precise control over the conditions under which changes are promoted. -Visibility: Provides clear insights into the progress and status of changes across environments. -Contribution to Deployments -Promotion flows streamline the process of moving code changes through different stages, such as testing, staging, and production. By defining specific criteria for promotion, they help maintain the integrity of the software and reduce the likelihood of introducing bugs into production. - -## Flow Builder vs. YAML -You can create Promotion Workflows through the Flow Builder, a graphical interface, or through a YAML Custom Resource Definition (CRD). You can switch seamlessly between both when creating Promotion Flows. - - -## Sequential vs. parallel promotions - -Promotion Flows can be designed to run sequentially or in parallel to suit the unique requirements of any deployment process. - -Sequential flows -Sequential flows are linear, where changes are promoted from the previous to the next environment in the order in which they are defined. -This is the more common and traditional kind of Promotion Flow where you start the flow from the development environment as the trigger environment, and then promote to the testing, staging, and finally to the production environments. - -Parallel flows -In a parallel flow, changes are promoted across multiple environments simultaneously. This promotion logic groups environments to create promotions after multiple environments are healthy. - - - +If you are new to promotions in GitOps, you may find it useful to review the entities involved in the promotion process, and their roles. +There are the core entities that define the structure of your development deployment lifecyles, and promotion-specific entities, each dedicated to a different aspect of the promotion process. ## Promotion building blocks A promotion sequence comprises several building blocks, optional and required, each serving a specific role in the promotion and deployment process. -Before creating promotion flows or sequences it is advisable to understand the role of these building blocks. - - -The table describes the entities involved in the promotion process, starting with the core entities and those entities wh +The table describes the core and promotion-specific entities. @@ -57,21 +34,21 @@ The table describes the entities involved in the promotion process, starting wit - + - + - + @@ -82,37 +59,27 @@ The table describes the entities involved in the promotion process, starting wit - + - + - + - +
Users with ABAC permissionsLinkEnvironments
Product (Optional) A Product in Codefresh GitOps groups related applications into a single entity. This simplifies promotions by allowing you to promote the entire Product and all its applications across different environments, rather than managing applications individually. Users with ABAC permissionsLinkProducts
Applications Applications are the core units around which promotions revolve. Each application can be promoted individually or as part of a product. Users with ABAC permissionsLinkCreating applications
Promotion Flows Promotion flows orchestrate the movement of applications through environments, ensuring a controlled and automated promotion process. Account administratorsLinkCreating Promotion Flows
Promotion SettingsPromotion settings specify what gets promoted across environments. If using a Product, these settings can be defined within the Product’s configuration or in a YAML CRD.Promotion settings specify what gets promoted across environments. With products, these settings can be defined within the Product’s configuration or in a YAML CRD. Users with ABAC permissionsLinkPromotion settings for products
Promotion Policy A Promotion Policy outlines the actions taken when changes are promoted. It ensures that the target environment is ready for promotion, with workflows to validate the environment both before and after the promotion action, like commits or pull requests. Account administratorsLinkPromotion Policies
-Inter-environment dependencies - In both sequential and parallel flows, adding a new environment automatically establishes a dependency on the previous environment. This ensures that changes are promoted in a controlled manner. - - For parallel flows, you can add multiple environments as simultaneous dependencies on new environments. This means that the changes from the previous environment are first promoted concurrently to each of the dependent environments, and only when successfully deployed across all environments are they promoted to the next environment in the flow. - - - - - - ## Promotion entites and GitOps Runtimes @@ -130,22 +97,11 @@ If you have more than one Configuration Runtime, Codefresh automatically consoli | Promotion Policy |isc/configuration/promotion-policies| | | Promotion Flow |isc/configuration/promotion-flows| | -## Promotion entities & creation modes - -UI form YAML - - - - - - - - - -## Promotion process -What happens when a promotion flow is triggerred automatically? -Manually through drag-n-drop +## Related articles +[About promotions]({{site.baseurl}}/docs/promotions/promotions-overview/) +[Promotion sequences]({{site.baseurl}}/docs/promotions/create-promotion-sequence/) +[Trigger promotions]({{site.baseurl}}docs/promotions/trigger-promotions/) diff --git a/_docs/promotions/promotion-flow.md b/_docs/promotions/promotion-flow.md index bf7478b51..77474fee8 100644 --- a/_docs/promotions/promotion-flow.md +++ b/_docs/promotions/promotion-flow.md @@ -11,8 +11,6 @@ A Promotion Flow is a structured sequence of actions that automates the promotio Promotion Flows streamline the process of moving code changes through different stages, such as testing, staging, and production. They automate repetitive tasks, reducing manual efforts, ensuring uniformity across deployments. By defining specific criteria for promotion, they help maintain the integrity of the software and reduce the likelihood of introducing bugs into production. -Our Flow Builder visually guides you through creating any type of Promotion Flow. See [Create a Promotion Flow](#create-a-promotion-flow). -As with other entities, you can toggle between YAML and chart modes while in the Flow Builder. Before creating promotion flows, review [our notes on Promotion Flows](#notes-on-promotion-flows) which highlights key factors to be aware of in promotion flow behavior. @@ -29,19 +27,15 @@ The Flow Builder visually guides you through creating any type of Promotion Flow Promotion Flows can be designed to run sequentially or in parallel to suit the unique requirements of any deployment process. -Sequential flows -Sequential flows are linear, where changes are promoted from the previous to the next environment in the order in which they are defined. -This is the more common and traditional kind of Promotion Flow where you start the flow from the development environment as the trigger environment, and then promote to the testing, staging, and finally to the production environments. +* **Sequential promotions** + Sequential flows are linear, where changes are promoted from the previous to the next environment in the order in which they are defined. + This is the more common and traditional kind of Promotion Flow, where you start the flow from the development environment as the trigger environment, and then promote to the other target environments in succession. -Parallel flows -In a parallel flow, changes are promoted across multiple environments simultaneously. This promotion logic groups environments to create promotions after multiple environments are healthy. +* **Parallel promotions** + In a parallel prompotion flow, changes are promoted across multiple environments simultaneously. This promotion logic groups environments and creates promotions _after_ multiple environments are healthy. ## Notes on Promotion Flows -Here are a few key factors to be aware of when creating Promotion Flows. - - - - +Here are a few additional factors to be aware of when creating Promotion Flows. ### Trigger and target environments @@ -51,26 +45,26 @@ You can create and assign environments for the Promotion Flow, starting with the When adding an environment, you can select from the list of available environments, or create a new one that takes you to the Environments page for defining settings. At this point, the Promotion Flow remains unsaved, allowing to return to the flow later. * Removing environments - You can remove an environment from the Promotion Flow, and decide how to reconnect next environments to previous environments. + You can remove an environment from the Promotion Flow, and decide how to reconnect next environments if any, to previous environments. - Reconnecting environments is only relevant when there is one or more environments in the flow _following_ the one being removed. If the environment you’re removing, for example `staging` is the final environment in the flow, you can remove it directly without needing to reconnect. + Reconnecting environments is only relevant when there are one or more environments in the flow _following_ the one being removed. If the environment you’re removing, for example `staging` is the final environment in the flow, you can remove it directly without needing to reconnect. -### ## Dependencies +### Dependencies ### Inline versus global Promotion Policy settings For each environment, you can explicitly set the Promotion Policy, including the Promotion Action (required), and the optional Pre- and Post-Action Workflows. ##### Inline Promotion Policy settings -The Flow Builder displays available settings for the Promotion Policy. If you manually select these settings, this _inline_ selection overides any automated Promotion Policy settings that match the product/environment when the flow is triggered. +The Flow Builder displays available settings for the Promotion Policy. If you manually select these settings, this _inline_ selection overrides any global Promotion Policy settings that match the product/environment when the flow is triggered. ##### Global Promotion Policy settings -If no inline settings are defined, the system applies automated Promotion Policy settings based on predefined priorities. See TBD +If no inline settings are defined, the system applies global Promotion Policy settings based on predefined priorities. See TBD ## Previewing Promotion Policies by Product -Instead of waiting for the Promotion Flow to be triggered, you can preview Promotion Policy settings for any product to ensure that the environment and product have the desired policies. -Previewing Policies by product confirms if the automated Policies that will be applied for the product are the correct ones for it. Preview is also useful to identify environments and products without matching Policies or Policies that are missing required settings such as the Promotion Action. -Note that only those settings without inline values are populated by the preview. +Instead of waiting for the Promotion Flow to be triggered, you can evaluate Promotion Policy settings for any product. Policy evaluation by product is useful to identify that the environment and product have the desired policies, no matching Policies, or Policies missing required settings such as the Promotion Action. + +Note that when you evaluate by product, only those settings without inline values are populated. ## Create a Promotion Flow Visually design and create the flow by selecting environments, Promotion Actions and Workflows, and defining dependencies through the Flow Builder. If needed create new environments and promotion workflows on-the-fly when doing so. @@ -210,36 +204,27 @@ SCREENSHOT * To apply an automated Promotion Policy, click Automated Promotion Policy. 1. To return to the Promotion Flow and continue, click **Go to Promotion Flow**. You can now pick up from where you left off. -1. Continue with [Step 8: (Optional) Preview automated Promotion Policy settings by product](#step-8-optional-preview-automated-promotion-policy-settings-by-product). - - - - - - - - +1. Continue with [Step 8: (Optional) Evaluate global Promotion Policy settings by product](#step-8-optional-evaluate-global-promotion-policy-settings-by-product). -### Step 8: (Optional) Preview automated Promotion Policy settings by product -Select a product to preview settings that will be applied from automated Promotion Policies for all target environments without inline settings. -When there are no inline settings selected or defined for an environment's Promition Polocy, the system applies settings from all predefined or automated Promotion Policies that match the product and the environment according to priority. +### Step 8: (Optional) Evaluate global Promotion Policy settings by product +Select a product to evaluate the settings that will be applied from global Promotion Policies for all target environments without inline settings. +Global Promotion Policy settings are applied from all Policies that match the product and the environment, according to priority. -Preview by product within a Promotion Flow shows you if there is a Promotion Policy that matches the product, and which settings will be applied. >**NOTE** -This action is only a preview and does not impact the Promotion Flow. +This action is only a preview and does not impact the Promotion Flow when triggered. 1. From the list of Products, select the product for which to evaluate or apply Promotion Policy settings. - The Promotion Action, Pre- and Post-Action Workflows that match are applied from the predefined or automated promotion policies and displayed for each environment. Mouse over the Pre-Action, Post-Action, and Action icons to see the Workflows and the Promotion Action assigned. + The Promotion Action, Pre- and Post-Action Workflows that match are applied from the global Promotion Policies and displayed for each environment. Mouse over the Pre-Action, Post-Action, and Action icons to see the Workflows and the Promotion Action assigned. SCREENSHOT -1. If you get an error component is not defined for the Policy, click the corresponding icon and assign a Workflow or an Action. +1. If you get an error that the component is not defined for the Policy, click the corresponding icon and assign a Workflow or an Action. ### Step 9: Save changes and commit flow @@ -251,7 +236,7 @@ TBD where are teh changes saved? ## Removing environments from Promotion Flows -Remove one or more environments from a Promotion Flow. TBD why would you want to remove an environment? What happens if the env is defined as part of the promotion policies? +Remove one or more environments from a Promotion Flow. Removing an environment requires you to reconnect environments linked to the one being removed to prevent orhpans. @@ -279,5 +264,6 @@ SCREENSHOT TBD ## Related articles -[Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/) -[Promotions overview]({{site.baseurl}}/docs/promotions/promotion-components/) +[Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/) +[Promotion sequences]({{site.baseurl}}/docs/promotions/create-promotion-sequence/) +[About promotions]({{site.baseurl}}/docs/promotions/promotions-overview/) diff --git a/_docs/promotions/promotions-overview.md b/_docs/promotions/promotions-overview.md index 37a1b7407..5b44fd89b 100644 --- a/_docs/promotions/promotions-overview.md +++ b/_docs/promotions/promotions-overview.md @@ -8,17 +8,11 @@ toc: true In the context of Continuous Delivery (CD), a promotion is the process of advancing an application version from one environment to another, from staging to production for example, based on predefined criteria or manual approval. Promotions ensure that only validated, reliable versions of your applications are deployed to production. -The current is experiencing rapid evolution, with a significant emphasis on automation, security, and cloud compatibility, revolving around the central concet of Git as the single source of truth. - -Here's how promotions are typically implemented: - -Promotion policies: Rules and conditions, such as passing test suites or code quality checks, must be satisfied before promotion. -Automated workflows: Once the criteria are met, the system automatically promotes the application to the next environment. -Manual approvals: In some cases, a manual approval gate requires human intervention before the promotion is finalized. +Promotions are typically implemented through rules and conditions, such as passing test suites or code quality checks, automated workflows to promote the application to the next environment, and manual approval gates before the promotion moves into deployment. ##### What is the unique value proposition of GitOps promotions in Codefresh? -Codefresh builds on the power of GitOps by fully integrating promotions into its framework, giving you enhanced visibility, control, and automation. +Codefresh builds on the power of GitOps by fully integrating promotions into its framework, giving you enhanced visibility, control, and automation, all with Git as the single source of truth. Here’s what makes our GitOps promotions stand out: @@ -29,24 +23,21 @@ Here’s what makes our GitOps promotions stand out: With GitOps, the desired state of environments is automatically synced based on the Git repository, ensuring that any promotion aligns with the latest approved application version. --> * **Context and visibility** - While Argo CD manages deployments as individual applications, Codefresh introduces **environments** and **products** for a more intuitive and cohesive view of your development and deployment system. - * Environments represent different stages helping teams manage applications as they progress through the software lifecycle. - * Products group related applications. Promoting a productInstead of individual applications, They simplify promotions as a applications are promoted as a unit instead of indTeams - * Releases, unique to Codefresh, give visibility to the deployment process for products, making it easy for any stakeholder to track the success and progress of application deployments. + While Argo CD manages deployments as individual applications, Codefresh introduces **environments** and **products** for a more intuitive and cohesive view and managment of your development and deployment system. + * Environments represent different stages, clearly showing teams the applications as they progress through the software lifecycle. + * Products group related applications. Products allow you to promote all its applications at once, simplifying promotions and saving valuable time. + * Releases, unique to Codefresh, give visibility to the promotion and deployment process for products, making it easy for you or any stakeholder to track the success and progress of application deployments. ##### Promotion entities -Codefresh offers several specialized entities to streamline and automate the promotion process: -* Promotion Templates: Define which properties to promote. -* Promotion Policies: Define validation and readiness requirements for environments through workflows. -* Promotion Flows: Create promotion sequences, whether simple or complex, reducing manual steps and improving accuracy. - -As with other GitOps entities, you can create these promotion entities in our intuitive UI or directly in YAML. +Codefresh also offers several specialized entities that streamline and automate the promotion process, while giving you the fleiabily ou need to match organization requirements: +* **Promotion Templates**: Define which properties to promote. +* **Promotion Policies**: Define validation and readiness requirements for environments through workflows. +* **Promotion Flows**: Create simple or complex promotion sequences, reducing manual steps, improving accuracy and efficency. -By leveraging GitOps for promotions, Codefresh ensures that the promotion process is transparent, automated, and easily auditable, offering a robust solution for enterprise-grade CD pipelines. -##### How do you get started with promotions? +##### How do you get started with promotions in GitOps? To get started, explore [promotion components]({{site.baseurl}}/docs/promotions/promotion-components/) to understand the entities involved. diff --git a/_docs/promotions/trigger-promotions.md b/_docs/promotions/trigger-promotions.md index 0a40c6a7b..716473418 100644 --- a/_docs/promotions/trigger-promotions.md +++ b/_docs/promotions/trigger-promotions.md @@ -1,6 +1,6 @@ --- title: "Trigger promotions" -description: "Orchestrate promotions automatically or manually trigger promotions" +description: "Orchestrate promotions automatically through flows or manually trigger promotions" group: promotions toc: true --- @@ -8,6 +8,14 @@ toc: true When you trigger a promotion ## Automatically trigger promotions +Promotions are triggered automatically when a change in the application triggers a Promotion Flow that matches the product and environment where the changes are made. + + +##### Before you begin +* Create at least one [Promotion Flow]([About promotions]({{site.baseurl}}/docs/promotions/promotion-flow/) + +##### How to +1. ???? ## Manually trigger a Promotion Flow @@ -65,6 +73,7 @@ SCREENSHOT A release is created for the Product and the Release tab displays the ongoing deployment. SCREENSHOT + ## Manually promote applications through Promotion Policies or Flows Manually promote an application in a product to a target environment either through a predefined Promotion Flow or by creating a custom Promotion Policy for the application. @@ -115,3 +124,8 @@ SCREENSHOT A release is created for the Product and the Release tab displays the ongoing deployment. SCREENSHOT + +## Related articles +[Promotion sequences]({{site.baseurl}}/docs/promotions/create-promotion-sequence/) +[Promotion building blocks]({{site.baseurl}}/docs/promotions/promotion-components/) +[Creating Promotion Flows]({{site.baseurl}}docs/promotions/promotion-flow/) From aac9dc54a57fd815e8a895fe53d9591a0c76c56e Mon Sep 17 00:00:00 2001 From: NimRegev Date: Wed, 18 Sep 2024 14:26:46 +0300 Subject: [PATCH 11/61] Update content and structure Added topics to nav yaml and updated content --- _data/nav.yml | 20 ++ .../{ => configuration}/promotion-flow.md | 0 .../configuration/promotion-policy.md | 319 ++++++++++++++++++ 3 files changed, 339 insertions(+) rename _docs/promotions/{ => configuration}/promotion-flow.md (100%) create mode 100644 _docs/promotions/configuration/promotion-policy.md diff --git a/_data/nav.yml b/_data/nav.yml index fc57071eb..d2fcc070a 100644 --- a/_data/nav.yml +++ b/_data/nav.yml @@ -368,6 +368,26 @@ - title: Troubleshooting Argo CD applications url: "/troubleshooting-gitops-apps" +- title: Promotions + url: "/promotions" + pages: + - title: About promotions + url: "/promotions-overview" + - title: Promotion building blocks + url: "/promotion-components" + - title: Promotion sequences + url: "/create-promotion-sequence" + - title: Configuration + url: "/configuration" + sub-pages: + - title: Promotion Flows + url: "/promotion-flow" + - title: Promotion Policies + url: "/promotion-flow" + - title: Trigger promotions + url: "/trigger-promotions" + + - title: Pipelines url: "/pipelines" pages: diff --git a/_docs/promotions/promotion-flow.md b/_docs/promotions/configuration/promotion-flow.md similarity index 100% rename from _docs/promotions/promotion-flow.md rename to _docs/promotions/configuration/promotion-flow.md diff --git a/_docs/promotions/configuration/promotion-policy.md b/_docs/promotions/configuration/promotion-policy.md new file mode 100644 index 000000000..700dfdeb8 --- /dev/null +++ b/_docs/promotions/configuration/promotion-policy.md @@ -0,0 +1,319 @@ +--- +title: "Configure Promotion Policies" +description: "Run validations through Promotion Policies to assess environment readiness before orchestrating promotion" +group: promotions +toc: true +--- + + + + +When a promotion is triggered for a product in an environment, it's essential to validate the environment's readiness before deploying changes and promoting the Product. +Readiness validation ensures that the product's applications and their dependencies meet the necessary requirements and standards for deployment in the target environment. +These validations include various checks, such as code quality, unit or smoke tests, compatibility with dependencies, security compliance, +and other relevant factors specific to the target environment. + +##### Promotion Policies for readiness validation +Codefresh empowers you to create and automate environment readiness validations through Promotion Policies. +A Promotion Policy combines promotion settings defining workflows to validate environment readiness, and targets defining the products or environments for which to implement the Policies. + +The Policies can be tailored for any combination of Products and Environments, or be generic to match all Products and Environments, giving you the flexibility you need to implement the most complex to the most simple of policies. + +You can create dedicated Promotion Policies, or define them as part of a Promotion Flow which orchestrates the promotion and deployment of the Product across all Environments. + +DIAGRAM + +Review the [settings](#promotion-policy-settings) you can configure for a Promotion Policy, and how to [create a Promotion Policy](#create-a-promotion-policy). + +##### Promotion Policy implementation +More than one Promotion Policy can match the same target Product or Environment. +The logic for applying Promotion Policy settings is based on predefined priorities and target attributes. +[Promotion Policy logic](#promotion-policy-logic) details different scenarios and examples describing the implementation logic. + + + + + + +## Key features of Promotion Policies + +* **Automated validation** + Validations defined in the Promotion Policy are enforced automatically, minimizing the risk of errors, and ensuring consistency and reliability in deployments. + +* **Flexible configuration** + Promotion Policies are highly customizable to match your requirements. Define Policies per Product, per Environment, + or with broader coverage for a specific Product across all environments, or only by specific types of Environments. + +* **Priority-driven enforcement** +In cases where multiple Promotion Policies match Products, Environments, or a combination of both, Codefresh merges Promotion Settings from matching Policies in order of priority, ensuring seamless enforcement. + +* **On-demand evaluation** +Visualize Promotion Settings applied to a Product-Environment pair with Evaluate Promotion Policy option. Not only does this option identify Product-Environment pairs which do match existing Promotion Policies, it also identifies misconfigured policies. + +* **Git-based and custom promotion actions** +Whether your promotion actions are Git-based or utilize custom repositories and mechanisms for compiling application repositories, Codefresh supports both types of actions. + + + +See ??? + + + + + +## Promotion Policy settings & targets + +A Promotion Policy comprises the Policy's promotion settings and the Policy's targets. +The table below describes the settings and targets you can define for a Promotion Policy. + +{% include +image.html +lightbox="true" +file="/images/promotions/promotion-policy-settings.png" +url="/images/promotions/promotion-policy-settings.png" +alt="Promotion Policy settings" +caption="Promotion Policy settings" +max-width="60%" +%} + + + +{: .table .table-bordered .table-hover} +| Item | Description | +| -------------- | -------------- | +|**Name** | The name of the Promotion Policy.
The name must be unique in the cluster and must match Kubernetes naming conventions. | +|**Promotion Settings** | The settings that comprise the Promotion Policy.
{::nomarkdown}
  • Pre-Action Workflow: Optional. The Promotion Workflow to run before the Promotion Action.
  • ActionRequired. The Promotion Action to update the target application's source repository:
    • Commit: Perform a Git commit on the source repository. Commits are implemented immediately without not requiring manual approval to move to the next stage of the Promotion Policy.
    • Pull Request: Open a pull request (PR) on the change to the source repository. Depending on your PR policy, this option may require manual approval to move to the nex stage.
    • No Action: Run the selected Pre-Action Workflow, and the Post-Action Workflow if any, without performing a commit or opening a pull request on the application's source repository.
      This option is useful to run custom promotion policy mechanisms, not involving updating the target application's source repository to promote the application.
    {:/}See [Promotion Workflows]({{site.baseurl}}/docs/promotions/promotion-workflow/).| +|**Products** |Single or multiple Products to which to apply the Promotion Policy.
    Match Products by the name or names defined. | +|**Environments** |Single or multiple Environments to which to apply the Promotion Policy. {::nomarkdown}
    • Kind: Match Environments by their type, either Pre-production or Production.
    • Environment: Match Environments by the name or names defined.
    {:/}| +|**Priority** |The priority assigned to the Promotion Policy. The priority determines how and which Promotion Settings are applied when two or Polices match the target attributes. The priority is a positive or negative integer and defined in ascending order.
    To understand how Promotion Settings are implemented, see [Promotion Policy implementation logic](#promotion-policy-implementation-logic).| + + +## Best practices for Promotion Policies + +TBD +Examples showing when to set by environment, by product and others + +## Promotion Policy implementation logic + +Every Promotion Policy can define a few or all promotion settings, and one or more Products or Environments as targets. +When a Promotion Policy is to be run to validate readiness for an environment, promotion settings are merged from all matched policies based on their priority. +Policies with higher priority always take precedence over those with lower priority. + + +### Example Promotion Policies + +Let's consider a few different Promotion Polices. As you can see in the table below, each Policy has a name, priority, validation settings, and target attributes. +Note that not all settings are defined or configured for all policies. But all policies have a pre-defined Priority, and one or both target attributes. + +{: .table .table-bordered .table-hover} +| Promotion Policy | | +| Name |Priority |Pre-Action Workflow | Action | Post-Action Workflow | Products | Environments | +| -----------| ----------| ------------------ | ---------------------| ----------| -------------| +| pp-demo | 20 |send-slack-alert | commit |- | demo | - | +| pp-notify | 300 |send-slack-alert-1 | ?? |send-slack-success-fail | demo | - | +| pp-pre-prod |200 | | commit | validate-deployment | - | ENV_TYPE=non-prod | +| pp-prod |100 | send-slack-alert | pr |- |- | ENV_TYPE=prod | + + +(NIMA: will convert this into a diagram) + + +### Promotion Policies in Trigger Environments +TBD + + + + + + +### Scenario 1: Applying Promotion Policies with identical target attributes +This scenario reviews how Promotion Policy settings are applied when at least two Policies match the same target attributes. + +**Goal**: Promote `demo` product +**Matched Promotion Policies**: + * `pp-demo` with the target Product attribute, `demo` + * `pp-notify` also with target Product attribute, `demo` +**Apply Promotion Policy**: +When more than one Policy matches the promotion requirement, the same Product in this case, the Priority determines how Policy settings are applied. +* **Priority**: Promotion Policy `pp-demo` has the highest priority (priority is in ascending order) +* **Promotion Policy settings**: + * Pre-Action Workflow: Configured for `pp-demo` as `send-slack-alert` + * Action: Configured for `pp-demo` as `commit` + * Post-Action Workflow: + Not configured for `pp-demo` + The Promotion Policy with the next highest priority that defines a Post-Action is `pp-notify`, as `send-slack-success-fail` + +##### Summary +The promotion policy `pp-demo` has the highest priority (20), so its Pre-Action (`send-slack-alert`) and Action (`commit`) are applied. +The Post-Action comes from `pp-notify`, the Policy with the next highest priority that defines a Post-Action. + + +### Scenario 2: Applying Promotion Policies with different target attributes + +This scenario reviews how Promotion Policy settings are applied when two Policies have different target attributes that match the requirements. + +**Goal**: Promote `demo` product to all non-production environments +**Matched Promotion Policies**: + * `pp-pre-prod` matches target Environment, `ENV_TYPE=non-prod` + * `pp-demo` matches target Product, `demo` +**Apply Promotion Policy**: +When there are no specific attributes, the Priority determines how Policy settings are applied. +* **Priority**: Promotion Policy `pp-demo` has the highest priority (priority is in ascending order) +* **Promotion Policy settings**: + * Pre-Action Workflow: Configured for `pp-demo` as `send-slack-alert` + * Action: Configured for `pp-demo` as `commit` + * Post-Action: + Not configured for `pp-demo` + The Promotion Policy with the next highest priority that defines a Post-Action is `pp-notify`, as `send-slack-success-fail` + +##### Summary +The promotion policy `pp-demo` has the highest priority (20), so its Pre-Action (`send-slack-alert`) and Action (`commit`) are applied. +The Post-Action comes from `pp-notify`, the Policy with the next highest priority that defines a Post-Action. + +## Create a Promotion Policy +Create a Promotion Policy to validate an environment's readiness before promoting and deploying changes to a Product. + +##### Before you begin + +* Create [Promotion Workflows]({{site.baseurl}}/docs/promotions/promotion-policy/) + +##### How to + +1. In the Codefresh UI, on the toolbar, click the **Settings** icon, and then from Promotions in the sidebar, select [Promotion Policies](https://g.codefresh.io/2.0/?????){:target="\_blank"}. +1. Do one of the following: + * To create your first Promotion Policy, click **Add Policy**. + * If you have already Promotion Policies, click **Add** at the bottom of the list. +1. Select the mode in which to define the Promotion Policy as **YAML** or **Form**. + You can toggle between the modes as you define the Promotion Policy. +1. Define the **Policy Settings**, as described in XREF: +1. Define how and which **Products** to select for this Promotion Policy. +1. Define how and which **Environments** to select for this Promotion Policy. +1. Commit the changes. + The Promotion Policy is added to the Promotion List. + +## Promotion Policy list + +Here's an example of the Promotion Policy page which displays all Promotion Policies in the account. This is also the location from which you can create and manage existing policies. +SCREENSHOT + +* If there are multiple Promotion Policies that match the same Product or Environments, the Priority determines how Promotion Policy settings are applied. +* The **Evaluate Promotion Policy** functionality allows you to select any Product and Environment pair and visualize the Promotion Settings that will be applied from all the Promotion Policies that match the selected pair. See [Evaluate Promotion Settings for Products and Environments ](#match-promotion-policies-to-products-and-environments). + + +## Evaluate Promotion Settings for Products and Environments +Select a specific Product-Environment pair and preview the Promotion Settings that will be applied for it. + +Evaluate Promotion Policies to identify: +* Product-Environment pairs that don't match any existing Promotion Policies +* Missing Promotion Settings +* Possible conflicts with Promotion Flows +* How to optimize existing Policies + +If there are multiple Policies with either identical or different target attributes that match the Product-Environment selected, Codefresh merges Promotion Settings from all matched polices based on the priority of each Policy and the [implementation logic](#promotion-policy-implementation-logic). + +##### How to + +1. In the Codefresh UI, on the toolbar, click the **Settings** icon, and then from Promotions in the sidebar, select **Promotion Policies**. +1. In the Promotion Policies page, click **Evaluate Promotion Policy**. + +{% include +image.html +lightbox="true" +file="/images/promotions/evaluate-promotion-policy.png" +url="/images/promotions/evaluate-promotion-policy.png" +alt="Evaluate Promotion Policy" +caption="Evaluate Promotion Policy" +max-width="60%" +%} + +{:start="3"} +1. Select the Product and Environment for which to evaluate the Promotion Policy, and click **Preview Promotion**. + The Result summarizes the Promotion Settings that will be applied for the selected pair from all matched Promotion Policies. + * If there are messages on misconfigured Policies, see [Evaluate Promotion Settings for Products and Environments](#match-promotion-policies-to-products-and-environments). + * On the right, select the Workflows if defined to view manifests. + +{% include +image.html +lightbox="true" +file="/images/promotions/promotion-policy-evaluation-result.png" +url="/images/promotions/promotion-policy-evaluation-result.png" +alt="Previewing results for Promotion Policy evaluation" +caption="Previewing results for Promotion Policy evaluation" +max-width="60%" +%} + +{:start="4"} +1. If required, update the Promotion Settings for one or more Promotion Policies. + + + + + +### Understand results from Promotion Policy evaluation +When you evaluate Promotion Policies, in addition to identifying Products and Environments that do not match any existing Policies, you can also identify misconfigured Policies. + +Misconfigured Policies include: +* [Action missing in matched Policies](#action-missing-in-matched-policies) +* [Pre-Action Workflow does not include required step with promotion action](#pre-action-workflow-does-not-include-required-step-with-promotion-action) + +#### No Promotion Policy matches + +#### Action missing in matched Policies + +**Message** +Unable to apply any Promotion Policy for the selected Product-Environment pair.
    +SCREENSHOT OF MESSAGE + +**Reason** +Promotion Action has not been configured in any of the Policies that match the selected Product-Environment pair. +Promotion Policy cannot be applied to the pair. + + +**Corrective action** +Promotion Policies must be configured with an Action: Commit, Pull request, or No Action. + + +#### Pre-Action Workflow does not include required step with promotion action +**Message** +Promotion Flow will fail for the selected Product-Environment pair.
    +Merged Promotion Settings from the matched Promotion Policies define No Action as the Promotion Action, but either matched Promotion Policies do not include a Pre-Action Workflow or Pre-Action Workflows do not include a step to initiate a corresponding promotion action.
    +Configure or update a Pre-Action Workflow in one of the matched Promotion Policies as required. + + +**Reason** +When No Action is configured as a Promotion Setting, one of the matched Promotion Policies: +* Must be configured with a Pre-Action Workflow +* Pre-Action Workflow must include a step that initiates or executes the corresponding Promotion Action + +**Corrective action** +Configure one of the matched Promotion Policies with a Pre-Action Workflow. +Make sure it includes a step to execute the Promotion Action that will promote the changes in the environment. + +## Edit/delete Promotion Policies +Manage Promotion Policies by updating settings for existing Promotion Policies, and deleting unused Policies. + +>**NOTES** +When editing Promotion Policy settings, you cannot change the name. + +Deleting a Promotion Policy removes it from all the Products and Environments it is assigned to. + +## Visualize Promotion Workflows in Releases + +When a product is promoted manually or automatically, the promotion mechanism create a release for the product with a unique release ID. The release provides a graphical representation of the promotion flow across the environments defined for it. +The visualization includes the Pre- and Post-Action Promotion Workflows within the environments, more specifically, the steps within the workflows. + +SCREENSHOT + +For more information, see [Promotion Workflows in Product Releases]({{site.baseurl}}/docs/promotions/releases/#promotion-workflows-in-product-releases). + +## Related articles +TBD \ No newline at end of file From f703cf5a73316e51cda6550ce54844a758514318 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Sun, 22 Sep 2024 11:50:05 +0300 Subject: [PATCH 12/61] Add product releases to bucket Added product releases topic to promotions bucket --- _data/nav.yml | 4 +- _docs/promotions/product-releases.md | 318 +++++++++++++++++++++++++++ 2 files changed, 321 insertions(+), 1 deletion(-) create mode 100644 _docs/promotions/product-releases.md diff --git a/_data/nav.yml b/_data/nav.yml index d2fcc070a..8deda92e6 100644 --- a/_data/nav.yml +++ b/_data/nav.yml @@ -385,7 +385,9 @@ - title: Promotion Policies url: "/promotion-flow" - title: Trigger promotions - url: "/trigger-promotions" + url: "/trigger-promotions" + - title: Monitor promotions for products + url: "/trigger-promotions" - title: Pipelines diff --git a/_docs/promotions/product-releases.md b/_docs/promotions/product-releases.md new file mode 100644 index 000000000..290c8b36d --- /dev/null +++ b/_docs/promotions/product-releases.md @@ -0,0 +1,318 @@ +--- +title: "Tracking product promotions" +description: "Monitor promotion orchestration for a product through Releases" +group: promotions +toc: true +--- + + + + +When a Promotion Flow is triggered for a product, the flow orchestrates deployment across one or more environments until the new version is deployed to production or to the desired target environment. + +In the context of GitOps, a release is a comprehensive view of the progression of a product as it is promoted through different environments when a promotion flow is triggered. The release encompasses the collective state of all environments and workflows involved in deploying that change, from the initial trigger environment to the final target environment. + +The Releases feature in Codefresh is designed for tracking deployments of a product across multiple environments. + +{% include +image.html +lightbox="true" +file="/images/gitops-promotions/releases/releases-list.png" +url="/images/gitops-promotions/releases/releases-list.png" +alt="Release list for a product" +caption="Release list for a product" +max-width="60%" +%} + + + + +##### Releases & Products +A Release is added for a Product when a Promotion Flow is triggered, either automatically or manually for that product. +On drill down into a Product, the Releases tab displays the list of ongoing and completed releases for the product, with the option of getting detailed insights on a specific release. + +##### Releases & developers +As an application developer or a DevOps engineer, you often lack visibility into the deployment process after pushing your code, only being alerted when issues arise. Our Releases feature changes this dynamic by offering full visibility at all times, whether you need to monitor an ongoing deployment, identify and resolve issues for deployments, or understand the changes involved in a release. + +##### Use cases +Whether you are a product manager or an application developer, with Releases, you can: +* Visualize the product's deployment lifecycle +* Access an integrated list of changes that led to the deployment +* See the current status of ongoing deployments +* Troubleshoot issues preventing deployment to production +* Address customer-reported issues through detailed insights into the deployment lifecycle + + +There are two key aspects of tracking deployments for a product through releases: +* **Promotion Flow** + Tracking the Promotion Flow for the release provides a graphical representation of how the release is orchestrated, showing the progression through different environments. + See [Monitor promotion orchestration for releases](#monitor-promotion-orchestration-for-releases). + +* **Release notes** + Tracking through release notes provides an integrated list of changes from various sources and tools, providing a comprehensive view of what led to the deployment. + See [Analyze change history in Release Notes](#analyze-change-history-in-release-notes). + + + + + +## View Releases for products + +The Releases tab for a product displays the releases for that product, whether successful or failed. + +1. In the Codefresh UI, from the sidebar, select **Products**. +1. Select the product and then click the **Releases** tab. + +The Releases page displays on-going and completed releases for the product. + +{% include +image.html +lightbox="true" +file="/images/gitops-promotions/releases/releases-list.png" +url="/images/gitops-promotions/releases/releases-list.png" +alt="Release list for a product" +caption="Release list for a product" +max-width="60%" +%} + +The table describes important insights in the Releases page. + +|Item | Description* | +|-------------|---------------------| +| **Release ID** | The Codefresh-assigned identifier uniquely identifying the release. Clicking the Release ID displays the ongoing or completed Promotion Flow for the release. | +| **Promotion Flow** | The flow orchestrating the promotion for the specific release. Clicking the link takes you to the Promotion Flow page with a graphical representation of the flow. For details, see ??? | +| **Environments** | The environments defined in the Promotion Flow for the release and their deployment statuses, which can be one of the following:{::nomarkdown}
    • : Successful
    • : Running
    • : Pending
    • : Failed
    {:/} See [Status logic for releases](#status-logic-for-releases).| + + + + + +## Monitor promotion orchestration for releases + +Monitor promotion orchestration for an on-going release, or analyze that of a completed release, across the different environments defined for it in the Promotion Flow: +* View how different environments are interconnected within the Promotion Flow to understand the dependencies and flow of deployment. +* Monitor executions of workflow steps in each environment and get alerted to failed steps in workflows. Early detection of failures allows for quick intervention, reducing the risk of prolonged issues and ensuring the deployment process remains on track. + +##### How to + +1. In the Codefresh UI, from the sidebar, select **Products**. +1. Select the product and then click the **Releases** tab. +1. Click a Release ID to view the promotion orchestration. +1. To view the complete history of code changes, click **Release Notes**. + +{% include +image.html +lightbox="true" +file="/images/gitops-promotions/releases/release-visualization.png" +url="/images/gitops-promotions/releases/release-visualization.png" +alt="Promotion visualization for a release" +caption="Promotion visualization for a release" +max-width="60%" +%} + +### Header in Product Releases +The header summarizes the change that triggered the promotion, the overall status of the release, and the number of failed, successful, running, and pending environments. + +The commit details are always for the trigger environment that initiated the promotion. + +See also [Release status](#release-status). + + + +### Environments in Product Releases + +Graphical view of the different environments defined in the Promotion Flow. + +You can: +* Understand the interconnections between the environments, whether linear or parallel. +* Visualize the dependencies between environments to see how changes propagate through the deployment process + +Each environment is color-coded to indicate the overall status of the promotion for that environment. See also [Environment (deployment) status](#environment-deployment-status). + + +#### Concurrent promotions within environments + +If there is an update that triggers a Pre- or Post-Action Workflow within an environment while the same Workflow is already in progress, the ongoing Workflow is automatically terminated and the latest Workflow is run instead. + + +For example, if an update in the `staging` environment triggers the `echo-pre-action` Pre-Action Workflow, and a later update in the same environment also triggers the same `echo-pre-action` Pre-Action Workflow, the earlier instance is terminated, and the later instance continues to run. + + +NIMA: how will it be shown in the releases tab? + +### Promotion Workflows in Product Releases + +Each environment displays the steps for the Pre- and Post-Action Workflows defined for it. The workflows are designed to ensure that the deployment process is thoroughly validated and executed correctly. +See [Workflow and workflow-step status](#workflow-and-workflow-step-status). + +#### Pre- and Post-Action Workflows + +* Trigger Environment: Can run only Post-Action workflows. +* Other Environments: Can run both Pre- and Post-Action workflows as defined by the Promotion Policies applied to the environments. + +#### Versioning in Environments +When the Post-Action Workflow in the trigger environment, or the Pre-Action Workflow and Promotion Action in any other environment, completes successfully, the promotion mechanism commits the changes and advances the version number for the applications within the product. This occurs even if the Post-Action Workflow in a specific environment fails to complete. + +Because of this automatic version update, it's essential to incorporate a revert or rollback mechanism in the Post-Action Workflow to easily revert changes if needed. + + + + +#### Errors for Workflow steps +Workflows fail when at least one step in the workflow does not complete successful execution. +Identifying and resolving these failures in real-time are critical to maintaining smooth deployment processes. + +Errors can be categorized into: + +* **Workflow errors** + * Prefixed with {::nomarkdown}{:/}. + * Listed at the top of each environment for easy identification. + * Clicking on the issue shows a description of the error, logs for the step, the workflow manifest used, and a link to the workflow. + +* **Application errors** + * Prefixed with {::nomarkdown}{:/}. + * Occurs when the health status of an application connected to the product is Degraded, indicating that one of its resources is not healthy. + See [Health status for application resources]({{site.baseurl}}/docs/deployments/gitops/applications-dashboard/#health-status-for-application-resources). + Clicking on the error takes you to the Current State tab in the GitOps Apps dashboard. + +* **Git errors** + * Prefixed with {::nomarkdown}{:/}. + * Typically commit failures related to Git operations. + + + +Other types of errors that result in failed workflows can include network or connectivity errors, or errors +arising from insufficient permissions to execute workflow steps or access necessary resources. + + + +## Analyze change history in Release Notes + +Access the release notes to see a detailed history of all changes that led to the deployed release and artifacts created for it. + +These changes are collated from different tools and sources, and include code changes, commits, and associated issues or fixes. +Use the historical data to troubleshoot issues, understand the context of the deployment, and improve future releases. + +NIMA: Add here use case of how to use release notes to troubleshoot/trace issue? + +{% include +image.html +lightbox="true" +file="/images/gitops-promotions/releases/release-notes.png" +url="/images/gitops-promotions/releases/release-notes.png" +alt="Release notes with change history for release" +caption="Release notes with change history for release" +max-width="60%" +%} + + + +## Status logic for Releases + + +There are three levels of statuses for a product release. + +In top-down order, you have the: +* Overall release status +* Environment deployment status +* Workflow step status + + + +### Release status +The release status is displayed on the right on drilldown into a release ID. +It is determined from the statuses of all the environments defined in the Promotion Flow that orchestrates the deployment of the product. + +The table describes the possible statuses of a Release. + +{: .table .table-bordered .table-hover} +| Release Status | Description | +|------------ |---------------------------------------| +| **Successful** | Promotions were completed successfully in all the environments and the changes were successfully deployed . | +| **Progressing** | Promotion is currently on-going for at least one environment. | +| **Suspended** | Promotion in an environment is pending completion. This could be because of a condition in one of its workflows or because a pull request is waiting for approval. | +| **Terminated** | Promotion currently being run in an environment was terminated, preventing deployment to the other environments defined in the Promotion Flow. | +| **Failed** | Promotion failed in at least one environment causing the entire release to fail. This could be because:
    -The Pre- or Post-Action Workflow, or Promotion Action failed.
    -At least one application is out of sync or degraded.

    Failures are flagged in the environment under Issues. Clicking on Issues opens a panel displaying the reason for the error, with links to the resource causing the issue, or to the logs and manifests of the resource.| + + + +### Environment (deployment) status +The overall deployment status of an environment is determined by the cumulative statuses of its Promotion (Pre- and Post-Action) Workflows and the Promotion Action. + +The table describes the possible deployment statuses for environments. + +{: .table .table-bordered .table-hover} +| Environment Status | Description | +|------------ |---------------------------------------| +| **Successful** | All Workflows in the environment completed successfully and the Promotion Action was successful. | +| **Running** | At least one step in a Pre- or Post-Action Workflow in the environment is currently in progress. | +| **Suspended** | One or both the Pre- and Post-Action Workflows or the Promotion Action is pending execution. This could be because of a condition in the Workflow or because a pull request is pending manual approval. | +| **Failed** | At least one step in a Workflow failed to execute, has a syntax error, was manually terminated, or the application is out of sync or degraded. | + + +### Workflow and workflow-step status + +* The status of a Workflow is determined by the status of all its steps. + +* The status of a step in the Pre- or Post-Action Workflow is its aggregated status across all the Workflows including and running that step within the environment. Step status is aggregated because a product typically includes multiple applications, and therefore executes multiple Promotion Workflows in parallel through the Promotion Policies. + +The table describes the possible statuses for Promotion Workflow steps. + +{: .table .table-bordered .table-hover} +| Workflow-step Status | Description | +|------------ |---------------------------------------| +| **Success** | The step completed execution without errors in all the Pre- and Post-Action Workflows that included it. | +| **Running** | The step is currently in progress in at least one of the Pre- and Post-Action Workflows. | +| **Pending** | The step is pending execution in at least one of the Pre- and Post-Action Workflows. | +| **Failed** | At least one step in a Pre- or Post-Action Workflow failed to execute. (NIMA: what could be the reasons?) | +| **Error** | At least one step in a Pre- or Post-Action Workflow has a syntax error. (NIMA: example| +| **Terminated** | At least one step in a Pre- or Post-Action Workflow was manually terminated. (NIMA: example of reasons)| + + + + +## Retry a failed release +Retry a failed release to restart the process from the exact point of failure. Restarting from the point of failure rather than from scratch saves time and resources, enabling a quicker recovery and minimizing downtime. + +For example, you may want to retry a release if the deployment failed due to an application being out of sync or in a degraded state, and the issue has since been resolved. +Another scenario where a retry is useful is when a workflow step encountered a temporary network issue that has now been corrected. By retrying the release, you can continue the deployment without redoing steps that were already successful. + +1. In the Codefresh UI, from the sidebar, select **Products**. +1. Select the product and then click the **Releases** tab. +1. Click the Release ID for a failed release, and then click **Retry**. + +{% include +image.html +lightbox="true" +file="/images/gitops-promotions/releases/retry-failed-release.png" +url="/images/gitops-promotions/releases/retry-failed-release.png" +alt="Retry failed release" +caption="Retry failed release" +max-width="60%" +%} + + The release resumes execution from the point of failure, in this case, retries the Post-Action Workflow step, and the status of the release changes to Running. Note that the release ID does not change. + + + + +## Related articles +TBD + + + + + + + From c24c3ecf6ecc327f88fe3bc3b1a0099908aecedd Mon Sep 17 00:00:00 2001 From: NimRegev Date: Sun, 22 Sep 2024 13:58:48 +0300 Subject: [PATCH 13/61] Update promotion articles Updated content and formatting for articles in promotion bucket --- _data/nav.yml | 4 +-- _docs/promotions/configuration.md | 8 +++++ .../configuration/promotion-flow.md | 6 +++- _docs/promotions/create-promotion-sequence.md | 35 +++++++++---------- _docs/promotions/promotion-components.md | 26 +++++++------- 5 files changed, 46 insertions(+), 33 deletions(-) create mode 100644 _docs/promotions/configuration.md diff --git a/_data/nav.yml b/_data/nav.yml index 8deda92e6..181f9e062 100644 --- a/_data/nav.yml +++ b/_data/nav.yml @@ -383,11 +383,11 @@ - title: Promotion Flows url: "/promotion-flow" - title: Promotion Policies - url: "/promotion-flow" + url: "/promotion-policy" - title: Trigger promotions url: "/trigger-promotions" - title: Monitor promotions for products - url: "/trigger-promotions" + url: "/product-releases" - title: Pipelines diff --git a/_docs/promotions/configuration.md b/_docs/promotions/configuration.md new file mode 100644 index 000000000..228d88283 --- /dev/null +++ b/_docs/promotions/configuration.md @@ -0,0 +1,8 @@ +--- +title: "Configuration" +description: "Configure promotion entities" +group: promotions +toc: true +--- + +TBD \ No newline at end of file diff --git a/_docs/promotions/configuration/promotion-flow.md b/_docs/promotions/configuration/promotion-flow.md index 77474fee8..03bfca53e 100644 --- a/_docs/promotions/configuration/promotion-flow.md +++ b/_docs/promotions/configuration/promotion-flow.md @@ -51,6 +51,8 @@ You can create and assign environments for the Promotion Flow, starting with the ### Dependencies +TBD + ### Inline versus global Promotion Policy settings For each environment, you can explicitly set the Promotion Policy, including the Promotion Action (required), and the optional Pre- and Post-Action Workflows. @@ -223,7 +225,8 @@ This action is only a preview and does not impact the Promotion Flow when trigge The Promotion Action, Pre- and Post-Action Workflows that match are applied from the global Promotion Policies and displayed for each environment. Mouse over the Pre-Action, Post-Action, and Action icons to see the Workflows and the Promotion Action assigned. SCREENSHOT - + +{:start="2"} 1. If you get an error that the component is not defined for the Policy, click the corresponding icon and assign a Workflow or an Action. @@ -265,5 +268,6 @@ TBD ## Related articles [Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/) +[Tracking product promotions]({{site.baseurl}}/docs/promotions/product-releases/) [Promotion sequences]({{site.baseurl}}/docs/promotions/create-promotion-sequence/) [About promotions]({{site.baseurl}}/docs/promotions/promotions-overview/) diff --git a/_docs/promotions/create-promotion-sequence.md b/_docs/promotions/create-promotion-sequence.md index 94352efed..e18d14a26 100644 --- a/_docs/promotions/create-promotion-sequence.md +++ b/_docs/promotions/create-promotion-sequence.md @@ -10,7 +10,7 @@ This guide lists the steps required to create a promotion sequence. Follow the s ## Prerequisites -1. [Configuration Runtime]({{site.baseurl}}/docs/installation/gitops/monitor-manage-runtimes/#designating-configuration-runtimes) +1. [Configuration Runtime]({{site.baseurl}}/docs/installation/gitops/monitor-manage-runtimes/#designating-configuration-runtimes) The Configuration Runtime is a GitOps Runtime that stores the manifests of the promotion entities. Designate at least one GitOps Runtime as the Cofiguration Runtime. If no GitOps Runtime has been designated as such, Codefresh assigns one of the existing Runtimes. @@ -18,26 +18,26 @@ This guide lists the steps required to create a promotion sequence. Follow the s 1. Admin permissions Only account admins can create promotion entities such as Promotion Policies and Promotion Flows. -1. [User permissions]({{site.baseurl}}/docs/administration/account-user-management/gitops-abac/) +1. [User permissions]({{site.baseurl}}/docs/administration/account-user-management/gitops-abac/) Users need the required ABAC permissions to create Promotion Workflows and configure product settings. ## How to: Step-by-step -1. [Create environments]({{site.baseurl}}/docs/dashboards/gitops-environments/#create-environments) +1. [Create environments]({{site.baseurl}}/docs/dashboards/gitops-environments/#create-environments) Environments define the starting and the end points of promotions. + For a promotion sequence, you need at least two environments: the trigger environment, which is the source of the changes to promote, and the target environment, to which the changes need to be promoted. -1. [Create applications]({{site.baseurl}}//docs/deployments/gitops/create-application/#create-an-argo-cd-application) +1. [Create applications]({{site.baseurl}}//docs/deployments/gitops/create-application/#create-an-argo-cd-application) Applications represent the components or services to promote and deploy. They are the smallest unit of deployment within a promotion sequence. Create an Argo CD application in Form or YAML mode. -1. [Create products]({{site.baseurl}}/docs/products/create-product/) +1. [Create products]({{site.baseurl}}/docs/products/create-product/) Products connect related applications and group them as a single entity. Being able to apply promotion settings at the level of the product, and being able to promote the product with all its applications, simplifies promotion management. - Create a product and connect related applications to it, either manually or declaratively. -1. [Create workflows]({{site.baseurl}}/docs/promotions/promotion-workflows/) +1. [Create workflows]({{site.baseurl}}/docs/promotions/promotion-workflows/) Before promoting changes across environments, it's customary to run tests and validations that match the requirements of the target environments in the promotion sequence. Promotion Workflows allow you to create steps for testing different environments, and enforce checks before and after promoting changes. @@ -45,27 +45,24 @@ This guide lists the steps required to create a promotion sequence. Follow the s Instead of doing a manual diff and deciding which changes to promote, or promoting entire applications, configure the precise changes to promote, ensuring consistency and reducing errors. Promotion Templates define which files and attributes within those files to promote across the applications in the product. --> - -1. [Create policies for environment validation]({{site.baseurl}}/docs/promotions/promotion-policy/) - Define the conditions to validate that the target environments are ready for promotion: workflows to run before and after changes are promoted, along with the action that promotes the changes. Enforcing these conditions ensure that promotions do not break or destabilize environments. - +1. [Create policies for environment validation]({{site.baseurl}}/docs/promotions/promotion-policy/) + Define the conditions to validate that the target environments are ready for promotion: workflows to run before and after changes are promoted, along with the action that promotes the changes. Enforcing these conditions ensure that promotions do not break or destabilize environments. Promotion Policies define the products or type of environments with the promotion action (mandatory), and any Promotion Workflows to run before and after the promotion action (optional). -1. [Create flows to orchestrate promotions]({{site.baseurl}}/docs/promotions/promotion-flow/) +1. [Create flows to orchestrate promotions]({{site.baseurl}}/docs/promotions/promotion-flow/) Orchestrate the sequence of actions to move and deploy changes through the required environments, from the trigger environment to the final target environment. Promotion Flows ensure that changes are promoted in a controlled and predictable manner by integrating environments, products and applications, promotion workflows, and policies. - -1. Configure [promotion settings]({{site.baseurl}}/docs/products/configure-product-settings/#configure-promotion-settings) and [flows]({{site.baseurl}}/products/configure-product-settings/#configure-promotion-flows) for product - After setting up the core and promotion-specific entities, configure additional promotion-specific settings for your product. +1. Configure [promotion settings]({{site.baseurl}}/docs/products/configure-product-settings/#configure-promotion-settings) and [flows]({{site.baseurl}}/products/configure-product-settings/#configure-promotion-flows) for product + After setting up the core and promotion-specific entities, configure additional promotion-specific settings for your product. These settings include the attributes to be promoted across the product's applications (Product Promotion Templates), the promotion flows valid for the product and flow-specific trigger conditions (Promotion Flows). -1. [Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/) +1. [Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/) Implement the changes to initiate the promotion. The change made to an application in the trigger environment starts the process of moving these changes through the defined sequence of environments, either automatically or manually. -1. [Track deployments for products]({{site.baseurl}}/docs/promotions/releases/) +1. [Track deployments for products]({{site.baseurl}}/docs/promotions/releases/) Monitor the deployment progress for the product as it moves through the promotion sequence. Use the Releases feature to track and ensure successful deployments across environments. @@ -73,4 +70,6 @@ This guide lists the steps required to create a promotion sequence. Follow the s ## Related articles [About promotions]({{site.baseurl}}/docs/promotions/promotions-overview/) [Promotion building blocks]({{site.baseurl}}/docs/promotions/promotion-components/) -[Trigger promotions]({{site.baseurl}}docs/promotions/trigger-promotions/) +[Trigger promotions]({{site.baseurl}}docs/promotions/trigger-promotions/) +[Tracking product promotions]({{site.baseurl}}/docs/promotions/product-releases/) + diff --git a/_docs/promotions/promotion-components.md b/_docs/promotions/promotion-components.md index 5dc037c34..dccd709f8 100644 --- a/_docs/promotions/promotion-components.md +++ b/_docs/promotions/promotion-components.md @@ -81,27 +81,29 @@ The table describes the core and promotion-specific entities. -## Promotion entites and GitOps Runtimes +## Promotion entities and GitOps Runtimes -All promotion entities are stored as manifests in the Shared Configuration Repository of the GitOps Runtime designated as the Configuration Runtime. +All promotion entities are stored as manifests in the Shared Configuration Repository of the GitOps Runtime designated as the [Configuration Runtime]({{site.baseurl}}/docs/installation/gitops/monitor-manage-runtimes/#designating-configuration-runtimes). If you have more than one Configuration Runtime, Codefresh automatically consolidates the settings into a single set of promotion manifests. {: .table .table-bordered .table-hover} -| Entity | Location | Toekn -| -------------- | -------------- | -| Environments |- | | -| Product |user-isc/resources/configuration/products | | -| Applications |Git Source associated with Runtime | | -| Promotion Workflows |isc/resources/all-runtimes-all-clusters/promotion-workflows |should be covered by ABAC, and commit done via Runtime Token.reason for having to be stored in the ISC is that is needs to be in all clusters and run | -| Promotion Template |isc/configuration/promotion-templates| | -| Promotion Policy |isc/configuration/promotion-policies| | -| Promotion Flow |isc/configuration/promotion-flows| | +| Entity | Location | Token +| -------------- | -------------- |---------| +| Environments |N/A | None | +| Product |`isc/resources/configuration/products` | Git user token | +| Applications |Git Source associated with Runtime | Git user token | +| Promotion Flow |`isc/configuration/promotion-flows`| Git user token | +| Promotion Policy |`isc/configuration/promotion-policies`| Git user token | +| Promotion Workflows |`isc/resources/all-runtimes-all-clusters/promotion-workflows` |Git user token | +| Promotion Template |`isc/configuration/promotion-templates`| N/A | + ## Related articles [About promotions]({{site.baseurl}}/docs/promotions/promotions-overview/) [Promotion sequences]({{site.baseurl}}/docs/promotions/create-promotion-sequence/) -[Trigger promotions]({{site.baseurl}}docs/promotions/trigger-promotions/) +[Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/) +[Tracking product promotions]({{site.baseurl}}/docs/promotions/product-releases/) From 1843a3cba5b5abd5914ddd294acf0a61f4544940 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Sun, 27 Oct 2024 16:39:15 +0200 Subject: [PATCH 14/61] Update promotion topics Implemented feedback on promotion topics from product --- .../configuration/promotion-flow.md | 68 +++++++++++++++---- _docs/promotions/create-promotion-sequence.md | 37 ++++++---- _docs/promotions/promotion-components.md | 18 ++--- _docs/promotions/promotions-overview.md | 41 ++++++----- 4 files changed, 112 insertions(+), 52 deletions(-) diff --git a/_docs/promotions/configuration/promotion-flow.md b/_docs/promotions/configuration/promotion-flow.md index 03bfca53e..c75d4adc1 100644 --- a/_docs/promotions/configuration/promotion-flow.md +++ b/_docs/promotions/configuration/promotion-flow.md @@ -39,7 +39,9 @@ Here are a few additional factors to be aware of when creating Promotion Flows. ### Trigger and target environments -You can create and assign environments for the Promotion Flow, starting with the Trigger Environment, where the change initiates the flow, and the other target environments required for promotion. You need at least one target environment for promotions. +You can create and assign environments for the Promotion Flow, starting with the Trigger Environment, where the change to the application initiates the flow, and the other target environments required for promotion. You need at least one target environment for promotions. + +The Trigger * Adding environments When adding an environment, you can select from the list of available environments, or create a new one that takes you to the Environments page for defining settings. At this point, the Promotion Flow remains unsaved, allowing to return to the flow later. @@ -83,23 +85,69 @@ Open the Flow Builder to add a Promotion Flow. SCREENSHOT {:start="3"} -1. Continue with [Step 2: Select Trigger Environment](#step-2-select-trigger-environment). +1. In **Select Trigger Environment**, click ??? to see the list of available environments: + * Select an existing environment, select it and click **Add**. + * To create a new environment, click **Add New Environment**. + +SCREENSHOT + +{:start="4"} +1. Optional. To add a Trigger Workflow and validate the readiness of the trigger environment after the change and commit action, click {::nomarkdown}{:/}. + * To review the manifest of an inline Trigger Workflow, click ??? and then select the required workflow. + * To apply a Trigger Workflow from global Promotion Policy settings, click **Automated Promotion Policy**. + * To add a new Promotion Workflow as the trigger workflow, click **Add New Workflow**. + +SCREENSHOT + +{:start="5"} +1. To add a target environment to promote to, either sequentially or in parallel, mouse over the right of the environment and click ??. + To add parallel environments, click ?? on the right of the previous environment. For example, to add `qa` and `staging` as parallel environments to `dev`, you would click ?? on the `dev` environment. + +SCREENSHOT + +{:start="6"} +1. To add a dependency between two environments, from the **Depends on** list in the target environment, select the environment and click **Update Dependency**. + The environment is added with a link is between it and the next environment to indicate a dependency. + + SCREENSHOT + +{:start="7"} +1. To select the Promotion Action for the target environment, do the following: + 1. Mouse over the left of the target environment and click ??. + 1. Select an inline action from the list, or to automatically select an action from the global promotion policies, click **Account-level promotion policies**. + + SCREENSHOT + +{:start="8"} +1. To add a Pre- or Post-Action Promotion for the target environment, mouse over the left of the target environment and click ??. + * To add an inline Workflow, select it and click **Add**. Continue from step ?? + * To add a new Workflow, click **Add New Workflow**. + * To apply an automated Promotion Policy, click Account-level Promotion Policy. + + SCREENSHOT + +{:start="8"} + +1. To commit changes, click **Save Promotion Flow**. + + + + - -### Step 8: (Optional) Evaluate global Promotion Policy settings by product +## Evaluate global Promotion Policy settings by product Select a product to evaluate the settings that will be applied from global Promotion Policies for all target environments without inline settings. Global Promotion Policy settings are applied from all Policies that match the product and the environment, according to priority. @@ -230,11 +278,7 @@ SCREENSHOT 1. If you get an error that the component is not defined for the Policy, click the corresponding icon and assign a Workflow or an Action. -### Step 9: Save changes and commit flow -As the final action in creating a Promotion Flow, save the settings and commit the changes. -TBD where are teh changes saved? -1. Click **Save Promotion Flow** to commit changes. diff --git a/_docs/promotions/create-promotion-sequence.md b/_docs/promotions/create-promotion-sequence.md index e18d14a26..8876e6d1b 100644 --- a/_docs/promotions/create-promotion-sequence.md +++ b/_docs/promotions/create-promotion-sequence.md @@ -6,7 +6,9 @@ toc: true --- -This guide lists the steps required to create a promotion sequence. Follow the steps in the order in which they are listed. Each step is followed by a brief description of its purpose and objective in the promotion sequence. For detailed information, click the step title. +This guide lists the steps required to create a promotion sequence. Each step is followed by a brief description of its purpose and objective in the promotion sequence. For detailed information, click the step title. + +Follow the steps in the order in which they are listed. ## Prerequisites @@ -28,28 +30,33 @@ This guide lists the steps required to create a promotion sequence. Follow the s For a promotion sequence, you need at least two environments: the trigger environment, which is the source of the changes to promote, and the target environment, to which the changes need to be promoted. 1. [Create applications]({{site.baseurl}}//docs/deployments/gitops/create-application/#create-an-argo-cd-application) - Applications represent the components or services to promote and deploy. They are the smallest unit of deployment within a promotion sequence. - Create an Argo CD application in Form or YAML mode. + Applications represent the components or services to be promoted and deployed, and are the smallest unit of deployment within a promotion sequence. To promote across an application across environments, you need an application for each target environment. + + Create Argo CD applications in our user interface. For seamless promotions, group related applications within a product to manage them collectively. 1. [Create products]({{site.baseurl}}/docs/products/create-product/) - Products connect related applications and group them as a single entity. - Being able to apply promotion settings at the level of the product, and being able to promote the product with all its applications, simplifies promotion management. + Products connect related applications and group them as a single entity. Applications represent instances of products within each environment. + Being able to apply promotion settings at the level of the product, and being able to promote applications belonging to the same product, simplifies promotion management. Create a product and connect related applications to it, either manually or declaratively. -1. [Create workflows]({{site.baseurl}}/docs/promotions/promotion-workflows/) - Before promoting changes across environments, it's customary to run tests and validations that match the requirements of the target environments in the promotion sequence. - Promotion Workflows allow you to create steps for testing different environments, and enforce checks before and after promoting changes. +1. [Create promotion workflows]({{site.baseurl}}/docs/promotions/promotion-workflows/) + As part of promoting changes across environments, it's customary to run tests and validations that match the requirements of the target environments in the promotion sequence. For example, implement smoke tests to verify basic functionality or database validation checks to ensure data integrity. - + Create Promotion Workflows to test different environments and enforce checks before and after promoting changes. 1. [Create policies for environment validation]({{site.baseurl}}/docs/promotions/promotion-policy/) Define the conditions to validate that the target environments are ready for promotion: workflows to run before and after changes are promoted, along with the action that promotes the changes. Enforcing these conditions ensure that promotions do not break or destabilize environments. Promotion Policies define the products or type of environments with the promotion action (mandatory), and any Promotion Workflows to run before and after the promotion action (optional). -1. [Create flows to orchestrate promotions]({{site.baseurl}}/docs/promotions/promotion-flow/) + +Optionally, define patterns to validate changes within the target environment by establishing conditions that enforce specific promotion workflows. This ensures that the target environments are prepared for promotion. Use Promotion Policies as advanced actions to combine Promotion Workflows with the promotion action, defining these patterns by products or types of environments. This includes the mandatory promotion action and any optional Promotion Workflows that should execute before and after the promotion action. For instance, a policy could dictate that a comprehensive set of regression tests must run in staging environments before deploying to production, thereby enhancing stability and reliability during the promotion process. + + + Define patterns to validate the changes within the target environment. Establish conditions that enforce specific promotion workflows, ensuring that the target environments are prepared for promotion. + Use Promotion Policies to define patterns by products or types of environments, including the mandatory promotion action and any optional Promotion Workflows that should execute before and after the promotion action. Enforcing these conditions helps maintain stability and reliability during the promotion process. + +1. [Create promotion flows to orchestrate promotions]({{site.baseurl}}/docs/promotions/promotion-flow/) Orchestrate the sequence of actions to move and deploy changes through the required environments, from the trigger environment to the final target environment. Promotion Flows ensure that changes are promoted in a controlled and predictable manner by integrating environments, products and applications, promotion workflows, and policies. @@ -62,11 +69,15 @@ This guide lists the steps required to create a promotion sequence. Follow the s The change made to an application in the trigger environment starts the process of moving these changes through the defined sequence of environments, either automatically or manually. -1. [Track deployments for products]({{site.baseurl}}/docs/promotions/releases/) +1. [Track releases for products]({{site.baseurl}}/docs/promotions/releases/) Monitor the deployment progress for the product as it moves through the promotion sequence. Use the Releases feature to track and ensure successful deployments across environments. + + ## Related articles [About promotions]({{site.baseurl}}/docs/promotions/promotions-overview/) [Promotion building blocks]({{site.baseurl}}/docs/promotions/promotion-components/) diff --git a/_docs/promotions/promotion-components.md b/_docs/promotions/promotion-components.md index dccd709f8..f81eec4d3 100644 --- a/_docs/promotions/promotion-components.md +++ b/_docs/promotions/promotion-components.md @@ -33,38 +33,38 @@ The table describes the core and promotion-specific entities.
  • Target environments: The environments where changes are promoted after the trigger environment.
- Users with ABAC permissions + Users Environments - Product (Optional) - A Product in Codefresh GitOps groups related applications into a single entity. This simplifies promotions by allowing you to promote the entire Product and all its applications across different environments, rather than managing applications individually. - Users with ABAC permissions + Product (Required) + A Product in Codefresh GitOps groups related applications into a single entity. This simplifies promotions by allowing you to promote applications within the product across different environments, rather than promotion each application manually. + Users Products Applications - Applications are the core units around which promotions revolve. Each application can be promoted individually or as part of a product. + Applications are the core units around which promotions revolve. Each Argo CD application can be promoted individually or as part of a product. Users with ABAC permissions Creating applications - Promotion Building Blocks
These entities define how promotions are orchestrated, what gets promoted, and under what conditions. + Promotion Building Blocks
These entities are specific to promotions and define promotions are orchestrated, what gets promoted, and under what conditions. Promotion Flows - Promotion flows orchestrate the movement of applications through environments, ensuring a controlled and automated promotion process. + Promotion flows orchestrate the movement of applications through environments, ensuring a controlled and automated promotion process for applications within the same product. Account administrators Creating Promotion Flows Promotion Settings - Promotion settings specify what gets promoted across environments. With products, these settings can be defined within the Product’s configuration or in a YAML CRD. + Promotion settings specify what gets promoted across environments. With products, these settings can be defined within the product’s configuration, either inline exclusive to the product, or a reusable promotion template. Users with ABAC permissions Promotion settings for products @@ -83,7 +83,7 @@ The table describes the core and promotion-specific entities. ## Promotion entities and GitOps Runtimes -All promotion entities are stored as manifests in the Shared Configuration Repository of the GitOps Runtime designated as the [Configuration Runtime]({{site.baseurl}}/docs/installation/gitops/monitor-manage-runtimes/#designating-configuration-runtimes). +Most of the core and promotion-specific entities are stored as Custom Resource Definitions (CRDs) in the Shared Configuration Repository of the GitOps Runtime designated as the [Configuration Runtime]({{site.baseurl}}/docs/installation/gitops/monitor-manage-runtimes/#designating-configuration-runtimes). If you have more than one Configuration Runtime, Codefresh automatically consolidates the settings into a single set of promotion manifests. {: .table .table-bordered .table-hover} diff --git a/_docs/promotions/promotions-overview.md b/_docs/promotions/promotions-overview.md index 5b44fd89b..487d05575 100644 --- a/_docs/promotions/promotions-overview.md +++ b/_docs/promotions/promotions-overview.md @@ -1,20 +1,22 @@ --- title: "Promotions" -description: "The power of promotions in Codefresh GitOps" +description: "Explore the power of GitOps promotions for continuous delivery" group: promotions toc: true --- +Continuous Delivery (CD) is an essential practice in the Software Development Lifecycle (SDLC) that automates the release process, ensuring that application updates are and can be consistently and reliably deployed across various environments. +CD bridges the gap between development and operations, empowering teams to deliver changes to production with speed and confidence by automating testing, validation, and deployment tasks. CD enables rapid response to customer needs and frequent, low-risk releases, ultimately resulting in a more responsive and efficient development process. -In the context of Continuous Delivery (CD), a promotion is the process of advancing an application version from one environment to another, from staging to production for example, based on predefined criteria or manual approval. Promotions ensure that only validated, reliable versions of your applications are deployed to production. +A key component of CD is promotion—the process of advancing an application version from one environment to the next,from staging to production for example, based on specific criteria or approvals. Promotion sequences help ensure that only validated, stable versions of applications make it to production, minimizing risk in every release. +Promotions in CD are typically structured with a combination of policies, workflows, and approval gates: -Promotions are typically implemented through rules and conditions, such as passing test suites or code quality checks, automated workflows to promote the application to the next environment, and manual approval gates before the promotion moves into deployment. -##### What is the unique value proposition of GitOps promotions in Codefresh? -Codefresh builds on the power of GitOps by fully integrating promotions into its framework, giving you enhanced visibility, control, and automation, all with Git as the single source of truth. +##### GitOps promotions, the Codefresh advantage +Codefresh builds on the power of GitOps by fully integrating promotions into its framework, giving you enhanced visibility, control, and automation, with Git as the single source of truth. -Here’s what makes our GitOps promotions stand out: +Here’s what makes Codefresh's GitOps promotions unique: * **Declarative and version-controlled** Promotions are tracked in Git as code. Every promotion is tied to a Git commit, giving you full traceability and version control. This means teams can always see who approved or triggered a promotion and why. @@ -23,23 +25,26 @@ Here’s what makes our GitOps promotions stand out: With GitOps, the desired state of environments is automatically synced based on the Git repository, ensuring that any promotion aligns with the latest approved application version. --> * **Context and visibility** - While Argo CD manages deployments as individual applications, Codefresh introduces **environments** and **products** for a more intuitive and cohesive view and managment of your development and deployment system. - * Environments represent different stages, clearly showing teams the applications as they progress through the software lifecycle. - * Products group related applications. Products allow you to promote all its applications at once, simplifying promotions and saving valuable time. - * Releases, unique to Codefresh, give visibility to the promotion and deployment process for products, making it easy for you or any stakeholder to track the success and progress of application deployments. + While Argo CD manages deployments as individual applications, Codefresh introduces **environments** and **products** for a more intuitive and cohesive view of complex systems, and CD management: + * Environments represent different stages in development. Environments allow teams to easily track applications as they progress through the SDLC. + Read more on Environments. + * Products group related applications. Products allow teams to manage promotions across applications within a specific product from one environment to another, for seamless coordination and control over applications. + Read more on Products. + * Releases provide end-to-end visibility into the promotion and deployment journey for each product. Releases allow all stakeholders to easily to track the deployment process across environments and verify successful deployment. + Read more on [Releases]({{site.baseurl}}/docs/promotions/product-releases/). -##### Promotion entities -Codefresh also offers several specialized entities that streamline and automate the promotion process, while giving you the fleiabily ou need to match organization requirements: -* **Promotion Templates**: Define which properties to promote. -* **Promotion Policies**: Define validation and readiness requirements for environments through workflows. -* **Promotion Flows**: Create simple or complex promotion sequences, reducing manual steps, improving accuracy and efficency. +##### GitOps promotion entities +Codefresh's GitOps promotions include specialized entities that streamline and automate the promotion process. These entities provide you with the flexibility and control to model your delivery lifecycles with all the required checks built-in, and no custom scripting required. You get a predictable path to production that you can duplicate across projects, giving you ultimate control over your workflows. +* **Promotion Templates**: Define which application properties to promote. +* **Promotion Policies**: Define validation and readiness requirements for environments. +* **Promotion Flows**: Define automated promotion sequences, simple or complex, reducing manual steps and accuracy and efficiency. -##### How do you get started with promotions in GitOps? +##### Getting started with promotions in GitOps -To get started, explore [promotion components]({{site.baseurl}}/docs/promotions/promotion-components/) to understand the entities involved. +To get started, explore [promotion components]({{site.baseurl}}/docs/promotions/promotion-components/) and understand the entities involved. -For a step-by-step guide on creating and implementing a promotion and monitoring its deployment, see [Create a promotion sequence]({{site.baseurl}}/docs/promotions/create-promotion-sequence/). +For a step-by-step guide on implementing continuous delivery, see [Continuous Delivery s]({{site.baseurl}}/docs/promotions/create-promotion-sequence/). From f948d40856895a28d514ea1860a8d47200637d7a Mon Sep 17 00:00:00 2001 From: NimRegev Date: Wed, 30 Oct 2024 17:30:02 +0200 Subject: [PATCH 15/61] Update content Updated content and added missing screenshots for releases --- .../configuration/promotion-flow.md | 70 +++++--- .../configuration/promotion-policy.md | 29 +-- _docs/promotions/product-releases.md | 19 +- _docs/promotions/promotions-overview.md | 2 +- _docs/promotions/trigger-promotions.md | 169 +++++++++++------- .../releases/release-notes.png | Bin 0 -> 154757 bytes .../releases/release-visualization.png | Bin 0 -> 105786 bytes .../releases/releases-list.png | Bin 0 -> 92498 bytes .../releases/result-retry-failed-release.png | Bin 0 -> 68017 bytes .../releases/retry-failed-release.png | Bin 0 -> 91749 bytes images/icons/product-release-app-error.png | Bin 0 -> 835 bytes images/icons/product-release-git-error.png | Bin 0 -> 897 bytes .../product-release-workflow-step-error.png | Bin 0 -> 1115 bytes images/icons/promotion-failed.png | Bin 0 -> 746 bytes images/icons/promotion-pending.png | Bin 0 -> 876 bytes images/icons/promotion-running.png | Bin 0 -> 764 bytes images/icons/promotion-success.png | Bin 0 -> 1466 bytes images/icons/promotion-suspended.png | Bin 0 -> 567 bytes .../icons/promotion-suspending-pending-pr.png | Bin 0 -> 878 bytes images/icons/promotion-terminated.png | Bin 0 -> 835 bytes 20 files changed, 177 insertions(+), 112 deletions(-) create mode 100644 images/gitops-promotions/releases/release-notes.png create mode 100644 images/gitops-promotions/releases/release-visualization.png create mode 100644 images/gitops-promotions/releases/releases-list.png create mode 100644 images/gitops-promotions/releases/result-retry-failed-release.png create mode 100644 images/gitops-promotions/releases/retry-failed-release.png create mode 100644 images/icons/product-release-app-error.png create mode 100644 images/icons/product-release-git-error.png create mode 100644 images/icons/product-release-workflow-step-error.png create mode 100644 images/icons/promotion-failed.png create mode 100644 images/icons/promotion-pending.png create mode 100644 images/icons/promotion-running.png create mode 100644 images/icons/promotion-success.png create mode 100644 images/icons/promotion-suspended.png create mode 100644 images/icons/promotion-suspending-pending-pr.png create mode 100644 images/icons/promotion-terminated.png diff --git a/_docs/promotions/configuration/promotion-flow.md b/_docs/promotions/configuration/promotion-flow.md index c75d4adc1..d47650513 100644 --- a/_docs/promotions/configuration/promotion-flow.md +++ b/_docs/promotions/configuration/promotion-flow.md @@ -1,6 +1,6 @@ --- title: "Creating Promotion Flows" -description: "Create Promotion Flows to orchestrate promotion for products across environments" +description: "Orchestrate promotion for products across environment with Create Promotion Flows" group: promotions toc: true --- @@ -13,27 +13,30 @@ Promotion Flows streamline the process of moving code changes through different By defining specific criteria for promotion, they help maintain the integrity of the software and reduce the likelihood of introducing bugs into production. -Before creating promotion flows, review [our notes on Promotion Flows](#notes-on-promotion-flows) which highlights key factors to be aware of in promotion flow behavior. +Before creating promotion flows, review [notes on Promotion Flows](#notes-on-promotion-flows) which highlights key factors to be aware of in promotion flow behavior. ## Flow Builder vs. YAML You can create Promotion Workflows through the Flow Builder, a graphical interface, or through a YAML Custom Resource Definition (CRD). You can switch seamlessly between both when creating Promotion Flows. + The Flow Builder visually guides you through creating any type of Promotion Flow. See [Create a Promotion Flow](#create-a-promotion-flow). ## Sequential vs. parallel promotions -Promotion Flows can be designed to run sequentially or in parallel to suit the unique requirements of any deployment process. +Promotion Flows can be modeled to run sequentially or in parallel to suit the unique requirements of any deployment process. * **Sequential promotions** Sequential flows are linear, where changes are promoted from the previous to the next environment in the order in which they are defined. This is the more common and traditional kind of Promotion Flow, where you start the flow from the development environment as the trigger environment, and then promote to the other target environments in succession. * **Parallel promotions** - In a parallel prompotion flow, changes are promoted across multiple environments simultaneously. This promotion logic groups environments and creates promotions _after_ multiple environments are healthy. + In a parallel flow, changes are promoted across multiple environments simultaneously. This promotion logic groups environments and creates promotions only _after_ multiple environments are healthy. + + ## Notes on Promotion Flows Here are a few additional factors to be aware of when creating Promotion Flows. @@ -41,23 +44,42 @@ Here are a few additional factors to be aware of when creating Promotion Flows. ### Trigger and target environments You can create and assign environments for the Promotion Flow, starting with the Trigger Environment, where the change to the application initiates the flow, and the other target environments required for promotion. You need at least one target environment for promotions. -The Trigger +##### Applications in Trigger Environment +It is recommended to have a single application for a product in the Trigger Environment. If the product has multiple applications with changes, changes are promoted only for a single application. The other applications are ignored. -* Adding environments - When adding an environment, you can select from the list of available environments, or create a new one that takes you to the Environments page for defining settings. At this point, the Promotion Flow remains unsaved, allowing to return to the flow later. +##### Trigger Environment validation +If required, add a Promotion Workflow, as a Post-Action trigger workflow to specifically validate the readiness of the trigger environment after the change and commit action. -* Removing environments - You can remove an environment from the Promotion Flow, and decide how to reconnect next environments if any, to previous environments. +##### Applications in target environments +* A promotion will fail if the product does not contain an application in each environment defined in the Promotion Flow. +* A target environment can contain multiple applications, for example, representing different tenants or regions. When promoting to this environment, each application will be updated with changes from the corresponding application in the source environment. - Reconnecting environments is only relevant when there are one or more environments in the flow _following_ the one being removed. If the environment you’re removing, for example `staging` is the final environment in the flow, you can remove it directly without needing to reconnect. +##### Adding environments +When adding an environment, you can select from the list of available environments, or create a new one that takes you to the Environments page for defining settings. At this point, the Promotion Flow remains unsaved. A notification alerts you that there are unsaved changes to the Promotion Flow. This notification remains as long as you have unsaved changes in the Promotion Flow. allowing to return to the flow later. -### Dependencies +##### Removing environments +You can remove an environment from the Promotion Flow, and decide how to reconnect next environments if any, to previous environments. -TBD +Reconnecting environments is only relevant when there are one or more environments in the flow _following_ the one being removed. If the environment you’re removing, for example `staging` is the final environment in the flow, you can remove it directly without needing to reconnect. + +### Dependencies in Promotion Flows + +A dependency in a Promotion Flow is a direct relationship between two or more environments, where one environment’s promotion depends on the successful promotion of changes in another environment. Changes cannot be promoted to the dependent environment until the preceding one is successfully promoted. + +By default, environment + + + +##### Regional promotion model +In a global setup, promoting changes to primary regions can be a prerequisite before those changes are promoted to additional regions. +Internal and External Dependencies: You might set up an internal environment (for employee access) that must be updated and stable before changes are promoted to customer-facing environments. + +##### Dependencies in parallel flows +Dependencies in promotion flows arIn parallel flow designs, promotions to multiple environments occur concurrently. Unlike dependent flows, parallel flows assume that each target environment can be updated independently of the others. This design is ideal when environments serve distinct purposes or when they can be updated independently without risk to other environments, such as promoting changes to multiple regional clusters that do not have cross-dependencies. ### Inline versus global Promotion Policy settings -For each environment, you can explicitly set the Promotion Policy, including the Promotion Action (required), and the optional Pre- and Post-Action Workflows. +For each environment, you can explicitly set the Promotion Policy that defines how to validate environment readiness through the Promotion Action (required), and the optional Pre- and Post-Action Workflows. ##### Inline Promotion Policy settings The Flow Builder displays available settings for the Promotion Policy. If you manually select these settings, this _inline_ selection overrides any global Promotion Policy settings that match the product/environment when the flow is triggered. @@ -65,20 +87,25 @@ The Flow Builder displays available settings for the Promotion Policy. If you ma ##### Global Promotion Policy settings If no inline settings are defined, the system applies global Promotion Policy settings based on predefined priorities. See TBD -## Previewing Promotion Policies by Product -Instead of waiting for the Promotion Flow to be triggered, you can evaluate Promotion Policy settings for any product. Policy evaluation by product is useful to identify that the environment and product have the desired policies, no matching Policies, or Policies missing required settings such as the Promotion Action. +##### Promotion Workflows +Both Pre- and Post-Action Workflows are optional in a Promotion Flow. + +### Previewing Promotion Policies by Product +Instead of waiting for the Promotion Flow to be triggered, you can evaluate Promotion Policy settings for any product. Policy evaluation by product is useful to verify that the environment and product have the desired policies, or identify that there are no matching Policies, or have Policies missing required settings such as the Promotion Action. + +Note that when you evaluate by product, only those settings without inline values are populated. +Previewing Policy settings does not impact the Promotion Flow when triggered. + -Note that when you evaluate by product, only those settings without inline values are populated. ## Create a Promotion Flow -Visually design and create the flow by selecting environments, Promotion Actions and Workflows, and defining dependencies through the Flow Builder. If needed create new environments and promotion workflows on-the-fly when doing so. +Visually design and create the flow by selecting environments, Promotion Actions, and Workflows, and defining dependencies through the Flow Builder. If needed, s create new environments and promotion workflows on-the-fly when doing so. -### Before you begin +##### Before you begin * Review [Create a promotion sequence]({{site.baseurl}}/docs/promotions/create-promotion-sequence/) -### Step 1: Add a Promotion Flow -Open the Flow Builder to add a Promotion Flow. +##### How to 1. In the Codefresh UI, on the toolbar, click the **Settings** icon, and then from the sidebar, select **Promotion Flows**. 1. Click **Add Promotion Flow**. @@ -307,8 +334,9 @@ SCREENSHOT SCREENSHOT -## Troubleshooting Promotion Flow creation + ## Related articles [Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/) diff --git a/_docs/promotions/configuration/promotion-policy.md b/_docs/promotions/configuration/promotion-policy.md index 700dfdeb8..d8f02d29f 100644 --- a/_docs/promotions/configuration/promotion-policy.md +++ b/_docs/promotions/configuration/promotion-policy.md @@ -1,6 +1,6 @@ --- title: "Configure Promotion Policies" -description: "Run validations through Promotion Policies to assess environment readiness before orchestrating promotion" +description: "Define global rules through Promotion Policies to assess environment readiness for promotions" group: promotions toc: true --- @@ -8,14 +8,13 @@ toc: true -When a promotion is triggered for a product in an environment, it's essential to validate the environment's readiness before deploying changes and promoting the Product. -Readiness validation ensures that the product's applications and their dependencies meet the necessary requirements and standards for deployment in the target environment. +When a promotion is triggered for a product in an environment, it's essential to validate the environment's readiness before and after promoting changes. These validations include various checks, such as code quality, unit or smoke tests, compatibility with dependencies, security compliance, and other relevant factors specific to the target environment. ##### Promotion Policies for readiness validation Codefresh empowers you to create and automate environment readiness validations through Promotion Policies. -A Promotion Policy combines promotion settings defining workflows to validate environment readiness, and targets defining the products or environments for which to implement the Policies. +A Promotion Policy combines promotion settings defining workflows to validate environment readiness before and stability after promotion, and targets defining the products or environments for which to implement the Policies. The Policies can be tailored for any combination of Products and Environments, or be generic to match all Products and Environments, giving you the flexibility you need to implement the most complex to the most simple of policies. @@ -91,22 +90,28 @@ max-width="60%" | Item | Description | | -------------- | -------------- | |**Name** | The name of the Promotion Policy.
The name must be unique in the cluster and must match Kubernetes naming conventions. | -|**Promotion Settings** | The settings that comprise the Promotion Policy.
{::nomarkdown}