Spinnaker – Reference

Docs: Spinnaker Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Docs: API

Mon, 01 Jan 0001 00:00:00 +0000

Docs: Halyard

Mon, 01 Jan 0001 00:00:00 +0000

HALYARD IS DEPRECATED

[!IMPORTANT] At this time, halyard is considered deprecated and no longer supported.
This document is kept here and alive for historical purposes. Documentation should all be moved to native configuration files, and for more questions and information please join the spinnaker slack.

Legacy Documentation

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.

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:

dependencies:
  consul:
    version: 0.7.5
  redis:
    version: 2:2.8.4-2
  vault:
    version: 0.7.0
services:
  clouddriver:
    version: 0.4.0-393
  deck:
    version: 1.2.0-393
  echo:
    version: 0.2.1-393
  fiat:
    version: 0.2.0-393
  front50:
    version: 0.3.1-393
  gate:
    version: 0.4.0-393
  igor:
    version: 0.3.0-393
  monitoring-daemon:
    version: 0.1.0-393
  monitoring-third-party:
    version: 0.1.0-393
  orca:
    version: 0.4.0-393
  rosco:
    version: 0.3.0-393
  spinnaker:
    version: 0.4.0-393
timestamp: '2017-05-26 11:30:46'
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.

Links

Halyards code lives on GitHub at spinnaker/halyard .

Docs: Monitoring

Mon, 01 Jan 0001 00:00:00 +0000

If you’re looking on instructions for how to install or setup monitoring, checkout the Enable Monitoring section in the Spinnaker Setup Guide .

The /spectator/metrics JSON format documented here describes Spinnaker’s Spectator/Micrometer metric data model. For the recommended way to collect metrics and traces with OpenTelemetry, see OpenTelemetry (Recommended) in the setup guide.

Metrics overview

A Spinnaker metric is a named collection of measurements used to track a type of activity over time. There are two basic types of metrics: counters and gauges. A counter measures how many times the activity occured over the lifetime of the process (e.g. how many actions have ever occurred) whereas a gauge measures an instantaneous value (e.g. how many actions are active now).

Each recorded measurement has a set of tags and a timestamped value. The tags are used to capture the context or aspect of the value. For example, each Spinnaker microservice uses a single counter metric (“controller.invocations”) to monitor how many HTTP calls it handled. Since the microservices have many different HTTP endpoints, they add a tag (“method”) to the measurement indicating which was called. Internally the endpoints are grouped together for different types that are managed by a particular controller, so the measurements are also tagged with a “controller” tag.

Operationally, you want to be able to distinguish successful calls from failures in order to detect problems that might come up. Rather than creating different metrics for each type of failure or success (or failure vs success), the measurements are tagged with a “success” tag as well as a “statusCode” tag. The end result is that there is just a single metric “controller.invocations”, but the measurements within it are richly decorated with details so that individual metrics can be filtered to view a much finer granularity.

In essence, the sequence of timestamped measurements for a Spinnaker metric can be partitioned by their tag bindings so that all the measurements for the same set of tag bindings form their own sequence (e.g. all the successful calls to the “list” method vs all the failed calls to the “list” method vs all the failed calls to the “get” method). The monitoring systems will typically treat each of these as their own time-series and allow you to filter by some tags, then aggregate by or break out by each of the others so that you can view the measurements at the abstraction and granularity that makes sense for what your interest is (e.g. global failures, attempted modifications to a particular resource type, etc).

Here is an example of the metric controller.invocations in Front50.

"tags": [
    {
        "key": "application",
        "value": "mysnazzyapp"
    },
    {
        "key": "controller",
        "value": "PipelineController"
    },
    {
        "key": "method",
        "value": "listByApplication"
    },
    {
        "key": "statistic",
        "value": "count"
    },
    {
        "key": "status",
        "value": "2xx"
    },
    {
        "key": "statusCode",
        "value": "200"
    },
    {
        "key": "success",
        "value": "true"
    }
],
"values": [
    {
        "t": 1500000000000,
        "v": 100.0
    }
]

The interpretation of this is that as of time t=1500000000000 (milliseconds since unix epoch), there were v=100 calls to the listByApplication method of the pipeline controller, where the application was mysnazzyapp and resulted in a HTTP 200 status code. While there are some patterns to tags, there are no actual standards suggesting how to interpret these.

