doc: Image promotion policy

docs/SUMMARY.md

@@ -44,7 +44,8 @@
   * [Scoped Variables](user-guide/global-configurations/scoped-variables.md)
   * [Pull Image Digest](user-guide/global-configurations/pull-image-digest.md)
   * [Tags Policy](user-guide/global-configurations/tags-policy.md)
-  * [Lock Deployment Config](user-guide/global-configurations/lock-deployment-config.md)
+  * [Lock Deployment Configuration](user-guide/global-configurations/lock-deployment-config.md)
+  * [Image Promotion Policy](user-guide/global-configurations/image-promotion-policy.md)  
   * [Filter Condition](user-guide/global-configurations/filter-condition.md)
   * [Build Infra](user-guide/global-configurations/build-infra.md)
 * [Devtron Upgrade](setup/upgrade/README.md)

docs/user-guide/global-configurations/README.md

@@ -36,6 +36,8 @@ Before you start creating an application, we recommend to provide basic informat
 
 [Filter Condition](filter-condition.md)
 
+[Image Promotion](image-promotion-policy.md)
+
 [Lock Deployment Configuration](lock-deployment-config.md)
 
 [Build Infra](build-infra.md)

docs/user-guide/global-configurations/filter-condition.md

@@ -2,7 +2,7 @@
 
 ## Introduction [![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/elements/EnterpriseTag.svg)](https://devtron.ai/pricing)
 
-The [workflows](../creating-application/workflow/) you create in Devtron for managing the CI-CD of your application can be made flexible, for e.g., not all events (such as image builds) generated during the CI stage require progression to the CD stage. Therefore, instead of creating multiple pipelines that cater to complex requirements, Devtron provides you the option of creating filters to make your workflow efficient. 
+The [workflows](../creating-application/workflow/) you create in Devtron for managing the CI-CD of your application can be made flexible or restricting with the help of CD filter conditions, for e.g., not all events (such as image builds) generated during the CI stage require progression to the CD stage. Therefore, instead of creating multiple workflows that cater to complex requirements, Devtron provides you the option of defining filters to tailor your workflow according to your specific needs. 
 
 Using filter conditions, you can control the progression of events. Here are a few general examples:
 * Images containing the label "test" should not be eligible for deployment in production environment
@@ -31,8 +31,8 @@ Using filter conditions, you can control the progression of events. Here are a f
     * **Filter Name**: Give a name to the filter.
     * **Description**: (Optional) Add a description to the filter, preferably explaining what it does.
     * **Filter Condition**: You can specify either a pass condition, fail condition, or both the conditions:
-        * **Pass Condition**: Only those events that satisfy the condition will be directed through your pipeline.
-        * **Fail Condition**: Events that fail the condition will not be directed through your pipeline..
+        * **Pass Condition**: Events that satisfy the pass condition are eligible to trigger your CD pipeline.
+        * **Fail Condition**: Events that satisfy the fail condition are not eligible to trigger your CD pipeline.
     * **Use CEL Expression**: You can use `Common Expression Language` (CEL) to define the conditions. Currently, you can create conditions with the help of following variables:
         * **containerImage**: Package that contains all the necessary files and instructions to run an application in a container, e.g., gcr.io/k8s-minikube/kicbase:v0.0.39. It returns a string value in the following format: `<registry>/<repository>:<tag>`
         * **containerRepository**: Storage location for container images, e.g., kicbase

docs/user-guide/global-configurations/image-promotion-policy.md

