Armory Docs – Armory Continuous Deployment Overview

Continuous-Deployment: Spinnaker Nomenclature and Naming Conventions

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

Nomenclature

Application

An application inside Spinnaker represents what you would typically find in a single code repository - and in many cases, an application maps directly to a microservice.

Cluster

A server group is a regional view of servers, whereas a cluster is a world-wide view of server groups.

Execution

When a pipeline runs, the end result is called an execution.

Pipeline

A pipeline in Spinnaker is a series of stages linked together that can be executed serially or in parallel. All pipelines are defined in the context of an application. A typical pipeline will contain stages for “creating images”, “testing”, and “deploying”. The process of “creating images” is also commonly referred to as a “bake”.

Project

A project inside Spinnaker is a logical grouping of applications. For example, we might create a project called “Spinnaker” and its applications would be “Deck”, “Orca”, “Clouddriver”, etc. Spinnaker provides a helpful dashboard view for each project to visualize its applications and status of each application contained within it.

Server Group

From an Amazon Web Service (AWS) point of view, a server group is represented by an auto-scaling group (ASGs). All applications that are deployed by Spinnaker are deployed to server groups.

Stage

Within a pipeline, the tasks that pipeline performs are called stages.

Trigger

A trigger is the entry point to a pipeline.

Spinnaker Naming Conventions

Spinnaker has very specific naming conventions that help it identify resources in your cloud account.

Clusters and server groups follow the convention application_name-stack-detail-infrastructure_version

Application

The ‘Name’ is the name of your application in Spinnaker.

Stack

You can think of a ‘Stack’ as a tag you give to anything that you want to be integrated together. Environments are usually a good example of something you would tag with a Stack. If you have an app that has an ELB, a Cache, and an ASG, usually you would want to run integration tests on your staging environment separately from your production environment. In that case, you would give the staging ELB, Cache, and ASG all the “staging” stack, while prod ELB, Cache, and ASG would be the “prod” stack.

Note that Stack names are defined by the user in the Spinnaker configuration User Interface (UI).

Detail

Detail is also user-defined and can be any additional piece of information you want to label your cluster and server group with.

Infrastructure Version

The infrastructure’s version number; such as v011, v012, etc. This is automatically appended and is not user defined.

In AWS, Spinnaker will name your ASGs and Launch Configurations according to the naming convention mentioned above (ie. “armoryspinnaker-prod-polling-v015”).

Please note that if your user definition includes a hyphen, it will disrupt the naming convention.

Continuous-Deployment: Spinnaker™ Architecture

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

Armory Continuous Deployment architecture

Armory Continuous Deployment is an enterprise version of open source Spinnaker. It is composed of several microservices for resiliency and follows the single-responsibility principle. It allows for faster iteration on each individual component and a more pluggable architecture for custom components. See the open source Spinnaker microservices overview for port mappings and a table of service interdependencies.

Armory Continuous Deployment microservices

Clouddriver

Clouddriver is a core component of Armory Continuous Deployment and facilitates the interaction between a given cloud provider such as AWS, GCP or Kubernetes. There is a common interface that is used so that additional cloud providers can be added.

Deck

Deck is the UI for interactive and visualizing the state of cloud resources. It depends on Gate to interact with the cloud providers.

Echo

Echo is the service for Spinnaker which manages notifications, alerts and scheduled pipelines (Cron). It can also propagate these events out to other REST endpoints such as an Elastic Search, Splunk’s HTTP Event Collector or a custom event collector/processor.

Fiat

Fiat is the microservice responsible for authorization (authz) for the other microservices. By default, it is not enabled, so users are able to perform any action in Armory Continuous Deployment.

Front50

Front50 is the persistent datastore for Spinnaker. Most notabily pipelines, configurations, and jobs.

Gate

Gate is the front-end API that is exposed to the users of your Spinnaker instance. It also manages authentication and authorization for sub-service APIs and resources with Spinnaker. All communication between the UI and the back-end services happen through Gate. You can find a list of the endpoints available through Swagger: http://${GATE_HOST}:8084/swagger-ui.html

Igor

