Get Started with Skaffold in Google Cloud Deploy

This document describes how to get started using Skaffold as part of Google Cloud Deploy, including the following:

Configuring Skaffold for use with a Google Cloud Deploy delivery pipeline
Using Skaffold and Google Cloud Deploy with third-party rendering tools, such as Helm and Kustomize
Optionally, using Skaffold for local development
Optionally, using Skaffold for continuous integration and continuous deployment (CI/CD)

Why Skaffold?

Want to know why Google Cloud Deploy uses Skaffold, and why you need to manage a Skaffold configuration? Read on.

I'm experienced with CI/CD, but I don't use Skaffold currently

Skaffold is an open source command-line tool to improve productivity for developers. It orchestrates continuous development, continuous integration (CI), and continuous delivery (CD).

Skaffold provides declarative, portable configuration, using a pluggable architecture, letting you use different tools for the render phase.

When a release is created, Google Cloud Deploy calls Skaffold to render your manifests. At deploy time, Google Cloud Deploy calls Skaffold again to apply those manifests to deploy your application to each target in your progression. After deployment, Skaffold performs health checks to monitor the target runtime for successful deployment.

Skaffold for continuous development

When you use Skaffold for continuous development, images are built, tested, and deployed to a cluster (or Minikube) as you change your code. Cloud Code for VS Code and Cloud Code for IntelliJ IDE extensions integrate Skaffold into Visual Studio Code and JetBrains IDEs, for continuous development.

Skaffold for continuous delivery

You can also use Skaffold for continuous delivery, with build, deploy, render, and apply steps. Google Cloud Deploy uses Skaffold's render and apply capabilities. To use Google Cloud Deploy, you need at least a valid skaffold.yaml configuration file.

Through Skaffold, you can also integrate with third-party manifest-management tools, such as Helm, and Kustomize. Using Skaffold in this way lets you use the features of those tools to render manifests. kubectl remains the deployer for these manifests.

I'm new to deploying to Kubernetes

With Skaffold, you can configure a base set of manifests for all your deployments. You can then use Skaffold's rendering engine, through Google Cloud Deploy, to render, and then deploy, each deployment-specific manifest from one of those base manifests.

Read more about managing manifests, including examples of using Skaffold and Google Cloud Deploy with common manifest-templating tools, such as Helm and Kustomize.

What's required to make Google Cloud Deploy work?

To use a basic Google Cloud Deploy delivery pipeline, the skaffold.yaml configuration file needs at least the following configuration:

The header information that all skaffold.yaml configurations need:
```
apiVersion: skaffold/v2beta28
Kind: Config
```
A deploy stanza, with either deploy.kubectl, for deploying to GKE or to Anthos, or deploy.cloudrun for deploying to Cloud Run.

For GKE:
```
deploy:
  kubectl:
    manifests:
    - ...
```
In the manifests stanza, a list of all Kubernetes raw manifests. If you plan to use a renderer (like Helm or Kustomize) to render manifests, see Add Kustomize support to your skaffold.yaml and Add Helm support to your skaffold.yaml for guidance on how to configure Skaffold to use these tools.

For Cloud Run:
```
metadata: 
  name:
manifests:
  rawYaml:
  - ...
deploy:
  cloudrun: {}
```

Create a `skaffold.yaml` file

Google Cloud Deploy uses Skaffold for rendering and deploying your applications.

At a minimum, you need to provide a skaffold.yaml file that identifies the manifests to use. Here's an example:

apiVersion: skaffold/v2beta28
kind: Config
deploy:
  kubectl:
    manifests:
      - MANIFEST

In this configuration, MANIFEST is the path to the manifest or manifests to be processed by Skaffold.

Have Google Cloud Deploy generate your `skaffold.yaml`

If you don't have a skaffold.yaml file, but you do have a single Kubernetes manifest or a Cloud Run service definition file, Google Cloud Deploy can generate a skaffold.yaml file for you .

The generated Skaffold file will be available in the Cloud Storage source staging directory after the release is complete.

The following command includes the --from-k8s-manifest flag, passing the Kubernetes manifest. Google Cloud Deploy uses the information in the manifest to generate the skaffold.yaml, which is then used for the release.

gcloud deploy releases create  RELEASE_NAME --delivery-pipeline=PIPELINE_NAME --from-k8s-manifest=MANIFEST --region=REGION

To generate the skaffold.yaml from a Cloud Run service YAML, use the same command, but with --from-run-manifest instead of --from-k8s-manifest

Using either of these flags with either the --skaffold-file flag or the --source flag generates an error.

Using the generated `skaffold.yaml` file

The generated skaffold.yaml is suitable for onboarding, learning, and demonstrating Google Cloud Deploy. After you're familiar with Google Cloud Deploy, and for production workloads, you might want a Skaffold configuration that differentiates among your targets (using Skaffold profiles).

When you use the generated skaffold.yaml file as a starting point to create your own differentiated Skaffold config, be sure you use the file in the rendering source archive, not the rendered file. The rendering source is available to download from the Artifacts tab on the **Release details ** page.

This generated skaffold.yaml is included in the render source stored in a Cloud Storage bucket.

