A Cloud Deploy rollout includes phases. A phase is an ordered, logicalgrouping of jobs to do in a rollout.

Each phase includes jobs, which are the actions to take in each phase (forexample,deploy orverify). And each job can have zero or more job runs.A job run is an instance of a job. If the job hasn't run, there are no job runs.

This document describesphases,jobs, andjob runs, and how to manage them.

Structure of a rollout

A rollout is a Cloud Deploy resource that associates arelease with atarget.

Phases

A rollout consists of one or morephases.

For astandard deployment strategy, thereis only one phase:stable.

For acanary deployment strategy,There is a separate phase for each configured percentage. For example, if youconfigure a canary that deploys 25%, then 50%, then 100%, there will be threephases:

• canary-25
• canary-50
• stable

These phase names are standard:canary-[PERCENTAGE] for canary stages, andstable for the 100% phase. However, if you configure acustom-automated canary or custom canary, you cancontrol the phase names.

Jobs and job runs

Each rollout phase includes one or more jobs.

For a rollout in astandard deploymentstrategy, with no deployment verification enabled, there is one phase(stable).

For a canary rollout, there will be a phase for each part of the canary(for example,canary-25,canary-50,stable), and for each phase there is adeploy job. If verification is enabled, there is also averify job for eachphase.

A job run is an instance of a job. For example, a job run for adeploy job isexecuted, and if it succeeds, there is no further job run for that job. If itfails, it can be retried as another job run.

Skipping phases the first time

Some deployment strategies (for example, canary) apportion traffic between theold and new versions. If you're deploying to a target for the first time,there's no old version, so we can't apportion the traffic.

For this reason, when you deploy a canary for the first time, we skip the canaryphase or phases and run thestable phase. After that, the application isdeployed, and future canary deployments will include the canary phases.

In a real-world situation, you will usually execute a canary deployment whereyour application is already running, so this phase skipping will be rare.

States within a rollout

Rollouts, phases, jobs, and job runs all have states. This section describes thestates for each.

Rollout states

A rollout will have one of the following states:

• APPROVAL_REJECTED

  The rolloutrequired approval,but the approval was rejected.

• CANCELLED

  The terminal state for rollouts that have beencanceled bya user.

• CANCELLING

  A user has canceled the rollout, but the cancellation has not finishedprocessing.

• HALTED

  In aparallel deployment, if one or more childrollouts fail, but at least one child rollout succeeds, thecontroller rolloutis HALTED if there are more phases after the current one.

  You can resume a halted controller rollout by doing any of the following:

  • Cancel the controller rollout

  • Retry or ignore any failed jobs on child rollouts

• IN_PROGRESS

  A job run is processing.

• FAILED

  A job failed, and the user didn't choose toignore the failure.

• PENDING

  The rollout has not begun processing. This state transitions toIN_PROGRESSorCANCELED.

• PENDING_APPROVAL

  The rolloutrequires approval,but has not yet been approved.

• PENDING_RELEASE

  The rollout is waiting for therelease to be rendered.

• SUCCEEDED

  The rollout has finished, with no failures.

Phase states

A phase will have one of the following states:

• PENDING

  The phase is waiting for another phase in the rollout to finish.

• IN_PROGRESS

  The phase has started.

• SUCCEEDED

  The phase completed successfully.

• FAILED

  A job in the phase failed, and the user didn't choose toignore the failure.

• ABORTED

  A previous phase failed.

• SKIPPED

  When you're running a deployment strategy, such as acanary, Cloud Deployskips to thestable phase in cases where there isn't yet a running versionof the application with which to split traffic. In this case, the state isset toSKIPPED.

Job states

A job will have one of the following states:

• ABORTED

  If a phase fails, subsequent phases are aborted.

  If a job fails, and that failure is notignored, subsequentjobs are aborted. For example, if a phase includes a deploy job and a verifyjob, and the deploy job fails, the verify job is aborted.

• DISABLED

  Some jobs in a Phase might be disabled. For example, phases always includeverify jobs, whether or notverification isenabled. If verificationisn't enabled, then the verify job is set toDISABLED.

• FAILED

  A job run for this job failed, and the user didn't choose toignore the failure.

  The user chose toterminate the job run for this job.

• IGNORED

  A job run for this job failed, and the user chose toignore the failure.

• IN_PROGRESS

  A job run for this job is currently running.

• PENDING

  The job run for this job is waiting to begin, because another phase or jobhasn't finished.

