Spinnaker – User Guides

Docs: Get Started Using Spinnaker

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

This article assumes you are new to Spinnaker. It contains basic information about what to do after Spinnaker is installed .

Before you get going…

Whether you’re an operator or admin installing or managing Spinnaker or an end user getting started using Spinnaker, here are some pointers to get you started.

Operators (managing Spinnaker)

If you want to install Spinnaker, see the instructions here .
If you want to find out more about tuning and maintaining Spinnaker, here are some things to check out:
- Advanced configuration
- Productionize Spinnaker

Users (deploying with Spinnaker)

If you want to try out Spinnaker, please read the installation guide
If Spinnaker is already installed in your organization, and you want to practice it using some guided tutorials, here are codelabs .
If you want a basic overview of how to use Spinnaker, the high-level process is described below.

Using Spinnaker: the high-level process

Create an application

Typically, you’ll have one application per microservice.

Note: Your application configuration affects what you can do with Spinnaker—you can enable or disable some Spinnaker features.
Define the infrastructure the service will run on

You define infrastructure for each application. Your pipelines deploy services to the server groups you define.

Note: This step is not a prerequisite for creating pipelines. In fact, you can use pipelines to create infrastructure.
Create a pipeline

Create all the pipelines you need to deploy the service or services covered by the application, in whatever ways you want to deploy.

Learn more in the Managing pipelines guide .
Run your pipeline to deploy your service

You can run a pipeline manually, but most pipelines are triggered automatically .
For practice, and to see some sample deployment scenarios, check out our codelabs .

Docs: Application User Guide

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

An application in Spinnaker is a construct that represents some service that you are going to deploy (typically a microservice). It includes:

the pipelines that process the service through to deployment in production
the infrastructure on which the service is run:
- clusters
- server groups
- firewalls
- load balancers
canary configs

Important note about applications

When you first access a new instance of Spinnaker, you might notice that there are already several applications visible when you click the Applications tab. This happens if you install Spinnaker on an existing Kubernetes cluster, using the Kubernetes provider . These applications are derived from existing infrastructure.

Don’t delete any of them.

Also, don’t use any of them as applications in which to create pipelines or add further infrastructure. Instead, create new applications for your deployment pipelines.

What distinguishes one application from another?

By common practice, one application contains all of the above components for one microservice.

There is nothing in Spinnaker that enforces the level at which you divide up your services into applications, but it would be messy to put too much into one application, dealing not only with all the containers to bake, canary configs to manage, and so on, but also all the infrastructure.

For different reasons, you also don’t want to segregate different environments (dev, staging, prod) into different applications. In many cases you will have pipelines, which deploy into one environment, eventually trigger other pipelines that promote the same service into the next environment.

Create An Application

Docs: Using Spinnaker for Automated Canary Analysis

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

Docs: General Purpose Tagging Guide

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

This guide provides an introduction to the provider-agnostic tagging capabilities of Spinnaker, otherwise referred to as Entity Tags.

Requirements

This is an optional feature of Spinnaker that requires

Elasticsearch (tested with 6.8.2)
Front50 (backed by SQL, S3 or GCS)

See configuration for specific configuration details.

Overview

Spinnaker provides a provider-agnostic way of attaching additional attributes (key/value pairs) to any managed entity.

Managed Entities

Any object that is maintained (or visualized) by Spinnaker.

Includes (but is not limited to):

Applications

Server Groups

Load Balancers

Instances

Clusters

There are no restrictions on the size or quantity of these tags (unlike limitations imposed by native cloud provider tags).

Current limitations

Completely separate from any tag support on the underlying cloud provider
- Callers must make an additional API call to retrieve entity tags
Limited lifecycle support
- Only server groups have a delete hook that will cleanup associated tags

These limitations will be addressed on an as needed basis.

If they are blocking a particular use-case, please file an issue .

Common use cases

Server Group Alerts and Notices
Server Group Attribution (what pipeline / user created this server group)
Security (restricting when particular IAM roles can be used)

