Skip to main content

Jenkins CI Integration

Overview​

To configure Jenkins to use Signadot, below is an example following a Jenkins free-style project using a build script. This takes place in 3 steps.

  • Adding a sandbox specification to the repository.
  • Configuring Jenkins to use the Signadot API key.
  • Configuring a build step to run a script referencing the Signadot API key.

Adding a Sandbox Specification​

When a sandbox is created in a CI context, in general it needs to be tailored to run the changes represented in a pull request or commit. These customizations serve to identify the sandbox in a way that can be associated with the commit and to have the sandbox set up to run the changes in the commit.

To accomplish this, a template of the sandbox specification, in the form of a yaml file is stored within the git repository, by convention in .signadot/<service-name>-template.yaml. The sandbox template below provides a simple example that is setting up a sandbox for a single service called my-svc.

name: "my-svc-@{git-short-commit}"
spec:
  forks:
  - forkOf:
      kind: Deployment
      namespace: default
      name: my-svc
    customizations:
      images:
      - image: "@{image}"
  defaultRouteGroup: # CLI v0.3.7+ required (see sandbox specification for details)
    endpoints:
    - name: my-svc-endpoint       
      target: http://my-svc.default.svc:8080

Configuring the API Key​

First, you will need to obtain an API key from the dashboard.

The Signadot API key should be stored as a Jenkins credential. From the Jenkins main screen, select "Manage Jenkins", then "Manage Credentials" under "Security".

You will be presented with a set of credentials, and a set of credentials stores. You should select a credentials store by clicking on it, for example the store "Jenkins": jenkins-store

Next you will be presented with a list of domains in the store you clicked on. Click on the dropdown menu expander associated with a domain, and select "Add": jenkins-add

Then add the Signadot API key as type "Secret Text": jenkins-sectext

Once you have added the credential to Jenkins, you will be able to refer to it in a build script as described below.

Build Script​

Once the credentials are set up with Jenkins, create a build script and set up its environment.

First, configure the build environment to use the Signadot API key credential we created above: jenkins-buildenv

Then, add a build step to execute a shell script: jenkins-buildstep

Finally, provide the script to setup and test Signadot sandboxes. An example follows.


#
# create sandbox
# setting the gitsha to a short version to respect the name
# limit (30 chars)
#
SIGNADOT_ORG=<my signadot organization>
docker run -i \
  -e SIGNADOT_ORG=${SIGNADOT_ORG} \
  -e SIGNADOT_API_KEY=${SIGNADOT_API_KEY} \
  signadot/signadot-cli \
  /signadot sandbox apply \
  --set image=docker-user/repo:${GIT_COMMIT} \
  --set git-short-commit=${GIT_COMMIT:0:6} \
  -f - \
  -o yaml \
  < .signadot/my-svc-template.yaml \
  > .signadot/my-svc-response.yaml
# print out the sandbox yaml
cat .signadot/my-svc-response.yaml

#
# run integration test scripts here, providing the Signadot API key and
# endpoints as needed to each one.  In this example, we use curl
# as a minimal placeholder that will run on most systems.
#
endpoint=$(yq '.endpoints[0].url' ${GITHUB_WORKSPACE}/.signadot/my-svc-response.yaml)
curl --fail -H "signadot-api-key: ${{ secrets.SIGNADOT_API_KEY }}" $endpoint

#
# delete sandbox
#
docker run -i \
  -e SIGNADOT_ORG=${SIGNADOT_ORG} \
  -e SIGNADOT_API_KEY=${SIGNADOT_API_KEY} \
  signadot/signadot-cli \
  /signadot sandbox apply \
  -f - \
  < ${GITHUB_WORKSPACE}/.signadot/my-svc-response.yaml

Considerations​

Jenkins scripts can be run on a variety of platforms. The example script above supposes Docker and yq are available commands for such scripts.

It is also possible to install signadot directly onto the platform in which the build script is run, to forego the overhead of using docker on every run.