Igor is a wrapper API which communicates with Jenkins. It is responsible for kicking-off jobs and reporting the state of running or completing jobs.

Kayenta

Kayenta is Spinnaker’s canary analysis service, integrating with 3rd party monitoring services such as Datadog or Prometheus.

Orca

Orca is responsible for the orchestration of pipelines, stages, and tasks within Armory Continuous Deployment. Orca acts as the “traffic cop” within Armory Continuous Deployment making sure that sub-services, their executions and states are passed along correctly.

The smallest atomic unit within Orca is a task - stages are composed of tasks and pipelines are composed of stages.

Rosco

Rosco is the “bakery” service. It is a wrapper around Hashicorp’s Packer command line tool which bakes images for AWS, GCP, Docker, Azure, and other builders.

Armory Continuous Deployment proprietary microservices

Armory Scale Agent for Spinnaker and Kubernetes

The Scale Agent for Spinnaker and Kubernetes is a lightweight, scalable service that monitors your Kubernetes infrastructure and streams changes back to the Clouddriver service.

Dinghy

Dinghy is the microservice used to manage Pipelines-as-Code. It supports two main capabilities:

Automatically synchronizing pipeline definitions from an external Github or BitBucket repository to Armory.
Creating a library of pipeline modules (components) that can be templatized and used in Dinghy-managed pipeline definitions.

Policy Engine

The Armory Policy Engine is designed to allow enterprises more complete control of their software delivery process by providing them with the hooks necessary to perform more extensive verification of their pipelines and processes in Spinnaker. This policy engine is backed by Open Policy Agent(OPA) and uses input style documents to perform validation of pipelines during save time and runtime

Terraformer

Terraformer is the microservice behind Armory’s Terraform Integration. It allows Armory to natively use your infrastructure-as-code Terraform scripts as part of a deployment pipeline.

Installation and management

Armory Operator

The Armory Operator is a Kubernetes Operator that makes it easy to install, deploy, and upgrade Armory Continuous Deployment.

Continuous-Deployment: Permissions in Spinnaker

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

Overview of Fiat

Fiat is the microservice in Spinnaker responsible for authorization (authz) for the other Spinnaker services. By default, it is not enabled, so users are able to perform any action in Spinnaker. This page describes how Fiat interacts with the following Spinnaker services:

Clouddriver for account permission
Front50 for application permissions
Igor for build services permissions

When Fiat is enabled, users start with no permissions and must be explicitly granted permissions.

For a deeper dive into how authz works for Spinnaker, see Authorization. Much of Spinnaker’s configuration is done through your Halconfig, which can be found in ~/.hal/config.

Requirements

To use Fiat, you need an external identity provider. Create the user roles and maintain them in the identity provider. Fiat controls what permissions are mapped to roles.

Fiat supports the following identity providers:

SAML groups (includes OAuth ONLY with OIDC)
LDAP
GitHub teams
Google Groups

In all these methods, users are referenced by a userId, which is determined by the authentication method of your choice.

Clouddriver accounts

Clouddriver is the Spinnaker service that interacts with the various providers. When Fiat is enabled, account permissions for Clouddriver determine whether a role or group can perform the following actions:

READ - See objects in a given cloud account.
WRITE - Deploy objects to a given account.

Note that for AWS, a role/group needs both read and write access to deploy an AMI from the AWS account that Rosco uses to build AMIs.

Front50 accounts

Front50 is the Spinnaker service that acts as the system of record for all the other Spinnaker services. In other words, all metadata for things such as applications and pipelines are stored in and served by Front50. Control access to Front50 by creating service accounts. This can be done through a series of cURL commands.

Service accounts are used to delegate authority to a pipeline to perform actions in Spinnaker. Users with ALL the roles defined in a service account can grant a pipeline “Run as” permission. The service accounts you create should map to roles/groups in your identity provider. Additionally, all pipelines configured to run off of a trigger must also be configured with “Run as” permission, or they will fail.

Armory recommends that you map one service account for each role/group in the identity provider that will be accessing Spinnaker. This prevents privilege escalation and makes it easier to figure out which roles/group ran which pipeline.

Example roles

The rest of this explanation uses the following example roles to illustrate how Fiat works:

fiat-admin
- Administrator for all of Spinnaker. Can do anything implicitly.
admin
- Administrator. Can do anything for all apps. Can read and execute build/ci jobs.
dev
- Full control of pipeline definition for app1 & app2
- Can deploy to dev-infra
- Can see qa-infra
- Can attach a build/ci trigger to a pipeline definition
qa
- Full control of pipeline definition for app1 & app3
- Can deploy to qa-infra
- Can see dev-infra
- Can attach a build/ci trigger to pipeline definitions
ops
- Can deploy to all accounts but cannot change the pipeline definitions. Can read and execute build/ci jobs.

Note that roles, as far as Fiat is concerned, are case insensitive. This means that admin is equivalent to Admin, ADMIN, or any other permutation.

Mapping exercise

Answer the following questions to figure out how to map roles and permissions in your deployment:

Which roles/groups have READ and/or WRITE access to which Clouddriver accounts
Which roles/groups have READ, WRITE, EXECUTE access to each Spinnaker Application
Which roles/groups have READ and/or WRITE/EXECUTE access to which CI/Build accounts

The following image shows an example result of this exercise based on the user roles described in Example Roles:

Example Configurations

The following sections describe some of the roles from the role matrix example in the Mapping exercise.

Superuser

fiat-admin is the superuser and has permissions across your whole Spinnaker deployment.

The configuration for fiat-admin in the fiat-local.yml file looks like the following snippet:

admin:
 roles:
 - fiat-admin

Infrastructure