Tag namespaces

All tags have an associated namespace (default will be used if unspecified) that provides a means of grouping tags by a logical owner.

Tag names can be re-used across namespaces.

Eventually Spinnaker will allow permissions to be defined per-namespace (ie. certain namespaces can only be modified by particular users or groups).

Implementation details

These provider-agnostic tags are stored in S3 or GCS (via Front50) and indexed via Elasticsearch.

They are made up of:

An Identifier
An EntityRef
1..* Tags (key/value pairs with the value being either a literal or object)
1..* Tag Metadata (last modified timestamps per tag)

Identifier

A unique identifier representing a tagged entity: {cloudProvider}:{entityType}:{entityId}:{accountId}:{region}

EntityRef

cloudProvider The identifier of the cloud provider associated with this entity accountId The identifier of the account associated with this entity (supports * wildcard) region The identifier of the region associated with this entity (supports * wildcard) entityType The type of entity being tagged entityId The identifier of the entity being tagged application The identifier of the application associated with this entity

Supported Entity Types

Spinnaker has native support for the following:

application

servergroup

iamrole

tags structure

    {
      "id": "aws:servergroup:myservergroup-v001:100000000001:us-west-2",
      "tags": [
        {
          "name": "spinnaker_ui_alert:autoscaling:ec2_instance_launch_error",
          "namespace": "my_namespace",
          "value": {
            "message": "Insufficient capacity. Launching EC2 instance failed.",
            "type": "alert"
          },
          "valueType": "object"
        }
      ],
      "tagsMetadata": [
        {
          "name": "spinnaker_ui_alert:autoscaling:ec2_instance_launch_error",
          "lastModified": 1484162291500,
          "lastModifiedBy": "unknown",
          "created": 1484161809699,
          "createdBy": "unknown"
        }
      ],
      "entityRef": {
        "cloudProvider": "aws",
        "accountId": "100000000001",
        "region": "us-west-2",
        "entityType": "servergroup",
        "entityId": "myservergroup-v001",
        "application": "app"
      }
    }

API

The following APIs are exposed in gate but are subject to change given the current release candidate status.

GET /tags

Fetch all tags. Parameters are case-sensitive.

Parameter Name	Description	Examples
entityType	Filter by Entity Type	?entityType=servergroup
entityId	Filter by Entity Id	?entityId=myservergroup-v001
application	Filter by Application	?application=app
tag	Filter by Tag (specific value) Filter by Tag (any value)	?tag:my_tag=my_value ?tag:my_tag=*
maxResults	Maximum # of results to return (defaults to 100)	?maxResults=1000

POST /tags

Parameter Name	Description	Examples
entityType	Entity Type	?entityType=servergroup
entityId	Entity Id	?entityId=myservergroup-v001
application	application	?application=app
account	Account Name	?account=production ?account=* (wildcard)
region	Region	?region=us-west-2 ?region=* (wildcard)
cloudProvider	cloudProvider	?cloudProvider=aws ?cloudProvider=* (wildcard)

Upsert tags

    curl -X "POST" "http://gate/tags?entityId=myservergroup-v001&entityType=servergroup&account=production&region=us-west-2&cloudProvider=aws&application=app" \
         -H "Content-Type: application/json" \
         -d $'[
      {
        "name": "spinnaker_ui_alert:autoscaling:ec2_instance_launch_error",
        "namespace": "my_namespace",
        "value": {
          "message": "Insufficient capacity. Launching EC2 instance failed.",
          "type": "alert"
        },
        "valueType": "object"
      }
    ]'

POST /tasks

This API provides backwards compatibility with traditional Spinnaker tasks and can be used interchangeably with the POST /tags API.

