jobs.deployment.strategy.runOnce definition

The runOnce deployment strategy rolls out changes by executing each of its steps one time.

runOnce:
  preDeploy:  # Pre deploy hook for runOnce deployment strategy
    steps: [ task | script | powershell | pwsh | bash | checkout | download | downloadBuild | getPackage | publish | template | restoreCache | saveCache | reviewApp ]
    pool: pool # Pool where pre deploy steps will run
  deploy:  # Deploy hook for runOnce deployment strategy
    steps: [ task | script | powershell | pwsh | bash | checkout | download | downloadBuild | getPackage | publish | template | restoreCache | saveCache | reviewApp ]
    pool: pool # Pool where deploy steps will run
  routeTraffic:  # Route traffic hook for runOnce deployment strategy
    steps: [ task | script | powershell | pwsh | bash | checkout | download | downloadBuild | getPackage | publish | template | restoreCache | saveCache | reviewApp ]
    pool: pool # Pool where route traffic steps will run
  postRouteTraffic:  # Post route traffic hook for runOnce deployment strategy
    steps: [ task | script | powershell | pwsh | bash | checkout | download | downloadBuild | getPackage | publish | template | restoreCache | saveCache | reviewApp ]
    pool: pool # Pool where post route traffic steps will run
  on:  # On success or failure hook for runOnce deployment strategy
    failure:  # Runs on failure of any step
      steps: [ task | script | powershell | pwsh | bash | checkout | download | downloadBuild | getPackage | publish | template | restoreCache | saveCache | reviewApp ]
      pool: pool # Pool where post on failure steps will run
    success:  # Runs on success of all of the steps
      steps: [ task | script | powershell | pwsh | bash | checkout | download | downloadBuild | getPackage | publish | template | restoreCache | saveCache | reviewApp ]
      pool: pool # Pool where on success steps will run

Properties that use this definition: jobs.deployment.strategy.runOnce

Properties

preDeploy

preDeployHook

Pre deploy hook for runOnce deployment strategy.

deploy

deployHook

Deploy hook for runOnce deployment strategy.

routeTraffic

routeTrafficHook

Route traffic hook for runOnce deployment strategy.

postRouteTraffic

postRouteTrafficHook

Post route traffic hook for runOnce deployment strategy.

on

onSuccessOrFailureHook

On success or failure hook for runOnce deployment strategy.

runOnce:
  preDeploy:  # Pre deploy hook for runOnce deployment strategy
    steps: [ task | script | powershell | pwsh | bash | checkout | download | downloadBuild | getPackage | publish | template | restoreCache | saveCache | reviewApp ]
    pool: pool # Pool where pre deploy steps will run
  deploy:  # Deploy hook for runOnce deployment strategy
    steps: [ task | script | powershell | pwsh | bash | checkout | download | downloadBuild | getPackage | publish | template | restoreCache | saveCache | reviewApp ]
    pool: pool # Pool where deploy steps will run
  routeTraffic:  # Route traffic hook for runOnce deployment strategy
    steps: [ task | script | powershell | pwsh | bash | checkout | download | downloadBuild | getPackage | publish | template | restoreCache | saveCache | reviewApp ]
    pool: pool # Pool where route traffic steps will run
  postRouteTraffic:  # Post route traffic hook for runOnce deployment strategy
    steps: [ task | script | powershell | pwsh | bash | checkout | download | downloadBuild | getPackage | publish | template | restoreCache | saveCache | reviewApp ]
    pool: pool # Pool where post route traffic steps will run
  on:  # On success or failure hook for runOnce deployment strategy
    failure:  # Runs on failure of any step
      steps: [ task | script | powershell | pwsh | bash | checkout | download | downloadBuild | getPackage | publish | template | restoreCache | saveCache | reviewApp ]
      pool: pool # Pool where post on failure steps will run
    success:  # Runs on success of all of the steps
      steps: [ task | script | powershell | pwsh | bash | checkout | download | downloadBuild | getPackage | publish | template | restoreCache | saveCache | reviewApp ]
      pool: pool # Pool where on success steps will run

Properties that use this definition: jobs.deployment.strategy.runOnce

Properties

preDeploy

preDeployHook

Pre deploy hook for runOnce deployment strategy.

deploy

deployHook

Deploy hook for runOnce deployment strategy.

routeTraffic

routeTrafficHook

Route traffic hook for runOnce deployment strategy.

postRouteTraffic

postRouteTrafficHook

Post route traffic hook for runOnce deployment strategy.

on

onSuccessOrFailureHook

On success or failure hook for runOnce deployment strategy.

