Configure Armory Continuous Deployment Using Kustomize

This guide is for both the Armory Operator and the Spinnaker Operator. Armory Continuous Deployment and Spinnaker configuration is the same except for features only in Armory Continuous Deployment. Those features are marked .

Why use Kustomize patches for Spinnaker configuration

Even though you can configure Armory Continuous Deployment or Spinnaker in a single manifest file, the advantage of using Kustomize patch files is readability, consistency across environments, and maintainability.

How Kustomize works

Kustomize uses patch files to build a deployment file by overwriting sections of the spinnakerservice.yml manifest file. You declare your patch files in a kustomization.yml file, which kubectl and Kustomize and use to build the Armory Continuous Deployment or Spinnaker manifest file.

You can put each manifest config section in its own file. For example, if you create a profiles-patch.yml patch with configuration for various services, you are telling Kustomize to overwrite the profiles section of the spinnakerservice.yml manifest with the contents of profiles-patch.yml. Kustomize is flexible, though, so you could instead create a separate patch file for each service (profiles-clouddriver-patch.yml, profiles-gate-patch.yml, profiles-deck-patch.yml, etc.), and then declare those patches in the kustomization.yml file.

Kustomize is part of kubectl, so you do not need to install Kustomize locally to build and verify your manifest file. You can run kubectl kustomize <path-to-kustomization.yml>. This prints out the contents of the manifest file that Kustomize builds using your kustomization.yml file.

kubectl versions up to and including v1.20 come bundled with Kustomize v2.0.3. kubectl 1.21 comes bundled with Kustomize v4.0.5. Using Kustomize patches has been tested with kubectl v1.19.x. and standalone Kustomize v2 and v3. You may see a panic error if you use the spinnaker-kustomize-patches repo with Kustomize v4.0+ or kubectl v1.21+.

Kustomize resources

You should familiarize yourself with Kustomize before you create patch files to configure Armory Continuous Deployment.

• Kustomize Glossary
• Kustomize introduction
• Kustomization file overview

Kubernetes requirements

• You are familiar with Kubernetes Operators, which use custom resources to manage applications and their components.
• You understand the concept of managing Kubernetes resources using manifests.
• You have reviewed and met the Armory Continuous Deployment system requirements.

Spinnaker Kustomize patches repo

Armory maintains the spinnakaker-kustomize-patches repo, which contains common configuration options for Armory Continuous Deployment or Spinnaker as well as helper scripts. The patches in this repo give you a reliable starting point when adding and removing features.

Configuration in this repository is meant for Armory Continuous Delivery. To make it compatible with Spinnaker instead, apply the utilities/switch-to-oss.yml patch.

To start, create your own copy of the spinnaker-kustomize-patches repository by clicking the Use this template button:

If you intend to update your copy from upstream, use Fork instead. See Creating a repository from a template for the difference between Use this template and Fork.

Once created, clone this repository to your local machine.

Configure Armory Continuous Deployment

Follow these steps to configure Armory Continuous Deployment:

1. Choose a kustomization.yml file.
2. (Optional) If you are deploying open source Spinnaker, change the apiVersion in each patch file.
3. Set the Armory Continuous Deployment (or Spinnaker) version.
4. Verify the content of each resource file.
5. Verify the configuration contents of each patch file.

Choose a kustomization file

Before you begin configuring Armory Continuous Deployment, you need to choose or create a kustomization.yml file. The kustomization.yml specifies the namespace for Armory Continuous Deployment, a list of Kubernetes resources, and a list of patch files to merge into the spinnakerservice.yml manifest file. For example, the recipes/kustomization-minimum.yml file contains the following:

#-----------------------------------------------------------------------------------------------------------------------
# Minimum Starting Point recipe
#
# Self contained Spinnaker installation with no external dependencies and no additional configuration needed.
# This is intended as a starting point for any kubernetes cluster.
# Not for production use.
#
# Features:
# - One Kubernetes account (Spinnaker's own cluster) for deployment targets
# - Spinnaker authentication disabled
# - Self hosted minio as a persistent storage
# - Self hosted redis backend for caching and temporal storage of services
#-----------------------------------------------------------------------------------------------------------------------
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: spinnaker

components:
  - core/base
  - core/persistence/in-cluster
  - targets/kubernetes/default

patchesStrategicMerge:
  - core/patches/version.yml

transformers:
  - utilities/unique-service-account.yml

• The components section contains paths to directories that define collections of Kubernetes resources, such as: in-cluster Spinnaker persistence with Minio, Kubernetes Service Account and patches to enable the cluster in Spinnaker.

• The patchesStrategicMerge section contains links to files that contain partial resource definitions. Kustomize uses these patch files to overwrite sections of components or resources, such as the SpinnakerService definition.

spinnaker-kustomize-patches/kustomization.yml is a symlink that points to spinnaker-kustomize-patches/recipes/kustomization-all.yml. There are multiple kustomization examples in the recipes directory. Choose the one that most closely resembles your use case and link to it. Alternately, you can delete the symlink, move your desired Kustomization file from recipes to the top-level directory, and rename the file to kustomization.yml.

Choose Open Source Spinnaker

This step is required only if you are deploying open source Spinnaker.

Add the following patch to your kustomization.yml file:

patches:
  - target:
      kind: SpinnakerService
    path: utilities/switch-to-oss.yml

Set the Armory Continuous Deployment version

In spinnaker-kustomize-patches/core/patches/version.yml, set the Armory CD version or Spinnaker version that you want to deploy, such as 2.34 (Armory Continuous Deployment) or 1.25.3 (Spinnaker).

1
2
3
4
5
6
7

kind: SpinnakerService
metadata:
  name: spinnaker
spec:
  spinnakerConfig:
    config:
      version: 2.34

Verify resources

Read each file linked to from your chosen kustomization.yml file section to make sure that the Kubernetes resource as configured works with your environment.

Verify patches

Read each file linked to in the patchesStrategicMerge section. You may need to update each patch configuration with values specific to you and your environment. For example, the kustomization-quickstart.yml file described in the Choose a kustomization file section links to accounts/docker/patch-dockerhub.yml. You need to update that patch file with your own DockerHub credentials.

Explore the patches in various folders to see if there are any that you want to use. Remember to list additional patches in the patchesStrategicMerge section of your kustomization.yml file.

Secrets

If you want to store Spinnaker secrets in Kubernetes, we recommend using Kustomize generators.

Deploy Armory Continuous Deployment

Once you have configured your patch files, you can deploy Armory Continuous Deployment.

1. Create the spinnaker namespace:

   kubectl create ns spinnaker
   

   If you want to use a different namespace, you must update the namespace value in your kustomization.yml file.

2. (Optional) Verify the Kustomize build output:

   kubectl kustomize <path-to-kustomization.yml>
   

   This prints out the contents of the manifest file that Kustomize built based on your kustomization.yml file.

3. Apply the manifest:

   kubectl apply -k <path-to-kustomization.yml>
   

4. Watch the install progress and see the pods being created:

   kubectl -n spinnaker get spinsvc spinnaker -w
   

Help resources

• Armory Operator and Armory Continuous Deployment: contact Armory Support or use the Spinnaker Slack #armory channel.
• Spinnaker Operator and Spinnaker: Spinnaker Slack #kubernetes-operator channel.

What’s next

• See the Manifest Reference for configuration options by section.
• Learn how to manage your Spinnaker instance.
• See the Errors and Troubleshooting guide if you encounter issues.