Upsert tags

    curl -X "POST" "http://gate/tasks" \
         -H "Content-Type: application/json" \
         -d $'{
      "application": "spinnaker",
      "job": [
        {
          "type": "upsertEntityTags",
          "tags": [
            {
              "name": "spinnaker_ui_alert:autoscaling:ec2_instance_launch_error",
              "namespace": "my_namespace",
              "value": {
                "message": "Insufficient capacity. Launching EC2 instance failed.",
                "type": "alert"
              },
              "valueType": "object"
            }
          ],
          "entityRef": {
            "cloudProvider": "aws",
            "entityType": "servergroup",
            "entityId": "myservergroup-v001",
            "region": "us-west-2",
            "account": "production",
            "application": "app"            
          }
        }
      ],
      "description": "Updating tags"
    }'

DELETE /tags/:id/:tagName

Delete tags

    curl -X "DELETE" "http://gate/tags/myservergroup-v001:100000000001:us-west-2/spinnaker_ui_alert:autoscaling:ec2_instance_launch_error" \
         -H "Content-Type: application/json" \
         -d $'{}'

FEATURE: Server group alerts and notices

Server Group Alerts and Notices is a Spinnaker feature is built upon entity tags.

Add alert

    curl -X "POST" "http://gate/tags?entityId=spintest-v003&entityType=servergroup&account=test&region=us-west-2&cloudProvider=aws&application=app" \
         -H "Content-Type: application/json" \
         -d $'[
      {
        "name": "spinnaker_ui_alert:autoscaling:ec2_instance_launch_error",
        "namespace": "my_namespace",
        "value": {
          "message": "You have exceeded the number of VPC security groups allowed per instance. Launching EC2 instance failed.",
          "type": "alert"
        },
        "valueType": "object"
      }
    ]'

Add notice

    curl -X "POST" "http://gate/tags?entityId=spintest-v003&entityType=servergroup&account=test&region=us-west-2&cloudProvider=aws&application=app" \
         -H "Content-Type: application/json" \
         -d $'[
      {
        "name": "spinnaker_ui_notice:my_favorite_notice",
        "namespace": "my_namespace",
        "value": {
          "message": "This is an example notice!",
          "type": "notice"
        },
        "valueType": "object"
      }
    ]'

Delete alert (or notice)

    curl -X "DELETE" "http://gate/tags/aws:servergroup:spintest-v003:100000000001:us-west-2/spinnaker_ui_alert:autoscaling:ec2_instance_launch_error" \
         -H "Content-Type: application/json" \
         -d $'{}'

Configuration

The following configuration changes are necessary to enable entity tags on your Spinnaker installation:

clouddriver-local.yml

elasticSearch:
  activeIndex: "tags_v2"
  connection: http://my-elastic-search-cluster:port

deck/settings-local.js

window.spinnakerSettings.entityTags = {};
window.spinnakerSettings.feature.entityTags=true;

elasticsearch index template

Make a POST request to http://my-elastic-search-cluster:port/_template with this template template

Docs: Customizing Instance Links

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

Spinnaker makes it easy to give users links to common features of their applications (logs, health, etc.), which are accessible from the instance details panel:

There are two basic approaches to customizing links: organization-wide links (links that apply to every instance managed by Spinnaker), and application-specific links (links that are common to every instance of your application).

Default links

At Netflix, we use a common base server, which adds a number of default endpoints to every running instance. These are configured in Deck’s settings.js file:

window.spinnakerSettings = {
  // ...
  defaultInstanceLinks: [
        {
            title: 'Logs',
            links: [
                { title: 'catalina.out', path: ':7000/Logs/catalina.out'},
                { title: 'Log File Archive', path: ':7000/Logs/all'},
                { title: 'Thread dumps', path: ':7000/Logs/threadDumps'},
                { title: 'Admin Proxy Info', path: ':7000/ProxyInfo'},
                { title: 'Admin Proxy Status', path: ':7000/ProxyStatus'},
                { title: 'GC Visualization', path: ':7000/GCVisualization'},
            ]
        },
        {
            title: 'Netflix Configuration',
            links: [
                { title: 'Properties Console', path: ':8088/props'},
                { title: 'Libraries Console', path: ':8088/libraries'},
                { title: 'Machine Readable Properties', path: ':8088/machineProperties'},
                { title: 'Manifest', path: '/manifest'},
            ]
        }
    ]
  // ...
};

