Skip to content

Commit 279b671

Browse files
ashokdevtronabhibhaw
ashokdevtron
and
abhibhaw
authored
doc: Image promotion policy (#4762)
* Created Doc Structure * Promotion Policy Doc with RBAC * Fixes * CO Feedback Incorporated * Snapshots Added + PM/CO Feedback Incorporated * Figure Corrections * Added Promotion Approval Snap + Artifact Approver role * Final Fixes * Reworked PM Feedback * Added CLI steps + Fixes + PM Feedback * doc: updates CD filter def * Fixes and Corrections --------- Co-authored-by: Abhibhaw Asthana <[email protected]>
1 parent c690247 commit 279b671

File tree

5 files changed

+273
-5
lines changed

5 files changed

+273
-5
lines changed

‎docs/SUMMARY.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,8 @@
4444
* [Scoped Variables](user-guide/global-configurations/scoped-variables.md)
4545
* [Pull Image Digest](user-guide/global-configurations/pull-image-digest.md)
4646
* [Tags Policy](user-guide/global-configurations/tags-policy.md)
47-
* [Lock Deployment Config](user-guide/global-configurations/lock-deployment-config.md)
47+
* [Lock Deployment Configuration](user-guide/global-configurations/lock-deployment-config.md)
48+
* [Image Promotion Policy](user-guide/global-configurations/image-promotion-policy.md)
4849
* [Filter Condition](user-guide/global-configurations/filter-condition.md)
4950
* [Build Infra](user-guide/global-configurations/build-infra.md)
5051
* [Devtron Upgrade](setup/upgrade/README.md)

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ Before you start creating an application, we recommend to provide basic informat
3636

3737
[Filter Condition](filter-condition.md)
3838

39+
[Image Promotion](image-promotion-policy.md)
40+
3941
[Lock Deployment Configuration](lock-deployment-config.md)
4042

4143
[Build Infra](build-infra.md)

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
## Introduction [![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/elements/EnterpriseTag.svg)](https://devtron.ai/pricing)
44

5-
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.
5+
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.
66

77
Using filter conditions, you can control the progression of events. Here are a few general examples:
88
* 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
3131
* **Filter Name**: Give a name to the filter.
3232
* **Description**: (Optional) Add a description to the filter, preferably explaining what it does.
3333
* **Filter Condition**: You can specify either a pass condition, fail condition, or both the conditions:
34-
* **Pass Condition**: Only those events that satisfy the condition will be directed through your pipeline.
35-
* **Fail Condition**: Events that fail the condition will not be directed through your pipeline..
34+
* **Pass Condition**: Events that satisfy the pass condition are eligible to trigger your CD pipeline.
35+
* **Fail Condition**: Events that satisfy the fail condition are not eligible to trigger your CD pipeline.
3636
* **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:
3737
* **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>`
3838
* **containerRepository**: Storage location for container images, e.g., kicbase

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

Lines changed: 262 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
# Image Promotion Policy
2+
3+
## Introduction [![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/elements/EnterpriseTag.svg)](https://devtron.ai/pricing)
4+
5+
An ideal deployment workflow may consist of multiple stages (e.g., SIT, UAT, Prod environment).
6+
7+
![Figure 1: Workflow on Devtron](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/sample-cd-workflow.jpg)
8+
9+
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.
10+
11+
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:
12+
13+
* [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
14+
* All [approval nodes](../creating-application/workflow/cd-pipeline.md#manual-approval-for-deployment) of the intermediate stages
15+
16+
![Figure 2: Promoting an Image](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/image-promotion-visual.jpg)
17+
18+
19+
---
20+
21+
## Creating an Image Promotion Policy
22+
23+
{% hint style="warning" %}
24+
### Who Can Perform This Action?
25+
Users need to have super-admin permission to create an image promotion policy.
26+
{% endhint %}
27+
28+
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.
29+
30+
Here is the CLI approach:
31+
32+
**Syntax**:
33+
```
34+
devtctl create imagePromotionPolicy \
35+
--name="example-policy" \
36+
--description="This is a sample policy that promotes an image to production environment" \
37+
--passCondition="true" \
38+
--failCondition="false" \
39+
--approverCount=0 \
40+
--allowRequestFromApprove=false \
41+
--allowImageBuilderFromApprove=false \
42+
--allowApproverFromDeploy=false \
43+
--applyPath="path/to/applyPolicy.yaml"
44+
```
45+
46+
**Arguments**:
47+
48+
* `--name` (required): The name of the image promotion policy.
49+
* `--description` (optional): A brief description of the policy, preferably explaining what it does.
50+
* `--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.
51+
* `--failCondition` (optional): Images that match this condition will NOT be eligible for promotion to the target environment.
52+
* `--approverCount` (optional): The number of approvals required to promote an image (0-6). Defaults to 0 (no approvals).
53+
* `--allowRequestFromApprove` (optional): (Boolean) If true, user who raised the image promotion request can approve it. Defaults to false.
54+
* `--allowImageBuilderFromApprove` (optional): (Boolean) If true, user who triggered the build can approve the image promotion request. Defaults to false.
55+
* `--allowApproverFromDeploy` (optional): (Boolean) If true, user who approved the image promotion request can deploy that image. Defaults to false.
56+
* `--applyPath` (optional): Specify the path to the YAML file that contains the list of applications and environments to which the policy should be applicable.
57+
58+
{% hint style="info" %}
59+
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.
60+
{% endhint %}
61+
62+
{% hint style="info" %}
63+
If you don't define both pass and fail conditions, all images will be eligible for promotion.
64+
{% endhint %}
65+
66+
---
67+
68+
69+
<!-- {% hint style="warning" %}
70+
### Who Can Perform This Action?
71+
Users need to have super-admin permission to create an image promotion policy.
72+
{% endhint %}
73+
74+
1. Go to **Global Configurations** → **Image Promotion Policy**.
75+
76+
2. Click **Create Policy** on the top-right.
77+
78+
3. Give a name to the policy and write a brief description, preferably explaining what it does.
79+
80+
4. Under **Image Filter Condition**, you can enter the conditions which your image promotion should be subjected to (e.g., *`branchName.startsWith('hotfix')`*)
81+
82+
{% hint style="info" %}
83+
Use **View filter criteria** to check the supported variables.
84+
{% endhint %}
85+
86+
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):
87+
* **Pass Condition**: Images that match this condition will be eligible for promotion to the target environment.
88+
* **Fail Condition**: Images that match this condition will NOT be eligible for promotion to the target environment.
89+
90+
{% hint style="info" %}
91+
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.
92+
{% endhint %}
93+
94+
{% hint style="info" %}
95+
If you don't define both pass and fail conditions, all images will be eligible for promotion.
96+
{% endhint %}
97+
98+
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.
99+
100+
* **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).
101+
102+
* **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.
103+
104+
![Figure 3: Controlling Approvals](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/control-approval.jpg)
105+
106+
6. Click **Save Changes**.
107+
108+
---
109+
110+
## Applying an Image Promotion Policy
111+
112+
{% hint style="warning" %}
113+
### Who Can Perform This Action?
114+
Users need to have super-admin permission to apply an image promotion policy.
115+
{% endhint %}
116+
117+
Here, you can decide the application(s) and environment(s) for which image promotion is allowed.
118+
119+
1. Go to the **Apply Policy** tab.
120+
121+
2. Click the `Promotion Policy` dropdown next to the application, and choose the policy you wish to apply.
122+
123+
3. A confirmation dialog box would appear. Click **Confirm**.
124+
125+
### Performing Bulk Action
126+
127+
1. You can also apply a policy to multiple applications and environments ('App+Env' combinations) in bulk.
128+
129+
2. Simply use the checkboxes to select the desired application + environment combinations.
130+
131+
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.
132+
133+
Moreover, there are three filters available to make the selections easier for you:
134+
* Application
135+
* Environment
136+
* Policy
137+
138+
--- -->
139+
140+
## Applying an Image Promotion Policy
141+
142+
{% hint style="warning" %}
143+
### Who Can Perform This Action?
144+
Users need to have super-admin permission to apply an image promotion policy.
145+
{% endhint %}
146+
147+
You can apply a policy using our APIs or through [Devtron CLI](https://github.com/devtron-labs/devtron-cli). Here is the CLI approach:
148+
149+
* 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.
150+
151+
{% code title="applyPolicy.yaml" overflow="wrap" lineNumbers="true" %}
152+
```yaml
153+
apiVersion: v1
154+
kind: artifactPromotionPolicy
155+
spec:
156+
payload:
157+
applicationEnvironments:
158+
- appName: "app1"
159+
envName: "env-demo"
160+
- appName: "app1"
161+
envName: "env-staging"
162+
- appName: "app2"
163+
envName: "env-demo"
164+
applyToPolicyName: "example-policy"
165+
```
166+
{% endcode %}
167+
168+
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).
169+
170+
* Apply the policy using the following CLI command:
171+
172+
```
173+
devtctl apply policy -p="path/to/applyPolicy.yaml"
174+
```
175+
176+
177+
## Result
178+
179+
### Promoting Image to Target Environment
180+
181+
{% hint style="warning" %}
182+
### Who Can Perform This Action?
183+
Users with build & deploy permission or above (for the application and target environment) can promote an image if the image promotion policy is enabled.
184+
{% endhint %}
185+
186+
Here, you can promote images to the target environment(s).
187+
188+
1. Go to the **Build & Deploy** tab of your application.
189+
190+
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.
191+
192+
![Figure 3: Promote Button](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/promote-button.jpg)
193+
194+
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.
195+
196+
![Figure 4: Selecting an Image](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/show-images.jpg)
197+
198+
4. Use the **SELECT** button on the image, and click **Promote to...**
199+
200+
5. Select one or more target environments using the checkbox.
201+
202+
![Figure 5: Selecting the Destination Environment](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/selecting-env.jpg)
203+
204+
6. Click **Promote Image**.
205+
206+
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.
207+
208+
{% hint style="warning" %}
209+
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.
210+
{% endhint %}
211+
212+
7. If approval(s) are required for image promotion, you may check the status of your request in the `Approval Pending` tab.
213+
214+
### Approving Image Promotion Request
215+
216+
{% hint style="warning" %}
217+
### Who Can Perform This Action?
218+
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.
219+
{% endhint %}
220+
221+
1. Go to the **Build & Deploy** tab of your application.
222+
223+
2. Click the **Promote** button next to the workflow.
224+
225+
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.
226+
227+
![Figure 6: Checking Pending Approvals](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/pending-approvals.jpg)
228+
229+
{% hint style="info" %}
230+
All the images will show the source from which it is being promoted, i.e., CI stage or intermediate stage (environment).
231+
{% endhint %}
232+
233+
4. Click **Approve for...** to choose the target environments to which it can be promoted.
234+
235+
5. Click **Approve**.
236+
237+
You can also use the **Show requests** dropdown to filter the image promotion requests for a specific target environment.
238+
239+
![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)
240+
241+
If there are pending promotion requests, you can approve them as shown below:
242+
243+
![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)
244+
245+
### Deploying a Promoted Image
246+
247+
{% hint style="warning" %}
248+
### Who Can Perform This Action?
249+
Users with build & deploy permission or above for the application and environment can deploy the promoted image.
250+
{% endhint %}
251+
252+
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).
253+
254+
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.
255+
256+
In the **Build & Deploy** tab of your application, click **Select Image** for the CD pipeline, and choose your promoted image for deployment.
257+
258+
![Figure 9: Deploying Promoted Image](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/image-promotion/deploying-promoted-image.jpg)
259+
260+
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.
261+
262+
![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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,10 @@ Devtron supports 5 levels of access:
1818
3. **Admin**: Users with `admin` privileges can create, edit, delete, and view permitted applications in permitted projects.
1919
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.
2020
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.
21-
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.
21+
6. **Image approver**: Users with `Image approver` privileges have the authority to approve requests for image deployment.
22+
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.
23+
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.
24+
2225

2326
## User Roles And Permissions
2427

0 commit comments

Comments
 (0)