LinuxVMDeploy

Deprecated

This native step has been deprecated.

The LinuxVMDeploy native step uploads files to VMs in a VmCluster resource and runs commands on the VMs. If all deployments are successful, a copy of the deploy artifacts are stored in the ${HOME}/${step_name}/rollback on each VM. The file(s) may be provided in a FileSpec, BuildInfo or ReleaseBundle.

YAML Schema

The YAML schema for LinuxVMDeploy native step is as follows:

LinuxVMDeploy

pipelines: 
  - name:   <string>
    steps:
      - name: myLinuxVMDeployStep
        type: LinuxVMDeploy
        configuration:
          environmentVariables:
            dry_run:                 <string> # optional
                        deploy_targets_override: <string> # optional
          targetDirectory:           <string> # optional
          rolloutDelaySecs:          <integer> # optional
          fastFail:                  <boolean> # optional
          sshUser:                   <string> # required
          vmEnvironmentVariables:    <string[]> # optional
          strategy:                  <"rollingUpdate"|"blueGreen"> # optional; default "rollingUpdate"
          inputResources: 
            - name:                  <VMCluster resource> # 1 required (exacly 1, exactly 2 for blueGreen strategy).
            - name:                  <BuildInfo resource|FileSpec resource|ReleaseBundle resource> # required (exactly 1).
          scripts:
            - name:                  <string> # required
              context:               <"buildNode"|"targetCluster"|"currentCluster"> # required, "currentCluster" supported for blueGreen only.
              commands:              <string[]> # optional

Tags

name

An alphanumeric string (underscores are permitted) that identifies the step.

type

Must be LinuxVMDeploy for this step type.

configuration

Specifies all configuration selections for the step's execution environment. This step inherits the Bash/ PowerShell step configuration tags, including these pertinenttags:

Tag	Description of usage	Required/Optional
`integrations`	Must specify a VmCluster resource.	Required
`inputResources`	Must specify a FileSpec, BuildInfo or ReleaseBundle resource containing the file(s) to be uploaded. Exactly one must be specified.	Required

In addition, these tags can be defined to support the step's native operation:

Tag	Description of usage	Required/Optional
`sshUser`	The ssh user used to connect to target VMs.	Required
`targetDirectory`	Path of the directory where the deploy artifacts will be uploaded. The directory will be created if it does not exist. Default directory is `<sshUser's $HOME>/$step_name/$run_id`.	Optional
`vmEnvironmentVariables`	These variables will be exported on target VMs.	Optional
`rolloutDelaySecs`	Time in seconds to wait between deploys.	Optional
`fastFail`	If `true`, the step will not deploy to additional VMs after the first failure. Default is `true`.	Optional
strategy	The release strategy to be used. It can be either `rollingUpdate` or `blueGreen`. `rollingUpdate`: Deploy to each VM in one cluster, one after the other. `blueGreen`: Deploy to one of two VmCluster resources, swapping clusters each time the LinuxVMDeploy step runs.	Optional
`scripts`	User-defined commands to run on a given context. `name:` name for the command. `context:` where the script should run. `buildNode` runs on the build node. `targetCluster` runs on the supplied vmCluster.	Required

environment variables

The following environment variables are available for user-defined scripts written in the LinuxVMDeploy step.

Name	Description of usage
`target_cluster`	The name of the VM cluster being deployed to.
`current_cluster`	The name of the VM cluster that was last deployed to. Note Supported for `blueGreen` strategy only.
`current_command`	The name of the command that was running when the step exited. This should be blank if no user-defined command was running.

execution

Declares collections of shell command sequences to perform for pre- and post-execution phases:

Tag	Description of usage	Required/Optional
`onStart`	Commands to execute in advance of the native operation	Optional
`onSuccess`	Commands to execute on successful completion	Optional
`onFailure`	Commands to execute on failed completion	Optional
`onComplete`	Commands to execute on any completion	Optional

The actions performed for the onExecute phase are inherent to this step type and may not be overridden.

Examples

The following examples show a few ways in which a LinuxVMDeploy step can be configured.

Uploading an App in a FileSpec Resource to VMs and Running It

The most basic form of LinuxVMDeploy. Uses all default values. The step will upload files to the default targetDirectory and run a deploy command.

LinuxVMDeploy

resources:
  - name: myApplication
    type: FileSpec
    configuration:
      sourceArtifactory: myArtifactory
      pattern: "example-repo-local/myApp"
  - name: myVM
    type: VmCluster
    configuration:
      sshKey: mySSHKey
      targets:
        - 0.0.0.0
        - 1.1.1.1
pipelines: 
  - name: linuxVMDeployPipeline
    steps:
      - name: linuxVMDeploy
        type: LinuxVMDeploy
        configuration:
          inputResources:
            - name: myVM
            - name: myApplication
          scripts:
            - name: deployCommand
              context: targetCluster 
              commands:
                - "./myApp"

Uploading an App in a BuildInfo Resource to VMs, Running postDeploy command, and Handling Rollback.

Upload a BuildInfo resource and try to run deployCommand and postDeploy commands. If deployCommand succeeds, then postDeploy will run. If there is a failure on a VM (in case a command or postDeploy did not succeed), then rollbackCommand will run on any VM that deployed successfully.

LinuxVMDeploy

