hello-armory

Hello Armory

Welcome to Armory Continuous-Delivery-as-a-Service! In this tutorial for CDaaS beginners, you'll accomplish the following:

• Deploy Armory's sample application potato-facts to two environments: staging and prod.
• Use Armory's Cloud Console to approve an environment promotion.
• Observe a traffic split between two application versions.
• Learn CDaaS deployment YAML syntax.

Before you begin

Before you begin, make sure you've completed these steps:

1. Install:

   Install armory on Mac OS using Homebrew:

   brew install armory-io/armory/armory-cli

   To install armory on Linux, run the following command:

   curl -sL go.armory.io/get-cli | bash

   The script will install armory and avm. You can use avm (Armory Version Manager) to manage your armory version.

2. Log in:

   Log in with the CLI:

   armory login

   Confirm the device code in your browser when prompted, then return to this guide.

   If you've arrived at this tutorial without an Armory CDaaS account, that's OK! You can sign up for a free account when you run armory login.

3. Connect your cluster:

   CDaaS uses an agent to execute deployments in your Kubernetes cluster. Your cluster's API endpoint does not need to be publicly accessible to use CDaaS.

   The installation process will use credentials from your ~/.kube/config file to install the CDaaS agent. If you do not have access to a Kubernetes cluster, consider installing a local Kind or Minikube cluster.

   Run the following command to install an agent in your Kubernetes cluster:

   armory agent create

   You will name your agent during the installation process. That name will be referenced as <my-agent-identifier> throughout this tutorial.

First Deployment

Armory's sample application potato-facts is a simple web application. The UI polls the API backend for facts about potatoes and renders them for users.

Your first deployment will deploy the following resources into your Kubernetes cluster:

• Two namespaces: potato-facts-staging and potato-facts-prod.
• In each namespace, the potato-facts application and a Kubernetes Service.

Deploy

Run the following command:

armory deploy start -f https://go.armory.io/hello-armory-first-deployment --account <my-agent-identifier>

Congratulations, you've just started your first deployment with CDaaS!

You can use the link provided by the CLI to observe your deployment's progression in Cloud Console. Your resources will be deployed to staging. Once those resources have deployed successfully, CDaaS will deploy to prod.

Second Deployment

CDaaS is designed to help you build safety into your application deployment process. It does so by giving you declarative levers to control the scope of your deployment.

CDaaS has four kinds of constraints that you can use to control your deployment:

• Manual Approvals
• Timed Pauses
• Webhooks
• Automated Canary Analysis

You can use these constraints between environments and within environments:

• During your next deployment, you will need to issue a manual approval between staging and prod.
• Within the prod deployment, CDaaS will create a 25/75% traffic split between your application versions. CDaaS will wait for your approval before continuing the deployment.

Deploy

Start your second deployment:

armory deploy start -f https://go.armory.io/hello-armory-second-deployment --account <my-agent-identifier>

Use the link provided by the CLI to navigate to your deployment in Cloud Console. Once the staging deployment has completed, click "Approve" to allow the prod deployment to begin.

Click on the prod deployment, then click on the potato-facts link under "Resources":

This will open a preview of potato-facts. The app's graph plots the ratio of facts served by a given Kubernetes ReplicaSet.

CDaaS has deployed a new ReplicaSet with only one pod to achieve a 25/75% traffic split between application versions. The ratio of facts served by ReplicaSet backends in the graph should roughly match this 25/75% split.

Once you're ready to continue, return to Cloud Console to approve the prod deployment. CDaaS will fully shift traffic to the new application version and tear down the previous application version.

Deployment YAML

Now that you've used CDaaS to deploy to two environments, let's break down CDaaS's deployment YAML. You can find the full specification on our docs site.

targets

In CDaaS, a target is an (account, namespace) pair where account is the name of your agent identifier.

When deploying to multiple targets, you can specify dependencies between targets using the constraints.dependsOn field. In the case of this tutorial, the prod deployment will start only when the staging deployment has completed successfully.

targets:
  staging:
    # Account is optional when passed as a CLI flag (--account).
    # It's also required if you'd like to deploy to multiple Kubernetes clusters.
    # account: <my-agent-identifier> 
    namespace: potato-facts-staging
    strategy: rolling
  prod:
    namespace: potato-facts-prod
    strategy: trafficSplit
    constraints:
      dependsOn: ["staging"]
      beforeDeployment:
        - pause:
            untilApproved: true

manifests

CDaaS can deploy any Kubernetes manifest. You do not need to alter your manifests or apply any special annotations to use CDaaS.

By default, the manifests defined in path will be deployed to all of your targets. If you want to restrict the targets where a manifest should be deployed, use the manifests.targets field.

A path can be a path to an individual file or a directory. Each file can contain one or more Kubernetes manifests.

manifests:
  - path: ./manifests/potato-facts-v1.yaml
  - path: ./manifests/potato-facts-service.yaml
  - path: ./manifests/staging-namespace.yaml
    targets: ["staging"]
  - path: ./manifests/prod-namespace.yaml
    targets: ["prod"]

strategies

A strategy defines how manifests are deployed to a target.

A canary-type strategy is a linear sequence of steps. The setWeight step defines the ratio of traffic between application versions. This tutorial will introduce other step types later on.

CDaaS integrates with service meshes like Istio and Linkerd, but you do not need to use a service mesh to use a CDaaS canary strategy.

strategies:
  rolling:
    canary:
      steps:
        # This strategy immediately flips all traffic to the new application version.
        - setWeight:
            weight: 100
  trafficSplit:
    canary:
      steps:
        - setWeight:
            weight: 25
        - exposeServices:
            services:
              - potato-facts
            ttl:
              duration: 2
              unit: hours
        - pause:
            untilApproved: true
        - setWeight:
            weight: 100

Clean Up

You can clean up the resources created by this tutorial with kubectl:

kubectl delete ns potato-facts-staging potato-facts-prod