search

jenkinsci / docker-plugin

Jenkins cloud plugin that uses Docker
https://plugins.jenkins.io/docker-plugin/
MIT License
490 stars 318 forks source link

Introduce how to use this plugin in a Pipeline #1077

Closed WilliamShoww closed 2 months ago

WilliamShoww commented 4 months ago

Describe your use-case which is not covered by existing documentation.

The document introduces how to configure Jenkins free-style projects, but does not introduce how to write pipeline scripts for pipeline projects.

Reference any relevant documentation, other materials or issues/pull requests that can be used for inspiration.

No response

Are you interested in contributing to the documentation?

Interested, but I don’t know how to use this plug-in jenkins pipeline project

MarkEWaite commented 4 months ago

Thanks for the report @WilliamShoww .

I'm not sure of the best way to describe using the plugin with Pipeline, since it is not specific to Pipeline. Here is an example that I use to test the plugin.

The following Pipeline job uses an agent with the 'alpine' label defined on my controller. 

pipeline {
    agent {
        label 'alpine'
    }
    stages {
        stage('Hello from Alpine docker agent') {
            steps {
                sh 'whoami && uname -a && cat /etc/os-release && java -version && git --version'
            }
        }
    }
}

All agents with the label 'alpine' on my controller are started by the docker plugin when requested, then stopped by the docker plugin when the job completes. When I ran that job, the console output reported:

