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.

    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
  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud 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
  12. If you already have the Google Cloud CLI installed, make sure you're running the latest version:

    gcloud components update
    
  13. 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)")-compute@developer.gserviceaccount.com \
          --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)")-compute@developer.gserviceaccount.com \
          --member=serviceAccount:$(gcloud projects describe PROJECT_ID \
          --format="value(projectNumber)")-compute@developer.gserviceaccount.com \
          --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
            gcloud storage cp manifest.txt $CLOUD_DEPLOY_OUTPUT_GCS_PATH/manifest.txt
            echo {\"resultStatus\": \"SUCCEEDED\", \"manifestFile\": \"$CLOUD_DEPLOY_OUTPUT_GCS_PATH/manifest.txt\"} > results.json
            gcloud storage 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
            gcloud storage 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
    
  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.

    delivery pipeline page in Google Cloud console, showing your pipeline

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.

    Delivery pipeline visualization showing success

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

    Output of the custom render action

  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...

    List of Cloud Storage buckets

  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:

    Output from deploy custom action

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