As noted above, monitoring will typically aggregate many of these time-series together in practice allowing you to choose the level of granularity depending on what you are interested in paying attention to at any given point in time. Since the data is collected very granular, you can go back in time and dig into the details should you need to diagnose or compare them later.

Note that the values are for the lifetime of this particular process instance, and only this instance. Each repilca has its own count, and the counts are reset each time the process restarts. It is up to the backing monitoring service to aggregate these counts across replicas.

JSON document format

Metrics are returned in the following format:

Top-level document

Key	Format	Description
applicationName	string	The name of the microservice.
applicationVersion	string	The version number of the microservice.
metrics	See Metric Entry	The individual metric entries.
startTime	int	Unix epoch time milliseconds that process started.

Metric entry

The metrics dictionary contains an entry for each reported metric name. The dictionary key is the name of the metric. The entry contains the data for the metric.

Key	Format	Description
kind	String	The type of metric. `Counter` is a numeric monotonically increasing numeric counter. `Gauge` is an instantaneous numeric value. `Timer` is a nanosecond counter.
values	List of Time-Series Data Point	A metric will have one or more time-series associated with it. The current value for each of these is in this list.

Time-series data point

Key	Format	Description
tags	List of Tag Bindings	A tag-binding is a `key`, `value` pair expressed as a dictionary with two entries; `key` and `value`. Each of these has a string value. The value of the `key` is the name of the tag. The value of the `value` is the value for the tag. For example, `{"key": "success", "value": "true"}` is associating the tag `success=true` to the time-series. In practice, each time-series usually has several different tags (i.e. the context used to tag a metric, has multiple dimensions to it, each of which described by a different tag).
values	List of Timestamped Value	In practice this is a list of one element, which is only the most current value. The element is a dictionary with two keys. `v` for the value, which is a real, even for scalar values, and `t` for the timestamp as milliseconds since the Unix epoch.

Docs: Providers

Mon, 01 Jan 0001 00:00:00 +0000

To setup a cloud provider, see Cloud Provider .

Supported providers

These are the Cloud Providers currently supported by Spinnaker:

Note: The OpenStack provider was supported for a period of time, but after several releases without support this RFC concluded with the removal of the provider from Spinnaker. If you are interested in adding this provider back in and supporting it we would be more than happy to help revert the removal.

Docs: Secrets

Mon, 01 Jan 0001 00:00:00 +0000

Spinnaker supports separating your secrets from your configs through end-to-end secrets management. Simply replace secrets in your config files with the syntax described here, and Spinnaker decrypts them as needed at start time.

Secret Format

To reference secrets in configs, use the following general format for secret literal values, like passwords and tokens:

encrypted:<secret engine>!<key1>:<value1>!<key2>:<value2>!...

To reference secret files like kubeconfig files the syntax is:

encryptedFile:<secret engine>!<key1>:<value1>!<key2>:<value2>!...

The key-value parameters making up the string vary with each secret engine. Refer to the specific documentation for each engine for more information.

For instance, if you replace the GitHub token in your config with an encrypted syntax:

...
  github:
    enabled: true
    accounts:
    - name: github
      token: encrypted:<secret engine>!<key1>:<value1>!<key2>:<value2>!...
...

Spinnaker will read these secrets at start time.

Supported Secret Engines

The secrets framework is extensible and support for new engines can easily be added. Currently the following is supported:

Google Secrets manager is also supported though not at this time documented. You can see the code and translate it to a supported format.

Docs: What is a Spinnaker Artifact?

Mon, 01 Jan 0001 00:00:00 +0000

A Spinnaker artifact is a named JSON object that refers to an external resource.

Spinnaker supports a wide range of providers. An artifact can reference any of many different external resources, such as…

a Docker image
a file stored in GitHub
an Amazon Machine Image (AMI)
a binary blob in Amazon S3, Google Cloud Storage, etc.

Each of these could be fetched using a URI and used within a pipeline, but a URI alone can omit other important information about the resource. You may wish to also fetch provenance information such as the commit that triggered the resource’s build, or to store information about the account that has permission to download the resource.

To incorporate metadata such as this along with the resource’s URI, Spinnaker artifacts follow a particular specification that includes the human-readable name of the artifact, its URI, and any other applicable metadata. This is called “artifact decoration”. Every Spinnaker artifact–whether supplied to a pipeline, accessed within a pipeline, or produced by a pipeline–follows this specification.