You can view this file by downloading the .tar.gz file and extracting it.
The rendered skaffold.yaml is available in Target artifacts.

In the Target artifacts section, click View artifacts.

Using Skaffold for local development

One of the strengths of Skaffold is that you can use it for local development, and for CI/CD. In dev mode, Skaffold watches your source files, and when it detects a change, Skaffold rebuilds the images, retests, and redeploys the containers to a minikube cluster (for example) on your local machine.

When using Skaffold in this way, you can use the same commands locally as for remote deployment.

If you use Skaffold for local development, you can define separate Skaffold profiles for your targets, and a default deploy stanza for local development.

When you stop dev mode, Skaffold cleans up deployed artifacts from the cluster.

Using Skaffold for CI/CD

Besides using Skaffold for continuous local build and deploy, you can use Skaffold for CI/CD. Google Cloud Deploy uses the CI/CD features in Skaffold to render and apply your manifests and deploy your application to your defined targets, given container images built using a CI tool like Cloud Build and an image registry like Artifact Registry.

Render, deploy, and apply

Skaffold separates the manifest rendering process from deployment. Google Cloud Deploy calls skaffold render, to render the manifests, and skaffold apply to apply them to the target.

This separation between render and apply lets you capture the full declarative state of your application in configuration, so that it can be applied safely and repeatably (for example, for rollbacks). This technique also makes approvals easier. Because manifests are rendered for all targets before the first rollout, you can see the rendered YAML that will be applied to each target.

Google Cloud Deploy doesn't support using other deployers to deploy your application. You can, however, use tools like Helm or Kustomize for rendering.

To learn more about how Google Cloud Deploy deploys using kubectl as the deployer, see Google Cloud Deploy Service architecture.

About Skaffold profiles

You can create separate Skaffold profiles—identified in skaffold.yaml, in a profiles: stanza.

When using Skaffold profiles with Google Cloud Deploy, you might create separate profiles for all, or some, of your targets. For example, different profiles for dev, staging, and prod.

Profiles aren't necessary in order to use Skaffold in Google Cloud Deploy, but are useful for defining manifest customizations among your targets, for example using different Kustomize kustomization.yaml files per target.

Add Kustomize support to your `skaffold.yaml`

Integrating your Kustomize configuration with your Google Cloud Deploy/Skaffold configuration consists of the following:

Include a kustomization.yaml file among your configuration files.

You can store your configuration files in a local directory or in a Cloud Storage bucket.

In your skaffold.yaml file, create a deploy stanza for each profile.

You can also have a deploy stanza outside of any defined profiles, if you're not using profiles or for a default deploy configuration not tied to a profile. Here's an example:

apiVersion: skaffold/v2beta28
kind: Config
build:
  artifacts:
    - image: leeroy-web-profiles
      context: leeroy-web-profiles
    - image: leeroy-app-profiles
      context: leeroy-app-profiles
  googleCloudBuild:
    projectId: ${PROJECT_ID}
profiles:
- name: local
  deploy:
    kustomize:
      paths:
        - leeroy-app-profiles/kubernetes/local
- name: test
  deploy:
    kustomize:
      paths:
        - leeroy-app-profiles/kubernetes/test
- name: staging
  deploy:
    kustomize:
      paths:
        - leeroy-app-profiles/kubernetes/staging
- name: prod
  deploy:
    kustomize:
      paths:
        - leeroy-app-profiles/kubernetes/prod

The Skaffold configuration shown here has separate profiles for test, staging, and prod targets. It also shows a profile for local development. In each profile, there's a deploy.kustomize stanza with a path that points to the location of the kustomization to use for that target.

Add Helm support to your `skaffold.yaml`

You can use Helm to render your manifests. Google Cloud Deploy doesn't use Helm to deploy your applications, and supports only kubectl as a deployer.

To use Helm, you need your Helm chart or charts, stored in any location you can reference from within your skaffold.yaml. This location can be in a file system, a repository, possibly along with your skaffold.yaml, or an Open Container Initiative (OCI) repository.

To use a Helm chart, you add a helm stanza to your skaffold.yaml file.

apiVersion: skaffold/v2beta28
kind: Config
build:
  artifacts:
  - image: skaffold-helm-image
deploy:
  helm:
    releases:
    - name: skaffold-helm-image
      chartPath: charts

The skaffold.yaml reference shows what's required in this helm stanza.

Using kpt with Skaffold

We recommend that you don't use kpt with Skaffold V1 in Google Cloud Deploy.

Unsupported Skaffold features

The following features of Skaffold can't be used in Google Cloud Deploy:

Lifecycle hooks
Dynamic Skaffold modules

Using --module= to select specific modules for build, render, apply, and so on, is not supported. Static modules are supported.
In Helm, the ability to create a namespace if one doesn't exist.

What's next

Visit the Skaffold site to find out about how it works and what it can do for you.
Practice using Google Cloud Deploy with Kustomize and Skaffold profiles.
Learn how Google Cloud Deploy selects the Skaffold version to use, when the Skaffold version changes, and how to determine which version is in use.
Learn how to use Skaffold profiles with advanced manifest-management tools like Helm, Kustomize, and kpt.