Deployment Reference

Create a deployment config file to use with Armory CD-as-a-Service. Browse the deployment config file reference. Learn how to configure preview links and role-based manual approvals.

Deployment config file reference overview

The deployment config file is what you use to define how and where Armory CD-as-a-Service deploys your app.

Make sure you have installed the CD-as-a-Service CLI, which you can use to generate a deployment template.

Templates

You can generate a Kubernetes deployment config file template by running the following command with the CLI:

Basic template:

armory template kubernetes [command]

where command is the type of template.

Automated canary analysis template:

armory template kubernetes canary -f automated

Blue/green deployment template:

armory template kubernetes bluegreen

To use a template, output it to a file and modify it to suit your needs:

armory template kubernetes [template-type] > deployment-template.yaml

How to create a deployment config file

Create a YAML file with this basic content:

version: v1
kind: lambda
application: <application-name>
strategies:
  canary:
    steps:
      - setWeight:
          weight: 100
targets:
  <target-name>:
    account: <aws-account-name>
    deployAsIamRole: <armory-role-arn>
    region: <aws-region>
    strategy: canary
artifacts:
  - functionName: <function-name>
    path: <s3-path-to-function-zip>
    type: zipFile
providerOptions:
 lambda:
   - target: <target-name>
     name: <function-name>   
     runAsIamRole: <execution-role-arn>
     handler: <handler-function>
     runtime: <runtime>

These sections are the minimum you need to declare to deploy an AWS Lambda function.

Customize your deployment file by setting the following minimum set of parameters:
- application: The name of your function. This appears in the Deployments list page.
- targets.<target-name>: A descriptive name for your deployment.
  - account: A descriptive name for the AWS Account this target resides in, such as armory-docs-dev.
  - deployAsIamRole: The ARN of the ArmoryRole that CD-as-a-Service assumes to deploy your function.
  - region: The AWS Region to deploy your function to.
- artifacts
  - functionName: A unique name for each entry in the artifacts collection.
  - path: The S3 path to your function’s zip file.
- providerOptions.lambda
  - target: CD-as-a-Service deployment target name
  - name: This is the same value as artifacts.functionName and trafficManagement.alias.functionName for the target region. This function name appears on your AWS Lambda Functions list page.
  - runAsIamRole: Replace <execution-role-arn> with the ARN of your AWS Lambda execution role, which is not the ArmoryRole ARN.
  - handler: The function’s handler method, such as index.handler. This value is written to the Runtime settings section in the AWS Lambda function details page.
  - runtime: runtime identifier, such as python3.22 or nodejs18.x. This value is written to the Runtime settings section in the AWS Lambda function details page.
