Checkpoint in Declarative Jenkins Pipeline

I am looking at Cloudbees documentation that says :

The correct approach is to always keep the checkpoint step outside of any node block, not associated with either an agent or a workspace

The sample example given is for a scripted pipeline. I tried to implement this in Declarative Pipeline, but keep getting error. The only way I can make it work is :

stage ('Promotion Checkpoint') {
    steps {
        checkpoint 'Ready for Manual intervention'
        timeout(time: 60, unit: 'SECONDS') {
            input message: 'Do you want to proceed?'
        }
    }
}

My understanding is a stage in Declarative pipeline is similar to node in Scripted pipeline. I cannot make checkpoint work outside of stage or step, which seems to be my interpretation of suggestion from Cloudbees. Can someone help with right usage outside of checkpoint?

Your are facing a problem of declarative pipelines which make things which should run outside of agent and workspace kinda confusing.

The "normal" declarative pipeline has a agent defined at the top

pipeline {
  agent any
  stages {
    stage("Build") {
      echo 'Build' 
    }
  }
}

But now all stage tags will use the same agent and workspace. This makes it easier to write "standard" pipelines but making it impossible to have a command not using any agent. So using checkpointor writing a pipeline not blocking an executor when using input becomes impossible.

So the suggested right way for declarative pipeline is to use agent none at the top level pipeline and specify the agent any or agent none in each stage.

There are two examples in the CloudBees documentation. You can also find such workarounds for input in Jenkins documentation.

So one solution using the agent switch would look like this:

pipeline {
  agent none
  stages {
    stage("Build") {
      agent any
      steps {
        echo "Building"
      }
    }
    stage("Checkpoint") {
      agent none //running outside of any node or workspace
      steps {
        checkpoint 'Completed Build'
      }
    }
    stage("Deploy") {
      agent any
      steps {
        sh 'Deploying'
      }
    }
  }
} 

There is also one with uses a node block in a declarative pipeline.

pipeline {
  agent none
  stages{
    stage("Build"){
      // no agent defined will be solved with node
      steps{
        node('') { // this is equivalent to 'agent any'
          echo "Building"
        }
        checkpoint "Build Done"
      }
    }
    stage("Deploy") {
      agent any
      steps {
        echo 'Deploy'
      }
    }
  }
}