Following guidelines cover setting up dev environment, running, testing and deploying locally.
- Set up your Development Environment
- Contribution Workflow
- Custom Resource Definitions
- Deploy Image Scanner Operator
-
Install Go
The project requires Go 1.19 or later. We also assume that you're familiar with Go's GOPATH workspace convention, and have the appropriate environment variables set.
-
Get the source code:
git clone git@github.com:statnett/image-scanner-operator.git cd image-scanner-operator
Before you submit an issue, please search the issue tracker. An issue for your problem might already exist and the discussion might inform you of workarounds readily available.
We want to fix all the issues as soon as possible, but before fixing a bug, we need to reproduce and confirm it. To reproduce bugs, we require that you provide minimal reproduction. Having a minimal reproducible scenario gives us a wealth of important information without going back and forth to you with additional questions.
Before you submit your Pull Request (PR) consider the following guidelines:
-
Search GitHub for an open or closed PR that relates to your submission. You don't want to duplicate existing efforts.
-
Be sure that an issue describes the problem you're fixing, or documents the design for the feature you'd like to add. Discussing the design upfront helps to ensure that we're ready to accept your work.
-
Fork the repo.
-
In your forked repository, make your changes in a new git branch:
git checkout -b my-fix-branch main
-
Create your patch, including appropriate test cases.
-
Run
make test
to run both unit and integrations (envtest) tests. envtest runs etcd and apiserver locally without the need for a real Kubernetes cluster. It helps to test the controller and the reconciliation logic. -
Optionally, run the e2e-tests. The e2e tests assumes that you have a working kubernetes cluster (e.g. kind or k3s cluster) and
KUBECONFIG
environment variable is pointing to that cluster configuration file. For example:export KUBECONFIG=~/.kube/config
Note: The operator requires that some dependant software (at the moment Prometheus Operator) is installed in the cluster. If not already present, it can be provisioned by running
make deploy-dependencies
.Run the e2e-tests by running
make e2e-test
. -
Run
golangci-lint
to catch any linter errors.golangci-lint run
-
Commit your changes using a descriptive commit message.
git commit
-
Push your branch to GitHub:
git push origin my-fix-branch
-
In GitHub, send a pull request to
statnett:main
.PR title should be well written as that becomes the commit message when merging. We follow strict Semantic release to determine next semantic version number, generate a changelog and publish the release. Adherence to these conventions is a MUST because release notes are automatically generated from these messages.
Single commit PRs are preferred. We follow trunk based development so larger changes must be broken down to multiple single commit PRs.
This project uses controller-gen
to generate utility code and Kubernetes
manifests from source code and code markers. We currently generate:
- Custom Resource Definitions (CRD)
- RBACs
- Mandatory DeepCopy functions for a Go struct representing a CRD
This means that you should not try to modify any of these files directly, but instead change
the code and code markers. Our Makefile contains a target to ensure that all generated files
are up-to-date: So after doing modifications in code, affecting CRDs/RBAC, you should
run make generate-all
to regenerate everything.
Our CI will verify that all generated is up-to-date.
Any change to the CRD structs, including nested structs, will probably modify the CRD. This is also true for Go docs, as field/type doc becomes descriptions in CRDs.
When it comes to code markers added to the code, run controller-gen -h
for detailed
reference (add more h
's to the command to get more details) or the
markers documentation for an overview.
We are trying to place the RBAC markers close to the code that drives the requirement for permissions. This could lead to the same, or similar, RBAC markers multiple places in the code. This is how we want it to be, since it will allow us to track RBAC changes to code changes. Any permission granted multiple times by markers will be deduplicated by controller-gen.
By default, the operator is deployed to image-scanner
namespace and monitors all the namespaces.
-
Install the image-scanner CRD via
make install
-
Build and deploy the operator image into the kind/k3s cluster:
make k3d-deploy
You can uninstall the operator with:
make undeploy