Define and use a custom target type

Define and use a custom target type

This quickstart shows you how to use Cloud Deploy to create a custom target type, then deploy to a custom target of that type.

In this quickstart, you'll do the following:

1. Create a Skaffold configuration.

   The Skaffold configuration file is where you configure the behavior of the target. This configuration references container images plus shell commands to run on those images, which are the actions for render and deploy operations.

2. Define a custom target type, and a target that references that type.

3. Define your Cloud Deploy delivery pipeline.

   This pipeline includes only one stage and uses only one target. In that stage, you'll reference the target you configured.

4. Create a release, which automatically creates a rollout, resulting in the custom render and deploy operations being performed.

   As part of this release and rollout, the render and deploy operations defined in your Skaffold configuration are both run.

5. View the results of the custom operations. This includes a rendered configuration file uploaded to Cloud Storage, and a string written to that file, as well as a results file that includes the status of the operation.

Before you begin

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Cloud Deploy, Cloud Build, GKE, Cloud Run, and Cloud Storage APIs.

   Enable the APIs

5. Install the Google Cloud CLI.

6. To initialize the gcloud CLI, run the following command:

   gcloud init

   Note: You can run the gcloud CLI in the Google Cloud console without installing the Google Cloud CLI. To run the gcloud CLI in the Google Cloud console, use Cloud Shell.

7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

8. Make sure that billing is enabled for your Google Cloud project.

9. Enable the Cloud Deploy, Cloud Build, GKE, Cloud Run, and Cloud Storage APIs.

   Enable the APIs

10. Install the Google Cloud CLI.

11. To initialize the gcloud CLI, run the following command:

    gcloud init

    Note: You can run the gcloud CLI in the Google Cloud console without installing the Google Cloud CLI. To run the gcloud CLI in the Google Cloud console, use Cloud Shell.

If you already have the Google Cloud CLI installed, make sure you're running the latest version:

gcloud components update

12. Make sure the default Compute Engine service account has sufficient permissions.

    The service account might already have the necessary permissions. These steps are included for projects that disable automatic role grants for default service accounts.

1. First add the clouddeploy.jobRunner role:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:$(gcloud projects describe PROJECT_ID \
       --format="value(projectNumber)")[e-mail] \
       --role="roles/clouddeploy.jobRunner"
   

2. Add the developer role for your specific runtime.
3. Add the iam.serviceAccountUser role, which includes the actAspermission to deploy to the runtime:

   gcloud iam service-accounts add-iam-policy-binding $(gcloud projects describe PROJECT_ID \
       --format="value(projectNumber)")[e-mail] \
       --member=serviceAccount:$(gcloud projects describe PROJECT_ID \
       --format="value(projectNumber)")[e-mail] \
       --role="roles/iam.serviceAccountUser" \
       --project=PROJECT_ID
   

Prepare your Skaffold configuration and application manifest

Cloud Deploy uses Skaffold to provide the details for what to deploy and how to deploy it to your target.

In this quickstart, you create a skaffold.yaml file, which which defines custom actions that represent the render and deploy operations for the custom target type.

Note that the custom actions provided in this quickstart don't actually deploy any application to a runtime. Both the render and deploy actions upload a results file to Cloud Storage to fulfill the custom-target contract between Cloud Deploy and the user-defined render and deploy.

1. Open a terminal window.

2. Create a new directory and navigate into it.

   mkdir custom-target-quickstart
   cd custom-target-quickstart
   

