How to Pass a Value of Avriable From Jenkins to Read a Yaml File

Jenkins Configuration as Lawmaking is finally here. In this weblog I'll cover how to catechumen an existing Jenkins instance to JCasC and also how to outset from scratch. Let'south get it up and running!

What is Jenkins Configuration equally Code (JCasC)?

JCasC is a Jenkins plugin that allows you to store and maintain your Jenkins configuration in a YAML file. I provided an outline of the main benefits in a previous web log post: Jenkins Configuration as Code - Automating an automation server.

Installation

Scenario i: Starting from scratch with Docker

To demonstrate how to start from scratch with Docker I'll be using our Praqma/praqma-jenkins-casc GitHub repository. Information technology contains a Dockerfile and docker-etch.yml ready for utilise. You can utilize your ain images or you lot tin can fork ours and use them.

Allow's have a look at the repository contents: Beginning upwardly is the primary/Dockerfile. This is based on the praqma/jenkins4casc:1.0 Docker image, which in turn is based on the official Jenkins Docker image. It comes with JCasC pre-installed and its Setup Magician disabled, so when you spin upward your container it's ready to go.

            FROM praqma/jenkins4casc:ane.0
Label maintainer="human being@praqma.cyberspace"
Copy plugins_extra.txt /usr/share/jenkins/ref/plugins_extra.txt
              
ARG JAVA_OPTS
              
RUN xargs /usr/local/bin/install-plugins.sh < /usr/share/jenkins/ref/plugins_extra.txt
                      

Up adjacent is the master/plugins_extra.txt file which contains a list of plugins that volition be pre-installed on the Jenkins instance. If you want more than plugins to come with your instance, add together them here.

Next, in that location's the docker-etch.yml file which is used to kickoff the container. This ane's worth a closer look:

            version: '3.three'
services:
                jenkins:
                build: #TODO: In one case plugin installation is handled through c-equally-c this can exist removed and replaced with 'image'.
                context: ./main
                ports:
                - 80:8080
                - 50000:50000
                volumes:
                - jenkins_home:/var/jenkins_home
                - ./jenkins.yaml:/var/jenkins_home/jenkins.yaml
                secrets:
                - github  #Github username with password as an example.  Purpose hither is to have a user with write-admission for special cases.  Similar the git-publisher.
                - adminpw  #Initial administrator user password.  Added for debugging purposes.  Should exist removed prior to become-live.
                - agent_private_key #ssh private key for connecting ssh slaves
                environment:
                - CASC_JENKINS_CONFIG=/var/jenkins_home/jenkins.yaml #Use a github repo.  Be aware that the raw content is cached, so it can have a couple of minutes to have effect
secrets: #Be careful with newlines in your secrets, make sure to remove them before running docker-compose upwardly.
                github:
                file: /var/deploy/secrets/github
                adminpw:
                file: /var/deploy/secrets/adminpw
                agent_private_key: #This should point to the private key you want your jenkins master to apply when connecting to slaves.  So in AWS for case this would exist your .pem file
                file: ~/.ssh/id_rsa
volumes:
                jenkins_home:
                      

The Jenkins configuration file, jenkins.yaml, is mapped to /var/jenkins_home/jenkins.yaml (line 12), and sets the CASC_JENKINS_CONFIG environs variable to point to our newly mapped config file (line 18). Great! At present the JCasC plugin has admission to our Jenkins configuration file and knows where to observe it.

Docker secrets are also declared (line 19+) allowing us to laissez passer in sensitive data such as credentials and SSH keys. You'll need to tweak these to point to the secrets you want to pass in.

If you want to replicate my setup you'll need to put the SSH primal y'all desire to utilize in ~/.ssh/id_rsa and 2 text files containing a password at:
/var/deploy/secrets/github
/var/deploy/secrets/adminpw

If y'all determine to change the secret definitions make certain to update the passing in of secrets also (line 13+).

Now you lot're prepare to move on to the next section.

Annotation: Text files containing a password should contain simply a single line. Sentinel out for editors (similar Cantlet) that automatically add a trailing newline when y'all save a file.

Scenario 2: Getting started on existing Jenkins instances

This section focuses on introducing JCasC to a running Jenkins instance, freshly prepare upward or otherwise. This should go without saying, but avoid tinkering with your production instance without properly testing your configuration changes.

Head over to the Plugin Manager under Manage Jenkins to install the Configuration as Code and configuration-as-code-support plugins. You'll discover them under the Available tab. Apply the filter for convenience, select the plugins, and hitting Install without restart.

In one case the plugins are installed you can continue to the next section.

Configuration

Scenario 1 & ii: Initial configuration

How you run Jenkins doesn't influence what your configuration file looks like, so you lot're able to use the same file for both Dockerized and archetype Jenkins instances. The just requirement is that the plugins you configure must be installed.

For Dockerized Jenkins instances refer to the "Scenario 1: Starting from scratch" section higher up on pre-installing plugins. For archetype setups I'll rely on manual installation for the moment. Configuration as Lawmaking can handle installing plugins, just I'll encompass that in a split up weblog mail service.

For now, here'due south what your very first JCasC configuration file can look like:

            _jenkins.yaml_
jenkins:
                systemMessage: "Hello, earth!"
                      

Scenario 1: Using your configuration file with Docker

In the "Scenario 1: Starting from scratch" section to a higher place I showed how the docker-compose.yml file sets up jenkins.yaml every bit our configuration file. I encourage y'all to edit that file directly. Either start with the basic example above, practice your own thing, or use parts of my configuration. One time you're happy with the configuration file spin up your container past calling:

docker-compose upwardly –build

One time your container is up and running you can admission your Jenkins case at localhost:8080.

Scenario 2: Using your configuration file in a classic setup

