Spinnaker Installation

The instructions listed below will help you install an open-source Spinnaker. If you want to install OpsMx Enterprise for Spinnaker (OES), please refer to the following page.


Now that we have the basic idea about Spinnaker, the concepts of Spinnaker and the architecture of Spinnaker, let’s learn how to install and configure Spinnaker to use it in production.

By the end of this chapter, you should be able to:

  • Install Spinnaker

  • Configure Spinnaker


  • A local machine, VM or Docker container to install Halyard. A minimum of 12GB of memory should be available on the system.

  • The Spinnaker will be installed on a Kubernetes cluster. It is recommended to make a minimum of 4 cores and 16GB of RAM available to the cluster.

  • Java 11

Halyard Installation

Halyard, a command-line administration tool, is used to manage the entire lifecycle of Spinnaker deployment. This includes writing and validating the deployment's configuration, updating the deployment, and deploying each Spinnaker microservice. Spinnaker requires Halyard to install, configure, and update Spinnaker for all production-ready deployments.

There are two ways to install a halyard as follow:

  • Locally on Debian/Ubuntu or macOS

  • On Docker

"Install Halyard on Debian/Ubuntu or macOS" or "Install Halyard on Docker" depending on which option you prefer.

Install Halyard on Debian/Ubuntu or macOS

Please note that Halyard will only run on:

  • Ubuntu 14.04, 16.04 or 18.04 (Ubuntu 16.04 requires Spinnaker 1.6.0 or later)

  • Debian 8 or 9

  • macOS (tested on 10.13 High Sierra only)

  1. Download the latest Halyard version:

    • For Debian/Ubuntu:

    curl -O \
    • For macOS:

    curl -O \
  2. After downloading, install the latest version of Halyard:

    sudo bash InstallHalyard.sh
  3. Run the below command to check the status of the installation:

    hal -v

    The above command will display the version of Halyard.

Install Halyard on Docker

  1. Before you start, make sure Docker CE is installed on the machine. Run the following command:

    $ sudo systemctl status docker
  2. Create a local Halyard config directory in your machine using the following command:

    mkdir ~/.hal
  3. Start Halyard in a new Docker container. Use the below command to create the Halyard Docker container, mounting the Halyard config directory:

    docker run -p 8084:8084 -p 9000:9000 \
    --name halyard --rm \
    -v ~/.hal:/home/spinnaker/.hal \
    -it \
  4. Connect to Halyard in a separate shell to run the specific micro-services using the command below:

    docker exec -it halyard bash
  5. Run the command below to enable command completion:

    source <(hal --print-bash-completion)
  6. To check the status of the installation run the following command:

    $ sudo docker stats

Configuring Cloud Service Providers

Cloud Platforms and Spinnaker Accounts

The next step is to select and configure the cloud platforms where you want to deploy the applications. Supported providers are:

  • App Engine

  • Amazon Web Services

  • Azure

  • Cloud Foundry

  • DC/OS

  • Google Compute Engine

  • Kubernetes

  • Oracle

You'll also need to register for cloud platform credentials. These credentials are called accounts in Spinnaker. Spinnaker uses the accounts to deploy the applications. To work with Spinnaker, enable at least one cloud platform and add at least one account. Adding an account instructions can be found later in this chapter (Choosing the Environment > Distributed Installations).

Choosing the Environment

Where Should Spinnaker be Installed?

Now it is time to configure the environment in which Spinnaker will be installed. In this step, you tell Halyard the environment where you want to install Spinnaker. The three distinct environments are as follows:

Distributed installation on Kubernetes: Halyard deploys each of Spinnaker's microservices separately in this environment. Highly recommend this for use in production.

Local installations of Debian packages: This type of installation is best for small Spinnaker deployments. Spinnaker is currently hosted on a single machine, but it will be unavailable once it is updated. For more details click here.

Local Git installations from Github: You can also install the Local Git from GitHub.This is suggested if you want to contribute to Spinnaker. For more details click here.

Distributed Installations:

Distributed installations are useful for organizations with huge resource footprints, and they can’t afford downtime while Spinnaker is updating.

You must first set up the cloud provider for the environment. We'll use Kubernetes in this example. After that, you'll need to add a Spinnaker account, as previously mentioned.

Configure Kubernetes


  • A kubeconfig file: The kubeconfig file authenticates Spinnaker against the cluster. After authentication, read/write access to the resources is granted.

  • kubectl CLI tool: Spinnaker depends on kubectl to manage all API access. Along with Spinnaker, it's installed.

Adding an Account

A Spinnaker account always maps to the credential that authenticates the Kubernetes cluster.

Follow the steps below to add an account:

  1. First, enable the provider using the command below:

    hal config provider kubernetes enable
  2. Add the account using the command below:

    CONTEXT=$(kubectl config current-context)
    hal config provider kubernetes account add my-k8s-account \
        --context $CONTEXT