Keep in mind that the artifact in Spinnaker is a reference to an external resource–it is not the resource itself. The resource itself could be of any type supported by Spinnaker; the artifact is the named JSON object that contains information about the resource.

The artifact format

As an example, an object stored in Google Cloud Storage (GCS) might be accessed using the following Spinnaker artifact:

{
  "type": "gcs/object",
  "reference": "gs://bucket/file.json#135028134000",
  "name": "gs://bucket/file.json",
  "version": "135028134000"
  "location": "us-central1"
}

As another example, a Docker image might be accessed using the following artifact:

{
  "type": "docker/image",
  "reference": "gcr.io/project/image@sha256:29fee8e284",
  "name": "gcr.io/project/image",
  "version": "sha256:29fee8e284"
}

The fields that make up a Spinnaker artifact are described below.

Field	Explanation	Notes
`type`	How the external resource is classified. (This allows for easy distinction between Docker images and Debian packages, for example).
`reference`	The URI used to fetch the resource.
`artifactAccount`	The Spinnaker artifact account that has permission to fetch the resource.
`version`	The version of the resource. (By convention, `version` should only be compared between artifacts of the same `type` and `name`.)	Optional.
`provenance`	The relevant URI from the system that produced the resource. (This is used for deep-linking into other systems from Spinnaker.)	Optional.
`metadata`	Arbitrary key / value metadata pertaining to the resource. (This can be useful for scripting within pipeline stages.)	Optional.
`location`	The region, zone, or namespace of the resource. (This does not add information to the URI, but makes multi-regional deployments easier to configure.)	Optional.
`uuid`	Used for tracing the artifact within Spinnaker.	Assigned by Spinnaker.

Expected artifacts

Within a pipeline trigger or stage, you can declare that the trigger or stage expects a particular artifact to be available. This artifact is called an expected artifact. Spinnaker compares an incoming artifact (for example, a manifest file stored in GitHub) to the expected artifact (for example, a manifest with the file path path/to/my/manifest.yml); if the incoming artifact matches the specified expected artifact, the incoming artifact is bound to that expected artifact and used by the trigger or stage.

Match artifact

When declaring an expected artifact for a trigger, you can use fields under Match Artifact to specify metadata against which to compare the incoming artifact. This is how you can distinguish between similar artifacts coming from the same artifact account (for example, multiple manifest files stored in a single Git repository) and specify that the trigger should begin pipeline execution only if the incoming artifact matches the parameters that you provided.

Prior execution and default artifact

In the fields under If Missing, you can provide fallback behavior for the expected artifact in case the trigger doesn’t find the desired artifact. If you enable the Use prior execution checkbox, Spinnaker will fall back to the artifact used in the last execution. If you enable the Use default artifact checkbox, Spinnaker will use a default artifact, which you can specify in the form (this allows you to provide fallback behavior for the first time a trigger is used, when there is no previous execution yet).

Enabling artifact support

Clouddriver currently handles artifact fetches and processing and caching. Enable artifacts by setting up the appropriate artifact type . You can enable artifact handling in clouddriver by adding the following config:

artifacts:
  enabled: true

Old docs and references

These pages refer to the newer Artifacts UI. For information about the legacy Artifacts UI, see this page .

Docs: Spinnaker Artifacts - Legacy UI

Mon, 01 Jan 0001 00:00:00 +0000

This section refers to the legacy artifacts UI, which was removed in release 1.21. Please refer to the standard artifacts guide instead.

In Spinnaker, an artifact is an object that references an external resource. That resource could be…

a Docker image
a file stored in GitHub
an Amazon Machine Image (AMI)
a binary blob in S3, GCS, etc.

Any of these can be fetched using a URI , and can be used within a Spinnaker pipeline.

However, a URI alone isn’t always enough. Take the following examples:

