Project: Trivy-Operator (Provisioning / Security & Compliance)
File: CONTRIBUTING.md

These guidelines will help you get started with the Trivy-operator project. - - - - - - - - - - - - Feel free to open issues for any reason as long as you make it clear what this issue is about: bug/feature/proposal/comment. For questions and general discussions, please do not open an issue, and instead create a discussion in the "Discussions" tab. Please spend a minimal amount of time giving due diligence to existing issues or discussions. Your topic might be a duplicate. If it is, please add your comment to the existing one. Please give your issue or discussion a meaningful title that will be clear for future users. The issue should clearly explain the reason for opening, the proposal if you have any, and any relevant technical information. For technical questions, please explain in detail what you were trying to do, provide an error message if applicable, and your versions of Trivy-Operator and your environment. Every Pull Request should have an associated Issue unless it is a trivial fix. Your PR is more likely to be accepted if it focuses on just one change. Describe what the PR does. There's no convention enforced, but please try to be concise and descriptive. Treat the PR description as a commit message. Titles that start with "fix"/"add"/"improve"/"remove" are good examples. There's no need to add or tag reviewers, if your PR is left unattended for too long, you can add a comment to bring it up to attention, optionally "@" mention one of the maintainers that was involved with the issue. If a reviewer commented on your code or asked for changes, please remember to mark the discussion as resolved after you address it and re-request a review. When addressing comments, try to fix each suggestion in a separate commit. Tests are not required at this point as Trivy-Operator is evolving fast, but if you can include tests that will be appreciated. It is not that strict, but we use the in this repository. Each commit message doesn't have to follow conventions as long as it is clear and descriptive since it will be squashed and merged. Install Go The project requires or later. We also assume that you're familiar with Go's convention, and have the appropriate environment variables set. Get the source code: ``` git clone git@github.com:aquasecurity/trivy-operator.git cd trivy-operator ``` Access to a Kubernetes cluster. We assume that you're using a cluster. To create a single-node KIND cluster, run: ``` kind create cluster ``` Note: Some of our tests performs integration testing by starting a local control plane using . If you only run test using the Magefile (`mage test:unit`), no additional installation is required. But if you want to run some of these integration tests using `go test` or from your IDE, you'll have to . or use `go run mage.go <goal>` | Binary | Image | Description | |-||| | `trivy-operator` | `ghcr.io/aquasecurity/trivy-operator:dev` | Trivy Operator | To build all Trivy-operator binary, run: ``` mage build:all ``` This uses the `go build` command and builds binaries in the `./bin` directory. To build all Trivy-operator binary into Docker images, run: ``` mage build:docker ``` To load Docker images into your KIND cluster, run: ``` mage build:kindloadimages ``` We generally require tests to be added for all, but the most trivial of changes. However, unit tests alone don't provide guarantees about the behaviour of

To verify that each Go module correctly interacts with its collaborators, more coarse grained integration tests might be required. To run all tests with code coverage enabled, run: ``` mage test:unit ``` To open the test coverage report in your web browser, run: ``` go tool cover -html=coverage.txt ``` The Operator envtest spin us partial k8s components (api-server, etcd) and test controllers for reousce, workload, ttl, rbac and more ``` mage test:envtest ``` The integration tests assumes that you have a working kubernetes cluster (e.g KIND cluster) and `KUBECONFIG` environment variable is pointing to that cluster configuration file. For example: ```shell export KUBECONFIG=~/.kube/config ``` To open the test coverage report in your web browser, run: ```shell go tool cover -html=itest/trivy-operator/coverage.txt ``` To run the integration tests for Trivy-operator Operator and view the coverage report, first do the , and then run: ``` OPERATOR_NAMESPACE=trivy-system \ OPERATORTARGETNAMESPACES=default \ OPERATORLOGDEV_MODE=true \ mage test:integration go tool cover -html=itest/trivy-operator/coverage.txt ``` The end 2 end tests assumes that you have a working kubernetes cluster (e.g KIND cluster) and `KUBECONFIG` environment variable is pointing to that cluster configuration file. For example: ```shell export KUBECONFIG=~/.kube/config ``` install kuttl via krew ```shell kubectl krew install kuttl ``` Run cluster infra assessment end to end test via node collector ```shell kubectl kuttl test --start-kind=false --config tests/config/node-collector.yaml ``` Run vulnerability report generation via running trivy with image mode ```shell kubectl kuttl test --start-kind=false --config tests/config/image-mode.yaml ``` Run vulnerability report generation via running trivy with filesystem mode ```shell kubectl kuttl test --start-kind=false --config tests/config/fs-mode.yaml ``` Run vulnerability report generation via running trivy with client/server mode ```shell kubectl kuttl test --start-kind=false --config tests/config/client-server.yaml ``` In the CI workflow, after running all tests, we do upload code coverage reports to . Codecov will merge the reports automatically while maintaining the original upload context as explained . This project uses to generate code and Kubernetes manifests from source-code and code markers. We currently generate: Custom Resource Definitions (CRD) for CRDs defined in trivy-operator ClusterRole that must be bound to the trivy-operator serviceaccount to allow it to function 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 MageFile contains a target to ensure that all generated files are up-to-date: So after doing modifications in code, affecting CRDs/ClusterRole, you should run `mage generate:all` to regenerate everything. Our CI will verify that all generated is up-to-date by running `mage generate:verify`. 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 for an overview. We are trying to place the 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 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. You can deploy the operator in the `trivy-system` namespace and configure it to watch the `default` namespace. In OLM terms such install mode is called SingleNamespace. The SingleNamespace mode is good to get started with a basic development workflow. For other install modes see