dev-infra is one of the potential deployment targets (pictured in (Mapping exercise).

The Halconfig snippet for configuring access to dev-infra based on our mapping exercise looks similar to the following:

accounts:
- name: dev-infra
 permissions:
 READ:
 - admin
 - dev
 - qa
 - ops
 WRITE:
 - admin
 - dev
 - ops

Based on which roles have what access to other infrastructure accounts, the configuration looks different.

Note that fiat-admin does not need to be explicitly granted permissions. Every other user role must be granted permissions explicitly.

For information about how to configure permissions for Clouddriver accounts, see Accounts.

Continuous integration system

build1 is a Jenkins deployment used for CI in this example. The Halconfig for controlling access to build1 looks similar to the following snippet:

ci:
 jenkins:
 enabled: true
 masters:
 - name: build1
 permissions:
 READ:
 - admin
 - dev
 - qa
 - ops
 WRITE:
 - admin
 - ops

Applications

app1 is one of the applications that needs to be deployed. Configuring permissions for an application is done in Deck, Spinnaker’s UI, when you create or edit an application:

app2, app3, and app4 will look slightly different since they have different permissions based on the mapping exercise.

For information about how to configure permissions for applications, see Applications.

Applying changes

Whenever you make a change to permissions that involves modifying your Halconfig, run hal deploy apply to apply your changes to the Spinnaker deployment. Some permission changes do not require this, such as adding a service account.

Verifying permissions

You can verify what permissions are assigned to a role at any time.

Admin permissions

Check fiat-local.yml to see who is assigned an admin role.

Permissions in Halconfig

In your Halconfig, you can verify several sets of permissions.

For example, search for ci to find the continuous integration section. Look for the permissions key and examine the READ and WRITE subkeys. All the user roles that have read or write permission for the CI system are listed here. The same thing can be done for Clouddriver accounts.

Permissions for apps

Check the permissions for all applications in Spinnaker with a REST API call to Gate.

Headers

Header	Information
Request URL	`$GATE_URL/applications`
Request Method	`GET`
content-type	`application/json;charset=UTF-8`

The API call returns information about the apps. Refer to the name and permissions sections to find your applications and the corresponding permissions:

{
 ...
 "name": "app2",
 "permissions": {
 "EXECUTE": [
 "admin",
 "dev",
 "ops"
 ],
 "READ": [
 "admin",
 "dev",
 "ops"
 ],
 "WRITE": [
 "admin",
 "dev"
 ]
 },
 ...
}

Permissions for Spinnaker service accounts

Verifying the permissions for service accounts requires access to the Front50 and Fiat pods.

List all the service accounts with the following command (from the Front50 pod):

export FRONT50=http://spin-front50:8080
curl -s $FRONT50/serviceAccounts

Check user or service account permissions for all of Spinnaker (from the Fiat pod):

export FIAT=http://spin-fiat:7003
curl -s $FIAT/authorize/$user-or-service-account

The command returns JSON that lists the following information:

Roles the user/service account is part of
Spinnaker applications the user/service account has access to
Clouddriver accounts the user/service account has access to
Build services the user/service account has access to

Pub Sub and Webhooks

Fiat does not support Pub Sub triggers or authenticating webhooks with group permissions.

Permissions for Clouddriver accounts

Check Clouddriver’s current runtime context with a REST API call to Gate.

Headers

Header	Information
Request URL	`$GATE_URL/credentials`
Request Method	`GET`
content-type	`application/json;charset=UTF-8`

The API call returns JSON that lists the Clouddriver accounts.

[
 {
 "name": <account-name>,
 "type": <account-type>,
 "providerVersion": <version>,
 "requiredGroupMembership": [

 ],
 "skin": <version>,
 "permissions": {

 },
 "authorized": <true-or-false>
 },
 {
 "name": "my-docker-registry",
 "type": "dockerRegistry",
 "providerVersion": "v1",
 "requiredGroupMembership": [

 ],
 "skin": "v1",
 "permissions": {

 },
 "authorized": "true"
 }
]

Continuous-Deployment: Load Balancers in Spinnaker

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

What is a load balancer?

A load balancer is associated with an ingress protocol and port range. It balances traffic among instances in its server groups. Optionally, you can enable health checks for a load balancer, with flexibility to define health criteria and specify the health check endpoint.

Requirements

Before you create a load balancer, your Security Group will already need to exist.

Create a load balancer

Step 1: After you select your Application, click on the Load Balancers tab.

Step 2: Click the “Create Load Balancer” button.

Step 3: The Stack and Detail should be kept in mind when creating the pipeline because the pipeline’s deployment of server group should be using the same Stack and Detail.

Delete a load balancer

Note: You can only delete Load Balancers if they do not have any instances attached to them.

Step 1: Go to your Load Balancers in your Applications.

Step 2: Select a Load Balancer, then to the right a column with the Load Balancer’s details should appear. Select the drop down menu and press “Delete”.

Continuous-Deployment: Your First Application in Spinnaker

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

What is an application in Spinnaker?

Spinnaker™ is organized around the concept of applications. An application in Spinnaker is a collection of clusters, which in turn are collections of server groups. The application also includes firewalls and load balancers.

An application represents the service which you are going to deploy using Spinnaker, all configuration for that service, and all the infrastructure on which it will run.

The Spinnaker landing page

When you first log in to Spinnaker, the landing page should look like this:

The navigation bar at the top allows you to access Projects, Applications, and Infrastructure. The search bar allows you to search through your Infrastructure. (this search bar will find everything in all of your AWS Infrastructure)

Spinnaker should scan all of your infrastructure and create applications for anything that it finds. If you enter an application this way that was not configured by Spinnaker, it should state that the application has not been configured.

Note: The naming convention that you have been using is not necessarily the same one that Spinnaker uses, but accessing your applications through Spinnaker should allow you to configure it to your preferences. Remember that Spinnaker considers an application to be anything you would put into a single code repository.

Making an application

Enter Applications from your Navigation bar.
Click the “Create Application” button:
Fill out the pop-up form with desired user definitions.
- The name of the application cannot have hyphens. Using a hyphen in the application name interferes with the naming convention. This applies to all types of applications except for those that use the Kubernetes V2 provider to deploy.
- When you create an application in Spinnaker, consider it to be anything you would put into a single code repository.
After you fill out the form you should see this:
If you wish to modify the settings for the application, click “Config” for configurations.

Note that by now you should have created an application, but as you have not created a pipeline and executed it, nothing should show up yet.

Deleting an application

Go to your application, click on “Config” and scroll all the way down. There will be a prompt to confirm if you would like to delete your application.

Continuous-Deployment: Your First Pipeline in Spinnaker

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

What is a pipeline in Spinnaker?

The pipeline is the key deployment management construct in Spinnaker™. It consists of a sequence of actions, known as stages. You can pass parameters from stage to stage along the pipeline.

You can start a pipeline manually, or you can configure it to be automatically triggered by an event, such as a Jenkins job completing, a new Docker image appearing in your registry, a CRON schedule, or a stage in another pipeline.

Before you begin

This page assumes your application stack includes:

A Jenkins Master configured by your administrator
A Jenkins job that archives a Debian package
A security group within AWS with appropriate permissions
A Load Balancer

How to create a pipeline

This example creates a pipeline that takes the Debian package produced by a Jenkins job and uses it to create an Amazon Machine Image (AMI) before deploying that image to a server group.

After selecting your Application, click the Pipelines category.
On this page, click Configure a new pipeline.
Provide a name for your new pipeline and click Create.
On the Pipeline page you should see:
- A visual representation of your pipeline and its stages (you should only have configurations at the beginning)
- Execution Options
- Automated Triggers
- Parameters
- Notifications
- Description

Add a trigger

Define how your pipeline is triggered. Scroll down to the Automated Triggers section and click Add Trigger. This section enables you to select a Type:
For this example, select Jenkins. By adding a trigger, you are defining how your pipeline is initialized.

Note: Property File is an important topic that will be covered in a separate guide.
Before you test your pipeline, you may want to consider enabling or disabling the trigger via the checkbox at the bottom.

Add a Bake stage

Now add your first stage: Baking an AMI. Click the Add stage button in the visual representations section:
Select Bake from the Types drop down list.
If you have multiple providers configured, select Amazon from the Provider drop down list. Next select the region or regions you want to bake in. In the Package field, enter the name of the package that your Jenkins job archived.
- The package name should not include any version numbers. For example, if your build produces a deb file named “myapp_1.27-h343”, you would enter “myapp” here.
- If you configure your own Base AMI under the Advanced Options, the Base OS configuration is ignored.

Add a Deploy stage

Now add a Deploy stage by clicking Add stage again. Select Deploy In the Type drop down list. Deploy’s configuration settings should pop up on the screen.

Note: If you want to reorganize the order that the stages execute in the pipeline, you can add or remove precursor stages in the Depends On field.
In the Deploy Configuration section, click on the “Add server group” button. Pick your provider, if more than one is configured. This example uses AWS.
Because this is a new application, do not choose to copy a configuration from a template. Press the Continue without a template button.
It’s important to set up the correct Deploy Strategy for your use case. Use the Highlander strategy for this example, which will ensure that only one server group for your application exists at a time.
In the Load Balancers section, select the load balancer you created before you began this tutorial.
Select a security group that you are comfortable with, which will define the access rights to your resource.
Select Instance Type as Micro Utility, then set the size as “small”.
For Capacity, select how many instances you want in your server group. For our example, we will set it at 1.
Click “add”. You will be brought back to your Application and see a new Deploy Configuration. Press “Save Changes” at the bottom right of your window.

Execute the Pipeline

Click on the Pipelines option. You should see your new pipeline. Click on Start Manual Execution.
You will be able to select a Build for your Jenkins job from a drop down menu. By default, Spinnaker will not recreate an AMI unless the underlying package has changed. If you would like to force it, you may use the checkbox for “Rebake”.
Press “Run”, and you should see a progress bar where blue represents running and green represents complete. Gray represents not ran or canceled, which is not in our example picture.

If your pipeline does not succeed, refer to one of the troubleshooting sections in the pipelines, baking, or deploying guides.

Note: Always remember to save your changes by clicking the button in the bottom right of the window.

Continuous-Deployment: Spinnaker Glossary

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

Amazon Web Services

Amazon Web Services (AWS) is a cloud services provider from Amazon that offers computing power, database storage, content delivery and additional functionalities to businesses that operate in the cloud. For Spinnaker purposes, think of AWS as a data center but instead of being physical servers it is in the cloud.

Amazon Machine Images

Amazon Machine Images (AMIs) are predetermined ’templates’ for instances that can be used to launch an instance of a virtual server. They generally include the configurations for the instance (Operating System, application server, applications), the permissions and Secrets that control which AWS accounts can access the instances, and a block device mapping that specifies the volumes to attach to the instance when it is launched.

Application

An application inside Spinnaker™ represents what you would typically find in a single code repository - and in many cases, an application maps directly to a microservice.

Auto-Scaling Group

An auto-scaling group (ASG) contains a collection of EC2 instances that share similar characteristics and are treated as a logical grouping for the purposes of instance scaling and management.

Authorization

Authorization (Auth) is the level of access to APIs that a user, application or role has within your AWS account. This is usually configured by your administrator.

Baking

The term ‘Baking’ is used within Spinnaker to refer to the process of creating machine images, usually with AMIs.

Cloud

Short for cloud computing, the cloud as we refer to it is internet-based computing that provides processing resources (e.g.; database storage, networks, servers, applications) on demand to devices connected to the internet.

Clouddriver

A sub-service within Spinnaker. See the Spinnaker Architecture for more information.

Cluster

A server group is a regional view of servers, whereas a cluster is a world-wide view of server groups.

Code repository

A source code repository is a private or public storage location for file archive and web hosting, used for source codes of software or web pages.

Continuous Delivery

Continuous Delivery (CD) is an engineering approach for DevOps teams to produce software in short cycles: building, testing, and releasing software at a fast and frequent pace in order to iterate as quickly as possible.

Continuous Integration

Continuous Integration (CI) is a development practice where software developers merge their separate changes and updates to a main source code repository - usually multiple times a day.

Deck

A sub-service within Spinnaker. See the Spinnaker Architecture for more information.

Debian package

Debian packages (deb) are two tar archives contained in standard Unix ar archives - one holds the control information and the other contains the data used for installation.

Detail

For cluster and server group configurations, ‘Detail’ is usually any additional piece of user-defined information you want to label your cluster and server group(s) with.

Echo

A sub-service within Spinnaker. See the Spinnaker Architecture for more information.

Elastic Compute Cloud

Elastic Compute Cloud (EC2) is part of the AWS cloud platform, a “pay as you go” virtual computer renting system that contains preconfigured software and applications requested by the user.

Execution

When a pipeline runs, the end result is called an execution.

Gate

A sub-service within Spinnaker. See the Spinnaker Architecture for more information.

Igor

A sub-service within Spinnaker. See the Spinnaker Architecture for more information.

Infrastructure version

The infrastructure’s version number; such as v011, v012, etc. This is automatically appended and is not user defined.

In AWS, Spinnaker will name your ASGs and Launch Configurations according to the naming convention mentioned above (ie. “armoryspinnaker-prod-polling-v015”).

Please note that if your user definition includes a hyphen, it will disrupt the naming convention.

Jenkins

Jenkins is an open source automation server that can package applications for distribution. Spinnaker pipelines can be [triggered]trigger) from a build on Jenkins.

Load balancer

For Spinnaker’s purposes, a load balancer is a service that automatically distributes incoming traffic across all instances. The one most commonly used within AWS is the Elastic Load Balancer (ELB).

Orca

A sub-service within Spinnaker. See the Spinnaker Architecture for more information.

Pipeline

Learn to create your first pipeline here.

Project

A project inside Spinnaker is a logical grouping of applications. For example, we might create a project called “Spinnaker” and its applications would be “Deck”, “Orca”, “Clouddriver”, etc. Spinnaker provides a helpful dashboard view using Deck for each project to visualize its applications and status of each application contained within it.

Rosco

A sub-service within Spinnaker. See the Spinnaker Architecture for more information.

Scale server group

Reduce the total number of server groups remaining in the cluster.

Server group

From an Amazon Web Service (AWS) point of view, a server group is represented by an auto-scaling group (ASGs). All applications that are deployed by Spinnaker are deployed to server groups.

Shrink server group

Reduce the number of instances in a particular server group.

Stack

Note that Stack names are defined by the user in the Spinnaker configuration User Interface (UI).

Stage

Within a pipeline, the tasks that pipeline performs are called stages.

Trigger

A trigger is the entry point to a pipeline - when a pipeline is triggered, it attempts to execute.