Cloud customer?
Start for Free >
Upgrade in MyJFrog >
What's New in Cloud >

Search





Overview

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.

Page Contents


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 pertinent tags:

Tag

Description of usage

Required/Optional

integrationsMust specify a VmCluster resource.Required
inputResources 

Must specify a FileSpecBuildInfo 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
sshUserThe 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.

 NameDescription 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. 

Supported for blueGreen strategy only.

current_commandThe 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:

TagDescription of usageRequired/Optional
onStartCommands to execute in advance of the native operationOptional
onSuccessCommands to execute on successful completionOptional
onFailureCommands to execute on failed completionOptional
onCompleteCommands to execute on any completionOptional

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)
  • No labels
Copyright © 2021 JFrog Ltd.