3. Create a file named skaffold.yaml with the following contents:

   apiVersion: skaffold/v4beta7
   kind: Config
   customActions:
   - name: custom-render
     containers:
     - name: render
       image: gcr.io/google.com/cloudsdktool/google-cloud-cli@sha256:66e2681aa3099b4e517e4cdcdefff8f2aa45d305007124ccdc09686f6712d018
       command: ['/bin/bash']
       args:
         - '-c'
         - |-
           echo "Sample manifest rendered content" > manifest.txt
           gsutil cp manifest.txt $CLOUD_DEPLOY_OUTPUT_GCS_PATH/manifest.txt
           echo {\"resultStatus\": \"SUCCEEDED\", \"manifestFile\": \"$CLOUD_DEPLOY_OUTPUT_GCS_PATH/manifest.txt\"} > results.json
           gsutil cp results.json $CLOUD_DEPLOY_OUTPUT_GCS_PATH/results.json
   - name: custom-deploy
     containers:
     - name: deploy
       image: gcr.io/google.com/cloudsdktool/google-cloud-cli@sha256:66e2681aa3099b4e517e4cdcdefff8f2aa45d305007124ccdc09686f6712d018
       command: ['/bin/bash']
       args:
         - '-c'
         - |-
           echo {\"resultStatus\": \"SUCCEEDED\"} > results.json
           gsutil cp results.json $CLOUD_DEPLOY_OUTPUT_GCS_PATH/results.json
   

   This file includes the customActions: stanza, defining a custom render action and a custom deploy action. Each of these custom actions references a container image to run, and commands to run on that container.

   See the skaffold.yaml reference for more information about this configuration file.

Create your delivery pipeline, custom target type, and target

You can define your delivery pipeline, custom target type, and target in one file or in separate files. In this quickstart, you create a single file with all three.

1. In the custom-target-quickstart directory, create a new file, clouddeploy.yaml, with the following content:

   apiVersion: deploy.cloud.google.com/v1
   kind: DeliveryPipeline
   metadata:
     name: custom-targets-pipeline
   serialPipeline:
     stages:
     - targetId: sample-env
   ---
   
   apiVersion: deploy.cloud.google.com/v1
   kind: Target
   metadata:
     name: sample-env
   customTarget:
     customTargetType: basic-custom-target
   ---
   
   apiVersion: deploy.cloud.google.com/v1
   kind: CustomTargetType
   metadata:
     name: basic-custom-target
   customActions:
     renderAction: custom-render
     deployAction: custom-deploy
   

   Note: The custom target type and the target are included with the delivery pipeline in this file, but you can define them in a separate file or multiple separate files.

2. Register your pipeline and targets with the Cloud Deploy service:

   gcloud deploy apply --file=clouddeploy.yaml --region=us-central1 --project=PROJECT_ID
   

   You now have a delivery pipeline, with one target. This is your target using the custom target type, and this pipeline doesn't deploy an application to a runtime.

3. Confirm your pipeline and targets:

   In the Google Cloud console, navigate to the Cloud Deploy Delivery pipelines page to view of list of your available delivery pipelines.

   Open the Delivery pipelines page

   The delivery pipeline you just created is shown, with one target listed in the Targets column.

   

Create a release

A release is the central Cloud Deploy resource representing the changes being deployed. The delivery pipeline defines the lifecycle of that release. See Cloud Deploy service architecture for details about that lifecycle.

Run the following command from the custom-target-quickstart directory to create a release resource that represents the custom action to deploy:

gcloud deploy releases create test-release-001 \
  --project=PROJECT_ID \
  --region=us-central1 \
  --delivery-pipeline=custom-targets-pipeline

As with all releases (unless they include --disable-initial-rollout), Cloud Deploy automatically creates a rollout resource too. And all phases of that rollout are executed, including render and deploy.

View the results in Google Cloud console

After a few minutes, your deployment is complete. In this case, because the two custom actions are commands to echo strings into a file and upload the file to Cloud Storage, nothing is deployed into any target runtime.

However, you can view the file and the strings in that file:

1. In the Google Cloud console, navigate to the Cloud Deploy Delivery pipelines page to view your delivery pipeline (custom-targets-pipeline).

   Open the Delivery pipelines page

2. Click the name of your delivery pipeline (custom-targets-pipeline).

   The pipeline visualization shows the app's deployment status. Because there's only one stage in the pipeline, the visualization shows only one node.

   

   And your release is listed on the Releases tab under Delivery pipeline details.

3. Click the release name.

   The Release details page is shown.

4. Click the Artifacts tab.

5. Under Target artifacts, click the VIEW ARTIFACTS link.

   The rendered manifest file is shown. In this case, the file is the output of the custom render action you defined in your skaffold.yaml configuration file, containing the string "Sample manifest rendered content".

   

6. Find the Cloud Storage buckets created by this release.

   Open the Cloud Storage browser page

   The Buckets page is displayed, showing two buckets created for this release. One bucket contains the delivery pipeline configuration file and the rendered skaffold.yaml. The other includes the output file our custom action is configured to create.

7. Click the bucket whose name starts with us-central1.deploy-artifacts...

   

8. Click the folder whose name starts with custom-targets-pipeline-, then click the test-release-001 folder.

9. Click the folder whose name is your rollout name, which should be test-release-001-to-sample-env-0001.

10. Click the folder shown, which is a UUID, then click the custom-output folder.

11. Click results.json, then click the hyperlinked URL in the Authenticated URL field.

    This file contains the string you configured as output from the custom-deploy action, in your skaffold.yaml:

    

Note: you can also see the render results in the Cloud Storage bucket, but it's quicker to use the release inspector, as shown in the first steps of this procedure.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used on this page, follow these steps.

1. Delete the delivery pipeline, target, release, and rollout:

   gcloud deploy delete --file=clouddeploy.yaml --force --region=us-central1 --project=PROJECT_ID
   

2. Delete both of the Cloud Storage buckets that Cloud Deploy created.

   Open the Cloud Storage browser page

That's it, you completed this quickstart!

What's next

• Learn more about custom targets.

• See the available sample custom target types.

• Learn more about Cloud Deploy.

• Learn the basics of deploying applications.

• Try out the Cloud Deploy walkthrough.