Deploy Your Own App to Kubernetes

Use a canary strategy to deploy two versions of your app to your Kubernetes cluster with Armory CD-as-a-Service. Install the CLI, connect your cluster, create a deployment config file, and deploy your app to two environments.

Learning objectives

If you prefer a web-based, interactive tutorial, see the CD-as-a-Service Console’s Deploy Your Own App tutorial.

In this guide, you create a deployment config that declares two strategies to deploy your own app to “staging” and “prod” namespaces in your Kubernetes cluster.

  1. Sign up for CD-as-a-Service.
  2. Install the CD-as-as-Service CLI on your Mac, Linux, or Windows workstation.
  3. Connect your Kubernetes cluster to CD-as-a-Service.
  4. Create the directory structure that you use for this guide.
  5. Create Namespace manifests to simulate deploying to different targets.
  6. Create a deployment config file and learn config file syntax.
  7. Deploy your app and monitor its progress, observe a traffic split, and preview your v2 app from a link in the UI.
  8. Clean up resources created for this guide.

Before you begin

  • You have created the Kubernetes manifests for your web app. These should include a Deployment and related Service. You use the Service name in your deployment config file’s trafficSplit canary strategy so that CD-as-a-Service can create a preview link for your app.
  • You have two versions of your app to deploy.
  • You have access to a Kubernetes cluster. If you need a cluster, consider installing a local Kind or Minikube cluster. Your cluster’s API endpoint does not need to be publicly accessible to use CD-as-a-Service.

Sign up for CD-as-a-Service

Access the registration screen to create an account. Fill in the required fields. When you’re done, click Create Account.

When you create your account, CD-as-a-Service does the following:

  • Creates an Organization for your company
  • Creates a Tenant for the Organization
  • Creates a User account with an Organization Admin role for you.

See Identity & Access Management for details.

You may have to log in after creating your account.

The Welcome to Continuous Deployment-as-a-Service Configuration page lists the steps you need to complete to begin using Armory CD-as-a-Service.

Install the CD-as-as-Service CLI

brew tap armory-io/armory
brew install armory-cli

You can install the CLI with a one-line script that does the following:

  1. Fetches the correct Armory Version Manager binary (avm) for your operating system
  2. Installs the AVM binary
  3. Uses the AVM to install the CLI binary (armory)
  4. Adds the AVM and the CLI to the path in your bash or zsh profile

Execute the following script on the machine that has access to your Kubernetes cluster:

curl -sL | bash

After installation completes, you should start a new terminal session or source your profile.

  1. Download the AVM for your operating system and CPU architecture. You can manually download it from the repo or use the following command:

    curl -LO<os>-<architecture>

    For example, the following command downloads the latest version for macOS (Darwin):

    curl -LO

    You can see the full list of available releases in the repo.

    Note: You can also download AVM from the releases AWS S3 bucket:

    curl -LO
  2. Give AVM execute permissions. For example (on macOS):

    chmod +x avm-darwin-amd64
  3. Confirm that /usr/local/bin is on your PATH:

    echo $PATH

    The command returns your PATH, which should now include /usr/local/bin/.

  4. Rename the AVM binary to avm and move it to /usr/local/bin, which is on your PATH. For example (on macOS):

    mv avm-darwin-amd64 /usr/local/bin/avm
  5. Run the following command to install the CLI:

    avm install

    The command installs the CLI and returns a directory that you need to add to your path, such as /Users/milton/.avm/bin.

    If you get an developer cannot be identified error when trying to run AVM, you must allow AVM to run.

    Show me how to allow AVM to run.

    On macOS, go to System Preferences > Security & Privacy > General and click Allow Anyway.

    For more information, see the macOS documentation about how to open a Mac app from an unidentified developer.

  6. Add the directory that AVM returned when you ran avm install to your path.

    Show me how to add the directory.

    You can either add the path directly to /etc/paths or add it to your shell profile. The following steps describe how to add it to your shell profile:

    1. Edit the resource file for your shell, such as .bashrc, .bash_profile, or .zshrc. For example:

      vi ~/.bashrc
    2. In the file, find the line for the PATH that your resource file exports. They follow the format export PATH=$HOME/bin:/usr/local/bin:$PATH.

    3. Insert the path provided by AVM (such as /Users/brianle/.avm/bin) before the ending $PATH. The line should look similar to this:

      export PATH=$HOME/bin:/usr/local/bin::/Users/milton/.avm/bin:$PATH
    4. Save the file.

    5. Reload your terminal, open a new session, or source your terminal profile file (for example, source .bash_profile).

  7. Run the following command to verify that the CLI is installed:


    The command returns basic information about the CLI, including available commands.

For the AVM or the CLI, you can use the -h flag for more information about specific commands.

Armory provides the CD-as-a-Service CLI as a Docker image.

docker pull armory/armory-cli

Download the latest armory-cli Windows executable from the repo Releases page. Install on the machine that has access to your Kubernetes cluster.

Log in with the CLI

armory login

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

Connect your cluster

CD-as-a-Service uses a Remote Network Agent (RNA) to execute deployments in your Kubernetes cluster. The installation process uses credentials from your ~/.kube/config file to install the RNA.

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

armory agent create

You name your agent during the installation process. This guide references that name as <your-agent-identifier>.

Create your directory structure

In this guide, you create a deployment config and two simple namespace configs. The namespace manifests should be in a manifests directory along with the Kubernetes manifests for deploying your app.

