You are viewing version 2.25 of the documentation, which is no longer maintained. For up-to-date documentation, see the latest version.

Armory Agent for Kubernetes Quickstart Installation

Learn how to install the Armory Agent in your Kubernetes and Armory Enterprise environments.

Proprietary

Before you begin

  • This guide is for experienced Kubernetes and Armory Enterprise users.
  • You have read the Armory Agent overview.
  • You have a Redis instance. The Agent uses Redis to coordinate between Clouddriver replicas.
  • You have configured Clouddriver to use MySQL or PostgreSQL. See the Configure Clouddriver to use a SQL Database guide for details.

Compatibility matrix

The Armory Agent is compatible with Armory Enterprise and open source Spinnaker. It consists of a lightweight service that you deploy on Kubernetes and a plugin that you install into Spinnaker.

Armory (Spinnaker) Version Armory Agent Plugin Version Armory Agent Version
2.23.x (1.23.x) 0.6.8 0.5.11
2.24.x (1.24.x) 0.7.7 0.5.11
2.25.x (1.25.x) 0.8.6 0.5.11

The Agent consists of a service deployed as a Kubernetes Deployment and a plugin to Spinnaker’s Clouddriver service. You can review the architecture in the Armory Agent overview.

Networking requirements

Communication between Clouddriver and the Agent must be http/2. http/1.1 is not compatible and causes communication issues between Clouddriver and the Agent.

Kubernetes permissions needed by the Agent

The Agent should have ClusterRole authorization if you need to deploy pods across your cluster or Role authorization if you deploy pods only to a single namespace.

  • If Agent is running in Agent Mode, then the ClusterRole or Role is the one attached to the Kubernetes Service Account mounted by the Agent pod.
  • If Agent is running in any of the other modes, then the ClusterRole or Role is the one the kubeconfigFile uses to interact with the target cluster. kubeconfigFile is configured in kubesvc.yml of the Agent pod.

Example configuration for deploying Pod manifests:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: agent-role
rules:
- apiGroups: ""
  resources:
  - pods
  - pods/log
  - pods/finalizers  
  verbs:
  - get
  - list
  - watch
  - create
  - update
  - patch
  - delete

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: agent-role
rules:
- apiGroups: ""
  resources:
  - pods
  - pods/log
  - pods/finalizers  
  verbs:
  - get
  - list
  - watch
  - create
  - update
  - patch
  - delete

You can see a more detailed example of the kind of ClusterRole permissions you may need in the spinnaker-kustomize-patch repo’s spin-sa.yml file.

See the Kubernetes Using RBAC Authorization guide for details on configuring ClusterRole and Role authorization.

Step 1: Agent plugin installation

You modify the current Clouddriver deployment as well as add a new Kubernetes Service.

The easiest installation path is to modify an existing spinnakerservice.yaml with Kustomize. To start, download additional manifests into the directory with your SpinnakerService:

# AGENT_PLUGIN_VERSION is found in the compatibility matrix above
curl https://armory.jfrog.io/artifactory/manifests/kubesvc-plugin/agent-plugin-$AGENT_PLUGIN_VERSION.tar.gz | tar -xJvf -

Then include the manifests in your current kustomization:

# Existing kustomization.yaml
namespace: spinnaker  #   could be different
resources:
  # Pre-existing SpinnakerService resource (may have a different name)
  - spinnakerservice.yaml

bases:
  # Add the agent service
  - agent-service

patchesStrategicMerge:
  # Include plugin configuration
  - agent-plugin/config.yaml
  # Change plugin version as well the name of your SpinnakerService in this manifest
  - agent-plugin/clouddriver-plugin.yaml
  # Alternatively you can include this remote manifest
#  - https://armory.jfrog.io/artifactory/manifests/kubesvc-plugin/clouddriver-plugin-<AGENT_PLUGIN_VERSION>.yaml

You can then set the plugin options in agent-plugin/config.yaml.

  • For topologies like Infrastructure mode and Agent mode, in which the Agent is installed in a different cluster from Spinnaker, you should configure TLS through a load balancer.

  • For Spinnaker installations with one Clouddriver instance and no Redis, you can use kubesvc.cluster. However, a Spinnaker installation with Redis is recommended.

  • When running Spinnaker in HA, make sure to modify the following files:

    • agent-service/kustomization.yaml according to its comments
    • agent-plugin/clouddriver-plugin.yaml and agent-plugin/config.yaml references to Clouddriver should be to HA versions (i.e: -rw, -ro, etc)

When you’re ready, deploy with:

kustomize build . | kubectl apply -f -

Note:

  • If you gave SpinnakerService a name other than spinnaker, you need to change it in files under agent-plugin.
  • If you are using the Agent on an OSS installation, use the following download URL https://armory.jfrog.io/artifactory/manifests/kubesvc-plugin/agent-oss-plugin-${AGENT_PLUGIN_VERSION}-tar.gz or replace the apiVersion with spinnaker.io/v1alpha2.

Alternate methods

If you are not using Kustomize, you can still use the same manifests.

  • Deploy agent-service/clouddriver-grpc-service.yaml or agent-service/clouddriver-ha-grpc-service.yaml if using Clouddriver “HA” (caching, rw, ro).
  • Merge agent-plugin/config.yaml and agent-plugin/clouddriver-plugin.yaml into your existing SpinnakerService.

Step 2: Agent installation

Kustomize

Create the directory structure described below with kustomization.yaml, kubesvc.yaml, and kubecfg/ containing the kubeconfig files required to access target deployment clusters:

.
├── kustomization.yaml
├── kubesvc.yaml
├── kubecfgs/
│   ├── kubecfg-01.yaml
│   ├── kubecfg-02.yaml
│   ├── ...
│   └── kubecfg-nn.yaml
# ./kustomization.yaml

# Namespace where you want to deploy the agent
namespace: spinnaker
bases:
  - https://armory.jfrog.io/artifactory/manifests/kubesvc/armory-agent-0.5.11-kustomize.tar.gz

configMapGenerator:
  - name: kubesvc-config
    behavior: merge
    files:
      - kubesvc.yaml

secretGenerator:
  - name: kubeconfigs-secret
    files:
    # a list of all needed kubeconfigs
    - kubecfgs/kubecfg-account01.yaml
    - ...
    - kubecfgs/kubecfg-account1000.yaml

kubesvc.yaml contains the Agent options:

# ./kubesvc.yaml

kubernetes:
  accounts:
  - name: account01
    # /kubeconfigfiles/ is the path to the config files
    # as mounted from the `kubeconfigs-secret` Kubernetes secret
    kubeconfigFile: /kubeconfigfiles/kubecfg-account01.yaml
    ...
  - ...
...
  • For installations without gRPC TLS connections, you should include clouddriver.insecure: true in the Agent options.
  • For HA, make sure to set clouddriver.grpc: clouddriver-ha-grpc-service.yaml:9091

With the directory structure in place, deploy the Agent service:

kustomize build </path/to/directory> | kubectl apply -f -

Managing kustomization locally

If you prefer to manage manifests directly, download all the manifests:

AGENT_VERSION=0.5.11 && curl -s https://armory.jfrog.io/artifactory/manifests/kubesvc/armory-agent-$AGENT_VERSION-kustomize.tar.gz | tar -xJvf -
  • Change the version of the Agent in kustomization.yaml
  • Modify Agent options in kubesvc.yaml

What’s next

Last modified May 19, 2021: (426f70b)