In this lab learners will use Ansible to drive automated provisioning of Projects, Access Control, Git, Jenkins and Nexus
As a learner you will be able to
npm
and Docker
registries.This exercise begins with an empty Cluster
TODO - add big picture here...
This lab is aimed at the creation of the tooling that will be used to support the rest of the Exercises. The highlevel goal is to create a collection of project namespaces and populate them with Git, Jenkins & Nexus.
If you're feeling confident and don't want to follow the step-by-step guide these highlevel instructions should provide a challenge for you:
Clone the repo git@github.com:rht-labs/enablement-ci-cd.git
which contains the scaffold of the project.
Create <your-name>-ci-cd
, <your-name>-dev
and <your-name>-test
project namespaces using the inventory and run them with the OpenShift Applier to populate the cluster
Use the templates provided to create build and deployment configs in <your-name>-ci-cd
for. Templates are on a branch called exercise1/git-nexus
&& exercise1/jenkins
:
Commit your enablement-ci-cd
repository to the GitLab Instance you've created
Burn it all down and re-apply your inventory proving config-as-code works.
This is a structured guide with references to exact filenames and explanations.
Clone the scaffold project to your local machine and open it in your favourite editor.bash git clone git@github.com:rht-labs/enablement-ci-cd.git
The project is laid out as follows . ├── README.md ├── docker │ └── jenkins-slave-node ├── inventory │ ├── group_vars │ │ └── all.yml │ └── hosts ├── jenkins-s2i │ ├── configuration ├── params │ └── project-requests-ci-cd ├── requirements.yml └── templates └── project-requests.yml
docker
folder contains our jenkins-slave images that will be used by the builds.jenkins-s2i
contains the configuration and plugins we want to bring jenkins to life withparams
houses the variables we will load the templates withtemplates
is a collection of OpenShift templatesinventory/group_vars/all.yml
is the collection of objects we want to insert into the cluster.requirements.yml
is a manifest which contains the ansible modules needed to run the playbookinventory/group_vars/all.yml
file; you should see a some variables setup to create the ci-cd
namespace. This calls the templates/project-requests.yml
template with the params/project-requests-ci-cd
parameters. We will add some additional content here but first let's explore the parameters and the templateOpen the params/project-requests-ci-cd
and replace the <YOUR_NAME or initials>
with your name to create the correstponding projects in the cluster.
Create another two params files for params/project-requests-dev
& params/project-requests-test
and add the NAMESPACE=<YOUR_NAME>-dev
&& NAMESPACE=<YOUR_NAME>-test
and update their Display names.
In the inventory/group_vars/all.yml
file; add the new inventory items for the projects you want to create (dev & test) by adding another object to the content array. You can copy and paste them from the ci-cd
example and update them accordingly eg
```yaml
With the configuration in place; install the OpenShift Applier dependencybash $ ansible-galaxy install -r requirements.yml --roles-path=roles
Apply the inventory by logging into OpenShift and then runningbash $ oc login -p <password> -u <user> <cluster_url> $ ansible-playbook roles/openshift-applier/playbooks/openshift-cluster-seed.yml -i inventory/
Once successful you should see an output similar to this
Now that we have our Projects setup; we can start to populate them with Apps to be used in our dev lifecycle
In the enablement-ci-cd
repo, checkout the templates for Nexus by runningbash $ git checkout exercise1/git-nexus templates/nexus.yml
The tempate contains all the things needed to setup a persistent nexus server, exposing a service and route while also creating the persistent volume needed. Have a read through the template; at the bottom you'll see a collection of parameters we will pass to the template.
Add some parameters for running the template by creating a new file in the params
directory.bash $ touch params/nexus
The essential params to inclue in this file are: params
directory.bash VOLUME_CAPACITY=5Gi MEMORY_LIMIT=2Gi
Create a new object in the inventory variables called ci-cd-deployments
and populate it's content
is as follows (swapping <YOUR_NAME>-ci-cd
for the namespace you created earlier)
- object: ci-cd-deployments
content:
- name: "nexus"
namespace: "<YOUR_NAME>-ci-cd"
template: "{{ inventory_dir }}/../templates/nexus.yml"
params: "{{ inventory_dir }}/../params/nexus"
tags:
- nexus
Run the OpenShift applier, specifying the tag nexus
to speed up it's execution.bash $ ansible-playbook roles/openshift-applier/playbooks/openshift-cluster-seed.yml \ -i inventory/ \ -e "filter_tags=nexus"
Once successful; login to the cluster and navigate to the <YOUR_NAME>-ci-cd
. You should see Nexus up and running. You can login with default credentials (admin / admin123)
Now lets do the same thing for GitLab to get it up and running. Checkout the template provided by runningbash $ git checkout exercise1/gitlab-nexus templates/gitlab.yml
Explore the template; it contains the PVC, buildConfig and services. The DeploymentConfig is made up of these apps
Add a new params file in the params
folder called gitlab
bash $ touch params/gitlab
Open the params/gitlab
file and add the following params LDAP_BIND_DN=uid=<BIND_USER>,ou=People,dc=<YOUR_DOMAIN>,dc=com LDAP_USER_FILTER=(memberof=CN=YourGroup,OU=Users,DC=<YOUR_DOMAIN>,DC=com) LDAP_PASSWORD=<BIND_USER_PASSWORD> LDAP_HOST=<LDAP_HOST> LDAP_BASE=ou=People,dc=<YOUR_DOMAIN>,dc=com LDAP_LABEL="<LDAP_DESCRIPTION>" GITLAB_ROOT_PASSWORD=<GITLAB_ROOT_USER_PASSWORD> GITLAB_DATA_VOL_SIZE=2Gi POSTGRESQL_VOL_SIZE=1Gi APPLICATION_HOSTNAME=<GITLAB_URL> NAMESPACE=<YOUR_NAME>-ci-cd
where the following need to be replaced by actual values:
<BIND_USER>
is the user used to query the LDAP<BIND_USER_PASSWORD>
is the password used when querying the LDAP<YOUR_DOMAIN>
is the domain the LDAP is hosted on<LDAP_HOST>
is fqdn of the LDAP server<LDAP_DESCRIPTION>
is the description to be used on the sign-in header for GitLab eg "Name LDAP Login"<GITLAB_ROOT_USER_PASSWORD>
is the root user for GOD access on the GitLab instance eg password123<GITLAB_URL>
is the endpoint for gitlab. It will take the form gitlab-<YOUR_NAME>-ci-cd.apps.<ENV_ID>.<YOUR_DOMAIN>.com
Create another object in the inventory all_vars.yml
file to run the build & deploy of this template. Add the following and update the namespace:
accordingly
```yaml
Run the OpenShift applier, specifying the tag gitlab
to speed up it's execution.bash $ ansible-playbook roles/openshift-applier/playbooks/openshift-cluster-seed.yml \ -i inventory/ \ -e "filter_tags=gitlab"
Once successful; login to the cluster and navigate to the <YOUR_NAME>-ci-cd
. You should see GitLab up and running.
Navigate to gitlab. You can login with using your cluster credentials using the LDAP tab displaying your <LDAP_DESCRIPTION>
from previous steps
Once logged in create a new project called enablement-ci-cd
and mark it as public. Once created; copy out the git remote add origin ...
instructions for use on the next step.
Note - we would not normally make the project public here on residency but are for simplicity of the exercise
Commit your local project to this new origin by first removing the existing origin (github) where the the project was cloned from. Remember to substitute <YOUR_NEW_GIT_PROJECT>
accordinglybash $ git remote remove origin $ git remote add origin <YOUR_NEW_GIT_PROJECT> $ git add . $ git commit -m "Adding git and nexus config" $ git push -u origin --all
Add the Jenkins Build & Deployment configs to the enablement-ci-cd
repo by merging the contents exercise1/jenkins
inbash $ git checkout exercise1/jenkins templates/jenkins.yml
Add the Jenkins Build & Deployment configs to the enablement-ci-cd
repo by merging the contents exercise1/jenkins
inbash $ git checkout exercise1/jenkins templates/jenkins.yml
The Jenkins template is essentially the standard persistent jenkins one with OpenShift.
As before; create a new set of params by creating a params/jenkins
file and adding some overrides to the template and updating the NAMESPACE
value.bash MEMORY_LIMIT=8Gi VOLUME_CAPACITY=5Gi JVM_ARCH=x86_64 NAMESPACE=<YOUR_NAME>-ci-cd JENKINS_OPTS=--sessionTimeout=720
jenkins
variable to the ansible inventory underneath the git and nexus ones. Remember to replace <YOUR_NAME>
with the appropriate value. This configuration if applied now; it will create the deployment configuration needed for Jenkins but the
${NAMESPACE}:${JENKINS_IMAGE_STREAM_TAG}` in the template won't exist yet.To create this image we will take the supported OpenShift Jenkins Image and bake into it some extra configuration using an s2i builder image. More information on Jenkins s2i is found on the openshift/jenkins github page. To create an s2i configuration for jenkins, check out the pre-canned configuration source in the enablement-ci-cd
repobash $ git checkout exercise1/jenkins-s2i jenkins-s2i
The structure of the jenkins s2i config is jenkins-s2i ├── README.md ├── configuration │ ├── build-failure-analyzer.xml │ ├── init.groovy │ ├── jenkins.plugins.slack.SlackNotifier.xml │ └── jobs │ └── seed-multibranch-job │ └── config.xml └── plugins.txt
plugins.txt
is a list of pluginId:version
for Jenkins to pre-install when starting./configuration
contains content that is placed in ${JENKINS_HOME}
. A config.xml
could be placed in here to control the bulk of Jenkins configuration../configuration/jobs/*
contains job names and xml config that jenkins loads when starting. The seed job in there we will return to in later lessons.build-failure-analyzer.xml
is config for the plugin to read the logs and look for key items based on a Regexinit.groovy
contains a collection of settings jenkins configures itself with when launchingLet's add a plugin for Jenkins to be started with, green-balls. This simply changes the default SUCCESS
status of Jenkins from Blue to Green. Append the plugins.txt
file withtxt greenballs:1.15
Why does Jenkins have Blue Balls? More can be found on reddit or the jenkins blog
Before building and deploying Jenkins; add git credentials to the s2i by either adding them to the template/jenkins.yml
and params/jenkins
or for simplicity just replace the <USERNAME>
&& <PASSWORD>
with your ldap credentials.
Note in a residency we would not use your GitCredentials for pushing and pulling from Git, A service user would be created here.
groovy gitUsername = System.getenv("GIT_USERNAME") ?: "<USERNAME>" gitPassword = System.getenv("GIT_PASSWORD") ?: "<PASSWORD>"
Add a new params file in the params
folder called jenkins-s2i
bash $ touch params/jenkins-s2i
Open the params/jenkins-s2i
file and add the following content; replacing variables as appropriate SOURCE_REPOSITORY_URL=<YOUR_ENABLEMENT_REPO> NAME=jenkins SOURCE_REPOSITORY_CONTEXT_DIR=jenkins-s2i IMAGE_STREAM_NAMESPACE=<YOUR_NAME>-ci-cd
where
<YOUR_ENABLEMENT_REPO>
is the full path clone path of the repo where this project is stored (including the https && .git)<YOUR_NAME>
is the prefix for your -ci-cd
project.templates/jenkins-s2i.yml
ci-cd-builds
in the ansible all.yml
to drive the s2i build configuration.Commit your code to your GitLab instancebash $ git add . $ git commit -m "Adding Jenkins and Jenkins s2i" $ git push
When your code is commited; run the OpenShift Applier to add the config to the clusterbash $ ansible-playbook roles/openshift-applier/playbooks/openshift-cluster-seed.yml \ -i inventory/ \ -e "filter_tags=jenkins"
Commit your code to the new repo in GitLab
Burn your OCP content to the ground
Re-apply the inventory!
Ideas for go-getters. Advanced topic for doers to get on with if they finish early. These will usually not have a solution and are provided for additional scope.
ci-cd-deployments
section.jenkins.plugins.slack.SlackNotifier.xml
to jenkins-s2i/configuration
to include URL of Slack for team build notifications and rebuild Jenkins S2I> List of links or other reading that might be of use / reference for the exercise