> User Documentation Home

User Handbook
Tutorials
Resources

The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.

For a list of other such plugins, see the Pipeline Steps Reference page.

Docker plugin

View this plugin on the Plugins site

dockerNode: Docker Node (⚠️ Experimental)

Allocates a new Jenkins agent using a specified Docker image and runs tasks on it. Example: 

dockerNode('jenkins/jnlp-agent-maven') {
    git 'https://github.com/jglick/simple-maven-project-with-tests'
    sh 'mvn -B -Dmaven.test.failure.ignore install'
    junit '**/target/surefire-reports/TEST-*.xml'
}
  • image
    • Type: String
  • connector (optional)
      Nested Choice of Objects
    • attach
      • entryPointCmdString (optional)
        • Type: String
      • javaExe (optional)
        • Type: String
      • jvmArgsString (optional)
        • Type: String
      • user (optional)
        User that the Jenkins agent code will run as.
        The container's default user (typically "root") will be used if this is left blank.
        • Type: String
    • jnlp
      • jnlpLauncher
          Nested Choice of Objects
        • jnlp
          • tunnel
            • Type: String
          • webSocket (optional)
            Use WebSocket to connect to the Jenkins master rather than the TCP port. See JEP-222 for background.
            • Type: boolean
          • workDirSettings (optional)
              Nested Object
            • disabled
              Allows disabling Remoting Work Directory for the agent. In such case the agent will be running in the legacy mode without logging enabled by default.
              • Type: boolean
            • workDirPath
              If defined, a custom Remoting work directory will be used instead of the Agent Root Directory. This option has no environment variable resolution so far, it is recommended to use only absolute paths.
              • Type: String
            • internalDir
              Defines a storage directory for the internal data. This directory will be created within the Remoting working directory.
              • Type: String
            • failIfWorkDirIsMissing
              If defined, Remoting will fail at startup if the target work directory is missing. The option may be used to detect infrastructure issues like failed mount.
              • Type: boolean
      • entryPointArgumentsString (optional)
        • Type: String
      • jenkinsUrl (optional)
        If needed, the Jenkins URL can be overwritten with this property (e.g. to support other HTTP(S) endpoints due to reverse proxies or firewalling). By default the URL from the global Jenkins configuration is used.
        • Type: String
      • user (optional)
        User that the jenkins agent process will be run as. "root" if not specified.
        • Type: String
    • ssh
      • sshKeyStrategy
        Define how a SSH key pair is configured for ssh authentication in container.
          Nested Choice of Objects
        • $class: 'InjectSSHKey'
          • user
            Injected SSH key will let agent start as root in container. If you want to use another user configure it's name here. Please note such a user must pre-exist in container image.
            • Type: String
        • $class: 'ManuallyConfiguredSSHKey'
          • credentialsId
            • Type: String
          • sshHostKeyVerificationStrategy
              Nested Choice of Objects
            • $class: 'KnownHostsFileKeyVerificationStrategy'

              Checks the known_hosts file (~/.ssh/known_hosts) for the user Jenkins is executing under, to see if an entry exists that matches the current connection.

              This method does not make any updates to the Known Hosts file, instead using the file as a read-only source and expecting someone with suitable access to the appropriate user account on the Jenkins controller to update the file as required, potentially using the ssh hostname command to initiate a connection and update the file appropriately.

              • $class: 'ManuallyProvidedKeyVerificationStrategy'

                Checks the key provided by the remote host matches the key set by the user who configured this connection.

                • key

                  The SSH key expected for this connection. This key should be in the form `algorithm value` where algorithm is one of ssh-rsa or ssh-dss, and value is the Base 64 encoded content of the key.

                  • Type: String
              • $class: 'ManuallyTrustedKeyVerificationStrategy'

                Checks the remote key matches the key currently marked as trusted for this host.

                Depending on configuration, the key will be automatically trusted for the first connection, or an authorised user will be asked to approve the key. An authorised user will be required to approve any new key that gets presented by the remote host.

                • requireInitialManualTrust

                  Require a user with Computer.CONFIGURE permission to authorise the key presented during the first connection to this host before the connection will be allowed to be established.

                  If this option is not enabled then the key presented on first connection for this host will be automatically trusted and allowed for all subsequent connections without any manual intervention.

                  • Type: boolean
              • $class: 'NonVerifyingKeyVerificationStrategy'

                Does not perform any verification of the SSH key presented by the remote host, allowing all connections regardless of the key they present.

          • javaPath (optional)
            • Type: String
          • jvmOptions (optional)
            • Type: String
          • launchTimeoutSeconds (optional)
            • Type: int
          • maxNumRetries (optional)
            The number of times that attempts to connect to the newly-spun Docker container will be retried before the operation is abandoned.

            Note: That this field applies first to checks that the SSH port is open for new TCP connections, and secondly to checks that the SSH service that owns the TCP port is accepting SSH connections.
            e.g. a value of 3 would mean that (up to) 4 attempts (1 initial attempt plus 3 retries) would be made to check the availability of the TCP port, followed by (up to) 4 attempts (1 initial attempt plus 3 retries) to check the availability of the SSH service itself.

            • Type: int
          • port (optional)
            • Type: int
          • prefixStartSlaveCmd (optional)
            • Type: String
          • retryWaitTime (optional)
            Number of seconds to wait between attempts to connect to the newly-started Docker container.
            • Type: int
          • suffixStartSlaveCmd (optional)
            • Type: String
      • credentialsId (optional)
        • Type: String
      • dockerHost (optional)
        • Type: String
      • remoteFs (optional)
        Use a specific root directory for the Jenkins agent. This includes a workspace subdirectory as well as various control files. If not specified, uses the WORKDIR from the image.
        • Type: String

      step([$class: 'DockerBuilderControl']): Start/Stop Docker Containers

      • option
          Nested Choice of Objects
        • $class: 'DockerBuilderControlOptionProvisionAndStart'
          • cloudName
            • Type: String
          • templateId
            • Type: String
        • $class: 'DockerBuilderControlOptionRun'
          • cloudName
            • Type: String
          • image
            • Type: String
          • pullCredentialsId
            • Type: String
          • dnsString
            • Type: String
          • network
            • Type: String
          • dockerCommand
            • Type: String
          • mountsString
            • Type: String
          • volumesFrom
            • Type: String
          • environmentsString
            • Type: String
          • hostname
            • Type: String
          • user
            • Type: String
          • extraGroupsString
            • Type: String
          • memoryLimit
            • Type: int
          • memorySwap
            • Type: int
          • cpuPeriod
            • Type: long
          • cpuQuota
            • Type: long
          • cpuShares
            • Type: int
          • shmSize
            • Type: int
          • bindPorts
            • Type: String
          • bindAllPorts
            • Type: boolean
          • privileged
            • Type: boolean
          • tty
            • Type: boolean
          • macAddress
            • Type: String
        • $class: 'DockerBuilderControlOptionStart'
          • cloudName
            • Type: String
          • containerId
            • Type: String
        • $class: 'DockerBuilderControlOptionStop'
          • cloudName
            • Type: String
          • containerId
            • Type: String
          • remove
            • Type: boolean
        • $class: 'DockerBuilderControlOptionStopAll'
          • remove
            • Type: boolean

      step([$class: 'DockerBuilderPublisher']): Build / Publish Docker Image

      Build step that sends a Dockerfile for building to docker host that used for this build run.
      • dockerFileDirectory
        • Type: String
      • fromRegistry
          Nested Object
        • url
          URL to the Docker registry you are using. May be left blank to use the public DockerHub registry (currently https://index.docker.io/v1/).
          • Type: String
        • credentialsId
          • Type: String
      • cloud
        Cloud to do the build on - or, if empty, use the cloud that the build was performed on.
        • Type: String
      • tagsString
        Repository name (and optionally a tag) to be applied to the resulting image in case of success.
        Multiple entries are permitted if separated by newlines.
        Environment variable substitution is performed on the strings so you can use e.g. ${BUILD_NUMBER} as part of each entry.
        Each entry must be of the form IMAGE[:TAG] as per the docker tag command.
        • Type: String
      • pushOnSuccess
        If enabled (and the docker image builds successfully), the resulting docker image will be pushed to the registry (or registries) specified within the "Image" field.
        • Type: boolean
      • pushCredentialsId
        Credentials to push to a private registry.
        • Type: String
      • cleanImages
        • Type: boolean
      • cleanupWithJenkinsJobDelete
        • Type: boolean
      • buildArgs (optional)

        A map of build-time variables.

        • Type: java.util.Map<java.lang.String, java.lang.String>
      • buildArgsString (optional)

        A list of new line separated build-time variables, specified in the form "name=value".

        • Type: String
      • noCache (optional)
        If set, builds the image with --no-cache which disables caching of layers. See the docker build command for more information.
        • Type: boolean
      • pull (optional)
        If set, builds the image with --pull to pull the latest version of the base image, instead of using the local one. See the docker build command for more information.
        • Type: boolean

      Was this page helpful?

      Please submit your feedback about this page through this quick form.

      Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

          


      See existing feedback here.