Get Started with the CLI to Deploy Apps
Before you begin
- Make sure that your organization has completed the onboarding steps in Get Started with Armory CD-as-a-Service. That guide describes how to prepare your deployment target so that you can use the CLI to deploy apps to it.
- You have login credentials for Armory CD-as-a-Service.
Supported Operating SystemsThe Armory Version Manager and CLI are only supported on Linux and Mac OSX.
They do not run on Windows.
Install the CLI
You can run the CLI in Docker, or you can install the CLI on your Mac or Linux workstation.
Armory provides the CD-as-a-Service CLI as a Docker image.
docker pull armory/armory-cli
You can install the Armory Version Manager (AVM) and CLI using a one-line command or you can download the AVM manually.
The AVM enables you to quickly and easily download, install, and update the CLI. The AVM includes additional features such as the ability to list installed CLI versions and to declare which version of the CLI to use.
You can install the CLI with a one-line script that does the following:
- Fetches the correct Armory Version Manager binary (
avm) for your Linux or Mac OSX operating system
- Installs the AVM binary
- Uses the AVM to install the CLI binary (
- 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 go.armory.io/get-cli | bash
After installation completes, you should start a new terminal session or source your profile.
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 https://github.com/armory/avm/releases/latest/download/avm-<os>-<architecture>
For example, the following command downloads the latest version for macOS (Darwin):
curl -LO https://github.com/armory/avm/releases/latest/download/avm-darwin-amd64
You can see the full list of available releases in the repo.
Give AVM execute permissions. For example (on macOS):
chmod +x avm-darwin-amd64
/usr/local/binis on your
The command returns your
PATH, which should now include
Rename the AVM binary to
avmand move it to
/usr/local/bin, which is on your
PATH. For example (on macOS):
mv avm-darwin-amd64 /usr/local/bin/avm
Run the following command to install the CLI:
The command installs the CLI and returns a directory that you need to add to your path, such as
If you get an
developer cannot be identified errorwhen 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.
Add the directory that AVM returned when you ran
avm installto your path.
Show me how to add the directory.
You can either add the path directly to
/etc/pathsor add it to your shell profile. The following steps describe how to add it to your shell profile:
Edit the resource file for your shell, such as
.bash_profile, or .
zshrc. For example:
In the file, find the line for the
PATHthat your resource file exports. They follow the format
Insert the path provided by AVM (such as
/Users/brianle/.avm/bin) before the ending
$PATH. The line should look similar to this:
Save the file.
Reload your terminal, open a new session, or
sourceyour terminal profile file (for example,
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.
Create a deployment config file
Generate your deployment config template and output it to a file.
For example, this command generates a deployment template for canary deployments and saves it to a file named
armory template kubernetes canary > canary.yaml
Customize your deployment file by setting the following minimum set of parameters:
application: The name of your app.
targets.<deploymentName>: A descriptive name for your deployment. Armory recommends using the environment name.
targets.<deploymentName>.account: This is the name of your RNA. If you installed the RNA manually, it is the value that you assigned to the
targets.<deploymentName>.strategy: the name of the deployment strategy you want to use. You define the strategy in
manifests: a map of manifest locations. This can be a directory of
yaml (yml)files or a specific manifest. Each entry must use the following convention:
- path: /path/to/directory-or-file
strategies.<strategy-name>: the list of your deployment strategies. Use one of these for
If you are using a canary strategy, the strategy section consists of a map of steps for your canary strategy in the following format:
strategies: my-demo-strategy: # Name that you use for `targets.<deploymentName>.strategy - canary # The type of deployment strategy to use. steps: - setWeight: weight: <integer> # What percentage of the cluster to roll out the manifest to before pausing. - pause: duration: <integer> # How long to pause before deploying the manifest to the next threshold. unit: <seconds|minutes|hours> # The unit of time for the duration. - setWeight: weight: <integer> # The next percentage threshold the manifest should get deployed to before pausing. - pause: untilApproved: true # Wait until a user provides a manual approval before deploying the manifest
Each step can have the same or different pause behaviors. Additionally, you can configure as many steps as you want for the deployment strategy, but you do not need to create a step with a weight set to 100. Once CD-as-a-Service completes the last step you configure, the manifest is deployed to the whole cluster automatically. See the Canary fields section of the deployment file reference for more information.
(Optional) Configure a deployment timeout.
A deployment times out if the pods for your application fail to be in ready state in 30 minutes. You can optionally configure a deployment timeout by adding a
deploymentConfig: timeout: unit: <seconds|minutes|hours> duration: <integer>
Note that the minimum timeout you can specify is 60 seconds (1 minute). See the Deployment config section of the deployment file reference for more information.
(Optional) Ensure there are no YAML issues with your deployment file.
Since a hidden tab in your YAML can cause your deployment to fail, it’s a good idea to validate the structure and syntax in your deployment file. There are several online linters, IDE-based linters, and command line linters such as
yamllintthat you can use to validate your deployment file.
You can view detailed configuration options on the Deployment Config File Reference for CD-as-a-Service page.
Deploy your app
Armory CD-as-a-Service manages your Kubernetes deployments using ReplicaSet resources. During the initial deployment of your application using Armory CD-as-a-Service, the underlying Kubernetes deployment object is deleted in a way that it leaves behind the ReplicaSet and pods so that there is no actual downtime for your application. These are later deleted when the deployment succeeds.
Before you can deploy, make sure that you have the Client ID and Client Secret for your deployment target available. These are used to authenticate Armory’s hosted deployment services with the target cluster. The credentials were created and tied to your deployment target as part of the Get Started with Armory CD-as-a-Service guide.
Since you are using the CLI, you do not need to have service account credentials for authenticating your CLI to the deployment services. Instead, you log in manually with your user account.
If this is the first deployment of your app, Armory CD-as-a-Service automatically deploys the app to 100% of the cluster since there is no previous version. Subsequent deployments of this app follow the steps defined in your deployment file.
Log in to Armory’s hosted deployment services from the CLI.
The CLI returns a
Device Codeand opens your default browser. To complete the log in process, confirm the code in your browser.
After you successfully authenticate, the CLI returns a list of tenants if you have access to more than one. Select the tenant you want to access. Note that most users only have access to one tenant. If you have access to several tenants, you can can log in directly to your desired tenant with
armory login -e '<tenant>'.
Start the deployment.
armory deploy start -f canary.yaml
The command starts your deployment and progresses until the first weight and pause you set. It also returns a Deployment ID that you can use to check the status of your deployment and a link to the Deployments UI page for your deployment.
Note that you can deploy an app without manually logging into CD-as-a-Service. See the Deploy an App Using Credentials page for details.
If you want to monitor your deployment in your terminal, use the
--watchflag to output deployment status.
armory deploy start -f canary.yaml --watch
You can also monitor the progress of any deployment in the Deployments UI, which gives you a visual representation of a deployment’s health and progress. If your deployment strategy includes a manual approval step, use the Deployments UI to approve the step and continue your deployment.
If you forget to add the
--watchflag, you can run the
armory deploy status --deploymentID <deployment-id>command. Use the Deployment ID returned by the
armory deploy startcommand. For example:
armory deploy start -f deploy-simple-app.yml Deployment ID: 9bfb67e9-41c1-41e8-b01f-e7ad6ab9d90e See the deployment status UI: https://console.cloud.armory.io/deployments/pipeline/9bfb67e9-41c1-41e8-b01f-e7ad6ab9d90e?environmentId=82431eae-1244-4855-81bd-9a4bc165f90b
armory deploy status --deploymentId 9bfb67e9-41c1-41e8-b01f-e7ad6ab9d90e
Output is similar to:
application: sample-application, started: 2023-01-06T20:07:36Z status: RUNNING See the deployment status UI: https://console.cloud.armory.io/deployments/pipeline/9bfb67e9-41c1-41e8-b01f-e7ad6ab9d90e? environmentId=82431eae-1244-4855-81bd-9a4bc165f90b
armory deploy statuscommand returns a point-in-time status and exits. It does not watch the deployment.
Initial deployment failure
If the initial deployment of your app using Armory CD-as-a-Service fails or is manually rolled back, the ReplicaSet is orphaned rather than deleted. In this situation, you should manually delete the orphaned ReplicaSet only after the initial deployment runs successfully.
To delete the orphaned ReplicaSet:
Get a list of ReplicaSet objects
kubectl get rs -n <namespace>
Identify the ReplicaSet with the old version of your application. This is typically the ReplicaSet with the greater age.
Delete the orphaned ReplicaSet:
kubectl delete rs <ReplicaSet_name> -n <namespace>
Upgrade the CLI
Run the following command to upgrade your existing CLI:
- Troubleshoot CD-as-a-Service Tools
- Deployment Config File Reference for CD-as-a-Service
- CLI Cheatsheet
- Get Started with the GitHub Action to Deploy Apps
- Add New Context Variables at Deploy Time
- Deploy a Sample App Tutorial
Was this page helpful?
Thank you for letting us know!
Sorry to hear that. Please tell us how we can improve.
Last modified January 12, 2023: (f0e63a4)