Try out Halyard on GKE

Note: we recommend that you install Spinnaker following the standard setup directions rather than using this guide, which is just a set of commands to get Spinnaker up and running on GCS and GKE.

In this guide, you will learn the basics of Halyard, Spinnaker’s tool for managing your Spinnaker instance.


In our scenario, we want to create a Spinnaker instance and set it up as follows:

  • The Spinnaker instance is itself running in a Kubernetes cluster
  • The Kubernetes provider is set up so that we can deploy our custom apps to Kubernetes
  • We can pull Docker images from our Google Container Registry
  • We use GCS as our persistence store

For this exercise we will be operating entirely within one GCP project, and use Google Kubernetes Engine (GKE) as our Kubernetes cluster.

image of deployed environment including halyard vm
How your Kubernetes cluster can look at the end of this guide, with an app deployed (not covered).

Part 0: Preparation

Install gcloud

If you don’t already have gcloud installed, navigate to Installing Cloud SDK to install gcloud

Authenticate gcloud and set your default project.

Authenticate gcloud with your account. Follow the instructions after the following command.

gcloud auth login

Set your default gcloud project:

gcloud config set project <PROJECT_NAME>

Create a Kubernetes cluster

Navigate to the Google Cloud Console’s GKE section to create a new Kubernetes cluster (please note the cluster name and zone). Make sure to enable legacy authorization (in one of the drop-down menus shown when creating your cluster), or you may see authorization errors when deploying Spinnaker.

Enable APIs

Navigate to the Google Cloud Console and enable the following APIs:

Set up credentials

Create a service account for our halyard host VM:

GCP_PROJECT=$(gcloud config get-value project)

gcloud iam service-accounts create $HALYARD_SA \
    --project=$GCP_PROJECT \
    --display-name $HALYARD_SA

HALYARD_SA_EMAIL=$(gcloud iam service-accounts list \
    --project=$GCP_PROJECT \
    --filter="displayName:$HALYARD_SA" \

gcloud projects add-iam-policy-binding $GCP_PROJECT \
    --role roles/iam.serviceAccountKeyAdmin \
    --member serviceAccount:$HALYARD_SA_EMAIL

gcloud projects add-iam-policy-binding $GCP_PROJECT \
    --role roles/container.admin \
    --member serviceAccount:$HALYARD_SA_EMAIL

Create a service account for GCS and GCR that you’ll later be handing to Spinnaker


gcloud iam service-accounts create $GCS_SA \
    --project=$GCP_PROJECT \
    --display-name $GCS_SA

GCS_SA_EMAIL=$(gcloud iam service-accounts list \
    --project=$GCP_PROJECT \
    --filter="displayName:$GCS_SA" \

gcloud projects add-iam-policy-binding $GCP_PROJECT \
    --role roles/storage.admin \
    --member serviceAccount:$GCS_SA_EMAIL

gcloud projects add-iam-policy-binding $GCP_PROJECT \
    --member serviceAccount:$GCS_SA_EMAIL \
    --role roles/browser

Create halyard host VM

Create a VM with the service account:

HALYARD_HOST=$(echo $USER-halyard-`date +%m%d` | tr '_.' '-')

gcloud compute instances create $HALYARD_HOST \
    --project=$GCP_PROJECT \
    --zone=us-central1-f \
    --scopes=cloud-platform \
    --service-account=$HALYARD_SA_EMAIL \
    --image-project=ubuntu-os-cloud \
    --image-family=ubuntu-1404-lts \

SSH into the VM. We specify port forwarding because at the end of this exercise you’ll be port forwarding from this VM to Spinnaker running in the Kubernetes cluster. That is, you’ll be port forwarding twice: from your workstation browser to this GCE VM, and from this GCE VM to the Kubernetes cluster.

:warning: You need to SSH into the Halyard host VM from your local workstation; SSHing from Cloud Shell, a Chromebook or another VM won’t open the necessary SSH tunnels that will allow your local web browser to access Spinnaker.

gcloud compute ssh $HALYARD_HOST \
    --project=$GCP_PROJECT \
    --zone=us-central1-f \
    --ssh-flag="-L 9000:localhost:9000" \
    --ssh-flag="-L 8084:localhost:8084"

From this point on, you will be entering the commands below in the halyard ssh session.

Part 1: Install halyard

Install kubectl


curl -LO$KUBECTL_LATEST/bin/linux/amd64/kubectl

chmod +x kubectl

sudo mv kubectl /usr/local/bin/kubectl

Install halyard

curl -O

sudo bash

. ~/.bashrc

Part 2: Gather needed credentials


Generate your ~/.kube/config file:


gcloud config set container/use_client_certificate true

gcloud container clusters get-credentials $GKE_CLUSTER_NAME \

GCS service account

Download the service account json file for your GCP project with the following commands:


mkdir -p $(dirname $GCS_SA_DEST)

GCS_SA_EMAIL=$(gcloud iam service-accounts list \
    --filter="displayName:$GCS_SA" \

gcloud iam service-accounts keys create $GCS_SA_DEST \
    --iam-account $GCS_SA_EMAIL

Part 3: Set Spinnaker configuration

We configure Halyard to use the latest version of Spinnaker.

hal config version edit --version $(hal version latest -q)

Set up to persist to GCS

hal config storage gcs edit \
    --project $(gcloud config get-value project) \
    --json-path ~/.gcp/gcp.json

hal config storage edit --type gcs

Set up pulling from GCR

hal config provider docker-registry enable

hal config provider docker-registry account add my-gcr-account \
    --address \
    --password-file ~/.gcp/gcp.json \
    --username _json_key

Set up the Kubernetes provider

hal config provider kubernetes enable

hal config provider kubernetes account add my-k8s-account \
    --docker-registries my-gcr-account \
    --context $(kubectl config current-context)

Part 4: Deploy Spinnaker

hal config deploy edit \
    --account-name my-k8s-account \
    --type distributed

hal deploy apply

If you run into an error that looks something like: Unable to communicate with your Kubernetes cluster: Failure executing: GET at: https://xx.xx.xx.xx/api/v1/namespaces. Message: Forbidden!, check whether you have enabled legacy authorization on your GKE cluster. Navigate to the Google Cloud Console’s GKE section, click on the name of your cluster to see cluster details, and enable legacy authorization if necessary. Then re-run hal deploy apply.

:point_right: Halyard will warn you that you have deployed Spinnaker remotely without configuring an authentication mechanism. This is OK, but cumbersome, since we can connect via SSH tunnels. If you want to configure authentication, read more in the security documentation.

Now, to connect to Spinnaker, run:

hal deploy connect

Finally, from your local workstation browser, navigate to your brand new Spinnaker instance!

Next steps

For more information on halyard and managing Spinnaker, go to the Setup section for an overview of how halyard works, and the Reference section for an exhaustive listing of halyard commands.