Halyard

Halyard is a tool for configuring, installing, and updating Spinnaker.

This is the reference documentation for Halyard, and will go into more detail than is needed to deploy most Spinnaker environments. If you’re a new user looking for instructions for how to use Halyard to deploy Spinnaker, checkout the setup instructions first.

Terminology

Halconfig

The Halconfig is the source of all configuration for your Deployment of Spinnaker. It typically lives in ~/.hal/config, but its directory can be changed with the halyard.halconfig.directory Spring config property.

Deployments

A Deployment within Halyard is a single, deployed/installed & configured Spinnaker. Each deployment has its own set of configuration and running services, and is logically separated from any other Deployment of Spinnaker that Halyard is managing. The deployments are referenced by name, and the default name for your first Deployment is "default".

The intended use-case for Deployments is managing multiple, isolated Spinnakers that need to be kept separate for one reason or another (compliance, network configuration, etc…).

You can switch to/create a new deployment named $DEPLOYMENT by running the following command.

  1. hal config --set-current-deployment $DEPLOYMENT

Artifacts

Artifacts are unconfigured, versioned, prebuilt deployables consumed by Halyard.

For example, the Clouddriver Docker image gcr.io/spinnaker-marketplace/clouddriver:0.2.0-348 is an Artifact, or the Debian Echo package spinnaker-releases/debians/spinnaker-echo=0.2.0-214 is another Artifact.

Profiles

Profiles are configuration files applied to Artifacts to make them run in some desired fashion.

For example, clouddriver-bootstrap.yml and clouddriver.yml are both profiles that are consumed by the Clouddriver Artifact above.

During the deployment process Halyard will stage all generated profiles in ~/.hal-staging/ (configurable via spinnaker.config.staging.directory) before either uploading them to your deployment environment’s secret store, or copying them to the necessary local directories.

A Profile’s name is derived from its path relative to ~/.hal-staging/. For example, the Profile found under ~/.hal-staging/clouddriver.yml has name clouddriver.yml, and the Profile found under ~/.hal-staging/registry/echo.yml has name registry/echo.yml.

Services

Services are the combination of an Artifact, with a set of Profiles that apply to that Artifact. For example, the Artifact

  • gcr.io/spinnaker-marketplace/clouddriver:0.2.0-348

combined with the Profiles

  • clouddriver.yml
  • clouddriver-bootstrap.yml

constructs the spin-clouddriver-bootstrap service.

The associations between Profiles and Services are recorded in ~/.hal/$DEPLOYMENT/history/service-profiles.yml.

Service Settings

Service Settings are runtime properties of Services, such as which address they bind to, or what port they should listen on. Service Settings are ultimately baked into Profiles, but are kept separate since they need to be collectively distributed to each Service, since they describe how each Service discovers the others.

You can see what global Service Settings Halyard has generated for your current Deployment of Spinnaker by reading ~/.hal/$DEPLOYMENT/history/service-settings.yml.

Bill of Materials

Since Spinnaker is composed of several microservices, we need some way to express which versions of each service have been validated together, and provide that set of service versions a top-level version that can be referenced by users installing/deploying Spinnaker. This set of versions is referred to as the Bill of Materials (BOM). Below is an example BOM:

  1. dependencies:
  2.   consul:
  3.     version: 0.7.5
  4.   redis:
  5.     version: 2:2.8.4-2
  6.   vault:
  7.     version: 0.7.0
  8. services:
  9.   clouddriver:
  10.     version: 0.4.0-393
  11.   deck:
  12.     version: 1.2.0-393
  13.   echo:
  14.     version: 0.2.1-393
  15.   fiat:
  16.     version: 0.2.0-393
  17.   front50:
  18.     version: 0.3.1-393
  19.   gate:
  20.     version: 0.4.0-393
  21.   igor:
  22.     version: 0.3.0-393
  23.   monitoring-daemon:
  24.     version: 0.1.0-393
  25.   monitoring-third-party:
  26.     version: 0.1.0-393
  27.   orca:
  28.     version: 0.4.0-393
  29.   rosco:
  30.     version: 0.3.0-393
  31.   spinnaker:
  32.     version: 0.4.0-393
  33. timestamp: '2017-05-26 11:30:46'
  34. version: master-2017-05-26-393

If you’re curious how to deploy Spinnaker yourself using a validated BOM, read more in the deployments section.

Halyards code lives on GitHub at spinnaker/halyard .

Commands

Halyard command reference

Component Sizing

Use Halyard to size your Spinnaker services to meet your usage requirements.

Custom Settings

“While Halyard handles the majority of Spinnaker configuration, there will always be feature flags and properties either too new or niche to be supported by Halyard.”

High Availability
Secrets

Storing Spinnaker configs in a Git repository is a great solution for maintaining versions of your configurations, but storing secrets in plain text is a bad security practice.

Last modified May 4, 2021: rest of migration (700781a)