When users create a new application, these links are available in each instance in Spinnaker with no additional input from the application owner.

Customizing application links

These links are customizable via the application’s Config tab in Spinnaker. If configured in settings.js, the default links are displayed. Users can then customize the links for their particular application.

Links support templating based on the instance’s attributes by wrapping the value in two curly braces, e.g. {{ "{{id"}}}}. Common attributes available in templates are listed below.

Note: Templating only applies to the path portion of the link - the title must be a hard-coded value.

Most links will be endpoints on your running server. These will be resolved using the public IP address of the instance if available, falling back to the private IP address. If you’ve specified an instance port in the application attributes, that will be used to generate the link. If the link should point to a different port, the path should start with a colon, then the port.

If no instance port is configured for the application, port 80 will be used for links (unless the path starts with a colon).

Some example paths: An application configured with a default port of 9000, and an instance (id: ‘i-1234’) with an IP address of 104.156.81.74

path	result
/help	http://104.156.81.74:9000/help
:9001/admin	http://104.156.81.74:9001/admin
https://my.company/trafficFrom?instance={{"{{id"}}}}	https://my.company/trafficFrom?instance=i-1234
https://{{"{{publicIpAddress"}}}}:9090/secureAdmin	https://104.156.81.74:9090/secureAdmin

Available template fields

This is not a comprehensive list of fields - just the most common ones. Not all fields will be available for every instance, as some are VPC-only, and some depend on subnet, launch configuration, and other factors. Trial and error is a good way to figure out what’s going to work for your application.

AWS

name	description	example
account	account owner of the instance	prod
availabilityZone	zone where instance resides	us-east-1a
cloudProvider	“aws”	“aws”
clientToken	see AWS Documentation	(string)
cluster	cluster name	myapp-staging
id	instance ID	i-12345678
imageId	ID of the AMI running on this instance	ami-123456
instanceId	same as id	i-12345678
instanceType	AWS instance type	m3.medium
ipAddress	convenience field for private IP address (internal subnets) or publicDnsName (external subnets)	104.156.81.74
keyName	See AWS Documentation	my-keypair-for-this-account
launchTime	timestamp of when instance launched	1486146739000
privateDnsName	internal DNS name associated by AWS to this instance	ip-104-156-81-74.ec2.internal
privateIpAddress	internal IP address (within AWS)	104.156.81.74
publicDnsName	external DNS name (for instances in external subnets only)	ip-104-156-81-74.ec2.external
region	region where instance resides	us-east-1
serverGroup	ASG name	myapp-v002
subnetId	subnet where instance resides	subnet-1abcde2f
vpcId	vpc where instance resides	vpc-1234567
zone	alias of availabilityZone	us-east-1c

Google Compute Engine

name	description	example
account	account owner of the instance	prod
availabilityZone	zone where instance resides	us-central1-f
cloudProvider	cloud provider abbreviation	gce
externalIpAddress	external IP address	104.156.81.74
id	instance id	app-stack-detail-v000-e20p
instanceType	GCE instance type	f1-micro
internalDnsName	internal DNS name associated by GCE to the instance	app-stack-detail-v000-e20p
internalIpAddress	internal IP address (within GCE)	104.156.81.74
launchTime	timestamp of when instance launched	1485801280421
network	network where instance resides	default
region	region where instance resides	us-central1
serverGroup	name of Spinnaker server group (GCE managed instance group) where instance resides	app-stack-detail-v000
subnet	subnet where instance resides	default-b13fe48693219e49

Docs: Kubernetes

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

Docs: Managed Delivery

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

Getting started

When you’re ready to give Managed Delivery a try, check out the Getting started page.

Docs: Pipeline User Guide

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

