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:
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.
Define a custom target type, and a target that references that type.
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.
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.
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
- 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Cloud Deploy, Cloud Build, GKE, Cloud Run, and Cloud Storage APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Cloud Deploy, Cloud Build, GKE, Cloud Run, and Cloud Storage APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
- 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.
- 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"
- Add the developer role for your specific runtime.
-
Add the
iam.serviceAccountUser
role, which includes theactAs
permission 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
If you already have the Google Cloud CLI installed, make sure you're running the latest version:
gcloud components update
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.
Open a terminal window.
Create a new directory and navigate into it.
mkdir custom-target-quickstart cd custom-target-quickstart
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.
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
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.
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:
In the Google Cloud console, navigate to the Cloud Deploy Delivery pipelines page to view your delivery pipeline (
custom-targets-pipeline
).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.
Click the release name.
The Release details page is shown.
Click the Artifacts tab.
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".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.Click the bucket whose name starts with
us-central1.deploy-artifacts
...Click the folder whose name starts with
custom-targets-pipeline-
, then click thetest-release-001
folder.Click the folder whose name is your rollout name, which should be
test-release-001-to-sample-env-0001
.Click the folder shown, which is a UUID, then click the
custom-output
folder.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 yourskaffold.yaml
:
Clean up
To avoid incurring charges to your Google Cloud account for the resources used on this page, follow these steps.
Delete the delivery pipeline, target, release, and rollout:
gcloud deploy delete --file=clouddeploy.yaml --force --region=us-central1 --project=PROJECT_ID
Delete both of the Cloud Storage buckets that Cloud Deploy created.
That's it, you completed this quickstart!