Modifying the Operator

Prerequisites

Golang

The operator is written in Golang. To build the operator you will need to install Go.

Local Kubernetes Environment

For local development we recommend to use Minikube or kind. If you are using MacOS or Windows you can also use the kubernetes cluster included within Docker for Mac/Windows. All of these tools will enable you to run a local kubernetes cluster on your development machine.

Operating Your Local Kubernetes Cluster

To operate your (local) Kubernetes cluster you will need to install kubectl and helm

macOS

For macOs simply use Homebrew to install all the tools:

brew cask install docker
brew install go helm

After that start the Docker.app and go to it's settings and start Kubernetes.

Minio

For your local development you will need a S3 compatible storage. We would recommend to use Minio inside a docker container.

docker container run \
  --name minio \
  -p 9000:9000 \
  -p 9001:9001 \
  -d \
  --rm \
  minio/minio \
  server /data \
  --console-address ":9001"

In the Minio management GUI you will need to add a new bucket for the operator. The default credentials for your minio instance are minioadmin:minioadmin. You might change those. Go to the management UI at http://localhost:9001/ and add a new bucket. After creating your bucket you will need to specify some environment variables to enable the operator to use the bucket. For that export these variables:

export MINIO_ACCESS_KEY="your-minio-access-key"
export MINIO_SECRET_KEY="your-minio-secret-key"
export S3_BUCKET="name-of-your-bucket"
export S3_USE_SSL="false" # This ensures that the operator will connect even without HTTPS
export S3_ENDPOINT="127.0.0.1:9000"

You can save time by using direnv to export these variables in your project. If you use direnv just add a file .s3_credentials with your Minio credentials.

Build and Run the Operator

To build and run the operator you can simply execute make in the operator directory of this repository:

cd operator
make

This will produce the operator as bin/manager. If you wonder why the operator is named manager (the resulting binary). The reason for that is in Kubernetes a combination of more than one controller is called controller-manager or short manager. In contrast, operator is created by the community to name a controller-manager which controls custom resources and hence we use custom resources. (see https://book.kubebuilder.io/ for further information)

To run the operator locally you can simply execute make run in the operator directory of this repository:

NOTICE: You will need to uninstall the operator with helm -n securecodebox-system uninstall securecodebox-operator from your local cluster, if you've installed it via helm. Unless both operators try to work on the same cluster which may cause unexpected behavior.

cd operator
make run

To run multiple operator instances locally (e.g. SCB operator and SCB Autodiscovery operator) the metrics-bind-address and health-probe-bind-address port needs to be changed via commandline arguements for one of the operators.

go run ./main.go -metrics-bind-address :9090 -health-probe-bind-address :9595

Structure

The operator was build based on the kubebuilder. Here is a very short summery on the important files. For a better understanding you should read the kubebuilder

API and Controller Files:

apis/

The files defines the APIs for the custom resources (CRDs) e.g. the file scan_types.go defines the schema (Spec, Status etc.) for the CRD Scan. The fields and definitions are changed here. To update the the CRDs in the operator run make install in the /operator directory.

controllers/

Contains the controllers that manage the CRDs e.g. scantype_controller.go implements how scans are started, updated and terminated.

Reconcile Function: The reconcile function is a loop that checks the current state of the resource and updates them according to their state.