Started by user Mark Waite
[Pipeline] Start of Pipeline
[Pipeline] node
Running on alpine-jdk21-00048adis7zag on mark-pc2 in /home/jenkins/agent/workspace/alpine-whoami
[Pipeline] {
[Pipeline] stage
[Pipeline] { (Hello from Alpine docker agent)
[Pipeline] sh
+ whoami
jenkins
+ uname -a
Linux abf179eeac7d 6.5.0-35-generic #35~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC Tue May  7 09:00:52 UTC 2 x86_64 Linux
+ cat /etc/os-release
NAME="Alpine Linux"
ID=alpine
VERSION_ID=3.19.1
PRETTY_NAME="Alpine Linux v3.19"
HOME_URL="https://alpinelinux.org/"
BUG_REPORT_URL="https://gitlab.alpinelinux.org/alpine/aports/-/issues"
+ java -version
openjdk version "21.0.3" 2024-04-16 LTS
OpenJDK Runtime Environment Temurin-21.0.3+9 (build 21.0.3+9-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.3+9 (build 21.0.3+9-LTS, mixed mode)
+ git --version
git version 2.43.0
[Pipeline] }
[Pipeline] // stage
[Pipeline] }
[Pipeline] // node
[Pipeline] End of Pipeline
[Gitea] do not publish assets due to source being no GiteaSCMSource
Finished: SUCCESS

In the configuration as code definition for my Jenkins controller, I have the following entry:

jenkins:
  clouds:
  - docker:
      containerCap: 3
      dockerApi:
        connectTimeout: 23
        dockerHost:
          uri: "tcp://docker-host.markwaite.net:2375"
        readTimeout: 43
      errorDuration: 313
      name: "mark-pc2"
      templates:
      - connector:
          jnlp:
            jenkinsUrl: "http://mark-pc2.markwaite.net}:8080/"
            user: "1000"
        dockerTemplateBase:
          cpuPeriod: 0
          cpuQuota: 0
          image: "jenkins/inbound-agent:3248.v65ecb_254c298-2-alpine-jdk21"
        labelString: "alpine jdk21 alpine-jdk21 git-2.43"
        name: "alpine-jdk21"
        pullTimeout: 171
        remoteFs: "/home/jenkins/agent"

That configuration as code entry describes the agent definition for the 'alpine' label.

Does that help answer your question?

Is the example the key part of that or does it also need an explanation that the docker plugin creates new agents based on labels requested by jobs? Those jobs can be Pipeline, freestyle, or matrix jobs.

WilliamShoww commented 4 months ago

感谢您的报告@WilliamShoww。

我不确定如何最好地描述插件与 Pipeline 的配合使用，因为它不是特定于 Pipeline 的。下面是我用来测试插件的示例。

以下管道作业使用在我的控制器上定义的带有‘alpine’标签的代理。

pipeline {
    agent {
        label 'alpine'
    }
    stages {
        stage('Hello from Alpine docker agent') {
            steps {
                sh 'whoami && uname -a && cat /etc/os-release && java -version && git --version'
            }
        }
    }
}

我的控制器上所有带有标签“alpine”的代理在请求时由docker插件启动，然后在作业完成时由docker插件停止。当我运行该作业时，控制台输出报告：

Started by user Mark Waite
[Pipeline] Start of Pipeline
[Pipeline] node
Running on alpine-jdk21-00048adis7zag on mark-pc2 in /home/jenkins/agent/workspace/alpine-whoami
[Pipeline] {
[Pipeline] stage
[Pipeline] { (Hello from Alpine docker agent)
[Pipeline] sh
+ whoami
jenkins
+ uname -a
Linux abf179eeac7d 6.5.0-35-generic #35~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC Tue May  7 09:00:52 UTC 2 x86_64 Linux
+ cat /etc/os-release
NAME="Alpine Linux"
ID=alpine
VERSION_ID=3.19.1
PRETTY_NAME="Alpine Linux v3.19"
HOME_URL="https://alpinelinux.org/"
BUG_REPORT_URL="https://gitlab.alpinelinux.org/alpine/aports/-/issues"
+ java -version
openjdk version "21.0.3" 2024-04-16 LTS
OpenJDK Runtime Environment Temurin-21.0.3+9 (build 21.0.3+9-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.3+9 (build 21.0.3+9-LTS, mixed mode)
+ git --version
git version 2.43.0
[Pipeline] }
[Pipeline] // stage
[Pipeline] }
[Pipeline] // node
[Pipeline] End of Pipeline
[Gitea] do not publish assets due to source being no GiteaSCMSource
Finished: SUCCESS

在我的 Jenkins 控制器的配置即代码定义中，我有以下条目：

jenkins:
  clouds:
  - docker:
      containerCap: 3
      dockerApi:
        connectTimeout: 23
        dockerHost:
          uri: "tcp://docker-host.markwaite.net:2375"
        readTimeout: 43
      errorDuration: 313
      name: "mark-pc2"
      templates:
      - connector:
          jnlp:
            jenkinsUrl: "http://mark-pc2.markwaite.net}:8080/"
            user: "1000"
        dockerTemplateBase:
          cpuPeriod: 0
          cpuQuota: 0
          image: "jenkins/inbound-agent:3248.v65ecb_254c298-2-alpine-jdk21"
        labelString: "alpine jdk21 alpine-jdk21 git-2.43"
        name: "alpine-jdk21"
        pullTimeout: 171
        remoteFs: "/home/jenkins/agent"

该配置作为代码条目描述了“高山”标签的代理定义。

这有助于回答你的问题吗？

这个例子是关键部分吗？还是还需要解释一下 Docker 插件根据作业请求的标签创建新代理？这些作业可以是管道作业、自由式作业或矩阵作业。

Thanks for the report @WilliamShoww .

I'm not sure of the best way to describe using the plugin with Pipeline, since it is not specific to Pipeline. Here is an example that I use to test the plugin.

The following Pipeline job uses an agent with the 'alpine' label defined on my controller.

pipeline {
    agent {
        label 'alpine'
    }
    stages {
        stage('Hello from Alpine docker agent') {
            steps {
                sh 'whoami && uname -a && cat /etc/os-release && java -version && git --version'
            }
        }
    }
}

All agents with the label 'alpine' on my controller are started by the docker plugin when requested, then stopped by the docker plugin when the job completes. When I ran that job, the console output reported:

Started by user Mark Waite
[Pipeline] Start of Pipeline
[Pipeline] node
Running on alpine-jdk21-00048adis7zag on mark-pc2 in /home/jenkins/agent/workspace/alpine-whoami
[Pipeline] {
[Pipeline] stage
[Pipeline] { (Hello from Alpine docker agent)
[Pipeline] sh
+ whoami
jenkins
+ uname -a
Linux abf179eeac7d 6.5.0-35-generic #35~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC Tue May  7 09:00:52 UTC 2 x86_64 Linux
+ cat /etc/os-release
NAME="Alpine Linux"
ID=alpine
VERSION_ID=3.19.1
PRETTY_NAME="Alpine Linux v3.19"
HOME_URL="https://alpinelinux.org/"
BUG_REPORT_URL="https://gitlab.alpinelinux.org/alpine/aports/-/issues"
+ java -version
openjdk version "21.0.3" 2024-04-16 LTS
OpenJDK Runtime Environment Temurin-21.0.3+9 (build 21.0.3+9-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.3+9 (build 21.0.3+9-LTS, mixed mode)
+ git --version
git version 2.43.0
[Pipeline] }
[Pipeline] // stage
[Pipeline] }
[Pipeline] // node
[Pipeline] End of Pipeline
[Gitea] do not publish assets due to source being no GiteaSCMSource
Finished: SUCCESS

In the configuration as code definition for my Jenkins controller, I have the following entry:

jenkins:
  clouds:
  - docker:
      containerCap: 3
      dockerApi:
        connectTimeout: 23
        dockerHost:
          uri: "tcp://docker-host.markwaite.net:2375"
        readTimeout: 43
      errorDuration: 313
      name: "mark-pc2"
      templates:
      - connector:
          jnlp:
            jenkinsUrl: "http://mark-pc2.markwaite.net}:8080/"
            user: "1000"
        dockerTemplateBase:
          cpuPeriod: 0
          cpuQuota: 0
          image: "jenkins/inbound-agent:3248.v65ecb_254c298-2-alpine-jdk21"
        labelString: "alpine jdk21 alpine-jdk21 git-2.43"
        name: "alpine-jdk21"
        pullTimeout: 171
        remoteFs: "/home/jenkins/agent"

That configuration as code entry describes the agent definition for the 'alpine' label.

Does that help answer your question?

Is the example the key part of that or does it also need an explanation that the docker plugin creates new agents based on labels requested by jobs? Those jobs can be Pipeline, freestyle, or matrix jobs.

I didn't understand what you meant. It seems like the method you mentioned didn't solve my problem. After looking at the source code, what I want is a way to describe the exact same functionality as the src/main/java/com/nirima/jenkins/plugins/docker/builder/DockerBuilderPublisher.java class using a scripting language in the pipeline. Because I want to use this plugin with a script in the matching line, similar to the configuration in a freestyle project, in Jenkins without having Docker software installed. freestyle project use way see img: image

MarkEWaite commented 4 months ago

what I want is a way to describe the exact same functionality as the src/main/java/com/nirima/jenkins/plugins/docker/builder/DockerBuilderPublisher.java class using a scripting language in the pipeline

I don't intend to add that type of capability to the plugin. The Pipeline already has facilities that allow a Jenkins provided credential to be provided to shell steps that can perform command line operations like docker push. I recommend that you use those facilities rather than waiting for an implementation inside the Jenkins docker plugin.

WilliamShoww commented 4 months ago

what I want is a way to describe the exact same functionality as the src/main/java/com/nirima/jenkins/plugins/docker/builder/DockerBuilderPublisher.java class using a scripting language in the pipeline

I don't intend to add that type of capability to the plugin. The Pipeline already has facilities that allow a Jenkins provided credential to be provided to shell steps that can perform command line operations like docker push. I recommend that you use those facilities rather than waiting for an implementation inside the Jenkins docker plugin.

If I use native commands, docker must be installed on my jenkins machine, otherwise the docker command cannot be executed. My situation is: Jenkins is started through the docker image, then I need to install another docker in the image container or need to share the socket file directory mapping docker when starting. If such a method is provided, then I don’t have to do these things.

MarkEWaite commented 2 months ago

Closing as "Won't implement"