Image Promotion Policy

Introduction

An ideal deployment workflow may consist of multiple stages (e.g., SIT, UAT, Prod environment).

If you have built such a workflow, 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 and Post-CD of the intermediate stages

• All approval nodes of the intermediate stages

Creating an Image Promotion Policy

You can create a policy using our APIs or through Devtron CLI. To get the latest version of the devtctl binary, please contact your enterprise POC or reach out to us directly for further assistance.

Here is the CLI approach:

Syntax:

devtctl create imagePromotionPolicy \
    --name="example-policy" \
    --description="This is a sample policy that promotes an image to production environment" \
    --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 (optional): A brief description of the policy, preferably explaining what it does.

• --passCondition (optional): Specify a condition using Common Expression Language (CEL). 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.

Applying an Image Promotion Policy

You can apply a policy using our APIs or through 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.

```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"
```

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:

  Copy

  devtctl apply policy -p="path/to/applyPolicy.yaml"

Result

Promoting Image to Target Environment

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.

   
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.

   
4. Use the SELECT button on the image, and click Promote to...

5. Select one or more target environments using the checkbox.

   
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.

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

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.

   

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.

If there are pending promotion requests, you can approve them as shown below:

Deploying a Promoted Image

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.

However, a promoted image does not automatically qualify as a deployable image. It must fulfill all configured requirements (Image Deployment Approval, Filter Conditions, 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.

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.