The directory structure should look like this:

├── deployment.yaml  # created as part of this guide
└── manifests
    ├── <your-app-service>.yaml
    ├── <your-app>.yaml
    ├── namespace-staging.yaml  # created as part of this guide
    └── namespace-prod.yaml     # created as part of this guide

Create Namespace manifests

To illustrate deploying to different targets, you deploy to two namespaces in the same cluster. In production, you would deploy to different clusters.

Create two manifests, one for staging (namespace-staging.yaml) and the other for prod (namespace-prod.yaml). Save these to the manifests directory.


apiVersion: v1
kind: Namespace
  name: staging-ns

apiVersion: v1
kind: Namespace
  name: prod-ns

Create a deployment config file

Next, create your deployment config file.

Learn deployment file syntax


In CD-as-a-Service, a target is an (account, namespace) pair where account is the agent identifier you created when you connected your cluster.

When deploying to multiple targets, you can specify dependencies between targets using the constraints.dependsOn field. In this guide, the prod deployment starts only after the staging deployment has completed successfully, and you have manually approved deployment to prod.


CD-as-a-Service can deploy any Kubernetes manifest. You do not need to alter your manifests or apply any special annotations.

By default, CD-as-a-Service deploys all the manifests defined in path 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 a directory or to an individual file. Each file may contain one or more Kubernetes manifests.


A strategy defines how CD-as-a-Service deploys manifests to a target.

A canary-type strategy is a linear sequence of steps. The setWeight step defines the ratio of traffic between app versions.

This config defines staging and prod deployment targets in the same cluster. The targets have different Namespaces. Deployment to prod depends on successful deployment to staging. The prod deployment requires a manual approval to begin deployment and another to continue deployment after the traffic split.

You can create deployment strategies with as many steps as you want. There are two strategies in this config:

  • rolling: deploy 100% of the app (staging deployment)
  • trafficSplit: 75% to the current version and 25% to the new version (prod deployment). In this section, you expose your Service in the trafficSplit.canary.steps.exposeServices section so CD-as-a-Service can create a preview link for you in the UI.

Save the following config as deployment.yaml in the root of your app directory, the same level as your manifests directory. Replace the bracketed values with your own.

version: v1
kind: kubernetes
application: <your-app-name> # the name of your app
    account: <your-agent-identifier>
    namespace: staging-ns # defined in namespace-staging.yaml
    strategy: rolling
    account: <your-agent-identifier>
    namespace: prod-ns # defined in namespace-prod.yaml
    strategy: trafficSplit
      dependsOn: ["staging"]
        - pause:
            untilApproved: true
  - path: manifests/<your-app>.yaml # replace with the name of your app manifest
  - path: manifests/<your-app-service>.yaml # replace with the name of your app service manifest
  - path: manifests/namespace-staging.yaml  
    targets: ["staging"]
  - path: manifests/namespace-prod.yaml
    targets: ["prod"]
        - setWeight:
            weight: 100
        - setWeight:
            weight: 25
        - exposeServices:
              - <your-app-service>
              duration: 30
              unit: minutes
        - pause:
            untilApproved: true
        - setWeight:
            weight: 100

Deploy your app

In order to see some deployment strategies at work, you need to deploy your app twice. The first time, CD-as-a-Service skips any traffic splitting or manual approval steps in order to fully deploy a stable version to prod. The second deployment demonstrates an advanced deployment strategy, routing only 25% of traffic to your new version, while routing the rest to the stable version.

Deploy the first version

  1. Start the deployment from the root of your directory.

    armory deploy start  -f deployment.yaml

    This command starts your deployment, and then returns a Deployment ID and a link to your deployment details.

  2. Monitor your deployment execution.

    Use the link provided by the CLI to view your deployment in the CD-as-a-Service Console Deployments screen.

    For more info on monitoring your deployment via the UI or CLI, see:

  3. Issue manual approval.

    Once CD-as-a-Service successfully deploys your resources to staging, it waits for your manual approval before deploying to prod. When the staging deployment has completed, click Approve to allow the prod deployment to begin.

    You must issue manual approvals using the UI. You cannot issue manual approvals using the CLI.

Deploy second version

When you deploy the second version of your app, CD-as-a-Service uses the trafficSplit canary strategy to route 25% of traffic to your new version. You can preview the new version from the link in the Resources area on the deployment details screen.

  1. Update your Kubernetes manifest to deploy a new version of your app.

  2. Start the deployment from the root of your directory.

    armory deploy start  -f deployment.yaml
  3. Monitor your deployment.

    Use the link provided by the CLI to navigate to your deployment in the CD-as-a-Service Console.

  4. Issue manual approval to begin prod deployment.

    Once the staging deployment has completed, click Approve to allow the prod deployment to begin. Once deployment begins, you can see the traffic split. CD-as-a-Service has deployed a new ReplicaSet with only one pod to achieve a 75/25% traffic split between app versions.

  5. Preview your app.

    Click the prod deployment to open the details window. You can find a link to your v2 app in the Resources section.

  6. Finish deployment.

    Return to the deployment details window. Click Approve & Continue to finish deployment. CD-as-a-Service fully shifts traffic to the new app version and tears down the previous app version.

Clean up

You can clean kubectl to clean up the app resources you created:

kubectl delete ns staging-ns prod-ns

To clean up the Remote Network Agent you installed:

kubectl delete ns armory-rna

What’s next

Last modified November 27, 2023: (803ecce)