Perceptor is an API server and event handler for consuming, storing, and queueing various workloads associated with responding to events that occur in distributed orchestration systems. Canonically, it manages information related to container events that happen in cloud native orchestration systems (i.e. openshift, kubernetes, ...).
This maintains a model which is essentially a join of the pods and images currently running in the system, and the information relating to those images from the hub.
It contains business logic for deciding when and what to scan, and provides a REST API for perceivers and scanners to communicate with it.
The Perceptor REST API can be consumed from any programming language. We have a Swagger specification. Check out this online viewer or this online viewer to get a nice UI.
Modifications to the REST API or data model should be made with great care in order to maintain backward compatibility. REST API change checklist:
TODO: Automatically generate server stubs from the swagger specification.
Perceivers are workers that notify Perceptor of events, and respond to information that Perceptor acquires about those events.
Perceivers are the canonical extension point to a Perceptor-based deployment to support new platforms and orchestration systems. If you want to build one for your own platform, or customize the way cluster events are processed, check out our Perceivers repo to learn more about them!
Perceivers are responsible for interacting with the platform machinery, finding events and information of interest, and forwarding those to Perceptor. Perceivers are also responsible for taking action based on the scan results available in Perceptor -- whether creating alerts, or writing information into Kubernetes objects.
By splitting perceivers into a separate pod, we gain two things:
Scanners are responsible for performing scan jobs by pulling from the Perceptor scan queue. They do this by using a Black Duck Hub scan client and a running Black Duck Hub. While perceptor scanners can be scaled, the hub itself remains a bottleneck.
curl -sL -o ~/bin/gimme https://raw.githubusercontent.com/travis-ci/gimme/master/gimme
chmod +x ~/bin/gimme
export PATH=$PATH:~/bin/
gimme 1.11
If necessary, set up your GOPATH
and GOROOT
environment variables.
Create a directory based off your GOPATH for Perceptor:
cd $GOPATH
mkdir -p src/github.com/blackducksoftware
cd go/src/github.com/blackducksoftware
git clone https://github.com/blackducksoftware/perceptor.git
Check out the makefile -- from the root directory, run:
make
To run tests:
make test
To run standard go linters:
make lint
We build images, per commit, using cloud build files. We're open to changing our build artifacts over time; take a look at cloudbuild.yaml.
Check out Protoform!
Perceptor embraces the traditional values of open source projects in the Apache and CNCF communities, and emphasizes ideas and community over the code itself.
Please create an issue -- better yet, accompanied with a pull request-- if you have any ideas for metrics, features, tests, or anything else related to Perceptor.
We follow the same standards for golang as are followed in the moby project, the kubernetes project, and other major golang projects.
We embrace modern golang idioms including usage of viper for configuration and dep for dependencies.
We enable travis-ci for builds, which runs all the unit tests associated with your patches. Make sure you submit code with unit tests when possible and verify your tests pass in your pull request. If there are any issues with travis, file an issue and assign it to Jay (jayunit100) and Senthil (msenmurgan).