LinuxVMDeploy

JFrog Pipelines Documentation
Products
JFrog Pipelines
Content Type
User Guide
ft:sourceType
Paligo

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)