Fix README.md typo

[jamesrwhite]

No description provided.

[dihedron]

Thanks a lot. bTW if you happen to use this plugin, find it useful and are willing to help documenting how it works, I would be very grad to merge your PR.

[jamesrwhite]

I had a go at using it and got it connected to our Jenkins server but it seemed to silently fail to create my job. I was trying to recreate an existing job that I had exported the XML for. Do you have any examples of how you've successfully used it?

[dihedron]

Hi James,
the .tf file under the tests/ directory used to work just fine and shows how to use an external XML template and a HEREDOC-style template. Try those, if they don't work then there might have been a change in the Jenkins API.
The point with Jenkins is that the product does not have a "real" API, nor a real schema for the internal configuration: each plugin provides its own extensions to the job definition XML, with its own syntax and even its naming conventions. Internal configuration details percolate everywhere.
I have been working for a while on a tool to extract a template from an existing Jenkins job definition file (see here) and given up after a while for lack of time. It may work for you, it's a while back and I can't remember if it was feature complete.
Anyway, you should be able to get more info by exporting TF_LOG=TRACE before running the terraform apply command and look for the Jenkins provider output in there. For details on how to do this, you can check on the Hashicorp website about "debugging Terraform".
If you find something that looks suspicious in the generated output and attach it to this thread, I can try to help.

[jamesrwhite]

I did actually get this working in the end, the issue turned out to be with our authentication proxy we have in front of jenkins I believe.

I'm not seeing the disabled option have any effect though. If I directly add:

<disabled>true</disabled>

into my template then it works though which is probably good enough. I'm planning on creating a wrapper terraform module around this that we can use internally so people don't have to deal with the XML templates in their individual projects.

This is the terraform code I'm using:

provider "jenkins" {
  server_url = "http://jenkins.example.com"
  username   = "james@example.com"
  password   = "password"
}

resource "jenkins_job" "job" {
  name         = "terraform_test"
  display_name = "Terraform Test"
  description  = "This is a job created via terraform as a test"
  disabled     = true

  template = <<EOF
<flow-definition plugin="workflow-job@2.29">
  <definition class="org.jenkinsci.plugins.workflow.cps.CpsScmFlowDefinition" plugin="workflow-cps@2.61">
    <scm class="hudson.plugins.git.GitSCM" plugin="git@3.9.1">
      <configVersion>2</configVersion>
      <userRemoteConfigs>
        <hudson.plugins.git.UserRemoteConfig>
          <url>https://github.com/example/project</url>
          <credentialsId>abc</credentialsId>
        </hudson.plugins.git.UserRemoteConfig>
      </userRemoteConfigs>
      <branches>
        <hudson.plugins.git.BranchSpec>
          <name>master</name>
        </hudson.plugins.git.BranchSpec>
      </branches>
    </scm>
    <scriptPath>Jenkinsfile</scriptPath>
  </definition>
</flow-definition>
EOF
}

I'm guessing I will need to keep those version numbers of the workflow and git plugins in sync with what we have installed on Jenkins?

Thanks again for creating this, I'm really excited to be able to manage our jobs via terraform 🤞

[dihedron]

I'm glad you made it work.

As a matter of fact Jenkins's REST API is so simple (poor?) that it requires you to post the exact XML it would use internally to represent the job in order to create a new one. In the end you have to use the UI, copy the generated XML, use it with terraform.

The abstraction leak is so terrible that all version numbers and XML namespaces and internal field values are exposed to whomever wants to use the API. Sorry about that: you will have to keep those numbers in sync with your installed plugins and there's no way around it AFAIK. :-(

BTW I started working on a tiny tool to extract a template from an existing job XML (it's called jted if I remember correctly). It's not complete but it may still help you extract variables from the template. Check it out.

[jamesrwhite]

It actually seems to accept plugin references without version numbers 😄. I assume is it uses whatever version is installed. There may still be issues if the class names change I suppose but hopefully that is less likely.

Like so:

<flow-definition plugin="workflow-job">
  <definition class="org.jenkinsci.plugins.workflow.cps.CpsScmFlowDefinition" plugin="workflow-cps">
    <scm class="hudson.plugins.git.GitSCM" plugin="git">
      <configVersion>2</configVersion>
      <userRemoteConfigs>
        <hudson.plugins.git.UserRemoteConfig>
          <url>https://github.com/pricesearcher/terraform-jenkins-test</url>
          <credentialsId>abc</credentialsId>
        </hudson.plugins.git.UserRemoteConfig>
      </userRemoteConfigs>
      <branches>
        <hudson.plugins.git.BranchSpec>
          <name>master</name>
        </hudson.plugins.git.BranchSpec>
      </branches>
    </scm>
    <scriptPath>Jenkinsfile</scriptPath>
  </definition>
</flow-definition>

[dihedron]

Cool. Hope you keep using this plugin and find it useful.
If you have ideas on enhancements or improvements, I'll be glad to spend the little spare time I have improving it.
If you wish to improve the README.md, please do and send me a PR.