• SKIPPED

  When you're running a deployment strategy, such as acanary, Cloud Deployskips to thestable phase in cases where there isn't yet a running versionof the application with which to split traffic. In this case, the state isset toSKIPPED on jobs within the skipped phase or phases.

• SUCCEEDED

  The job run finished successfully, and the next job in the phase has started,or the next phase has started or is ready to start (possibly pending userinput), or the rollout has finished.

Job run states

• FAILED

  The job run failed during execution.

• IN_PROGRESS

  The job run has begun, but hasn't finished.

• TERMINATED

  The userterminated the job run.

• TERMINATING

  The userterminated the job run, but it hasn't finishedterminating yet.

• SUCCEEDED

  When a job run finishes successfully, without failing or being terminated bya user, it's put into aSUCCEEDED state, which

Manage your rollout

Using the Google Cloud console or the Google Cloud SDK, you can do thefollowing with a Cloud Deploy rollout:

• Advance the rollout

• Cancel the rollout

• Terminate a job run

• Ignore a job

• Retry a failed job

If you're using parallel deploymentwith a canary deployment strategy,seehow to manage parallel canary rollouts.

Advance a rollout

For targets configured to use a deployment strategy other than "standard," youneed to advance the rollout from phase to phase.

For example, if you have a target configured to perform a simple canary deploywith 50% andstable (100%) phases only, you would need to advance the rolloutonce, from thecanary-50 phase to thestable (100%) phase.

gclouddeployrolloutsadvanceROLLOUT_NAME\--release=RELEASE_NAME\--delivery-pipeline=PIPELINE_NAME\--region=REGION

Cancel a rollout

You can cancel any rollout which hasn't finished. You can also cancel a failedrollout to prevent further actions on it (such as ignore or retry). The rolloutmust be in one of the following states:

• FAILED
• HALTED
• IN_PROGRESS
• PENDING
• PENDING_APPROVAL
• PENDING_RELEASE

After you cancel a rollout, that rollout is in aCANCELLING state until alloutstanding job runs have completed. You canterminateoutstanding job runs that you don't want to wait for. Once the rollout isCANCELLED, it can no longer be advanced or modified.

To cancel a rollout:

gclouddeployrolloutscancelROLLOUT_NAME\--release=RELEASE_NAME\--delivery-pipeline=PIPELINE_NAME\--region=REGION

Terminate a job run

You can end a job run that's currently in progress. You might want to do this,for example, if a job run appears to be taking too long or not working asexpected. The job run must beIN_PROGRESS for you to terminate it.

gclouddeployjob-runsterminateJOB_RUN_ID\--release=RELEASE_NAME\--delivery-pipeline=PIPELINE_NAME\--rollout=ROLLOUT_NAME\--region=REGION

After you terminate a job run, the job is considered failed and you can do anyof the following:

• Leave it that way and disregard the failed rollout
• Retry the job
• Ignore the job and continue with the next job or phase in therollout

Ignore a job

You can ignore a failed job and move immediately to the next job in the phase.That job might have failed for any reason, including you or someone elseterminated a job run for that job.

A failed job means a failed phase and a failed rollout. However if you ignorethe failure, both the phase and the rollout can be progressed and can ultimatelyhaveSUCCEEDED states.

gclouddeployrolloutsignore-jobROLLOUT_NAME\--release=RELEASE_NAME\--delivery-pipeline=PIPELINE_NAME\--job-id=JOB_ID\--phase-id=PHASE_ID\--region=REGION

Retry a failed job

You can retry a job run that failed. The job can fail for any of the followingreasons:

• A job run failed to complete.

  For example, there could have been a permissions failure.

• A userterminated a job run from that job.

  Terminating a job run results in a failed job, which you can retry.

• A verification test failed.

  For averification job, a verification testfailed. Even though the verification job completed correctly, one of yourverification tests failed, and we propagate that back to the verification job.In this case, you would retry the job as part of debugging the failed testagainst your application.

To retry a failed job:

gclouddeployrolloutsretry-jobJOB_NAME\--release=RELEASE_NAME\--delivery-pipeline=PIPELINE_NAME\--rollout=ROLLOUT_NAME\--phase=PHASE_ID\--region=REGION

What's next

• Find out more abouthow deployment strategies workin Cloud Deploy.

• See theCloud Deploy service architecture documentation formore information about how rollouts, phases, jobs, and job runs fit in withthe rest of Cloud Deploy.