From aa2b52d58f630f21cbb36ed58f7b5876b1d8ea54 Mon Sep 17 00:00:00 2001 From: mattsanta Date: Fri, 6 Mar 2026 16:05:36 +0000 Subject: [PATCH 1/4] Introduce a cloud-deploy-pipeline-designer skill that guides users through the process of designing a Cloud Deploy delivery pipeline --- .../cloud-deploy-pipeline-designer/SKILL.md | 78 ++++++++++++ .../references/basic-cloudrun-manifests.md | 35 ++++++ .../references/basic-k8s-manifests.md | 49 ++++++++ .../references/configure-automations.md | 118 ++++++++++++++++++ .../references/configure-pipelines.md | 87 +++++++++++++ .../references/configure-skaffold.md | 114 +++++++++++++++++ .../references/configure-targets.md | 59 +++++++++ 7 files changed, 540 insertions(+) create mode 100644 skills/cloud-deploy-pipeline-designer/SKILL.md create mode 100644 skills/cloud-deploy-pipeline-designer/references/basic-cloudrun-manifests.md create mode 100644 skills/cloud-deploy-pipeline-designer/references/basic-k8s-manifests.md create mode 100644 skills/cloud-deploy-pipeline-designer/references/configure-automations.md create mode 100644 skills/cloud-deploy-pipeline-designer/references/configure-pipelines.md create mode 100644 skills/cloud-deploy-pipeline-designer/references/configure-skaffold.md create mode 100644 skills/cloud-deploy-pipeline-designer/references/configure-targets.md diff --git a/skills/cloud-deploy-pipeline-designer/SKILL.md b/skills/cloud-deploy-pipeline-designer/SKILL.md new file mode 100644 index 0000000..44d7cd4 --- /dev/null +++ b/skills/cloud-deploy-pipeline-designer/SKILL.md @@ -0,0 +1,78 @@ +--- +name: cloud-deploy-pipeline-designer +description: > + Design and create Cloud Deploy delivery pipelines to deploy applications to Cloud Run and Google Kubernetes Engine (GKE). Use when users want to deploy their application to multiple environments (e.g. dev and prod), require approvals for promoting their application to production, configure automatic rollbacks, or leverage deployment strategies (i.e. canary). +--- + +# Cloud Deploy Pipeline Designer + +## Overview + +This skill helps you design and create Cloud Deploy delivery pipelines. It guides you through defining targets, configuring promotion sequences, enabling automatic rollbacks, and setting up advanced deployment strategies like canary deployments. + +## Constraints & Rules + +1. **NO PLACEHOLDERS**: Never generate YAML with placeholders like ``. Ask the user for values first. +2. **Context First**: Always check existing files and conversation context before asking. +3. **Step-by-Step**: Perform the steps one at a time. The goal is to guide the user through designing a delivery pipeline. + +## Workflow: Designing a Pipeline + +Follow these steps to create a comprehensive Cloud Deploy pipeline. + +### Step 0: Prerequisites + +**Required Context**: Before generating ANY configuration for this workflow, you **MUST** have the following values. Ask the user strictly for any missing information: +- **Project ID**: The Google Cloud project ID for the Cloud Deploy resources. +- **Region**: The region for the Cloud Deploy resources (e.g., `us-central1`). +- **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. +- **Runtime**: Either Cloud Run or Google Kubernetes Engine (GKE). + - **If Cloud Run**: The Cloud Run project and location. + - **If GKE**: The GKE cluster name. + +### Step 1: Define the target environments + +1. Identify the number of environments (e.g., dev, staging, production). +2. Identify if promotions should require user approval. +3. Define each of the environments as Cloud Deploy `Target` resources in a `clouddeploy.yaml` file. + - Use `references/configure-targets.md` as a reference when generating the resource YAML. + - 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. + +### Step 2: Define the delivery pipeline + +1. Identify whether the user wants to use a canary deployment strategy for any of the target environments. +2. Define the Cloud Deploy `DeliveryPipeline` in the `clouddeploy.yaml` file. + - Use `references/configure-pipelines.md` as a reference when generating the resource YAML. + - Use application name as the `DeliveryPipeline` ID. + +### Step 3: Define automations + +1. Identify whether the user wants to automatically rollback if any failures occur during the rollout. +2. **If the user specified multiple environments in the previous step** + - Identify if they want automatic promotions between environments. +3. **If the user specified a canary deployment strategy in the previous step** + - Identify if they want to automatically advance the rollout through the phases after a wait period. +4. Define the Cloud Deploy `Automation` resources in the `clouddeploy.yaml` file. + - Use `references/configure-automations.md` as a reference when generating the resource YAML. + +### Step 4: Validate the clouddeploy.yaml file + +Ensure that the `clouddeploy.yaml` file is valid. See https://docs.cloud.google.com/deploy/docs/config-files for the schema. + +### Step 5: Create the delivery pipeline + +Run the following command to create the Cloud Deploy `DeliveryPipeline` and associated resources, using the values collected in Step 0: + +```bash +gcloud deploy apply --file=clouddeploy.yaml --region= --project= +``` + +### Step 6: Create a skaffold.yaml file and runtime manifests + +**Required Context**: Before generating a `skaffold.yaml` file, you **MUST** know if the user has manifests for the runtime they are deploying to. + +1. **If the user does not have runtime manifests**: Generate some basic ones based on the runtime. + - **If Cloud Run**: Generate a Cloud Run manifest. Use `references/basic-cloudrun-manifests.md` as a reference. + - **If GKE**: Generate a Kubernetes `Deployment` and `Service `manifest. Use `references/basic-k8s-manifests.md` as a reference. +2. Create a `skaffold.yaml` file required to create a Cloud Deploy `Release` for the `DeliveryPipeline`. + - Use `references/configure-skaffold.md` as a reference when generating the `skaffold.yaml` file. diff --git a/skills/cloud-deploy-pipeline-designer/references/basic-cloudrun-manifests.md b/skills/cloud-deploy-pipeline-designer/references/basic-cloudrun-manifests.md new file mode 100644 index 0000000..bff38a6 --- /dev/null +++ b/skills/cloud-deploy-pipeline-designer/references/basic-cloudrun-manifests.md @@ -0,0 +1,35 @@ +# Basic Cloud Run manifests + +This document provides examples for generating Cloud Run resource manifests that are used with Cloud Deploy to deploy to Cloud Run. + +The examples in this file use placeholders between `<` and `>`, e.g. ``. Replace these placeholders with the actual values when generating the YAML. + +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. + +## Cloud Run Service + +```yaml +apiVersion: serving.knative.dev/v1 +kind: Service +metadata: + name: +spec: + template: + spec: + containers: + - image: app-image +``` + +## Cloud Run Worker Pool + +```yaml +apiVersion: run.googleapis.com/v1 +kind: WorkerPool +metadata: + name: +spec: + template: + spec: + containers: + - image: app-image +``` \ No newline at end of file diff --git a/skills/cloud-deploy-pipeline-designer/references/basic-k8s-manifests.md b/skills/cloud-deploy-pipeline-designer/references/basic-k8s-manifests.md new file mode 100644 index 0000000..52efdde --- /dev/null +++ b/skills/cloud-deploy-pipeline-designer/references/basic-k8s-manifests.md @@ -0,0 +1,49 @@ +# Basic Kubernetes manifests + +This document provides examples for generating Kubernetes `Deployment` and `Service` resource manifests that are used with Cloud Deploy to deploy to GKE. + +The examples in this file use placeholders between `<` and `>`, e.g. ``. Replace these placeholders with the actual values when generating the YAML. + +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. + +## Kubernetes Deployment + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: + labels: + app: +spec: + replicas: 1 + selector: + matchLabels: + app: + template: + metadata: + labels: + app: + spec: + containers: + - name: + image: app-image +``` + +## Kubernetes Service + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: + labels: + app: +spec: + selector: + app: + ports: + - protocol: TCP + port: 80 + type: LoadBalancer +``` \ No newline at end of file diff --git a/skills/cloud-deploy-pipeline-designer/references/configure-automations.md b/skills/cloud-deploy-pipeline-designer/references/configure-automations.md new file mode 100644 index 0000000..f205158 --- /dev/null +++ b/skills/cloud-deploy-pipeline-designer/references/configure-automations.md @@ -0,0 +1,118 @@ +# Configure Automations + +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. + +The examples in this file use placeholders between `<` and `>`, e.g. ``. Replace these placeholders with the actual values when generating the YAML. + +**CRITICAL**: +- 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". +- 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: + +``` +-compute@developer.gserviceaccount.com +``` + +## Automatic Rollbacks + +This `Automation` will rollback for any `Target` in the `DeliveryPipeline` progression sequence if the `Rollout` fails. + +The `*` in the `selector.targets.id` field means that this `Automation` will apply to all `Target` resources in the `DeliveryPipeline`. + +```yaml +apiVersion: deploy.cloud.google.com/v1 +kind: Automation +metadata: + name: / +serviceAccount: -compute@developer.gserviceaccount.com +selector: + targets: + - id: "*" +rules: +- repairRolloutRule: + id: "repair-rule" + repairPhases: + - rollback: {} +``` + +## Automatic Rollbacks with Retry + +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. + +```yaml +apiVersion: deploy.cloud.google.com/v1 +kind: Automation +metadata: + name: / +serviceAccount: -compute@developer.gserviceaccount.com +selector: + targets: + - id: "*" +rules: +- repairRolloutRule: + id: "repair-rule" + repairPhases: + - retry: + attempts: 3 + wait: 1m + - rollback: {} +``` + +## Automatic Promotions on a Schedule + +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. + +```yaml +apiVersion: deploy.cloud.google.com/v1 +kind: Automation +metadata: + name: / +serviceAccount: -compute@developer.gserviceaccount.com +selector: + targets: + - id: +rules: +- timedPromoteReleaseRule: + id: "timed-promote-rule" + schedule: "0 12 * * 1" # Cron format. + timeZone: "America/New_York" # IANA format. + destinationTargetId: "@next" # promote to the next `Target` in the `DeliveryPipeline` progression sequence. +``` + +## Automatic Promotion after a Delay + +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`. + +```yaml +apiVersion: deploy.cloud.google.com/v1 +kind: Automation +metadata: + name: / +serviceAccount: -compute@developer.gserviceaccount.com +selector: + targets: + - id: +rules: +- promoteReleaseRule: + id: "promote-rule" + wait: 3h + destinationTargetId: "@next" # promote to the next `Target` in the `DeliveryPipeline` progression sequence. +``` + +## Automatic Canary Advance + +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. + +```yaml +apiVersion: deploy.cloud.google.com/v1 +kind: Automation +metadata: + name: / +serviceAccount: -compute@developer.gserviceaccount.com +selector: + targets: + - id: +rules: +- advanceRolloutRule: + id: "advance-rule" + wait: 1h +``` diff --git a/skills/cloud-deploy-pipeline-designer/references/configure-pipelines.md b/skills/cloud-deploy-pipeline-designer/references/configure-pipelines.md new file mode 100644 index 0000000..20b7aef --- /dev/null +++ b/skills/cloud-deploy-pipeline-designer/references/configure-pipelines.md @@ -0,0 +1,87 @@ +# Configure Delivery Pipelines + +This document provides examples for configuring Cloud Deploy `DeliveryPipeline` 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. + +The examples in this file use placeholders between `<` and `>`, e.g. ``. Replace these placeholders with the actual values when generating the YAML. + +## Pipeline with a single target + +This is the minimal `DeliveryPipeline` that can be defined. It only contains a single target. + +```yaml +apiVersion: deploy.cloud.google.com/v1 +kind: DeliveryPipeline +metadata: + name: +serialPipeline: + stages: + - targetId: + profiles: [] +``` + +## Pipeline with multiple targets + +This `DeliveryPipeline` contains multiple targets in the progression sequence. Cloud Deploy will deploy to the targets in the order they are listed in the `stages` field. + +```yaml +apiVersion: deploy.cloud.google.com/v1 +kind: DeliveryPipeline +metadata: + name: +serialPipeline: + stages: + - targetId: # e.g. "Dev" target. + profiles: [] + - targetId: # e.g. "Production" target. + profiles: [] +``` + +## Pipeline with the canary deployment strategy + +The `percentages` field is a list of percentages to use for the canary deployment strategy. For example, deploy 10% of traffic to the canary, then 50%, before the stable phase. The `percentages` field **cannot** contain 100 since that is assumed by the stable phase. + +### Cloud Run + +For Cloud Deploy to automatically handle canarying for Cloud Run the `canary.runtimeConfig.cloudRun.automaticTrafficControl` field **must** be set to `true`. + +```yaml +apiVersion: deploy.cloud.google.com/v1 +kind: DeliveryPipeline +metadata: + name: +serialPipeline: + stages: + - targetId: + profiles: [] + strategy: + canary: + runtimeConfig: + cloudRun: + automaticTrafficControl: true + canaryDeployment: + percentages: [10, 50] +``` + +### GKE + +Cloud Deploy requires the Kubernetes `Deployment` and `Service` names to automatically handle canarying for GKE. Check the local workspace for Kubernetes manifests to determine the `Deployment` and `Service` names, or ask the user to provide them. If the former, confirm with the user that the right `Deployment` and `Service` were determined. + +```yaml +apiVersion: deploy.cloud.google.com/v1 +kind: DeliveryPipeline +metadata: + name: +serialPipeline: + stages: + - targetId: + profiles: [] + strategy: + canary: + runtimeConfig: + kubernetes: + serviceNetworking: + service: + deployment: + canaryDeployment: + percentages: [10, 50] +``` diff --git a/skills/cloud-deploy-pipeline-designer/references/configure-skaffold.md b/skills/cloud-deploy-pipeline-designer/references/configure-skaffold.md new file mode 100644 index 0000000..4c02a1d --- /dev/null +++ b/skills/cloud-deploy-pipeline-designer/references/configure-skaffold.md @@ -0,0 +1,114 @@ +# Configure Skaffold YAML + +This document provides examples for configuring a `skaffold.yaml` file used when creating a Cloud Deploy `Release` for a `DeliveryPipeline`. Use these examples if it fits the users requirements. + +## Deploy to Cloud Run + +**CRITICAL** when deploying to Cloud Run: +- **MUST** include the `cloudrun` deployer. +- **ALWAYS** use `rawYaml` under `manifests` unless the user specifies otherwise. + +Minimal `skaffold.yaml` file for deploying to Cloud Run. Requires a reference to the Cloud Run manifest file that contains the Cloud Run resource. + +```yaml +apiVersion: skaffold/v4beta13 +kind: Config +deploy: + cloudrun: {} +profiles: +- name: + manifests: + rawYaml: + - +``` + +### With different files per target + +Uses different Cloud Run manifests for each `Target` in the `DeliveryPipeline`. Since the Cloud Run resource name is defined within the manifest files, this is generally the expected configuration when deploying to Cloud Run to multiple `Target`s. + +```yaml +apiVersion: skaffold/v4beta13 +kind: Config +deploy: + cloudrun: {} +profiles: +- name: + manifests: + rawYaml: + - +- name: + manifests: + rawYaml: + - +``` + +## Deploy to GKE + +Minimal `skaffold.yaml` file for deploying to GKE. Requires a reference to the Kubernetes manifests file that contains resources such as a `Deployment` and `Service`. + +```yaml +apiVersion: skaffold/v4beta13 +kind: Config +deploy: + kubectl: {} +profiles: +- name: + manifests: + rawYaml: + - +``` + +### With different files per target + +Uses different Kubernetes manifests for each `Target` in the `DeliveryPipeline`. This is useful when the Kubernetes resource configurations are not identical across environments. + +```yaml +apiVersion: skaffold/v4beta13 +kind: Config +deploy: + kubectl: {} +profiles: +- name: + manifests: + rawYaml: + - +- name: + manifests: + rawYaml: + - +``` + +### Helm chart + +Minimal `skaffold.yaml` file for deploying to GKE when the Kubernetes resources are defined in a Helm chart. + +```yaml +apiVersion: skaffold/v4beta13 +kind: Config +deploy: + kubectl: {} +profiles: +- name: + manifests: + helm: + releases: + - name: + chartPath: +``` + +### Kustomize + +Minimal `skaffold.yaml` file for deploying to GKE when the Kubernetes resources are defined in Kustomization file. + +```yaml +apiVersion: skaffold/v4beta13 +kind: Config +deploy: + kubectl: {} +profiles: +- name: + manifests: + kustomize: + path: + - +``` diff --git a/skills/cloud-deploy-pipeline-designer/references/configure-targets.md b/skills/cloud-deploy-pipeline-designer/references/configure-targets.md new file mode 100644 index 0000000..91f7daa --- /dev/null +++ b/skills/cloud-deploy-pipeline-designer/references/configure-targets.md @@ -0,0 +1,59 @@ +# Configure Targets + +This document provides examples for configuring Cloud Deploy `Target` 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. + +The examples in this file use placeholders between `<` and `>`, e.g. ``. Replace these placeholders with the actual values when generating the YAML. + +## Cloud Run target + +### Minimal Cloud Run target + +Minimal Cloud Run `Target` only requires specifying the project and location of the Cloud Run Service. + +```yaml +apiVersion: deploy.cloud.google.com/v1 +kind: Target +metadata: + name: +run: + location: projects//locations/ +``` + +### Require approval + +```yaml +apiVersion: deploy.cloud.google.com/v1 +kind: Target +metadata: + name: +run: + location: projects//locations/ +requireApproval: true +``` + +## Google Kubernetes Engine (GKE) target + +### Minimal GKE target + +Minimal GKE `Target` only requires specifying the name of the GKE cluster. + +```yaml +apiVersion: deploy.cloud.google.com/v1 +kind: Target +metadata: + name: +gke: + cluster: projects//locations//clusters/ +``` + +### Require approval + +```yaml +apiVersion: deploy.cloud.google.com/v1 +kind: Target +metadata: + name: +gke: + cluster: projects//locations//clusters/ +requireApproval: true +``` From d6f972458eb0280edddf021f99b1c090a788a842 Mon Sep 17 00:00:00 2001 From: mattsanta Date: Fri, 6 Mar 2026 16:17:00 +0000 Subject: [PATCH 2/4] Address typos and lint issues --- skills/cloud-deploy-pipeline-designer/SKILL.md | 2 +- .../references/basic-cloudrun-manifests.md | 2 +- .../references/configure-skaffold.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/cloud-deploy-pipeline-designer/SKILL.md b/skills/cloud-deploy-pipeline-designer/SKILL.md index 44d7cd4..126415c 100644 --- a/skills/cloud-deploy-pipeline-designer/SKILL.md +++ b/skills/cloud-deploy-pipeline-designer/SKILL.md @@ -73,6 +73,6 @@ gcloud deploy apply --file=clouddeploy.yaml --region= --project= manifests: kustomize: - path: + paths: - ``` From e93ea18b884d6969d480d76ef8358bbce2aeb776 Mon Sep 17 00:00:00 2001 From: mattsanta Date: Fri, 6 Mar 2026 16:18:54 +0000 Subject: [PATCH 3/4] One more missing new line --- .../references/basic-k8s-manifests.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/cloud-deploy-pipeline-designer/references/basic-k8s-manifests.md b/skills/cloud-deploy-pipeline-designer/references/basic-k8s-manifests.md index 52efdde..e897b45 100644 --- a/skills/cloud-deploy-pipeline-designer/references/basic-k8s-manifests.md +++ b/skills/cloud-deploy-pipeline-designer/references/basic-k8s-manifests.md @@ -46,4 +46,4 @@ spec: - protocol: TCP port: 80 type: LoadBalancer -``` \ No newline at end of file +``` From 327ebe4df97c563ad0a4b95f2b4c56f0e4d1089b Mon Sep 17 00:00:00 2001 From: mattsanta Date: Fri, 6 Mar 2026 21:03:31 +0000 Subject: [PATCH 4/4] Update skill to be Cloud Deploy generic and add release management sections --- .../cloud-deploy-pipeline-designer/SKILL.md | 78 ---------- skills/cloud-deploy-pipelines/SKILL.md | 135 ++++++++++++++++++ .../references/basic-cloudrun-manifests.md | 0 .../references/basic-k8s-manifests.md | 0 .../references/configure-automations.md | 0 .../references/configure-pipelines.md | 0 .../references/configure-skaffold.md | 0 .../references/configure-targets.md | 0 8 files changed, 135 insertions(+), 78 deletions(-) delete mode 100644 skills/cloud-deploy-pipeline-designer/SKILL.md create mode 100644 skills/cloud-deploy-pipelines/SKILL.md rename skills/{cloud-deploy-pipeline-designer => cloud-deploy-pipelines}/references/basic-cloudrun-manifests.md (100%) rename skills/{cloud-deploy-pipeline-designer => cloud-deploy-pipelines}/references/basic-k8s-manifests.md (100%) rename skills/{cloud-deploy-pipeline-designer => cloud-deploy-pipelines}/references/configure-automations.md (100%) rename skills/{cloud-deploy-pipeline-designer => cloud-deploy-pipelines}/references/configure-pipelines.md (100%) rename skills/{cloud-deploy-pipeline-designer => cloud-deploy-pipelines}/references/configure-skaffold.md (100%) rename skills/{cloud-deploy-pipeline-designer => cloud-deploy-pipelines}/references/configure-targets.md (100%) diff --git a/skills/cloud-deploy-pipeline-designer/SKILL.md b/skills/cloud-deploy-pipeline-designer/SKILL.md deleted file mode 100644 index 126415c..0000000 --- a/skills/cloud-deploy-pipeline-designer/SKILL.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -name: cloud-deploy-pipeline-designer -description: > - Design and create Cloud Deploy delivery pipelines to deploy applications to Cloud Run and Google Kubernetes Engine (GKE). Use when users want to deploy their application to multiple environments (e.g. dev and prod), require approvals for promoting their application to production, configure automatic rollbacks, or leverage deployment strategies (i.e. canary). ---- - -# Cloud Deploy Pipeline Designer - -## Overview - -This skill helps you design and create Cloud Deploy delivery pipelines. It guides you through defining targets, configuring promotion sequences, enabling automatic rollbacks, and setting up advanced deployment strategies like canary deployments. - -## Constraints & Rules - -1. **NO PLACEHOLDERS**: Never generate YAML with placeholders like ``. Ask the user for values first. -2. **Context First**: Always check existing files and conversation context before asking. -3. **Step-by-Step**: Perform the steps one at a time. The goal is to guide the user through designing a delivery pipeline. - -## Workflow: Designing a Pipeline - -Follow these steps to create a comprehensive Cloud Deploy pipeline. - -### Step 0: Prerequisites - -**Required Context**: Before generating ANY configuration for this workflow, you **MUST** have the following values. Ask the user strictly for any missing information: -- **Project ID**: The Google Cloud project ID for the Cloud Deploy resources. -- **Region**: The region for the Cloud Deploy resources (e.g., `us-central1`). -- **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. -- **Runtime**: Either Cloud Run or Google Kubernetes Engine (GKE). - - **If Cloud Run**: The Cloud Run project and location. - - **If GKE**: The GKE cluster name. - -### Step 1: Define the target environments - -1. Identify the number of environments (e.g., dev, staging, production). -2. Identify if promotions should require user approval. -3. Define each of the environments as Cloud Deploy `Target` resources in a `clouddeploy.yaml` file. - - Use `references/configure-targets.md` as a reference when generating the resource YAML. - - 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. - -### Step 2: Define the delivery pipeline - -1. Identify whether the user wants to use a canary deployment strategy for any of the target environments. -2. Define the Cloud Deploy `DeliveryPipeline` in the `clouddeploy.yaml` file. - - Use `references/configure-pipelines.md` as a reference when generating the resource YAML. - - Use application name as the `DeliveryPipeline` ID. - -### Step 3: Define automations - -1. Identify whether the user wants to automatically rollback if any failures occur during the rollout. -2. **If the user specified multiple environments in the previous step** - - Identify if they want automatic promotions between environments. -3. **If the user specified a canary deployment strategy in the previous step** - - Identify if they want to automatically advance the rollout through the phases after a wait period. -4. Define the Cloud Deploy `Automation` resources in the `clouddeploy.yaml` file. - - Use `references/configure-automations.md` as a reference when generating the resource YAML. - -### Step 4: Validate the clouddeploy.yaml file - -Ensure that the `clouddeploy.yaml` file is valid. See https://docs.cloud.google.com/deploy/docs/config-files for the schema. - -### Step 5: Create the delivery pipeline - -Run the following command to create the Cloud Deploy `DeliveryPipeline` and associated resources, using the values collected in Step 0: - -```bash -gcloud deploy apply --file=clouddeploy.yaml --region= --project= -``` - -### Step 6: Create a skaffold.yaml file and runtime manifests - -**Required Context**: Before generating a `skaffold.yaml` file, you **MUST** know if the user has manifests for the runtime they are deploying to. - -1. **If the user does not have runtime manifests**: Generate some basic ones based on the runtime. - - **If Cloud Run**: Generate a Cloud Run manifest. Use `references/basic-cloudrun-manifests.md` as a reference. - - **If GKE**: Generate a Kubernetes `Deployment` and `Service`manifest. Use `references/basic-k8s-manifests.md` as a reference. -2. Create a `skaffold.yaml` file required to create a Cloud Deploy `Release` for the `DeliveryPipeline`. - - Use `references/configure-skaffold.md` as a reference when generating the `skaffold.yaml` file. diff --git a/skills/cloud-deploy-pipelines/SKILL.md b/skills/cloud-deploy-pipelines/SKILL.md new file mode 100644 index 0000000..4be1317 --- /dev/null +++ b/skills/cloud-deploy-pipelines/SKILL.md @@ -0,0 +1,135 @@ +--- +name: cloud-deploy-pipelines +description: > + 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 enable automatic rollbacks when there are issues with the rollout. Should also be used if the user is already using Cloud Deploy and wants to create releases, promote releases across environments, or debug release failures. +--- + +# Cloud Deploy Pipelines + +## Overview + +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. + +## Workflow: Designing a Pipeline + +This workflow provides steps for designing a Cloud Deploy `DeliveryPipeline`. + +### Constraints & Rules + +1. **NO PLACEHOLDERS**: Never generate YAML with placeholders like ``. Ask the user for values first. +2. **Context First**: Always check existing files and conversation context before asking. +3. **Step-by-Step**: Perform the steps one at a time. The goal is to guide the user through designing a delivery pipeline. + +### Step 0: Prerequisites + +**Required Context**: Before generating ANY configuration for this workflow, you **MUST** have the following values. Ask the user strictly for any missing information: +- **Project ID**: The Google Cloud project ID for the Cloud Deploy resources. +- **Region**: The region for the Cloud Deploy resources (e.g., `us-central1`). +- **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. +- **Runtime**: Either Cloud Run or Google Kubernetes Engine (GKE). + - **If Cloud Run**: The Cloud Run project and location. + - **If GKE**: The GKE cluster name. + +### Step 1: Define the target environments + +1. Identify the number of environments (e.g., dev, staging, production). +2. Identify if promotions should require user approval. +3. Define each of the environments as Cloud Deploy `Target` resources in a `clouddeploy.yaml` file. + - Use `references/configure-targets.md` as a reference when generating the resource YAML. + - 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. + +### Step 2: Define the delivery pipeline + +1. Identify whether the user wants to use a canary deployment strategy for any of the target environments. +2. Define the Cloud Deploy `DeliveryPipeline` in the `clouddeploy.yaml` file. + - Use `references/configure-pipelines.md` as a reference when generating the resource YAML. + - Use application name as the `DeliveryPipeline` ID. + +### Step 3: Define automations + +1. Identify whether the user wants to automatically rollback if any failures occur during the rollout. +2. **If the user specified multiple environments in the previous step** + - Identify if they want automatic promotions between environments. +3. **If the user specified a canary deployment strategy in the previous step** + - Identify if they want to automatically advance the rollout through the phases after a wait period. +4. Define the Cloud Deploy `Automation` resources in the `clouddeploy.yaml` file. + - Use `references/configure-automations.md` as a reference when generating the resource YAML. + +### Step 4: Validate the clouddeploy.yaml file + +Ensure that the `clouddeploy.yaml` file is valid. See https://docs.cloud.google.com/deploy/docs/config-files for the schema. + +### Step 5: Create the delivery pipeline + +Run the following command to create the Cloud Deploy `DeliveryPipeline` and associated resources, using the values collected in Step 0: + +```bash +gcloud deploy apply --file=clouddeploy.yaml --region= --project= +``` + +### Step 6: Create a skaffold.yaml file and runtime manifests + +**Required Context**: Before generating a `skaffold.yaml` file, you **MUST** know if the user has manifests for the runtime they are deploying to. + +1. **If the user does not have runtime manifests**: Generate some basic ones based on the runtime. + - **If Cloud Run**: Generate a Cloud Run manifest. Use `references/basic-cloudrun-manifests.md` as a reference. + - **If GKE**: Generate a Kubernetes `Deployment` and `Service`manifest. Use `references/basic-k8s-manifests.md` as a reference. +2. Create a `skaffold.yaml` file required to create a Cloud Deploy `Release` for the `DeliveryPipeline`. + - Use `references/configure-skaffold.md` as a reference when generating the `skaffold.yaml` file. + +## Release Management + +This section covers the various aspects of managing Cloud Deploy `Release` resources. + +### Constraints & Rules + +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. + +**Required Context**: + - **Project ID**: The Google Cloud project ID of the `DeliveryPipeline`. + - **Region**: The region of the `DeliveryPipeline` (e.g., `us-central1`). + - **Delivery Pipeline ID**: The `DeliveryPipeline` ID. + +### Create a release + +**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`. + +Run the following command to create a `Release` for the `DeliveryPipeline`: + +```bash +gcloud deploy releases create release-$DATE-$TIME --delivery-pipeline= --region= --project= +``` + +If the user is leveraging build artifact substitution with a placeholder in the image field of the runtime manifests then use the `--images` flag: + +```bash +gcloud deploy releases create release-$DATE-$TIME --delivery-pipeline= --region= --project= --images = +``` + +**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. + +Reference documenation for `gcloud deploy releases create`: https://docs.cloud.google.com/sdk/gcloud/reference/deploy/releases/create. + +### Promote a release + +Run the following command to promote a `Release` to the next target in the `DeliveryPipeline` progression sequence: + +```bash +gcloud deploy promote --release= --delivery-pipeline= --region= --project= +``` + +Reference documentation for `gcloud deploy releases promote`: https://docs.cloud.google.com/sdk/gcloud/reference/deploy/releases/promote. + +### Monitor a release + +Monitoring a release across a delivery pipeline 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`. + +### Troubleshoot + +#### Release failed + +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. + +#### Rollout failed + +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. diff --git a/skills/cloud-deploy-pipeline-designer/references/basic-cloudrun-manifests.md b/skills/cloud-deploy-pipelines/references/basic-cloudrun-manifests.md similarity index 100% rename from skills/cloud-deploy-pipeline-designer/references/basic-cloudrun-manifests.md rename to skills/cloud-deploy-pipelines/references/basic-cloudrun-manifests.md diff --git a/skills/cloud-deploy-pipeline-designer/references/basic-k8s-manifests.md b/skills/cloud-deploy-pipelines/references/basic-k8s-manifests.md similarity index 100% rename from skills/cloud-deploy-pipeline-designer/references/basic-k8s-manifests.md rename to skills/cloud-deploy-pipelines/references/basic-k8s-manifests.md diff --git a/skills/cloud-deploy-pipeline-designer/references/configure-automations.md b/skills/cloud-deploy-pipelines/references/configure-automations.md similarity index 100% rename from skills/cloud-deploy-pipeline-designer/references/configure-automations.md rename to skills/cloud-deploy-pipelines/references/configure-automations.md diff --git a/skills/cloud-deploy-pipeline-designer/references/configure-pipelines.md b/skills/cloud-deploy-pipelines/references/configure-pipelines.md similarity index 100% rename from skills/cloud-deploy-pipeline-designer/references/configure-pipelines.md rename to skills/cloud-deploy-pipelines/references/configure-pipelines.md diff --git a/skills/cloud-deploy-pipeline-designer/references/configure-skaffold.md b/skills/cloud-deploy-pipelines/references/configure-skaffold.md similarity index 100% rename from skills/cloud-deploy-pipeline-designer/references/configure-skaffold.md rename to skills/cloud-deploy-pipelines/references/configure-skaffold.md diff --git a/skills/cloud-deploy-pipeline-designer/references/configure-targets.md b/skills/cloud-deploy-pipelines/references/configure-targets.md similarity index 100% rename from skills/cloud-deploy-pipeline-designer/references/configure-targets.md rename to skills/cloud-deploy-pipelines/references/configure-targets.md