Skip to content

Commit b3f067e

Browse files
mattsantamattsanta
authored
Introduce a cloud-deploy-pipelines skill (#85)
* Introduce a cloud-deploy-pipeline-designer skill that guides users through the process of designing a Cloud Deploy delivery pipeline * Address typos and lint issues * One more missing new line * Update skill to be Cloud Deploy generic and add release management sections * Update SKILL.md based on PR feedback * Add use-case to each subsection in Release Management
1 parent f79fae6 commit b3f067e

7 files changed

Lines changed: 603 additions & 0 deletions

File tree

‎skills/cloud-deploy-pipelines/SKILL.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
name: cloud-deploy-pipelines
3+
description: >
4+
Design Cloud Deploy delivery pipelines and manage releases when deploying applications to Cloud Run and Google Kubernetes Engine (GKE). Use when users want to deploy their applications to multiple environments (e.g. dev and prod), leverage deployment strategies (i.e. canary), or rollback (manually or automatically) when there are issues deploying their application.
5+
---
6+
7+
# Cloud Deploy Pipelines
8+
9+
## Overview
10+
11+
This skill encompasses the entire lifecycle of Cloud Deploy for a user, from designing and creating delivery pipelines to managing releases and debugging release failures.
12+
13+
## Workflow: Designing a Pipeline
14+
15+
This workflow provides steps for designing a Cloud Deploy `DeliveryPipeline`.
16+
17+
### Constraints & Rules
18+
19+
1. **NO PLACEHOLDERS**: Never generate YAML with placeholders like `<PROJECT_ID>`. Ask the user for values first.
20+
2. **Context First**: Always check existing files and conversation context before asking.
21+
3. **Step-by-Step**: Perform the steps one at a time. The goal is to guide the user through designing a delivery pipeline.
22+
23+
### Step 0: Prerequisites
24+
25+
**Required Context**: Before generating ANY configuration for this workflow, you **MUST** have the following values. Ask the user strictly for any missing information:
26+
- **Project ID**: The Google Cloud project ID for the Cloud Deploy resources.
27+
- **Region**: The region for the Cloud Deploy resources (e.g., `us-central1`).
28+
- **Application Name**: The name of the application that will be deployed. Use the application name to generate the names of the Cloud Deploy resources, such as `DeliveryPipeline` and `Target` resources.
29+
- **Runtime**: Either Cloud Run or Google Kubernetes Engine (GKE).
30+
- **If Cloud Run**: The Cloud Run project and location.
31+
- **If GKE**: The GKE cluster name.
32+
33+
### Step 1: Define the target environments
34+
35+
1. Identify the number of deployment environments (e.g., dev, staging, production).
36+
2. Identify if promotions should require user approval.
37+
3. Define each of the deployment environments as Cloud Deploy `Target` resources in a `clouddeploy.yaml` file.
38+
- Use `references/configure-targets.md` as a reference when generating the resource YAML.
39+
- Use the application name provided by the user when naming the Cloud Deploy `Target` resources. For example, if the user wants to deploy an application named "hello-world" to a test and production environment then use "hello-world-test" and "hello-world-prod" as the `Target` IDs.
40+
41+
### Step 2: Define the delivery pipeline
42+
43+
1. Identify whether the user wants to use a canary deployment strategy for any of the target environments.
44+
2. Define the Cloud Deploy `DeliveryPipeline` in the `clouddeploy.yaml` file.
45+
- Use `references/configure-pipelines.md` as a reference when generating the resource YAML.
46+
- Use application name as the `DeliveryPipeline` ID.
47+
48+
### Step 3: Define automations
49+
50+
1. Identify whether the user wants to automatically rollback if any failures occur during the rollout.
51+
2. **If the user specified multiple deployment environments in the previous step**
52+
- Identify if they want automatic promotions between deployment environments.
53+
3. **If the user specified a canary deployment strategy in the previous step**
54+
- Identify if they want to automatically advance the rollout through the phases after a wait period.
55+
4. Define the Cloud Deploy `Automation` resources in the `clouddeploy.yaml` file.
56+
- Use `references/configure-automations.md` as a reference when generating the resource YAML.
57+
58+
### Step 4: Validate the clouddeploy.yaml file
59+
60+
Ensure that the `clouddeploy.yaml` file is valid. See https://docs.cloud.google.com/deploy/docs/config-files for the schema.
61+
62+
### Step 5: Create the delivery pipeline
63+
64+
Run the following command to create the Cloud Deploy `DeliveryPipeline` and associated resources, using the values collected in Step 0:
65+
66+
```bash
67+
gcloud deploy apply --file=clouddeploy.yaml --region=<REGION> --project=<PROJECT_ID>
68+
```
69+
70+
### Step 6: Create a skaffold.yaml file and runtime manifests
71+
72+
**Required Context**: Before generating a `skaffold.yaml` file, you **MUST** know if the user has manifests for the runtime they are deploying to.
73+
74+
1. **If the user does not have runtime manifests**: Generate some basic ones based on the runtime.
75+
- **If Cloud Run**: Generate a Cloud Run manifest. Use `references/basic-cloudrun-manifests.md` as a reference.
76+
- **If GKE**: Generate a Kubernetes `Deployment` and `Service`manifest. Use `references/basic-k8s-manifests.md` as a reference.
77+
2. Create a `skaffold.yaml` file required to create a Cloud Deploy `Release` for the `DeliveryPipeline`.
78+
- Use `references/configure-skaffold.md` as a reference when generating the `skaffold.yaml` file.
79+
80+
## Release Management
81+
82+
This section covers the various aspects of managing Cloud Deploy `Release` resources.
83+
84+
### Constraints & Rules
85+
86+
In order to manage releases, a `DeliveryPipeline` MUST already be defined and configured in Cloud Deploy. Determine whether a delivery pipeline is defined by checking for a `clouddeploy.yaml` file and checking if the resources exist in Cloud Deploy or ask the user directly.
87+
88+
**Required Context**:
89+
- **Project ID**: The Google Cloud project ID of the `DeliveryPipeline`.
90+
- **Region**: The region of the `DeliveryPipeline` (e.g., `us-central1`).
91+
- **Delivery Pipeline ID**: The `DeliveryPipeline` ID.
92+
93+
### Create a release
94+
95+
**Use case**: The user wants to deploy a new version of their application.
96+
97+
**Required Context**: Before creating a `Release`, you **MUST** know whether the users runtime manifests are using a placeholder for the container image and the value of the placeholder. This is **CRITICAL** for build artifact substitution in Cloud Deploy. Check the users runtime manifests or ask the user directly. See examples in `references/basic-cloudrun-manifests.md` and `references/basic-k8s-manifests.md`.
98+
99+
Run the following command to create a `Release` for the `DeliveryPipeline`:
100+
101+
```bash
102+
gcloud deploy releases create release-$DATE-$TIME --delivery-pipeline=<DELIVERY_PIPELINE_ID> --region=<REGION> --project=<PROJECT_ID>
103+
```
104+
105+
If the user is leveraging build artifact substitution with a placeholder in the image field of the runtime manifests then use the `--images` flag:
106+
107+
```bash
108+
gcloud deploy releases create release-$DATE-$TIME --delivery-pipeline=<DELIVERY_PIPELINE_ID> --region=<REGION> --project=<PROJECT_ID> --images <IMAGE_PLACEHOLDER>=<IMAGE_URI>
109+
```
110+
111+
**CRITICAL**: If the `skaffold.yaml` is not in the current directory, use the `--source` flag to specify the directory where the `skaffold.yaml` file is located.
112+
113+
Reference documenation for `gcloud deploy releases create`: https://docs.cloud.google.com/sdk/gcloud/reference/deploy/releases/create.
114+
115+
### Promote a release
116+
117+
**Use case**: The user wants to promote the application to the next target environment in the `DeliveryPipeline` progression sequence.
118+
119+
Run the following command to promote a `Release` to the next target in the `DeliveryPipeline` progression sequence:
120+
121+
```bash
122+
gcloud deploy promote --release=<RELEASE_ID> --delivery-pipeline=<DELIVERY_PIPELINE_ID> --region=<REGION> --project=<PROJECT_ID>
123+
```
124+
125+
Reference documentation for `gcloud deploy releases promote`: https://docs.cloud.google.com/sdk/gcloud/reference/deploy/releases/promote.
126+
127+
### Monitor a release
128+
129+
**Use case**: Monitor the status of a release across a `DeliveryPipeline`.
130+
131+
Monitoring a release across a `DeliveryPipeline` consists of checking the status of both the `Release` resource and its child `Rollout` resource(s). Always ensure that the `Release` has completed successfully before checking the status of the `Rollout`.
132+
133+
### Troubleshoot
134+
135+
#### Release failed
136+
137+
Get the release to determine which of the target renders failed and inspect the failure message and failure cause. Additionally the target renders contain a Cloud Build reference where the target render was executed. Retrieve the build logs to determine the root cause of the failure.
138+
139+
#### Rollout failed
140+
141+
Get the rollout to determine which of the jobs failed and inspect the failure message and failure cause. Additionally the `Rollout` contains a Cloud Build reference where the failed job was executed. Retrieve the build logs to determine the root cause of the failure.

‎skills/cloud-deploy-pipelines/references/basic-cloudrun-manifests.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Basic Cloud Run manifests
2+
3+
This document provides examples for generating Cloud Run resource manifests that are used with Cloud Deploy to deploy to Cloud Run.
4+
5+
The examples in this file use placeholders between `<` and `>`, e.g. `<SERVICE_NAME>`. Replace these placeholders with the actual values when generating the YAML.
6+
7+
Cloud Deploy performs build artifact substitutions on the image field so a placeholder like `app-image` is used. When a Cloud Deploy `Release` is created the user supplies the actual image and associates it with the `app-image` key.
8+
9+
## Cloud Run Service
10+
11+
```yaml
12+
apiVersion: serving.knative.dev/v1
13+
kind: Service
14+
metadata:
15+
name: <SERVICE_NAME>
16+
spec:
17+
template:
18+
spec:
19+
containers:
20+
- image: app-image
21+
```
22+
23+
## Cloud Run Worker Pool
24+
25+
```yaml
26+
apiVersion: run.googleapis.com/v1
27+
kind: WorkerPool
28+
metadata:
29+
name: <WORKER_POOL_NAME>
30+
spec:
31+
template:
32+
spec:
33+
containers:
34+
- image: app-image
35+
```

‎skills/cloud-deploy-pipelines/references/basic-k8s-manifests.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Basic Kubernetes manifests
2+
3+
This document provides examples for generating Kubernetes `Deployment` and `Service` resource manifests that are used with Cloud Deploy to deploy to GKE.
4+
5+
The examples in this file use placeholders between `<` and `>`, e.g. `<DEPLOYMENT_NAME>`. Replace these placeholders with the actual values when generating the YAML.
6+
7+
Cloud Deploy performs build artifact substitutions on the image field so a placeholder like `app-image` is used. When a Cloud Deploy `Release` is created the user supplies the actual image and associates it with the `app-image` key.
8+
9+
## Kubernetes Deployment
10+
11+
```yaml
12+
apiVersion: apps/v1
13+
kind: Deployment
14+
metadata:
15+
name: <DEPLOYMENT_NAME>
16+
labels:
17+
app: <APPLICATION_NAME>
18+
spec:
19+
replicas: 1
20+
selector:
21+
matchLabels:
22+
app: <APPLICATION_NAME>
23+
template:
24+
metadata:
25+
labels:
26+
app: <APPLICATION_NAME>
27+
spec:
28+
containers:
29+
- name: <APPLICATION_NAME>
30+
image: app-image
31+
```
32+
33+
## Kubernetes Service
34+
35+
```yaml
36+
apiVersion: v1
37+
kind: Service
38+
metadata:
39+
name: <SERVICE_NAME>
40+
labels:
41+
app: <APPLICATION_NAME>
42+
spec:
43+
selector:
44+
app: <APPLICATION_NAME>
45+
ports:
46+
- protocol: TCP
47+
port: 80
48+
type: LoadBalancer
49+
```

‎skills/cloud-deploy-pipelines/references/configure-automations.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Configure Automations
2+
3+
This document provides examples for configuring Cloud Deploy `Automation` resources. The examples are in YAML format and are intended to be used with the `gcloud deploy apply` command to create or update the resource. Use these examples if it fits the users requirements.
4+
5+
The examples in this file use placeholders between `<` and `>`, e.g. `<AUTOMATION_ID>`. Replace these placeholders with the actual values when generating the YAML.
6+
7+
**CRITICAL**:
8+
- The `metadata.name` field for an `Automation` resource is made up of the `DeliveryPipeline` ID and the `Automation` ID, separated by a forward slash. For example, if the `DeliveryPipeline` ID is "hello-world" and the `Automation` ID is "promote" then the `metadata.name` field should be "hello-world/promote".
9+
- Automations **require** a service account to run as. Use the Compute Engine default service account if the user doesn't provide one. The format is:
10+
11+
```
12+
<PROJECT_NUMBER>-compute@developer.gserviceaccount.com
13+
```
14+
15+
## Automatic Rollbacks
16+
17+
This `Automation` will rollback for any `Target` in the `DeliveryPipeline` progression sequence if the `Rollout` fails.
18+
19+
The `*` in the `selector.targets.id` field means that this `Automation` will apply to all `Target` resources in the `DeliveryPipeline`.
20+
21+
```yaml
22+
apiVersion: deploy.cloud.google.com/v1
23+
kind: Automation
24+
metadata:
25+
name: <PIPELINE_ID>/<AUTOMATION_ID>
26+
serviceAccount: <PROJECT_NUMBER>-compute@developer.gserviceaccount.com
27+
selector:
28+
targets:
29+
- id: "*"
30+
rules:
31+
- repairRolloutRule:
32+
id: "repair-rule"
33+
repairPhases:
34+
- rollback: {}
35+
```
36+
37+
## Automatic Rollbacks with Retry
38+
39+
This `Automation` will attempt to retry the failed `Rollout` job up to 3 times with a 1 minute wait between attempts. If the `Rollout` still fails after the retries then it will be rolled back.
40+
41+
```yaml
42+
apiVersion: deploy.cloud.google.com/v1
43+
kind: Automation
44+
metadata:
45+
name: <PIPELINE_ID>/<AUTOMATION_ID>
46+
serviceAccount: <PROJECT_NUMBER>-compute@developer.gserviceaccount.com
47+
selector:
48+
targets:
49+
- id: "*"
50+
rules:
51+
- repairRolloutRule:
52+
id: "repair-rule"
53+
repairPhases:
54+
- retry:
55+
attempts: 3
56+
wait: 1m
57+
- rollback: {}
58+
```
59+
60+
## Automatic Promotions on a Schedule
61+
62+
This `Automation` will automatically promote a release to the next `Target` in the `DeliveryPipeline` progression sequence every Monday at 12:00 PM New York time.
63+
64+
```yaml
65+
apiVersion: deploy.cloud.google.com/v1
66+
kind: Automation
67+
metadata:
68+
name: <PIPELINE_ID>/<AUTOMATION_ID>
69+
serviceAccount: <PROJECT_NUMBER>-compute@developer.gserviceaccount.com
70+
selector:
71+
targets:
72+
- id: <FROM_TARGET_ID>
73+
rules:
74+
- timedPromoteReleaseRule:
75+
id: "timed-promote-rule"
76+
schedule: "0 12 * * 1" # Cron format.
77+
timeZone: "America/New_York" # IANA format.
78+
destinationTargetId: "@next" # promote to the next `Target` in the `DeliveryPipeline` progression sequence.
79+
```
80+
81+
## Automatic Promotion after a Delay
82+
83+
This `Automation` will automatically promote a release to the next `Target` in the `DeliveryPipeline` after 3 hours has passed since the release was rolled out to the previous `Target`.
84+
85+
```yaml
86+
apiVersion: deploy.cloud.google.com/v1
87+
kind: Automation
88+
metadata:
89+
name: <PIPELINE_ID>/<AUTOMATION_ID>
90+
serviceAccount: <PROJECT_NUMBER>-compute@developer.gserviceaccount.com
91+
selector:
92+
targets:
93+
- id: <FROM_TARGET_ID>
94+
rules:
95+
- promoteReleaseRule:
96+
id: "promote-rule"
97+
wait: 3h
98+
destinationTargetId: "@next" # promote to the next `Target` in the `DeliveryPipeline` progression sequence.
99+
```
100+
101+
## Automatic Canary Advance
102+
103+
This `Automation` will automatically advance through each phase of a canary `Rollout` for a specific `Target` after 1 hour has passed since the previous phase completed.
104+
105+
```yaml
106+
apiVersion: deploy.cloud.google.com/v1
107+
kind: Automation
108+
metadata:
109+
name: <PIPELINE_ID>/<AUTOMATION_ID>
110+
serviceAccount: <PROJECT_NUMBER>-compute@developer.gserviceaccount.com
111+
selector:
112+
targets:
113+
- id: <TARGET_ID>
114+
rules:
115+
- advanceRolloutRule:
116+
id: "advance-rule"
117+
wait: 1h
118+
```

0 commit comments

Comments
 (0)