(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 yamllint that you can use to validate your deployment file.

You can view detailed configuration options in the Deployment Config File Reference section.

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 canary.yaml:
```
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 agentIdentifier parameter.
- targets.<deploymentName>.strategy: the name of the deployment strategy you want to use. You define the strategy in strategies.<strategy-name>.
- 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 targets.<target-cluster>.strategy.
  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 strategies 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 top-level section:
```
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 yamllint that you can use to validate your deployment file.

You can view detailed configuration options in the Deployment Config File Reference section.

Deployment config file examples

AWS Lambda

Expand to see a skeleton config file for a deployment to AWS Lambda. All all config options are listed for each section.

Click to view a skeleton deployment config file

---
version: v1
kind: lambda
application: <application-name>
targets:
  <targetName>:
    account: <account-name>
    region: <aws-region>
    deployAsIamRole: <Armory-Role-arn>
    strategy: <strategy-name>
    constraints:
      dependsOn:
        - <target-name>
        - <target-name>
artifacts:
  - functionName: <function-name>
    path: <path-to-function>  # S3 bucket
    type: zipFile
providerOptions:
  lambda:
    - handler: <function-handler>  # typically index.handler
      name: <function-name>
      runAsIamRole: <lambda-execution-role>
      runtime: <function-runtime>  # nodejs18.x, Python, etc
      target: <target-name>
strategies:
  <strategy-name>:
    canary:
      steps:
        - pause:
            duration: <integer>
            unit: <seconds|minutes|hours>
        - setWeight:
            weight: 100
        - runWebhook:
            name: <webhook-name>
trafficManagement:
  - targets: ["<target-name>"]
    alias:
      - functionName: <function-name>
        aliasName: <alias-name>
analysis:
  defaultMetricProviderName: <provider-name>
  queries:
    - name: <query-name>
      upperLimit: <integer>
      lowerLimit: <integer>
      queryTemplate: >-
                <query>
webhooks:
  - name: <webhook-name>
    method: <endpoint-method-type>
    uriTemplate: <endpoint-uri>
    networkMode: <network-mode>
    agentIdentifier: <remote-network-agent-id>
    headers:
      - key: Authorization
        value: <auth-type-and-value>
      - key: Content-Type
        value: application/json
    bodyTemplate:
      inline: >-
        {
          "event_type": "<event-type>",
          "client_payload": {
            "callbackUri": "{{armory.callbackUri}}/callback"
            }
        }        
    retryCount: <num-retries>
deploymentConfig:
  timeout:
    unit: <seconds|minutes|hours>
    duration: <integer>

Kubernetes

Expand to see a skeleton config file for a deployment to Kubernetes. All all config options are listed for each section.

Click to view a skeleton deployment config file

---
version: v1
kind: kubernetes
application: <application-name>
targets:
  <targetName>:
    account: <account-name>
    namespace: <namespace-override>
    strategy: <strategy-name>
    constraints:
      dependsOn: ["<target-name>", "<target-name>"]
      beforeDeployment:
        - pause:
            untilApproved: true
            requiresRoles:
              - <role-name>
            approvalExpiration:
              duration: <integer>
              unit: <seconds|minutes|hours>
        - pause:
            duration: <integer>
            unit: <seconds|minutes|hours>
        - runWebhook:
            name: <webhook-name>
        - analysis:
            metricProviderName: <metric-provider-name>
            context:
              keyName: <value>
            interval: <integer>
            units: <seconds|minutes|hours>
            numberOfJudgmentRuns: <integer>
            rollBackMode: <manual|automatic>
            rollForwardMode: <manual|automatic>
            queries:
              - <queryName1>
              - <queryName2>
      afterDeployment:
        - pause:
            untilApproved: true
            requiresRoles:
              - <role-name>
            approvalExpiration:
              duration: <integer>
              unit: <seconds|minutes|hours>
        - pause:
            duration: <integer>
            unit: <seconds|minutes|hours>
        - runWebhook:
            name: <webhook-name>
        - analysis:
            metricProviderName: <metric-provider-name>
            context:
              keyName: <value>
            interval: <integer>
            units: <seconds|minutes|hours>
            numberOfJudgmentRuns: <integer>
            rollBackMode: <manual|automatic>
            rollForwardMode: <manual|automatic>
            queries:
              - <queryName1>
              - <queryName2>
manifests:
  - path: <path-to-manifest-or-directory>
  - path: <path-to-manifest-or-directory>
    targets:
      - <target-name>
strategies:
  myCanary:
    canary:
      steps:
        - setWeight:
            weight: <integer>
        - analysis:
            metricProviderName: <metric-provider-name>
            context:
              keyName1: <value>
              keyName2: <value>
            interval: <integer>
            units: <seconds|minutes|hours>
            numberOfJudgmentRuns: <integer>
            rollBackMode: <manual|automatic>
            rollForwardMode: <manual|automatic>
            queries:
              - <queryName1>
              - <queryName2>
        - runWebhook:
            name: <webhook-name>
        - pause:
            duration: <integer>
            unit: <seconds|minutes|hours>
        - setWeight:
            weight: <integer>
        - exposeServices:
            services:
              - <service-1>
              - <service-2>
              - <service-n>
            ttl:
              duration: <integer>
              unit: <seconds|minutes|hours>
        - analysis:
            metricProviderName: <metric-provider-name>
            context:
              keyName1: <value>
              keyName2: <value>
            interval: <integer>
            units: <seconds|minutes|hours>
            numberOfJudgmentRuns: <integer>
            rollBackMode: <manual|automatic>
            rollForwardMode: <manual|automatic>
            queries:
              - <queryName1>
              - <queryName2>
        - pause:
            untilApproved: true
            requiresRoles:
              - <role-name>
            approvalExpiration:
              duration: <integer>
              unit: <seconds|minutes|hours>
        - setWeight:
            weight: <integer>
  myBlueGreen:
    blueGreen:
      activeService: <active-service-name>
      previewService: <preview-service-name>
      redirectTrafficAfter:
        - runWebhook:
            name: CheckLogs
        - analysis:
            metricProviderName: <metric-provider-name>
            context:
              keyName1: <value>
              keyName2: <value>
            interval: <integer>
            units: <seconds|minutes|hours>
            numberOfJudgmentRuns: <integer>
            rollBackMode: <manual|automatic>
            rollForwardMode: <manual|automatic>
            queries:
              - <queryName1>
              - <queryName2>
        - pause:
            duration: <integer>
            unit: <seconds|minutes|hours>
        - exposeServices:
            services:
              - <service-1>
              - <service-2>
              - <service-n>
            ttl:
              duration: <integer>
              unit: <seconds|minutes|hours>
      shutDownOldVersionAfter:
        - pause:
            untilApproved: true
            approvalExpiration:
              duration: <integer>
              unit: <seconds|minutes|hours>
              requiresRoles:
                - <role-name>
        - pause:
            duration: <integer>
            unit: <seconds|minutes|hours>
        - analysis:
            metricProviderName: <metric-provider-name>
            context:
              keyName1: <value>
              keyName2: <value>
            interval: <integer>
            units: <seconds|minutes|hours>
            numberOfJudgmentRuns: <integer>
            rollBackMode: <manual|automatic>
            rollForwardMode: <manual|automatic>
            queries:
              - <queryName>
analysis:
  defaultMetricProviderName: <provider-name>
  queries:
    - name: <query-name>
      upperLimit: <integer>
      lowerLimit: <integer>
      queryTemplate: >-
                <query>
webhooks:
  - name: <webhook-name>
    method: <endpoint-method-type>
    uriTemplate: <endpoint-uri>
    networkMode: <network-mode>
    agentIdentifier: <remote-network-agent-id>
    headers:
      - key: Authorization
        value: <auth-type-and-value>
      - key: Content-Type
        value: application/json
    bodyTemplate:
      inline: >-
        {
          "event_type": "<event-type>",
          "client_payload": {
            "callbackUri": "{{armory.callbackUri}}/callback"
            }
        }        
    retryCount: <num-retries>
deploymentConfig:
  keepDeploymentObject: <true|false>
  timeout:
    unit: <seconds|minutes|hours>
    duration: <integer>

What’s next

Feedback

Was this page helpful?

Thank you for letting us know!

Sorry to hear that. Please tell us how we can improve.

Last modified November 27, 2023: (803ecce)