resources:
  - name: myApplication
    type: BuildInfo
    configuration:
      sourceArtifactory: myArtifactory
      buildName: myBuild
      buildNumber: 1
  - name: myVM
    type: VmCluster
    configuration:
      sshKey: mySSHKey
      targets:
        - 0.0.0.0
        - 1.1.1.1
pipelines: 
  - name: linuxVMDeployPipeline
    steps:
      - name: linuxVMDeploy
        type: LinuxVMDeploy
        configuration:
          inputResources:
            - name: myVM
            - name: myApplication
          sshUser: myUser
                  scripts:
            - name: deployCommand
              context: targetCluster 
              commands:
                - "./myApp"
          onFailure:
            - 'if [ "$current_command" == "deployCommand" ]; then ./doRollback.sh fi'

Overriding VmCluster Targets

In this example, a VmCluster resource is supplied alongside deploy_targets_override environment variable. Artifacts will be deployed to the targets specified in deploy_targets_override. The ssh keys from the VmCluster resource will still be used.

LinuxVMDeploy

resources:
  - name: myApplication
    type: FileSpec
    configuration:
      sourceArtifactory: myArtifactory
      pattern: "example-repo-local/myApp"
  - name: myVM
    type: VmCluster
    configuration:
      sshKey: s_VM_DEPLOY_SSHKEY
      targets:
        - 0.0.0.0
        - 1.1.1.1
pipelines:
  - name: linuxVMDeployPipeline
    steps:
      - name: linuxVMDeploy
        type: LinuxVMDeploy
        configuration:
          environmentVariables:
                        deploy_targets_override: "123.456.78.90,127.0.0.1"
          inputResources:
            - name: myVM
            - name: myApplication
          sshUser: myUser
          scripts:
            - name: deployCommand
              context: targetCluster 
              commands:
                - "./myApp"

Passing Environment Variables to Commands Run on the VM

In this example, a VmCluster resource is supplied with vmEnvironmentVariables. These variables will be available to user-defined commands running on the targetCluster.

LinuxVMDeploy

resources:
  - name: myApplication
    type: FileSpec
    configuration:
      sourceArtifactory: myArtifactory
      pattern: "example-repo-local/myApp"
  - name: myVM
    type: VmCluster
    configuration:
      sshKey: s_VM_DEPLOY_SSHKEY
      targets:
        - 0.0.0.0
        - 1.1.1.1
pipelines: 
  - name: linuxVMDeployPipeline
    steps:
      - name: linuxVMDeploy
        type: LinuxVMDeploy
        configuration:
          vmEnvironmentVariables:
            - "LOG_LEVEL=DEBUG"
          inputResources:
            - name: myVM
            - name: myApplication
          sshUser: myUser
          scripts:
            - name: deployCommand
              context: targetCluster 
              commands:
                - "./myApp $LOG_LEVEL"

Setting up a blueGreen Deploy Strategy

In this example, two VmCluster resources are supplied and a strategy of blueGreen is specified. Each time the step runs, targetCluster and currentCluster swap between the two supplied VmCluster resources.

LinuxVMDeploy

resources:
  - name: myApplication
    type: FileSpec
    configuration:
      sourceArtifactory: myArtifactory
      pattern: "example-repo-local/myApp"
  - name: myVM
    type: VmCluster
    configuration:
      sshKey: s_VM_DEPLOY_SSHKEY
      targets:
        - 0.0.0.0
        - 1.1.1.1
pipelines: 
  - name: linuxVMDeployPipeline
    steps:
      - name: linuxVMDeploy
        type: LinuxVMDeploy
        configuration:
          vmEnvironmentVariables:
            - "LOG_LEVEL=DEBUG"
          inputResources:
            - name: myBlueCluster
            - name: myGreenCluster
            - name: myApplication
          sshUser: myUser
          strategy: blueGreen
          scripts:
            - name: deployCommand
              context: targetCluster 
              commands:
                - "./myApp $LOG_LEVEL"
                        - name: cleanupCommand
              context: currentCluster 
              commands:
                - "./stopApp"
            - name: swapCluster
              context: buildNode
              commands:
                - "./swapLoadBalancer $target_cluster"

How it Works

When you use the LinuxVMDeploy native step in a pipeline, it performs the following functions in the background:

jfrog rt download (download files from FileSpec, BuildInfo or ReleaseBundle)
tar (compress all files to be uploaded to VMs)
scp (upload compressed artifacts to VMs)
ssh"mkdir -p" (create the targetDirectory if it does not exist)
Script commands run on target VMs via ssh or on the build node itself if context is "buildNode".
- Commands run in the order they were written in the yaml.
- Commands running on the target cluster will have access to variables defined in vmEnvironmentVariables.
- A rollback archive is created on the targetCluster (only happens when entire step succeeds)
  - Rollback directory location: /home/$ssh_user/LinuxVMDeploy/rollback
  - mkdir -p (create rollback directory if it does not exist).
  - rm -rf $rollbackDirectory/* (remove any old rollback artifacts)
  - cp -r $targetDirectory/* $rollbackDirectory (copy all uploaded artifacts to rollback archive)

Deprecated

YAML Schema

Tags

name

type

configuration

environment variables

Note

execution

Examples

Uploading an App in a FileSpec Resource to VMs and Running It

Uploading an App in a BuildInfo Resource to VMs, Running postDeploy command, and Handling Rollback.

Overriding VmCluster Targets

Passing Environment Variables to Commands Run on the VM

Setting up a blueGreen Deploy Strategy

How it Works