Build the operator binary into the Docker image and load it from your host into KIND cluster nodes: ``` mage build:docker && kind load docker-image aquasecurity/trivy-operator:dev ``` Create the `trivy-operator` Deployment in the `trivy-system` namespace to run the operator's container: ``` kubectl create -k deploy/static ``` You can uninstall the operator with: ``` kubectl delete -k deploy/static ``` Deploy the operator in cluster: ``` kubectl apply -f deploy/static/trivy-operator.yaml ``` Scale the operator down to zero replicas: ``` kubectl scale deployment trivy-operator \ -n trivy-system \ --replicas 0 ``` Delete pending scan jobs with: ``` kubectl delete jobs -n trivy-system --all ``` Run the main method of the operator program: ``` OPERATOR_NAMESPACE=trivy-system \ OPERATORTARGETNAMESPACES=default \ OPERATORLOGDEV_MODE=true \ OPERATORVULNERABILITYSCANNER_ENABLED=true \ OPERATORVULNERABILITYSCANNERSCANONLYCURRENTREVISIONS=false \ OPERATORCONFIGAUDITSCANNERENABLED=true \ OPERATORRBACASSESSMENTSCANNERENABLED=true \ OPERATORCONFIGAUDITSCANNERSCANONLYCURRENT_REVISIONS=false \ OPERATORVULNERABILITYSCANNERREPORTTTL="" \ OPERATORBATCHDELETE_LIMIT=3 \ OPERATORBATCHDELETE_DELAY="30s" \ go run cmd/trivy-operator/main.go ``` You can uninstall the operator with: ``` kubectl delete -f deploy/static/trivy-operator.yaml ``` We consider the Helm chart to be the master for deploying trivy-operator. Since some prefer to not use Helm, we also provide static resources to install the operator. To avoid maintaining resources in multiple places, we have a created a script to (re)generate the static resources from the Helm chart. So if modifying the operator resources, please do so by modifying the Helm chart, then run `mage generate:manifests` to ensure the static resources are up-to-date. We consider the Helm chart to be the master for deploying trivy-operator. Since some prefer to not use Helm, we also provide helm config documentation to install the operator. So if modifying the operator helm params, please do so by modifying the Helm chart, then run `mage generate:docs` to ensure the helm docs are up-to-date. To install [Operator Lifecycle Manager] (OLM) run: ``` kubectl apply -f https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.20.1/crds.yaml kubectl apply -f https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.20.1/olm.yaml ``` or ``` curl -L https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.21.4/install.sh -o install.sh chmod +x install.sh ./install.sh v0.20.1 ``` The Trivy Operator metadata is formatted in packagemanifest layout, so you need to place it in the directory structure of the [community-operators] repository. ``` git clone git@github.com:k8s-operatorhub/community-operators.git cd community-operators ``` Build the catalog image for OLM containing just Trivy Operator with a Dockerfile like this: ``` cat << EOF > trivy-operator.Dockerfile FROM quay.io/operator-framework/upstream-registry-builder as builder COPY operators/trivy-operator manifests RUN /bin/initializer -o ./bundles.db FROM scratch COPY --from=builder /etc/nsswitch.conf /etc/nsswitch.conf COPY --from=builder /bundles.db /bundles.db COPY --from=builder /bin/registry-server /registry-server COPY --from=builder /bin/grpchealthprobe /bin/grpchealthprobe EXPOSE 50051 ENTRYPOINT ["/registry-server"] CMD ["--database", "bundles.db"] EOF ``` Place the `trivy-operator.Dockerfile` in the top-level directory of your cloned copy of the [community-operators] repository, build it and push to a registry from where you can download it to your Kubernetes cluster: ``` docker image build -f trivy-operator.Dockerfile -t docker.io/<your account>/trivy-operator-catalog:dev . docker image push docker.io/<your account>/trivy-operator-catalog:dev ``` Create a CatalogSource instance in the `olm` namespace to reference in the Operator catalog image that contains the Trivy Operator: ``` cat << EOF | kubectl apply -f - apiVersion: operators.coreos.com/v1alpha1 kind: CatalogSource metadata: name: trivy-operator-catalog namespace: olm spec: publisher: trivy-operator Maintainers displayName: trivy-operator Catalog sourceType: grpc image: docker.io/<your account>/trivy-operator-catalog:dev EOF ``` You can delete the default catalog that OLM ships with to avoid duplicate entries: ``` kubectl delete catalogsource operatorhubio-catalog -n olm ``` Inspect the list of loaded package manifests on the system with the following command to filter for the Trivy Operator: ```console $ kubectl get packagemanifests NAME CATALOG AGE trivy-operator trivy-operator Catalog 97s ``` If the Trivy Operator appears in this list, the catalog was successfully parsed and it is now available to install. Follow the installation instructions for . Make sure that the Subscription's `spec.source` property refers to the `trivy-operator-catalog` source instead of `operatorhubio-catalog`. You can find more details about testing