Install Halyard

Halyard is a command-line administration tool that manages the lifecycle of your Spinnaker deployment, including writing & validating your deployment’s configuration, deploying each of Spinnaker’s microservices, and updating the deployment.

All production-capable deployments of Spinnaker require Halyard in order to install, configure, and update Spinnaker. Though it’s possible to install Spinnaker without Halyard, we don’t recommend it, and if you get stuck we’re just going to tell you to use Halyard.

There are two ways you can install Halyard:

• locally on Debian/Ubuntu or macOS

  This can be on a desktop or laptop computer, or on a VM.

• on Docker

We recommend you install Halyard on a machine with at least 12GB of RAM.

Note: If you need to run Halyard without access to public internet, read Deploy Custom Spinnaker Builds .

Install on Debian/Ubuntu and macOS

Halyard runs 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. Get the latest version of Halyard:

   For Debian/Ubuntu:

   curl -O https://raw.githubusercontent.com/spinnaker/halyard/master/install/debian/InstallHalyard.sh

   For macOS:

   curl -O https://raw.githubusercontent.com/spinnaker/halyard/master/install/macos/InstallHalyard.sh

2. Install it:

   sudo bash InstallHalyard.sh

   If you’re prompted for any information, default answers are usually suitable.

3. Check whether Halyard was installed properly:

   hal -v

   If this command fails, make sure hal is in your $PATH, and check the logs under /var/log/spinnaker/halyard/halyard.log.

4. Run . ~/.bashrc to enable command completion.

To get help with any hal command, append -h. Also, see the Halyard command Reference .

Update Halyard on Debian/Ubuntu or macOS

sudo update-halyard

Uninstall Halyard from Debian/Ubuntu or macOS

Important: uninstalling Halyard deletes the entire contents of your ~/.hal directory. Don’t do it unless you’re prepared to lose your configuration.

1. If you used Halyard to deploy Spinnaker, and you want to purge that deployment, run the following command:

   hal deploy clean

2. Now you can safely uninstall Halyard:

   sudo ~/.hal/uninstall.sh

Install Halyard on Docker

Note: If you install Halyard in a Docker container, you will need to manually change permissions on the mounted ~/.hal directory to ensure Halyard can read and write to it.

1. Make sure you have Docker CE installed .

2. On your current machine, make a local Halyard config directory.

   mkdir ~/.hal

   This will persist between runs of the Halyard docker container.

3. Start Halyard in a new Docker container.

   The following command creates 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 \
       us-docker.pkg.dev/spinnaker-community/docker/halyard:stable

   This runs as a foreground process in your current shell. This is useful because it emits all of the Halyard daemon’s logs, which are not persisted. If you don’t care about the logs, and would rather run in detached mode, replace the -it with -d

   Note: Any secrets/config you need to supply to the daemon (for example, a kubeconfig file) must be mounted in either your local ~/.hal directory, or another directory that you supply to docker run with additional -v command-line options.

4. In a separate shell, connect to Halyard:

   docker exec -it halyard bash

   You can interact with Halyard from here.

5. Run the following command to enable command completion:

   source <(hal --print-bash-completion)

To get help with any hal command, append -h. Also, see the Halyard command Reference .

Update Halyard on Docker

1. Fetch the latest Halyard version.

   docker pull us-docker.pkg.dev/spinnaker-community/docker/halyard:stable

2. Stop the running Halyard container.

   docker stop halyard

3. Re-run the container:

   docker run -p 8084:8084 -p 9000:9000 \
       --name halyard --rm \
       -v ~/.hal:/home/spinnaker/.hal \
       -it \
       us-docker.pkg.dev/spinnaker-community/docker/halyard:stable

   This re-starts the container using the updated image you got in step 1.

4. In a separate shell, run:

   docker exec -it halyard bash

Uninstall Halyard from Docker

To uninstall Halyard, just delete the container.

docker rm halyard

Next steps

Now that Halyard is running, it’s time to choose your cloud provider .

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