Docs: Plugin User Guide

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

Overview

Spinnaker uses PF4J-Update to load and manage plugins. These plugins can implement a PF4J extension point or be Spring components. See the Plugin Creators Guide for details.

Terms

plugins.json

required file
defines one to many plugins in a plugin repository
each plugin definition has an id, description, provider, and a collection of releases (version, date, requires, sha512sum, state, url)
the plugin developer provides access to this file

repositories.json

optional file
defines one to many plugin repositories
each repository definition consists of a unique identifier and the path to a plugins.json file
the plugin developer may supply this file

Plugin requirements

The plugin is either a Plugin Framework for Java (PF4J) plugin or a Spring plugin
The plugin repository is a web location that Spinnaker can access, like a GitHub repository

How to add a plugin to Spinnaker

Adding a plugin to Spinnaker consists of the following steps:

Add a plugin repository

Note: Your plugins.json and repository.json files must be in a location that Spinnaker can access. Token authentication to private repositories is not supported. Consider storing your plugins and repository files in an AWS S3 bucket (or similar) instead of a private repository.

When you configure a repository, you tell Spinnaker where to find the plugins.json file that defines the plugins you want to use. Each plugin repository entry in Spinnaker consists of a unique name and a URL.

If you want a repository to point to a single plugins.json file, you add it like this:

spinnaker:
  extensibility:
    repositories:
      observabilityy-plugin:
        url: https://raw.githubusercontent.com/armory-plugins/armory-observability-plugin-releases/master/plugins.json

It’s common to set this in the spinnaker-local.yml but it can be set on a per service basis for specific services.

If you want a single plugin repository entry to point to multiple plugins.json files, you need to create a repositories.json file that defines a collection of plugin repositories. The file format is:

[
  {
    "id": "<unique-repo-name>",
    "url": "<url-of-plugins.json-file>"
  }
]

For example:

[
  {
    "id": "spinnaker-plugin-examples",
    "url": "https://raw.githubusercontent.com/spinnaker-plugin-examples/examplePluginRepository/master/plugins.json"
  },
  {
    "id": "my-company-internal-plugins",
    "url": "https://<my-company-internal-github>/<repo-name>/plugins.json"
  },
  {
    "id": "my-plugins",
    "url": "https://github.com/aimeeu/pluginRepository/blob/master/plugins.json"
  }
]

Save your repositories.json file in a web location that Spinnaker can access. Then you can add a new plugin repository using the repositories.json file:

spinnaker:
  extensibility:
    repositories:
      all-the-plugins:
        url: https://raw.githubusercontent.com/aimeeu/all-the-plugins/master/repositories.json

Don’t forget to apply your configuration changes by redeploying spinnaker.

Add a plugin

Note: when added to spinnaker-local.yml, each service attempts to load the plugin. This means that when you restart Spinnaker, each service restarts, downloads the plugin, and checks if an extension exists for that service.

After you have added your plugin repository, you can add your plugin to Spinnaker.

spinnaker:
  extensibility:
    repositories:
      observabilityy-plugin:
        url: https://raw.githubusercontent.com/armory-plugins/armory-observability-plugin-releases/master/repositories.json
    deck-proxy:
      enabled: true
      plugins:
        Armory.ObservabilityPlugin:
          enabled: true
          version: 0.1.1
    plugins:
      Armory.ObservabilityPlugin:
        enabled: true
        version: 1.5.0
        config.metrics:
          prometheus:
            enabled: true
            meterRegistryConfig:
              armoryRecommendedFiltersEnabled: false

The plugin distributor should provide you with the plugin id LIKE Armory.ObservabilityPlugin and supported version and If you have to hunt for these values, you can find id and version in the plugins.json file, but you have to look at the code to find the value for extensions. Search for the deprecated @ExtensionConfiguration or the current @PluginConfiguration annotation. Both take a value, which is the extension name.