You have a “Bake Image” stage that defines which packages are to be consumed, which images are deployed into each environment, and which configuration files are mounted. If each of these artifact types is just a URI, you have to write (and maintain) RegEx (or similar) against URIs to match artifacts to stages.
Your build system produces provenance information about your Docker images (for example, which commit triggered the build, which build steps were used). This isn’t easy to store in or retrieve from the Docker image, but you want to trigger the pipeline on the arrival of a new image. If all you capture is the URI (for example, gcr.io/your-project/your-image:v1.0.0) you lose that provenance information.
Your Spinnaker instance is used by many teams in your organization, and your authorization policies isolate teams' infrastructure and pipelines from each other. You probably want your packages, configs, and images published and accessible only by the teams that need them. You need a way to annotate a URI with an account that can fetch it based on a user’s permissions.

To address situations like these, Spinnaker includes a format for supplying URIs alongside pertinent metadata. We call this “artifact decoration”.

Decorate your artifacts

In Spinnaker, artifacts must match a specification. This specification is consistent among all artifacts, whether they’re supplied to pipelines, accessed within pipelines, or produced by pipelines.

Every time we refer to an Artifact, we mean a JSON payload matching this specification, not the actual artifact contents. The key distinction is that the artifact is a reference or a pointer to a resource, not the resource itself.

Format

{
  "type":       // How this artifact is classified. Allows for easy distinction
                // between docker images and debian packages, for example.

  "reference":  // The URI.

  "artifactAccount": // The account configured within Spinnaker that has
                // permission to download this resource.

  "name":       // (Optional) A human-readable name that makes matching
                // artifacts simpler.

  "version":    // (Optional) The version of this artifact. By convention, the
                // "version" should be compared against other artifacts with
                // the same "type" and "name".

  "provenance": // (Optional) A link to whatever produced this artifact. This
                // is used for deep-linking into other systems from Spinnaker.

  "metadata":   // (Optional) Arbitrary k/v metadata useful for scripting
                // within stages.

  "location":   // (Optional) The region/zone/namespace this artifact can be
                // found in. This doesn't add information to the URI, but makes
                // multi-regional deployments easier to configure.

  "uuid":       // (Assigned by Spinnaker) Used for tracing artifacts within
                // Spinnaker.
}

Examples

// A docker image
{
  "type": "docker/image",
  "reference": "gcr.io/project/image@sha256:29fee8e284",
  "name": "gcr.io/project/image",
  "version": "sha256:29fee8e284"
}

// A GCS object
{
  "type": "gcs/object",
  "reference": "gs://bucket/file.json#135028134000",
  "name": "gs://bucket/file.json",
  "version": "135028134000"
  "location": "us-central1"
}

// An S3 object
{
  "type": "s3/object",
  "name": "s3://bucket/file.json",
  "location": "us-east-1"
}

Example for providing artifacts with `spin` CLI

When you execute a pipeline with the <code>spin</code> CLI , the -t, --artifacts-file option expects a valid JSON file containing a top-level artifacts key that maps to an array of artifact definitions as mentioned here . For example, you can call…

spin pipeline execute --application ${APPLICATION} --name ${PIPELINE} --parameter-file ${PARAMETER_FILE_PATH} --artifacts-file ${ARTIFACTS_FILE_PATH}

…with the contents of the file at ${ARTIFACTS_FILE_PATH} as follows:

{
  "artifacts" : [
    {
      "type": "s3/object",
      "name": "s3://bucket/file.json",
      "location": "us-east-1"
    },
    {
      "type": "s3/object",
      "name": "s3://bucket/file2.json",
      "location": "us-east-1"
    }
  ]
}

Docs: Spinnaker Pipeline Reference

Mon, 01 Jan 0001 00:00:00 +0000

Spinnaker – Reference

Docs: Spinnaker Architecture

Docs: API

Docs: Halyard

HALYARD IS DEPRECATED

Legacy Documentation

Terminology

Halconfig

Deployments

Artifacts

Profiles

Services

Service Settings

Bill of Materials

Links

Docs: Monitoring

Metrics overview

JSON document format

Top-level document

Metric entry

Time-series data point

Docs: Providers

Supported providers

Docs: Secrets

Secret Format

Supported Secret Engines

Docs: What is a Spinnaker Artifact?

The artifact format

Expected artifacts

Match artifact

Prior execution and default artifact

Enabling artifact support

Old docs and references

Docs: Spinnaker Artifacts - Legacy UI

Decorate your artifacts

Format

Examples

Example for providing artifacts with spin CLI

Docs: Spinnaker Pipeline Reference

Example for providing artifacts with `spin` CLI