runOnce:
  preDeploy:  # Pre deploy hook for runOnce deployment strategy
    steps: [ task | script | powershell | pwsh | bash | checkout | download | downloadBuild | getPackage | publish | template | restoreCache | saveCache | reviewApp ]
    pool: pool # Pool where pre deploy steps will run
  deploy:  # Deploy hook for runOnce deployment strategy
    steps: [ task | script | powershell | pwsh | bash | checkout | download | downloadBuild | getPackage | publish | template | restoreCache | saveCache | reviewApp ]
    pool: pool # Pool where deploy steps will run
  routeTraffic:  # Route traffic hook for runOnce deployment strategy
    steps: [ task | script | powershell | pwsh | bash | checkout | download | downloadBuild | getPackage | publish | template | restoreCache | saveCache | reviewApp ]
    pool: pool # Pool where route traffic steps will run
  postRouteTraffic:  # Post route traffic hook for runOnce deployment strategy
    steps: [ task | script | powershell | pwsh | bash | checkout | download | downloadBuild | getPackage | publish | template | restoreCache | saveCache | reviewApp ]
    pool: pool # Pool where post route traffic steps will run
  on:  # On success or failure hook for runOnce deployment strategy
    failure:  # Runs on failure of any step
      steps: [ task | script | powershell | pwsh | bash | checkout | download | downloadBuild | getPackage | publish | template | restoreCache | saveCache | reviewApp ]
      pool: pool # Pool where post on failure steps will run
    success:  # Runs on success of all of the steps
      steps: [ task | script | powershell | pwsh | bash | checkout | download | downloadBuild | getPackage | publish | template | restoreCache | saveCache | reviewApp ]
      pool: pool # Pool where on success steps will run

Properties that use this definition: jobs.deployment.strategy.runOnce

Properties

preDeploy

preDeployHook

Pre deploy hook for runOnce deployment strategy.

deploy

deployHook

Deploy hook for runOnce deployment strategy.

routeTraffic

routeTrafficHook

Route traffic hook for runOnce deployment strategy.

postRouteTraffic

postRouteTrafficHook

Post route traffic hook for runOnce deployment strategy.

on

onSuccessOrFailureHook

On success or failure hook for runOnce deployment strategy.

Remarks

runOnce is the simplest deployment strategy wherein all the lifecycle hooks, namely preDeploy deploy, routeTraffic, and postRouteTraffic, are executed once. Then, either on: success or on: failure is executed.

Descriptions of lifecycle hooks

preDeploy: Used to run steps that initialize resources before application deployment starts.

deploy: Used to run steps that deploy your application. Download artifact task will be auto injected only in the deploy hook for deployment jobs. To stop downloading artifacts, use - download: none or choose specific artifacts to download by specifying Download Pipeline Artifact task.

routeTraffic: Used to run steps that serve the traffic to the updated version.

postRouteTraffic: Used to run the steps after the traffic is routed. Typically, these tasks monitor the health of the updated version for defined interval.

on: failure or on: success: Used to run steps for rollback actions or clean-up.

Examples

The following example YAML snippet showcases a simple use of a deployment job by using the runOnce deployment strategy. The example includes a checkout step.


jobs:
  # Track deployments on the environment.
- deployment: DeployWeb
  displayName: deploy Web App
  pool:
    vmImage: ubuntu-latest
  # Creates an environment if it doesn't exist.
  environment: 'smarthotel-dev'
  strategy:
    runOnce:
      deploy:
        steps:
        - checkout: self 
        - script: echo my first deployment

With each run of this job, deployment history is recorded against the smarthotel-dev environment.

Note

  • It's also possible to create an environment with empty resources and use that as an abstract shell to record deployment history, as shown in the previous example.

The next example demonstrates how a pipeline can refer both an environment and a resource to be used as the target for a deployment job.

jobs:
- deployment: DeployWeb
  displayName: deploy Web App
  pool:
    vmImage: ubuntu-latest
  # Records deployment against bookings resource - Kubernetes namespace.
  environment: 'smarthotel-dev.bookings'
  strategy: 
    runOnce:
      deploy:
        steps:
          # No need to explicitly pass the connection details.
        - task: KubernetesManifest@0
          displayName: Deploy to Kubernetes cluster
          inputs:
            action: deploy
            namespace: $(k8sNamespace)
            manifests: |
              $(System.ArtifactsDirectory)/manifests/*
            imagePullSecrets: |
              $(imagePullSecret)
            containers: |
              $(containerRegistry)/$(imageRepository):$(tag)

This approach has the following benefits:

  • Records deployment history on a specific resource within the environment, as opposed to recording the history on all resources within the environment.
  • Steps in the deployment job automatically inherit the connection details of the resource (in this case, a Kubernetes namespace, smarthotel-dev.bookings), because the deployment job is linked to the environment. This is useful in the cases where the same connection detail is set for multiple steps of the job.

See also