Contributing to the Secretless Broker
Thanks for your interest in the Secretless Broker. Before contributing, please take a moment to read and sign our Contributor Agreement. This provides patent protection for all Secretless Broker users and allows CyberArk to enforce its license terms. Please email a signed copy to firstname.lastname@example.org.
Table of Contents
To work in this codebase, you will want to have at least Go 1.11.4 installed.
Due to a dependency on
k8s/client-go, our project requires that you have
installed Mercurial (
hg on the CLI) on your system.
$ brew install mercurial
# Alpine $ apk add -u mercurial # Debian-based $ apt update $ apt install mercurial
Pull Request Workflow
- Search the open issues in GitHub to find out what has been planned
- Select an existing issue or open an issue to propose changes or fixes
- Move the issue to "in progress" in Waffle as you work on it
- Run tests as described here, ensuring they pass
- Submit a pull request, linking the issue in the description
- Move the issue to "in review" in Waffle, ask another contributor to review and merge your code
Our Waffle.io is synchronized with GitHub and helps you navigate this workflow more easily.
In addition to technical workflow descriptions available in Waffle / GitHub, some of the project's technical design documents can be found in the project design folder.
Use this guide to maintain consistent style across the Secretless Broker project.
https://github.com/cyberark/secretless-broker. If you're new to Go, be aware that Go can be very selective
about where the files are placed on the filesystem. There is an environment variable called
GOPATH, whose default value
~/go. Secretless Broker uses go modules which
require either that you clone this repository outside of your
GOPATH or you set the
GO111MODULE environment variable to
on. We recommend cloning this repository outside of your
Once you've cloned the repository, you can build the Secretless Broker.
$ # From Secretless Broker repository root $ ./bin/build
This should create a Docker container with tag
secretless-broker:latest in your local registry.
$ # From Secretless Broker repository root $ go build -o ./secretless-broker ./cmd/secretless-broker
$ # From Secretless Broker repository root $ ./bin/build_darwin
- Docker You need Docker to run the tests.
Build the project by running:
Then run the test cases:
If you are on a Mac, you may also test the OSX Keychain provider:
cd test/manual/keychain_provider/ ./start ./test
This test will not be run as part of the test suite, since it requires access to the Mac OSX Keychain. You will be prompted for your password when running this test, as it temporarily adds a generic password to your account, and verifies that it can retrieve the value.
Kubernetes CRD loading test
cd test/manual/k8s_crds ./deploy
This test currently does not run as part of the test suite.
Profiling can be used to monitor the impact of Secretless on CPU and Memory consumption. Currently, Secretless supports two types- CPU and Memory.
We've provided sample instructions below for profiling the PostgreSQL handler.
Note: If you are running through these instructions yourself, you'll want to
<GOOS>/<GOARCH> with your particular operating system and compilation architecture.
Build Secretless locally
Run a Postgres backend named
pushd test/pg_handler docker build -t sample-pg -f Dockerfile.pg . docker run -d -p 5432:5432 sample-pg popd
Check if Postgres is running and query the database:
$ psql -h localhost -p 5432 -U test dbname=postgres -c "select count(*) from test.test;" count -------- 100000 (1 row)
Create a sample secretless.yml file in the project root that has:
listeners: - name: pg_tcp protocol: pg address: 0.0.0.0:15432 handlers: - name: pg_via_tcp listener: pg_tcp credentials: - name: address provider: env id: PG_ADDRESS - name: username provider: literal id: test - name: password provider: env id: PG_PASSWORD
The type of profiling is explicitly defined in the initial command that runs Secretless. Run Secretless with the profile desired like so:
$ PG_ADDRESS=localhost:5432/postgres \ PG_PASSWORD=test \ ./dist/<GOOS>/<GOARCH>/secretless-broker \ -profile=<cpu or memory> \ -f secretless.yml
Note: The location of the binary may vary across different OS
Once Secretless is running, the type of profiling defined in the previous step should state that it has been enabled. It should look something like:
2018/11/21 10:17:13 profile: cpu profiling enabled, /var/folders/wy/f9qn852d5_d4s_g06s1kwjcr0000gn/T/profile789228879/cpu.pprof
Note: The hash observed will be different each time a profile is run.
Once the Postgres database and Secretless are spun up, query the database through Secretless by running the provided scripts.
Script for CPU profile:
Script for Memory profile:
Note: Ensure that these scripts are given the proper permissions to run
Observe results in a PDF format by running:
go tool pprof --pdf dist/<GOOS>/<GOARCH>/secretless-broker /var/path/to/cpu.pprof > file.pdf
Plugins can be used to extend the functionality of the Secretless Broker via a shared library in
/usr/local/lib/secretless by providing a way to add additional:
- Listener plugins
- Handler plugins
- Connection management plugins
You can read more about how to make plugins and the underlying architecture in the API directory.
Please note: Plugin API interface signatures and supported plugin API version(s) are currently under heavy development so they will be likely to change in the near future.
- Based on the unreleased content, determine the new version number and update the VERSION file.
./bin/prefill_changelog $(cat VERSION)to populate the changelog with the changes included in the release.
- Commit these changes -
Bump version to x.y.zis an acceptable commit message.
- Once your changes have been reviewed and merged into master, tag the version
git tag -s v0.1.1. Note this requires you to be able to sign releases. Consult the github documentation on signing commits on how to set this up.
vx.y.zis an acceptable tag message.
- Push the tag:
git push vx.y.z(or
git push origin vx.y.zif you are working from your local machine).
- From a clean checkout of master run
./bin/build_releaseto generate the release artifacts. Upload these to the GitHub release.