Jenkins

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: "@{name}"
spec:
  cluster: "@{cluster}"
  forks:
  - forkOf:
      kind: Deployment
      namespace: default
      name: my-svc
    customizations:
      images:
      - image: "@{image}"

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":

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":

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

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:

Then, add a build step to execute a shell script:

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

# Set up env vars
export SIGNADOT_ORG=<my signadot organization>
export SIGNADOT_CLUSTER=<my signadot cluster>
export IMAGE_TAG="${GIT_COMMIT}"
# Define the sandbox name using a short version of the gitsha to respect the
# limit (30 chars)
export SANDBOX_NAME="my-svc-${GIT_COMMIT:0:6}"


# Create a sandbox
echo "Creating sandbox ${SANDBOX_NAME}..."
docker run -i \
  -e SIGNADOT_ORG=${SIGNADOT_ORG} \
  -e SIGNADOT_API_KEY=${SIGNADOT_API_KEY} \
  signadot/signadot-cli \
    /signadot sandbox apply \
      --set name=${SANDBOX_NAME} \
      --set image=docker-user/repo:${IMAGE_TAG} \
      --set cluster=${SIGNADOT_CLUSTER} \
      -f - \
      < .signadot/my-svc-template.yaml


# Optionally run automated tests using jobs
echo "Running automated tests..."
docker run -i \
  -e SIGNADOT_ORG=${SIGNADOT_ORG} \
  -e SIGNADOT_API_KEY=${SIGNADOT_API_KEY} \
  signadot/signadot-cli \
    /signadot job submit --attach -f \
      --set branch=... \
      -f - \
      < ${GITHUB_WORKSPACE}/.signadot/job.yaml

# Optionally delete the sandbox if only running automated tests
# else you may omit this and delete on PR close / using TTL
docker run -i \
  -e SIGNADOT_ORG=${SIGNADOT_ORG} \
  -e SIGNADOT_API_KEY=${SIGNADOT_API_KEY} \
  signadot/signadot-cli \
  /signadot sandbox delete ${SANDBOX_NAME}

Considerations

Jenkins scripts can be run on a variety of platforms. The example script above supposes Docker is an available command 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.