Skip to content

Latest commit

 

History

History
110 lines (86 loc) · 5.9 KB

adding-a-config-parameter.md

File metadata and controls

110 lines (86 loc) · 5.9 KB

Adding a Configuration Parameter

Before we get started, keep in mind that not all configuration needs to be surfaced in Halyard since Halyard exposes mechanisms for loading custom configuration. However, if you have a flag/parameter that you expect many users will need to modify or overwrite, it's probably a good idea to surface it in Halyard.

There are four steps that need to happen:

  1. Update the halconfig data structure
  2. (Optional) Update the config generation
  3. (Optional) Validate your parameter
  4. Update the CLI

We will be performing these steps alongside an example PR that adds support for the kubernetes.accounts[].omitNamespaces parameter in Clouddriver.

1. Update the halconfig data structure

All parts of the halconfig are stored under the model.v1 package. Find the class that will contain your config changes, and add the parameter as a field.

NOTE: If the parameter refers to a file, annotate it with the @LocalFile annotation as seen for the kubeconfig parameter here. This ensures that the file will be encrypted & mounted on whatever remote cloud provider you deploy Spinnaker to.

In our example PR, we add the List<String> omitNamespaces field to the KubernetesAccount class as shown here.

If the field requires a minimum Spinnaker version, annotate it with ValidForSpinnakerVersion, indicating the first Spinnaker version in which the field is supported as the lowerBound. Optionally, supply a message indicating why the field is unsupported in earlier versions as the tooLowMessage.

2. Update the config generation

The structure of the halconfig should closely mirror that of whatever configuration you intend to generate. Doing so means no transformation/extra work needs to happen when Halyard generates configuration for each Spinnaker component service.

As a result, if your parameter has been added to class that is already correctly generated by Halyard, this step can be skipped. This is the case in our example PR, since the existing config generation for Clouddriver is done here which simply copies all configuration under providers into clouddriver.yml.

In the case where special work needs to be done to add the parameter to the needed profile, take a look at the Gate profile factory which does extra work to generate the allowedOriginsPattern, for example.

3. Validate your parameter

A large part of Halyard is providing certainty that your halconfig will produce a working Spinnaker installation, so it's important that if your parameter can be configured incorrectly Halyard will warn you.

For a description of the validators, check out the account validation section described in this doc.

In our example PR, we want to reject configuration that supplies both namespaces and omitNamespaces, so we add this check to the existing validation.

4. Update the CLI

Lastly, we want to add this parameter to the hal CLI so users can easily modify the parameter without touching their halconfig file directly.

There are many ways to surface parameters in hal, so it's important to keep a few things in mind:

  1. Do as little client-side validation & transformation as possible, it's important to keep the complicated logic within the Halyard daemon (step 3).
  2. If your parameter corresponds to a sensitive data, mark it as a password so it doesn't have to appear on STDIN. See the --password parameter here.
  3. If your parameter is a local file, use the LocalFileConverter so the user can pass relative paths to the CLI and have the daemon understand them. See the --password-file parameter here.
  4. If your parameter is required, mark it as required. See the --address parameter here.
  5. Provide an ample description for your flag to help users troubleshoot.

In our example PR we are supplying a list, so we added some convenience flags (--add-*, --remove-*) to help modify it. See all the changes made to the corresponding edit and add commands.

4.a CLI docs

Every time you run make in the halyard-cli/ directory, the contents of docs/commands.md are updated. Please make sure you check in an up-to-date docs/commands.md file.