- Overview
- Reader Prerequisites
- Installing and developing
- Compatability with Declarative Pipeline
- Examples
- Hello, World
- Centralizing Cluster Configuration
- Sticking with the defaults
- Introduction to Selectors
- Actions speak louder than words
- Peer inside of Alauda objects
- Watching and waiting? Of course!
- Looking to Verify a Deployment? We Can Still Do That!
- Deleting objects. Easy.
- Creating objects. Easier than you were expecting... hopefully.
- Need to update an object without replacing it?
- Cannot live without Alauda templates? No problem.
- Want to promote or migrate objects between environments?
- ### Get Sonarqube Binding in Project and Inject Environment to Context
- Error handling
- Troubleshooting
- Who are you, really?
- I need more.
- Configuring an Alauda Cluster
- Setting up Credentials
- Setting up Jenkins Nodes
- You call this documentation?!
The Alauda Pipeline DSL Plugin is a Jenkins plugin which aims to provide a readable, concise, comprehensive, and fluent Jenkins Pipeline syntax for rich interactions with an Alauda API Server. The plugin leverages kubenetes command line tool (kubectl) which must be available on the nodes executing the script (options for getting the binary on your nodes can be found here).
- Familiarity with Kubenetes command line interface is highly encouraged before exploring the plugin's features. The DSL leverages the kubectl) binary and, in many cases, passes method arguments directly on to the command line. This document cannot, therefore, provide a complete description of all possible Alauda interactions -- the user may need to reference the CLI documentation to find the pass-through arguments a given interaction requires.
- A fundamental level of understanding of the Jenkins Pipeline architecture and basic pipeline steps may be required to appreciate the remainder of this document. Readers may also find it useful to understand basic Groovy syntax, since pipeline scripts are written using Groovy (Note: Jenkins sandboxes and interferes with the use of some Groovy facilities).
This plugin is available at the Jenkins Update Center.
Otherwise, if you are interested in building this plugin locally, follow these steps:
- Install maven (platform specific)
- Clone this git repository:
git clone git@github.com:alauda/alauda-devops-pipeline-plugin.git - In the root of the local repository, run maven
cd alauda-devops-pipeline-plugin mvn clean package - Maven will build target/alauda-devops-pipeline.hpi (the Jenkins plugin binary)
- Open Jenkins in your browser, and navigate (as an administrator):
- Manage Jenkins > Manage Plugins.
- Select the "Advanced" Tab.
- Find the "Upload Plugin" HTML form and click "Browse".
- Find the alauda-devops-pipeline.hpi built in the previous steps.
- Submit the file.
- Check that Jenkins should be restarted.
You should now be able to configure an Alauda Cluster. Before running a job, you may also need to ensure your Jenkins nodes have the 'kubectl' binary installed.
The means by which this plugin has been able to coexist with declarative pipeline has taken a few twists and turns since v1.0 of that feature first arrived in early 2017.
In particular, the recommendation around leveraging this plugin's directives with the declarative pipeline { ... } directory have
had to be adjusted as the pipeline-model-definition plugin has evolved.
Currently, there are two requirements of note:
- Per the requirements of declarative pipelines, the
pipeline {
...
}directive must be the outer most closure to fully enable all the declarative pipeline semantics and features.
- Declarative currently does not support groovy body/closures that are not pipeline script steps. And since this plugin integrates into Jenkins as a Global Variable, it does not meet that restriction. As such, you must encapsulate all use of this plugin with the declarative
script {
...
}directive such that the declarative interpreter is told to treat this as scripted pipeline.
As development of this plugin continues, periodic attempts will be made to monitor that these recommendations are still valid, and if not, either adjust recommendations accordingly, or leverage any new integration points with declarative that are synergistic with this plugin's design.
But certainly if users of this plugin notice changes before the maintainers of the plugin, please advise via opening issues at https://github.com/alauda/alauda-devops-pipeline-plugin/issues.
As the DSL is designed to be intuitive for experienced Alauda users, the following high level examples may serve to build that intuition before delving into the detailed documentation.
Let's start with a "Hello world" style example.
/** Use of hostnames and OAuth token values in the DSL is heavily discouraged for maintenance and **/
/** security reasons. The global Jenkins configuration and credential store should be used instead. **/
/** Subsequent examples will demonstrate how to do this. **/
alaudaDevops.withCluster( 'https://10.13.137.207:8443', 'CO8wPaLV2M2yC_jrm00hCmaz5Jgw...' ) {
alaudaDevops.withProject( 'myproject' ) {
echo "Hello from project ${alaudaDevops.project()} in cluster ${alaudaDevops.cluster()}"
}
}Now let's simplify the first example by moving host, port, token and project information out of the script and into the Jenkins cluster configuration. A single logical name (e.g. "mycluster") can now be used to reference these values. This means that if the cluster information changes in the future, your scripts won't have to!
/** The logical name references a Jenkins cluster configuration which implies **/
/** API Server URL, default credentials, and a default project to use within the closure body. **/
alaudaDevops.withCluster( 'mycluster' ) {
echo "Hello from ${alaudaDevops.cluster()}'s default project: ${alaudaDevops.project()}"
// But we can easily change project contexts
alaudaDevops.withProject( 'another-project' ) {
echo "Hello from a non-default project: ${alaudaDevops.project()}"
}
// And even scope operations to other clusters within the same script
alaudaDevops.withCluster( 'myothercluster' ) {
echo "Hello from ${alaudaDevops.cluster()}'s default project: ${alaudaDevops.project()}"
}
}We can make the previous example even simpler! If you have defined a cluster configuration named "default" or if the Jenkins instance is running within an Alauda pod, you don't need to specify any cluster information.
alaudaDevops.withCluster() { // Use "default" cluster or fallback to Alauda cluster detection
echo "Hello from the project running Jenkins: ${alaudaDevops.project()}"
}Now a quick introduction to Selectors which allow you to perform operations on a group of API Server objects.
alaudaDevops.withCluster( 'mycluster' ) {
/** Selectors are a core concept in the DSL. They allow the user to invoke operations **/
/** on group of objects which satisfy a given criteria. **/
// Create a Selector capable of selecting all service accounts in mycluster's default project
def saSelector = alaudaDevops.selector( 'serviceaccount' )
// Prints `kubectl describe serviceaccount` to Jenkins console
saSelector.describe()
// Selectors also allow you to easily iterate through all objects they currently select.
saSelector.withEach { // The closure body will be executed once for each selected object.
// The 'it' variable will be bound to a Selector which selects a single
// object which is the focus of the iteration.
echo "Service account: ${it.name()} is defined in ${alaudaDevops.project()}"
}
// Prints a list of current service accounts to the console
echo "There are ${saSelector.count()} service accounts in project ${alaudaDevops.project()}"
echo "They are named: ${saSelector.names()}"
// Selectors can also be defined using qualified names
alaudaDevops.selector( 'deploymentconfig/frontend' ).describe()
// Or Kind + Label information
alaudaDevops.selector( 'dc', [ tier: 'frontend' ] ).describe()
// Or a static list of names
alaudaDevops.selector( [ 'dc/jenkins', 'build/ruby1' ] ).describe()
}Describing things is fine, but let's actually make something happen! Here, notice that new Selectors are regularly returned by DSL operations.
alaudaDevops.withCluster( 'mycluster' ) {
// Run `kubectl new-app https://github.com/alaudaDevops/ruby-hello-world` . It
// returns a Selector which will select the objects it created for you.
def created = alaudaDevops.newApp( 'https://github.com/alaudaDevops/ruby-hello-world' )
// This Selector exposes the same operations you have already seen.
// (And many more that you haven't!).
echo "new-app created ${created.count()} objects named: ${created.names()}"
created.describe()
// We can create a Selector from the larger set which only selects
// the build config which new-app just created.
def bc = created.narrow('bc')
// Let's output the build logs to the Jenkins console. bc.logs()
// would run `kubectl logs bc/ruby-hello-world`, but that might only
// output a partial log if the build is in progress. Instead, we will
// pass '-f' to `kubectl logs` to follow the build until it terminates.
// Arguments to logs get passed directly on to the kubectl command line.
def result = bc.logs('-f')
// Many operations, like logs(), return a Result object (even a Selector
// is a subclass of Result). A Result object contains detailed information about
// what actions, if any, took place to accomplish an operation.
echo "The logs operation require ${result.actions.size()} kubectl interactions"
// You can even see exactly what kubectl command was executed.
echo "Logs executed: ${result.actions[0].cmd}"
// And even obtain the standard output and standard error of the command.
def logsString = result.actions[0].out
def logsErr = result.actions[0].err
// And if after some processing within your pipeline, if you decide
// you need to initiate a new build after the one initiated by
// new-app, simply call the `kubectl start-build` equivalent:
def buildSelector = bc.startBuild()
buildSelector.logs('-f')
}alaudaDevops.withCluster( 'mycluster' ) {
def dcs = alaudaDevops.newApp( 'https://github.com/alaudaDevops/ruby-hello-world' ).narrow('dc')
// dcs is a Selector which selects the deployment config created by new-app. How do
// we get more information about this DC? Turn it into a Groovy object using object().
// If there was a chance here that more than one DC was created, we should use objects()
// which would return a List of Groovy objects; however, in this example, there
// should only be one.
def dc = dcs.object()
// dc is not a Selector -- It is a Groovy Map which models the content of the DC
// new-app created at the time object() was called. Changes to the model are not
// reflected back to the API server, but the DC's content is at our fingertips.
echo "new-app created a ${dc.kind} with name ${dc.metadata.name}"
echo "The object has labels: ${dc.metadata.labels}"
}Patience is a virtue.
alaudaDevops.withCluster( 'mycluster' ) {
def bc = alaudaDevops.newApp( 'https://github.com/alaudaDevops/ruby-hello-world' ).narrow('bc')
// The build config will create a new build object automatically, but how do
// we find it? The 'related(kind)' operation can create an appropriate Selector for us.
def builds = bc.related('builds')
// There are no guarantees in life, so let's interrupt these operations if they
// take more than 10 minutes and fail this script.
timeout(10) {
// We can use watch to execute a closure body each objects selected by a Selector
// change. The watch will only terminate when the body returns true.
builds.watch {
// Within the body, the variable 'it' is bound to the watched Selector (i.e. builds)
echo "So far, ${bc.name()} has created builds: ${it.names()}"
// End the watch only once a build object has been created.
return it.count() > 0
}
// But we can actually want to wait for the build to complete.
builds.watch {
if ( it.count() == 0 ) return false
// A robust script should not assume that only one build has been created, so
// we will need to iterate through all builds.
def allDone = true
it.withEach {
// 'it' is now bound to a Selector selecting a single object for this iteration.
// Let's model it in Groovy to check its status.
def buildModel = it.object()
if ( it.object().status.phase != "Complete" ) {
allDone = false
}
}
return allDone;
}
// Uggh. That was actually a significant amount of code. Let's use untilEach(){}
// instead. It acts like watch, but only executes the closure body once
// a minimum number of objects meet the Selector's criteria only terminates
// once the body returns true for all selected objects.
builds.untilEach(1) { // We want a minimum of 1 build
// Unlike watch(), untilEach binds 'it' to a Selector for a single object.
// Thus, untilEach will only terminate when all selected objects satisfy this
// the condition established in the closure body (or until the timeout(10)
// interrupts the operation).
return it.object().status.phase == "Complete"
}
}If you are looking for the equivalent of alaudaDevopsVerifyDeployment from the Alauda Jenkins Plugin, the below performs the same operation.
alaudaDevops.withCluster() {
alaudaDevops.withProject( "${DEV_PROJECT}" ){
def latestDeploymentVersion = alaudaDevops.selector('dc',"${APP_NAME}").object().status.latestVersion
def rc = alaudaDevops.selector('rc', "${APP_NAME}-${latestDeploymentVersion}")
rc.untilEach(1){
def rcMap = it.object()
return (rcMap.status.replicas.equals(rcMap.status.readyReplicas))
}
}alaudaDevops.withCluster( 'mycluster' ) {
// Delete all deployment configs with a particular label.
alaudaDevops.selector( 'dc', [ environment:'qe' ] ).delete()
}alaudaDevops.withCluster( 'mycluster' ) {
// You can use sub-verbs of create for some simple objects
alaudaDevops.create( 'serviceaccount', 'my-service-account' )
// But you want to craft your own, don't you? First,
// model it with Groovy Maps, Lists, and primitives.
def secret = [
"kind": "Secret",
"metadata": [
"name": "mysecret",
"labels": [
'findme':'please'
]
],
"stringData": [
"username": "myname",
"password": "mypassword"
]
]
// create will marshal the model into JSON and send it to the API server.
// We will add some passthrough arguments (--save-config and --validate)
// just for fun.
def objs = alaudaDevops.create( secret, '--save-config', '--validate' )
// create(...) returns a Selector will select the resulting object(s).
objs.describe()
// But, you say, I've already modeled my object in JSON/YAML! It is in
// an SCM or accessible with via HTTP, or..., or ...
// Don't worry. Just get it to the current Jenkins workspace any way
// you want (e.g. using a Jenkins plugin for your SCM). Then read the
// file into a String using normal Jenkins steps.
def fromJSON = alaudaDevops.create( readFile( 'myobjects.json' ) )
// You will get a Selector for the objects created, as always.
echo "Created objects from JSON file: ${fromJSON.names()}"
}alaudaDevops.withCluster( 'mycluster' ) {
def p = alaudaDevops.selector( 'pods/mypod' ).object()
p.metadata.labels['newlabel']='newvalue' // Adjust the model
alaudaDevops.apply(p) // Patch the object on the server
}alaudaDevops.withCluster( 'mycluster' ) {
// One straightforward way is to pass string arguments directly to `kubectl process`.
// This includes any parameter values you want to specify.
def models = alaudaDevops.process( "alaudaDevops//mongodb-ephemeral", "-p", "MEMORY_LIMIT=600Mi" )
// A list of Groovy object models that were defined in the template will be returned.
echo "Creating this template will instantiate ${models.size()} objects"
// For fun, modify the objects that have been defined by processing the template
for ( o in models ) {
o.metadata.labels[ "mylabel" ] = "myvalue"
}
// You can pass this list of object models directly to the create API
def created = alaudaDevops.create( models )
echo "The template instantiated: ${models.names()}"
// Want more control? You could model the template itself!
def template = alaudaDevops.withProject( 'alaudaDevops' ) {
// Find the named template and unmarshal into a Groovy object
alaudaDevops.selector('template','mysql-ephemeral').object()
}
// Explore the template model
echo "Template contains ${template.parameters.size()} parameters"
// For fun, modify the template easily while modeled in Groovy
template.labels["mylabel"] = "myvalue"
// This model can be specified as the template to process
alaudaDevops.create( alaudaDevops.process( template, "-p", "MEMORY_LIMIT=600Mi" ) )
}alaudaDevops.withCluster( 'devcluster' ) {
def maps = alaudaDevops.selector( 'dc', [ microservice: 'maps' ] )
// Model the source objects using the 'exportable' flag to strip cluster
// specific information from the objects (i.e. like 'kubectl export').
def objs = maps.objects( exportable:true )
// Modify the models as you see fit.
def timestamp = "${System.currentTimeMillis()}"
for ( obj in objs ) {
obj.metadata.labels[ "promoted-on" ] = timestamp
}
alaudaDevops.withCluster( 'qecluster' ) {
// Might want Jenkins to ask someone before we do this ;-)
mail (
to: 'devops@acme.com',
subject: "Maps microservice (${env.BUILD_NUMBER}) is awaiting promotion",
body: "Please go to ${env.BUILD_URL}.");
input "Ready to update QE cluster with maps microservice?"
// Note that the selector is relative to its closure body and
// operates on the qecluster now.
maps.delete( '--ignore-not-present' )
alaudaDevops.create( objs )
// Let's wait until at least one pod is Running
maps.related( 'pods' ).untilEach {
return it.object().status.phase == 'Running'
}
}
}withBindingInProjectSonarEnv("test-namespace", "test-code-quality-binding") {
sh "echo \"SonarQube Server URL is $SONAR_SERVER_URL\""
sh "echo \"SonarQube Server token is $SONAR_TOKEN\""
}Error handling is fairly standard for Jenkins DSL scripts. try/catch blocks can be used prevent recoverable errors from causing a build to fail.
alaudaDevops.withCluster( 'mycluster' ) {
try {
alaudaDevops.withCredentials( 'some-invalid-token-value' ) {
alaudaDevops.newProject( 'my-new-project' )
// ...
}
} catch ( e ) {
// The exception is a hudson.AbortException with details
// about the failure.
"Error encountered: ${e}"
}
}The error printed out to the Jenkins console would look something like (and yes, the token will be masked as shown):
Error encountered: hudson.AbortException: new-project returned an error; sub-step failed:
{reference={}, err=error: You must be logged in to the server (the server has asked for the client to provide credentials),
verb=new-project, cmd=kubectl my-new-project --skip-config-write --insecure-skip-tls-verify
--server=https://192.168.1.109:8443 --namespace=myproject --token=XXXXX , out=, status=1}
Want to see the details of your Alauda API Server interactions?
alaudaDevops.withCluster( 'mycluster' ) {
alaudaDevops.verbose()
// Get details printed to the Jenkins console and pass high --log-level to all kubectl commands
alaudaDevops.newProject( 'my-new-project' )
alaudaDevops.verbose(false) // Turn it back
// If you want verbose output, but want a specific log-level
alaudaDevops.logLevel(3)
alaudaDevops.newProject( 'my-new-project-2' )
....
}Getting advanced? You might need more than just default credentials associated with your cluster. You can leverage any Alauda Token credential type in the Jenkins credential store by passing withCredentials the credential's identifier. If you think security is a luxury you can live without (it's not), you can also pass withCredentials a raw token value.
Note: doAs() has been deprecated in favor of withCredentials(), but is currently still supported for use in existing scripts
alaudaDevops.withCluster( 'mycluster' ) {
alaudaDevops.withCredentials( 'my-normal-credential-id' ) {
...
}
alaudaDevops.withCredentials( 'my-privileged-credential-id' ) {
...
}
// Raw token value. Not recommended.
alaudaDevops.withCredentials( 'CO8wPaLV2M2yC_jrm00hCmaz5Jgw...' ) {
...
}
}If the available DSL operations are not sufficient, you can always pass a raw command directly to the kubectl binary. If you do not specify a server, token, or project, normal closure context rules will apply.
alaudaDevops.withCluster( 'mycluster' ) {
def result = alaudaDevops.raw( 'status', '-v' )
echo "Cluster status: ${result.out}"
}But honestly, wouldn't you rather contribute and add the operation you need? ;-)
Are you running your Jenkins instance within an Alauda cluster? Does it only interact with resources within that cluster? You might not need to do anything here! Leaving out the cluster name when calling alaudaDevops.withCluster will cause the plugin to try:
- To access a Jenkins cluster configuration named "default" and, if one does not exist..
- To assume it is running within an Alauda Pod with a service account. In this scenario, the following cluster information will be used:
- API Server URL: "https://${env.KUBERNETES_SERVICE_HOST}:${env.KUBERNETES_SERVICE_PORT_HTTPS}"
- File containing Server Certificate Authority: /run/secrets/kubernetes.io/serviceaccount/ca.crt
- File containing Pod's project name: /run/secrets/kubernetes.io/serviceaccount/namespace
- File containing OAuth Token: /run/secrets/kubernetes.io/serviceaccount/token
alaudaDevops.withCluster() { // find "default" cluster configuration and fallback to Alauda cluster detection
// ... operations relative to the default cluster ...
}If you do need to configure clusters, it is a simple matter. As an authorized Jenkins user, navigate to Manage Jenkins -> Configure System -> and find the Alauda Plugin section.
Add a new cluster and you should see a form like the following.
The cluster "name" (e.g. "mycluster") is the only thing you need to remember when writing scripts. If the cluster configuration has a default credential or project, they will be used automatically when operations are performed relative to that cluster (unless they are explicitly overridden).
alaudaDevops.withCluster( 'mycluster' ) {
// ... operations relative to this cluster ...
}To define a new credential for the DSL in the Jenkins credential store, navigate to Credentials -> System -> Global credentials -> Add Credentials (you can the domain based on your particular security requirements).
This token can then be selected as the default token for a given Jenkins configuration cluster OR used tactically in the DSL with alaudaDevops.withCredentials( 'my-privileged-credential-id' ) {...} .
Each Jenkins node (master/agents) must have a copy of the Alauda command line tool (oc) installed and in the Jenkins PATH environment variable. If your Jenkins nodes are running Alauda images, stop reading here: they are already installed!
If your nodes are running outside of Alauda, you can install the tool on each node yourself, or use Jenkins' Tool installer to do it for you. To do this, as authorized Jenkins user, navigate to Manage Jenkins -> Global Tool Configuration -> and find the "Alauda Client Tools" section.
Here you can define a version of the client tools, where to find them, and if they should be automatically instead when a node requires them.
In the following example, a logical name "oc1.3.2" is associated with a particular build of the client tools available on github.
Using this tool is then a simple matter of executing the Alauda operations with the PATH adjusted to give it preference. If configured as above, the client tools will automatically be installed once on nodes that use the Pipeline 'tool' step.
node('agent1') {
def ocDir = tool "oc1.3.2"
withEnv(["PATH+OC=${ocDir}"]) {
alaudaDevops.withCluster( 'mycluster' ) {
echo "${alaudaDevops.raw( "version" ).out}"
echo "In project: ${alaudaDevops.project()}"
}
}
}Please refer to Jenkins documentation on Global Tool Configuration which allows, for example, Linux and Windows nodes to acquire different builds of a tool.
Understanding the implications of the KUBECONFIG environment variable or presence of .kube/config in the home directory of the user running Jenkins
Users with prior experience with the Alauda command line tool (oc) may be familiar with
the KUBECONFIG environment variable, and the config file location you set for KUBECONFIG,
as a means of establishing default settings for the various parameters for the command.
Similarly default settings can be provided by creating a .kube/config file in the home directory
of whatever user is invoking the oc command if no KUBECONFIG variable is set.
The settings in .kube/config are analogous to the arguments this plugin supplies to oc as a result
of the various DSL methods you employ in your pipeline. If you have established at .kube/config file
in your Jenkins environment which will be found by the invocations of oc your pipeline induces, they
may interfere with the intentions of your use of various alaudaDevops.with... directives in your pipeline.
In the case where you run Jenkins out of an Alauda pod though via the Alauda Jenkins image, the environment is set up such that conflicts of this nature will not occur.
Not exactly. This is a brief overview of some of the capabilities of the plugin. The details of the API are embedded within the plugin's online documentation within a running Jenkins instance. To find it:
- Create a new Pipeline Item
- Click "Pipeline Syntax" below the DSL text area
- On the left navigation menu, click "Global Variables Reference"