@@ -0,0 +1,260 @@
+# Image Promotion Policy
+
+## Introduction [![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/elements/EnterpriseTag.svg)](https://devtron.ai/pricing)
+
+An ideal deployment workflow may consist of multiple stages (e.g., SIT, UAT, Prod environment).
+
+![Figure 1: Workflow on Devtron](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/sample-cd-workflow.jpg)
+
+If you have built such a [workflow](../creating-application/workflow/README.md), your CI image will sequentially traverse and deploy to each environment until it reaches the target environment. However, if there's a critical issue you wish to address urgently (through a hotfix) on production, navigating the standard workflow might feel slow and cumbersome.
+
+Therefore, Devtron offers a feature called 'Image Promotion Policy' that allows you to directly promote an image to the target environment, bypassing the intermediate stages in your workflow including:
+
+* [Pre-CD](../creating-application/workflow/cd-pipeline.md#pre-deployment-stage) and [Post-CD](../creating-application/workflow/cd-pipeline.md#post-deployment-stage) of the intermediate stages
+* All [approval nodes](../creating-application/workflow/cd-pipeline.md#manual-approval-for-deployment) of the intermediate stages
+
+![Figure 2: Promoting an Image](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/image-promotion-visual.jpg)
+
+
+---
+
+## Creating an Image Promotion Policy
+
+{% hint style="warning" %}
+### Who Can Perform This Action?
+Users need to have super-admin permission to create an image promotion policy.
+{% endhint %}
+
+You can create a policy using our APIs or through [Devtron CLI](https://github.com/devtron-labs/devtron-cli). Here is the CLI approach:
+
+**Syntax**:
+```
+devtron-cli create imagePromotionPolicy \
+    --name="policyName" \
+    --description="desc" \
+    --passCondition="true" \
+    --failCondition="false" \
+    --approverCount=0 \
+    --allowRequestFromApprove=false \
+    --allowImageBuilderFromApprove=false \
+    --allowApproverFromDeploy=false \
+    --applyPath="path/to/applyPolicy.yaml"
+```
+
+**Arguments**:
+
+* `--name` (required): The name of the image promotion policy.
+* `--description` (required): A brief description of the policy, preferably explaining what it does.
+* `--passCondition` (optional): Specify a condition using [Common Expression Language (CEL)](https://github.com/google/cel-spec/blob/master/doc/langdef.md). Images that match this condition will be eligible for promotion to the target environment.
+* `--failCondition` (optional): Images that match this condition will NOT be eligible for promotion to the target environment.
+* `--approverCount` (optional): The number of approvals required to promote an image (0-6). Defaults to 0 (no approvals).
+* `--allowRequestFromApprove` (optional): (Boolean) If true, user who raised the image promotion request can approve it. Defaults to false.
+* `--allowImageBuilderFromApprove` (optional): (Boolean) If true, user who triggered the build can approve the image promotion request. Defaults to false.
+* `--allowApproverFromDeploy` (optional): (Boolean) If true, user who approved the image promotion request can deploy that image. Defaults to false.
+* `--applyPath` (optional): Specify the path to the YAML file that contains the list of applications and environments to which the policy should be applicable.
+
+{% hint style="info" %}
+If an image matches both pass and fail conditions, the priority of the fail condition will be higher. Therefore, such image will NOT be eligible for promotion to the target environment.
+{% endhint %}  
+
+{% hint style="info" %}
+If you don't define both pass and fail conditions, all images will be eligible for promotion.
+{% endhint %}  
+
+---
+
+
+<!-- {% hint style="warning" %}
+### Who Can Perform This Action?
+Users need to have super-admin permission to create an image promotion policy.
+{% endhint %}
+
+1. Go to **Global Configurations** → **Image Promotion Policy**.
+
+2. Click **Create Policy** on the top-right.
+
+3. Give a name to the policy and write a brief description, preferably explaining what it does.
+
+4. Under **Image Filter Condition**, you can enter the conditions which your image promotion should be subjected to (e.g., *`branchName.startsWith('hotfix')`*) 
+
+{% hint style="info" %}
+Use **View filter criteria** to check the supported variables.
+{% endhint %}  
+
+5. You can specify either a pass condition, fail condition, or both conditions using [Common Expression Language (CEL)](https://github.com/google/cel-spec/blob/master/doc/langdef.md):
+    * **Pass Condition**: Images that match this condition will be eligible for promotion to the target environment.
+    * **Fail Condition**: Images that match this condition will NOT be eligible for promotion to the target environment.
+
+{% hint style="info" %}
+If an image matches both pass and fail conditions, the priority of the fail condition will be higher. Therefore, such image will NOT be eligible for promotion to the target environment.
+{% endhint %}  
+
+{% hint style="info" %}
+If you don't define both pass and fail conditions, all images will be eligible for promotion.
+{% endhint %}  
+
+6. (Optional) If required, you can setup approval requirements for this policy. If **Approval for Image Promotion Policy** is enabled, an [approval will be required for an image]((#approving-image-promotion-request)) to be directly promoted to the target environment. Only the users having 'Artifact promoter' role (for the application and environment) will be able to approve the image promotion request.
+
+ * **Number of Approvals (1-6)**: Specify the number of approvals required to promote an image. This can vary from one approval (minimum) to six approvals (maximum).
+
+ * **Checkboxes for who can approve**: As a super-admin, you also have options to control the approval of image promotion and its deployment. These are available in the form of checkboxes.
+
+    ![Figure 3: Controlling Approvals](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/control-approval.jpg)
+
+6. Click **Save Changes**.
+
+--- 
+
+## Applying an Image Promotion Policy
+
+{% hint style="warning" %}
+### Who Can Perform This Action?
+Users need to have super-admin permission to apply an image promotion policy.
+{% endhint %}
+
+Here, you can decide the application(s) and environment(s) for which image promotion is allowed. 
+
+1. Go to the **Apply Policy** tab.
+
+2. Click the `Promotion Policy` dropdown next to the application, and choose the policy you wish to apply.
+
+3. A confirmation dialog box would appear. Click **Confirm**.
+
+### Performing Bulk Action
+
+1. You can also apply a policy to multiple applications and environments ('App+Env' combinations) in bulk.
+
+2. Simply use the checkboxes to select the desired application + environment combinations.
+
+3. You will see a draggable floating widget. Click **Change Policy** in the widget and select a desired policy to be applied to all your selections.
+
+Moreover, there are three filters available to make the selections easier for you:
+* Application
+* Environment
+* Policy
+
+--- -->
+
+## Applying an Image Promotion Policy
+
+{% hint style="warning" %}
+### Who Can Perform This Action?
+Users need to have super-admin permission to apply an image promotion policy.
+{% endhint %}
+
+You can apply a policy using our APIs or through [Devtron CLI](https://github.com/devtron-labs/devtron-cli). Here is the CLI approach:
+
+* Create a YAML file and give it a name (say `applyPolicy.yaml`). Within the file, define the applications and environments to which the image promotion policy should apply, as shown below.
+
+    {% code title="applyPolicy.yaml" overflow="wrap" lineNumbers="true" %}
+    ```yaml
+    apiVersion: v1
+    kind: artifactPromotionPolicy
+    spec:
+    payload:
+        applicationEnvironments:
+        - appName: "app1"
+            envName: "env-demo"
+        - appName: "app1"
+            envName: "env-staging"
+        - appName: "app2"
+            envName: "env-demo"
+        applyToPolicyName: "example-policy"
+    ```
+    {% endcode %}
+
+    Here, `applicationEnvironments` is a dictionary that contains the application names (app1, app2) and the corresponding environment names (env-demo/env-staging) where the policy will apply. In the `applyToPolicyName` key, enter the value of the `name` argument you used earlier while [creating the policy](#creating-an-image-promotion-policy).
+
+* Apply the policy using the following CLI command:
+
+    ```
+    devtron-cli apply policy -p="path/to/applyPolicy.yaml"
+    ```
+
+
+## Result
+
+### Promoting Image to Target Environment
+
+{% hint style="warning" %}
+### Who Can Perform This Action?
+Users with build & deploy permission or above (for the application and target environment) can promote an image if the image promotion policy is enabled.
+{% endhint %}
+
+Here, you can promote images to the target environment(s).  
+
+1. Go to the **Build & Deploy** tab of your application.
+
+2. Click the **Promote** button next to the workflow in which the you wish to promote the image. Please note, the button will appear only if image promotion is allowed for any environment used in that workflow.
+
+    ![Figure 3: Promote Button](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/promote-button.jpg)
+
+3. In the `Select Image` tab, you will see a list of images. Use the **Show Images from** dropdown to filter the list and choose the image you wish to promote. This can be either be an image from the CI pipeline or one that has successfully passed all stages (e.g., pre, post, if any) of that particular environment.
+
+    ![Figure 4: Selecting an Image](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/show-images.jpg)
+
+4. Use the **SELECT** button on the image, and click **Promote to...**
+
+5. Select one or more target environments using the checkbox.
+
+    ![Figure 5: Selecting the Destination Environment](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/selecting-env.jpg)
+
+6. Click **Promote Image**. 
+
+The image's promotion to the target environment now depends on the approval settings in the image promotion policy. If the super-admin has enforced an approval process, the image requires the necessary number of approvals before promotion. On the other hand, if the super-admin has not enforced approval, the image will be automatically promoted since there is no request phase involved.
+
+{% hint style="warning" %}
+In case you have configured [SES or SMTP on Devtron](../global-configurations/manage-notification.md#notification-configurations), an email notification will be sent to the approvers.
+{% endhint %}
+
+7. If approval(s) are required for image promotion, you may check the status of your request in the `Approval Pending` tab.
+
+### Approving Image Promotion Request
+
+{% hint style="warning" %}
+### Who Can Perform This Action?
+Only the users having [Artifact promoter](./user-access.md#role-based-access-levels) role (for the application and environment) or superadmin permissions will be able to approve the image promotion request.
+{% endhint %} 
+
+1. Go to the **Build & Deploy** tab of your application.
+
+2. Click the **Promote** button next to the workflow.
+
+3. Go to the `Approval Pending` tab to see the list of images requiring approval. By default, it shows a list of all images whose promotion request is pending with you. 
+
+    ![Figure 6: Checking Pending Approvals](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/pending-approvals.jpg)
+
+{% hint style="info" %}
+All the images will show the source from which it is being promoted, i.e., CI stage or intermediate stage (environment).
+{% endhint %}
+
+4. Click **Approve for...** to choose the target environments to which it can be promoted.
+
+5. Click **Approve**.
+
+You can also use the **Show requests** dropdown to filter the image promotion requests for a specific target environment.
+
+![Figure 7: Show Env-specific Promotion Requests](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/show-requests.jpg)
+
+If there are pending promotion requests, you can approve them as shown below:
+
+![Figure 8: Approving Image Promotion Requests](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/image-promo-approval.gif)
+
+### Deploying a Promoted Image
+
+{% hint style="warning" %}
+### Who Can Perform This Action?
+Users with build & deploy permission or above for the application and environment can deploy the promoted image.
+{% endhint %}
+
+If a user has approved the promotion request for an image, they may or may not be able to deploy depending upon the [policy configuration](#creating-an-image-promotion-policy).
+
+However, a promoted image does not automatically qualify as a deployable image. It must fulfill all configured requirements ([Image Deployment Approval](../creating-application/workflow/cd-pipeline.md#manual-approval-for-deployment), [Filter Conditions](./filter-condition.md), etc.) of the target environment for it to be deployed.
+
+In the **Build & Deploy** tab of your application, click **Select Image** for the CD pipeline, and choose your promoted image for deployment.
+
+![Figure 9: Deploying Promoted Image](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/deploying-promoted-image.jpg)
+
+You can check the deployment of promoted images in the **Deployment History** of your application. It will also indicate the pipeline from which the image was promoted and deployed to the target environment.
+
+![Figure 10: Deployment History - Checking Image Source](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/promoted-image-deploy-log.jpg)

docs/user-guide/global-configurations/user-access.md

@@ -18,7 +18,10 @@ Devtron supports 5 levels of access:
 3. **Admin**: Users with `admin` privileges can create, edit, delete, and view permitted applications in permitted projects.
 4. **Manager**: Users with `manager` privileges can do everything that an `admin` user can do. Additionally, they can also give and revoke access of users for the applications and environments of which they are the manager.
 5. **Super Admin**: Users with `super admin` privileges have unrestricted access to all the Devtron resources. Super Admins can create, modify, delete and view any Devtron resource without any restriction; it's like Superman without the weakness of Kryptonite. Moreover, they can add and delete user access across any Devtron resource, add delete git repository credentials, container registry credentials, cluster, and environment.
-6. **Approver**: Users with `approver` privileges have the authority to approve requests for image deployment. However, the user who built the image and/or requested approval cannot self-approve, even if they have approver or super-admin privileges.
+6. **Image approver**: Users with `Image approver` privileges have the authority to approve requests for image deployment.
+7. **Configuration approver**: Users with `Configuration approver` privileges have the authority to approve changes to protected configurations of Deployment Template, ConfigMaps, and Secrets. However, the user who proposed the changes cannot self-approve, even if they have configuration approver or super-admin privileges.
+8. **Artifact promoter**: Users with this privilege have the authority to approve promotion of [artifacts](../../reference/glossary.md#artifacts) directly to the target CD pipeline.
+
 
 ## User Roles And Permissions