BitBucket CI Integration
Overview
This document provides an overview of integrating the Signadot CLI with BitBucket, using BitBucket Pipelines.
Implementing the integration follows this basic outline:
- Adding a sandbox specification to the repository.
- Setting up the Signadot configuration.
- Creating the pipeline.
Finally, there is a description of an optional, more advanced custom image which speeds up CI runs by pre-installing dependencies in a custom pipelines container image.
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:
- container: hotrod
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
Setting up the Signadot configuration
The signadot
command needs to have two parameters configured.
- Signadot Org, which is the name of your organization's account
with Signadot. In CI contexts, this is usually easiest to accomplish by
setting the environmental variable
SIGNADOT_ORG
when running the command. - API key required to access Signadot. This is
also usally easiest to accommplish by setting the environmental variable
SIGNADOT_API_KEY
when running the command, which in turn should be stored as a BitBucket secured variable.
Both of these values are made available when a new API Key is created via the Signadot Dashboard.
Refer to BitBucket variables for more information about setting variables.
Pipeline YAML
Below is an example BitBucket pipeline configuration yaml file which sets up a single service sandbox for a 'my-svc' service.
image: atlassian/default-image:3
pipelines:
default:
- step:
name: 'Create Sandbox'
services:
- docker
script:
- |
# run the cli
# setting the gitsha to a short version to respect the name
# limit (30 chars)
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:${BITBUCKET_COMMIT} \
--set git-short-commit=${BITBUCKET_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
artifacts:
# store the response sandbox spec as an artifact for usage in
# subsequent steps.
- .signadot/my-svc-response.yaml
- step:
name: 'Test Changes'
# This supposes ./yq was stored as an artifact from a setup step
# created with
# - go install github.com/mikefarah/yq/v4@latest
# - cp ${HOME}/go/bin/yq .
script:
- |
endpoint=$(./yq '.endpoints[0].url' .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.
#
curl --fail -H "signadot-api-key: ${{ secrets.SIGNADOT_API_KEY }}" $endpoint
- step:
name: 'Delete Sandbox'
services:
- docker
script:
- |
docker run -i \
-e SIGNADOT_ORG=${SIGNADOT_ORG} \
-e SIGNADOT_API_KEY=${SIGNADOT_API_KEY} \
signadot/signadot-cli \
/signadot sandbox delete -f - \
< .signadot/my-svc-response.yaml
Optimization with a Custom Image
Bitbucket allows using a custom docker image, and doing so can significantly speed
up the execution of the steps associated with sandboxes. A custom image for
BitBucket can be built providing the commands signadot
and yq
directly, as in
the Dockerfile below. With this in place, one can use the commands directly instead
of calling them via docker run -i ... signadot/signadot-cli ...
, or installing yq
with every run.
# signadot
FROM signadot/signadot-cli as signadot
# yq
FROM golang:1.19 as yq
RUN go install github.com/mikefarah/yq/v4@latest
# this is the beginning of the BitBucket default
# Dockerfile for version 3.
FROM atlassian/default-image:3
# add the tools for working with signadot
COPY --from=signadot /signadot /usr/bin/signadot
COPY --from=yq /go/bin/yq /usr/bin/yq