Example of the deprecated @ExtensionConfiguration annotation in the pf4jStagePlugin , which is written in Kotlin:

package io.armory.plugin.stage.wait.random

import com.netflix.spinnaker.kork.plugins.api.ExtensionConfiguration

@ExtensionConfiguration("armory.randomWaitStage")
data class RandomWaitConfig(var defaultMaxWaitTime: Int)

Example of the @PluginConfiguration annotation in the Notification Plugin , which is also written in Kotlin:

package io.armory.plugin.example.echo.notificationagent

import com.netflix.spinnaker.kork.plugins.api.PluginConfiguration

@PluginConfiguration("armory.httpNotificationService")
data class HTTPNotificationConfig(val url: String)

Plugin configuration variables are passed into the primary class constructor. If the plugin developer doesn’t specify configuration details, you can find key and type, or a configuration tree, by looking at the primary class constructor.

Another example using the Random Wait Plugin:

spinnaker:
  extensibility:
    plugins:
      Armory.RandomWaitPlugin:
        id: Armory.RandomWaitPlugin
        enabled: true
        version: 1.1.14
        extensions:
          armory.randomWaitStage:
            id: armory.randomWaitStage
            enabled: true
            config:
              defaultMaxWaitTime: 60

Plugin configuration

To avoid each service restarting and downloading the plugin, do not add the plugin to the spinnaker-local.yml. Instead, configure the plugin in the service’s local file. For example, if your plugin extends Orca, add configuration to your orca-local.yml file.

spinnaker:
  extensibility:
    plugins:
      <unique-plugin-id>:
        id: <unique-plugin-id>
        enabled: <true-false>
        version: <version>
        extensions:
          <extension-name>:
            id: <extension-name>
            enabled: <true-false>
            config: {}

Add a Deck proxy to Gate

If your plugin has a Deck component, you need to configure a deck-proxy so Gate knows where to find the plugin.

In your gate-local.yml add:

spinnaker:
   extensibility:
     deck-proxy:
       enabled: true
       plugins:
         <unique-plugin-id>:
           enabled: true
           version: <version>
       repositories:
         <unique-repo-name>:
           url: <url-to-repositories.json-or-plugins.json>

unique-plugin-id: the plugin ID
unique-repo-name: the plugin repository ID
url: the location of the plugin repository

Redeploy Spinnaker

Remember to apply your manifest changes after you have finished configuring your plugin.

Deployment example

See the pf4jStagePlugin Deployment Example page for a walkthrough and troubleshooting.

Resources

A central repository for all Spinnaker plugins is available as an example but is no longer maintained or used.

You can ask for help with plugins in the Spinnaker Slack #plugins channel.

Spinnaker – User Guides

Docs: Get Started Using Spinnaker

Before you get going…

Operators (managing Spinnaker)

Users (deploying with Spinnaker)

Using Spinnaker: the high-level process

Docs: Application User Guide

Important note about applications

What distinguishes one application from another?

Next

Docs: Using Spinnaker for Automated Canary Analysis

Docs: General Purpose Tagging Guide

Requirements

Overview

Current limitations

Common use cases

Tag namespaces

Implementation details

Identifier

EntityRef

tags structure

API

GET /tags

POST /tags

Upsert tags

POST /tasks

Upsert tags

DELETE /tags/:id/:tagName

Delete tags

FEATURE: Server group alerts and notices

Add alert

Add notice

Delete alert (or notice)

Configuration

clouddriver-local.yml

deck/settings-local.js

elasticsearch index template

Docs: Customizing Instance Links

Default links

Customizing application links

Available template fields

AWS

Google Compute Engine

Docs: Kubernetes

Docs: Managed Delivery

Getting started

Docs: Pipeline User Guide

Docs: Plugin User Guide

Overview

Terms

Plugin requirements

How to add a plugin to Spinnaker

Add a plugin repository

Add a plugin

Plugin configuration

Add a Deck proxy to Gate

Redeploy Spinnaker

Deployment example

Resources