Once y'all've installed the plugin yous'll find the Configuration equally Code menu item under Manage Jenkins . This is where yous'll be configuring JCasC.

Under Configuration as Code change the Path or URL setting to point to your Jenkins configuration file and hit Apply new configuration . Voila! And no restart required!

You might run into the post-obit fault: "Configuration cannot be applied. File or URL cannot be parsed or does non exist". If and so, check that the path is correct and the Jenkins user has read admission.

If you run into an exception or the post-obit error: "Invalid configuration elements for […]", Jenkins failed to parse your configuration file - it probable contains a syntax error and isn't valid YAML.

Scenario i & ii: Resources for extending your configuration

Now y'all have your "Howdy, world!" configuration up and running. In the unlikely issue that's all the configuration you want, you can terminate reading here. Otherwise, permit'south press on!

Figuring out what to add to your YAML file and how to configure various settings tin be tricky in the beginning, merely there's a few resources to help you out.

Plugin contributors have already added numerous examples in the JCasC GitHub repository. This is a great place to find out how to configure specific plugins.

Under Manage Jenkins > Configuration equally Code , nigh the bottom of the page, you lot'll find handy reference links to both documentation and schemas you can use to validate your YAML file.

In our Praqma/praqma-jenkins-casc GitHub repository you'll find another case configuration file, although this one requires the installation of various plugins listed in the plugins_extra.txt file.

Extend your configuration file as you see fit - just make sure you maintain a valid entry hierarchy and, of course, a valid YAML syntax.

Example run-through

In this department I'll be explaining the contents of my Jenkins configuration file from the Praqma/praqma-jenkins-casc GitHub repository.

            jenkins:
              systemMessage: "Welcome to the demo setup for Jenkins Configuration equally Code plugin.  For more information look in the official repo with our demo setup: https://github.com/Praqma/praqma-jenkins-casc"
              agentProtocols:
              - "JNLP4-connect"
              securityRealm:
              local:
              allowsSignup: false
              users:
              - id: demoAdmin
              password: ${adminpw:-passw0rd}
              authorizationStrategy:
              globalMatrix:
              grantedPermissions:
              - "Overall/Read:anonymous"
              - "Job/Read:anonymous"
              - "View/Read:bearding"
              - "Overall/Administer:authenticated"
              crumbIssuer: "standard"
credentials:
              system:
              domainCredentials:
              - credentials:
              - usernamePassword:
              telescopic:    System
              id:       github-user
              username: ReleasePraqma
              password: ${github}
              - basicSSHUserPrivateKey:
              scope: SYSTEM
              id: amanuensis-individual-key
              username: agentuser
              passphrase:  ""
              description: "ssh private key used to connect ssh slaves"
              privateKeySource:
              directEntry: # The key 'agent_private_key' resolved from a docker secret defined in docker-compose.yml
              privateKey: ${agent_private_key}          

Most chiefly, I set up a user that I can always connect with. I added, among other things, a local Security Realm with disabled signups and the "demoAdmin" user. To configure user'southward password I expand an environs variable passed in as a Docker secret, or simply present in the surroundings. If the environs variable isn't available it falls back to passw0rd.

Always make sure you have a user configured or you could lock yourself out.

            securityRealm:
              local:
              allowsSignup: faux
              users:
              - id: demoAdmin
              countersign: ${adminpw:-passw0rd}          

I besides configured an authorizationStrategy to restrict anonymous user permissions.

                          authorizationStrategy:
              globalMatrix:
              grantedPermissions:
              - "Overall/Read:anonymous"
              - "Job/Read:bearding"
              - "View/Read:anonymous"
              - "Overall/Administer:authenticated"          

Upwards next is calculation some credentials. These are used for authentication confronting other applications, for example when you're cloning down Git repositories in your pipelines. I again rely on Docker secrets and surround variables for these.

            domainCredentials:
              - credentials:
              - usernamePassword:
              scope:    Organisation
              id:       github-user
              username: ReleasePraqma
              countersign: ${github}
              - basicSSHUserPrivateKey:
              scope: SYSTEM
              id: agent-private-central
              username: agentuser
              passphrase:  ""
              description: "ssh private key used to connect ssh slaves"
              privateKeySource:
              directEntry:
              privateKey: ${agent_private_key}          

The tools and security root elements also contain some configuration. This is a great time to look at the documentation to check configurable sub-elements.

            tool:
              git:
              installations:
              - name: Default
              home: "git"
security:
                remotingCLI:
                enabled: imitation
                      

Looking up the security element's documentation helps united states of america discover how to configure the remoting CLI setting. Beneath y'all'll find respective documentation pages for security and remoting CLIs.

You lot may notice that a number of configurators land under the unclassified root element. Of the various configurable elements here I set Jenkins' URL and admin address.

            unclassified:
              location:
              url: https://jenkins.company.com
              adminAddress: support@company.net          

In that location's many other elements to configure, just let'southward assume you lot're happy with the configuration. Allow'southward apply information technology!

Reloading changed configuration

To use any changes you lot've made to your configuration file, return to the Configuration as Code page under Manage Jenkins and click Reload existing configuration . Once the page finishes refreshing your configuration has been reloaded. Repeat the reload step every fourth dimension you edit your configuration file. This can be automated, but I'll be roofing that in a time to come mail.

In closing

I promise you've had fun getting started with JCasC. In that location's many more configurable elements bachelor than I covered here, and the Configuration as Code plugin has a bright future alee of information technology. Stay tuned for more than posts regarding Jenkins Configuration as Code.

Now leave there and commencement migrating your configuration to code using JCasC!

---

Watch the hands-on session 'How to use Jenkins Configuration equally Code' at Day of Jenkins

smithcrithimard.blogspot.com

Source: https://www.eficode.com/blog/start-jenkins-config-as-code

Share this post