Follow the steps below after you've configured Kubernetes:

  1. Use the $Account name created while configuring the provider and run the command below:

    hal config deploy edit --type distributed --account-name \ $ACCOUNT
  2. Update the $PATH to make sure Halyard can find it. If Halyard was already running, restart it to pick up the new $PATH:

    hal shutdown

Local Debian

In this type of installation, Spinnaker is downloaded and run on the single machine where Halyard is installed.

  • At least four cores and 16GB of RAM are recommended.

  • Local Debian installation requires Ubuntu 14.04 or 16.04

Required Halyard invocations

Halyard is, by default, installed to a local Debian when first run. So, no changes are required from your end.If Halyard's deployment type has been changed and you want to go back to a local installation, run the command below.

hal config deploy edit --type localdebian

Intended use case:

The Local Debian installation is intended for smaller Spinnaker deployments and clouds where the Distributed installation is not yet supported; however, since all services are on a single machine, there will be downtime when Halyard updates Spinnaker.

Note that a Halyard Docker installation cannot be used as a Local Debian base image because it does not contain the necessary packages to run Spinnaker

Local Git

The Local Git installation means Spinnaker will be cloned, built, and run on the same single machine Halyard is run on.


  • At least four cores and 16GB of RAM are recommended.

Install local dependencies

Make sure you have the following software installed on your computer:


  • git: sudo apt-get install git

  • curl: sudo apt-get install curl

  • netcat: sudo apt-get install netcat

  • redis-server: sudo apt-get install redis-server

OpenJDK 8 - JDK (we’re building from source, so a JRE is not sufficient)

sudo add-apt-repository ppa:openjdk-r/ppa
sudo apt-get update
sudo apt-get install openjdk-8-jdk

node (version >=12.16.0, can be installed via nvm , summarized below)

curl -o- 
https://raw.githubusercontent.com/creationix/nvm/v0.34.0/install.sh | bash
# Follow instructions at end of script to add nvm to ~/.bash_rc
nvm install v12.16.0
  • yarn: npm install -g yarn or guide


brew (a package manager for MacOS, can be installed via here , summarized below)

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  • git: brew install git

  • curl: brew install curl

  • netcat: brew install netcat

  • redis-server:

    • Install: brew install redis

    • Start: brew services start redis

OpenJDK 8 - JDK (we’re building from source, so a JRE is not sufficient)

brew cask install adoptopenjdk/openjdk/adoptopenjdk8

node (version >=12.16.0, can be installed via nvm , summarized below)

curl -o- 
https://raw.githubusercontent.com/creationix/nvm/v0.34.0/install.sh | bash
# Follow instructions at end of script to add nvm to ~/.bash_rc

nvm install v12.16.0
  • yarn: npm install -g yarn or guide

Fork all Spinnaker repos

Fork all of the microservices listed here: Spinnaker Microservices on github ( guide ).

Setup SSH keys

Follow these guides to setup SSH access to your github.com account from your local machine:

  • Generating a new ssh key and adding it to your ssh agent

  • Adding a new ssh key to your Github account. Refer Here.

Required Halyard invocations

Halyard defaults to a Local Debian install when first run. If you will be contributing code to the Spinnaker project, you can change your deployment type to Local Git type and set up your development environment with the latest code.

hal config deploy edit --type localgit --git-origin-user=<YOUR_GITHUB_USERNAME
hal config version edit --version branch:upstream/master

Intended use case

The Local Git installation is intended for developers who want to contribute to Spinnaker. It is not intended to be used to manage any production environment.

For a short guide to getting up and running with developing Spinnaker, see the developer setup guide.

NOTE: Be sure to use the same username here that you forked the Spinnaker repository.

Configure the Storage Service

Supported Storage Providers

Spinnaker requires an external storage provider to keep track of application settings and configured pipelines. Since this type of data is extremely sensitive and precious if lost, it is recommended that you use a trusted hosted storage solution.

The storage provider will not affect the cloud provider. For example, use Google Cloud Storage as a storage source but deploy to Microsoft Azure. The following storage providers are supported:

  • Azure Storage

  • Google Cloud Storage

  • Minio

  • Redis

  • S3

  • Oracle Object Storage

Deploy Spinnaker and Connect UI

Now you can select a Spinnaker version, start deploying it, and connect to it once it's finished.

Let’s select a Spinnaker version and deploy it.

  1. To view the list of available versions, run the command below:

    hal version list
  2. To set the version, run the command below:

    hal config version edit --version $VERSION
  3. Run the command below to deploy Spinnaker:

    hal deploy apply

    Once Spinnaker is deployed you can now connect to the Spinnaker UI.

  4. Run the command below:

    hal deploy connect
  5. Navigate to localhost:9000.

Last updated