Jenkins Pipeline Jenkinsfile: 'node' and 'pipeline' directives

I am getting started with Jenkins declarative Pipeline. From some of the examples I have seen, I notice that the Jenkinsfile is setup with the Pipeline directive:

pipeline {
    agent any 

    stages {
        stage('Build') { 
            steps { 
                sh 'make' 
            }
        }
        stage('Test'){
            steps {
                sh 'make check'
                junit 'reports/**/*.xml' 
            }
        }
        stage('Deploy') {
            steps {
                sh 'make publish'
            }
        }
    }
}

In other examples, I notice that the Jenkinsfile is setup with a node directive:

node {
	stage 'Checkout'
		checkout scm

	stage 'Build'
		bat 'nuget restore SolutionName.sln'
		bat "\"${tool 'MSBuild'}\" SolutionName.sln /p:Configuration=Release /p:Platform=\"Any CPU\" /p:ProductVersion=1.0.0.${env.BUILD_NUMBER}"

	stage 'Archive'
		archive 'ProjectName/bin/Release/**'

}

I haven't been able to find solid documentation on exactly when / why to use each of these. Does anybody have any information on why these differ and when it is appropriate to use either of them?

I'm not sure but I belive the 'node' directive is used in scripted pipeline as opposed to declarative pipeline.

Thanks in advance for any guidance.

yes, a top-level node implies scripted pipeline, and a top-level pipeline implies declarative pipeline.

declarative appears to be the more future-proof option and the one that people recommend, like in this jenkins user list post where a core contributor says "go declarative." it's the only one the Visual Pipeline Editor can support. it supports validation. and it ends up having most of the power of scripted since you can fall back to scripted in most contexts. occasionally someone comes up with a use case where they can't quite do what they want to do with declarative, but this is generally people who have been using scripted for some time, and these feature gaps are likely to close in time. and finally, if you really have to bail on one or the other, writing a programmatic translator from declarative to scripted would be easier than the other way around (sort of by definition, since the grammar is more tightly constrained).

more context on pros of declarative from the general availability blog post: https://jenkins.io/blog/2017/02/03/declarative-pipeline-ga/

the most official docs i could find that mention both (as of June 21, 2017): https://jenkins.io/doc/book/pipeline/syntax/