https://github.com/validator-labs/validator
validator monitors ValidationResults created by one or more validator plugins and uploads them to a configurable sink.
https://github.com/validator-labs/validator
alerting infrastructure-automation kubernetes validation validator validators verification
Last synced: about 2 months ago
JSON representation
validator monitors ValidationResults created by one or more validator plugins and uploads them to a configurable sink.
- Host: GitHub
- URL: https://github.com/validator-labs/validator
- Owner: validator-labs
- License: apache-2.0
- Created: 2023-08-22T22:05:20.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-02-03T22:30:03.000Z (about 2 months ago)
- Last Synced: 2026-02-04T06:32:14.081Z (about 2 months ago)
- Topics: alerting, infrastructure-automation, kubernetes, validation, validator, validators, verification
- Language: Go
- Homepage: https://validator-labs.github.io/docs
- Size: 1.99 MB
- Stars: 16
- Watchers: 3
- Forks: 3
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
[](https://github.com/validator-labs/validator/issues)
[](https://opensource.org/licenses/Apache-2.0)
[](https://goreportcard.com/report/github.com/validator-labs/validator)
[](https://codecov.io/gh/validator-labs/validator)
[](https://pkg.go.dev/github.com/validator-labs/validator)
validator (AKA Validation Controller) monitors ValidationResults created by one or more validator plugins and uploads them to a sink of your choosing, e.g., Slack or Alertmanager.
## Description
The validator repository is fairly minimal - all the heavy lifting is done by the validator plugins. Installation of validator and one or more plugins is accomplished via Helm.
Plugins:
- [AWS](https://github.com/validator-labs/validator-plugin-aws)
- [Azure](https://github.com/validator-labs/validator-plugin-azure)
- [Network](https://github.com/validator-labs/validator-plugin-network)
- [OCI](https://github.com/validator-labs/validator-plugin-oci)
- [vSphere](https://github.com/validator-labs/validator-plugin-vsphere)
- [Kubescape](https://github.com/validator-labs/validator-plugin-kubescape)
## Installation
### Connected
For connected installations, two options are supported: the validator CLI, `validatorctl`, and Helm. Using validatorctl is **recommended**, as it provides a text-based user interface (TUI) for configuring validator.
#### Validator CLI
1. Download the latest release of validatorctl from https://github.com/validator-labs/validatorctl/releases
2. Execute validatorctl
```bash
validatorctl install
```
#### Helm
Install Validator by pulling the latest Helm chart and installing it in your cluster. Use the following commands to install the latest version of the chart.
```bash
helm repo add validator https://validator-labs.github.io/validator
helm repo update
helm install validator validator/validator -n validator --create-namespace
```
Check out the [Helm install guide](./docs/install.md) for a step-by-step guide for installing and using Validator.
### Air-gapped
For air-gapped installations, the recommended approach is to use [Hauler](https://github.com/rancherfederal/hauler). Hauls containing all validator artifacts (container images, Helm charts, and the validator CLI) are generated for multiple platforms (linux/amd64 and linux/arm64) during each validator release.
Prerequisites:
* A Linux-based air-gapped workstation with:
* A container runtime, e.g., [containerd](https://containerd.io/docs/getting-started/), [Docker Engine](https://docs.docker.com/engine/), etc.
* If using a container runtime other than Docker Engine, [podman](https://podman.io/docs/installation) must be installed and [Docker CLI emulation](https://podman-desktop.io/docs/migrating-from-docker/emulating-docker-cli-with-podman) configured
* [kind](https://github.com/kubernetes-sigs/kind/releases) installed and on your PATH
* [hauler](https://github.com/hauler-dev/hauler/releases) installed and on your PATH
Once the prerequisites are met, the following steps document the air-gapped installation procedure:
1. Download the Hauler Store (then somehow get it across the air-gap)
```bash
# Download the Haul for your chosen release and platform, e.g.:
curl -L https://github.com/validator-labs/validator/releases/download/v0.0.46/validator-haul-linux-amd64.tar.zst -o validator-haul-linux-amd64.tar.zst
```
2. Load the Hauler Store (on the air-gapped workstation)
```bash
# Load the air-gapped content to your local hauler store.
hauler store load validator-haul-linux-amd64.tar.zst
```
3. Extract validatorctl from the Hauler Store
```bash
# Extract the validator CLI binary, validatorctl, from the hauler store.
# It's always tagged as "latest" within the store, despite being versioned.
# This is a hauler defect. The version can be verified via `validatorctl version`.
hauler store extract -s store hauler/validatorctl:latest
chmod +x validatorctl && mv validatorctl /usr/local/bin
```
4. Serve the Hauler Store
```bash
# Serve the content as a registry from the hauler store.
# (Defaults to :5000).
nohup hauler store serve registry | tee -a hauler.log &
# Optionally tail the hauler registry logs
tail -f hauler.log
```
5. Execute validatorctl
```bash
validatorctl install
```
## Sinks
Validator can be configured to emit updates to various event sinks whenever a `ValidationResult` is created or updated. See configuration details below for each supported sink.
### Alertmanager
Integrate with the Alertmanager API to emit alerts to all [supported Alertmanager receivers](https://prometheus.io/docs/alerting/latest/configuration/#receiver-integration-settings), including generic webhooks. The only required configuration is an Alertmanager endpoint. HTTP basic authentication and TLS are also supported. See [values.yaml](https://github.com/validator-labs/validator/blob/main/chart/validator/values.yaml) for configuration details.
#### Sample Output
#### Setup
1. Install Alertmanager in your cluster (if it isn't installed already)
2. Configure Alertmanager alert content. Alerts can be formatted/customized via the following labels and annotations:
Labels
- alertname
- plugin
- validation_result
- expected_results
Annotations
- state
- validation_rule
- validation_type
- message
- status
- detail
- pipe-delimited array of detail messages, see sample config for parsing example
- failure (also pipe-delimited)
- last_validation_time
Example Alertmanager ConfigMap used to produce the sample output above:
```yaml
apiVersion: v1
data:
alertmanager.yml: |
global:
slack_api_url: https://slack.com/api/chat.postMessage
receivers:
- name: default-receiver
slack_configs:
- channel:
text: |-
{{ range .Alerts.Firing -}}
*Validation Result: {{ .Labels.validation_result }}/{{ .Labels.expected_results }}*
{{ range $k, $v := .Annotations }}
{{- if $v }}*{{ $k | title }}*:
{{- if match "\\|" $v }}
- {{ reReplaceAll "\\|" "\n- " $v -}}
{{- else }}
{{- printf " %s" $v -}}
{{- end }}
{{- end }}
{{ end }}
{{ end }}
title: "{{ (index .Alerts 0).Labels.plugin }}: {{ (index .Alerts 0).Labels.alertname }}\n"
http_config:
authorization:
credentials: xoxb---
send_resolved: false
route:
group_interval: 10s
group_wait: 10s
receiver: default-receiver
repeat_interval: 1h
templates:
- /etc/alertmanager/*.tmpl
kind: ConfigMap
metadata:
name: alertmanager
namespace: alertmanager
```
2. Install validator and/or upgrade your validator Helm release, configuring `values.sink` accordingly.
### Slack
#### Sample Output
#### Setup
1. Go to https://api.slack.com/apps and click **Create New App**, then select **From scratch**. Pick an App Name and Slack Workspace, then click **Create App**.
2. Go to `OAuth & Permissions` and copy the `Bot User OAuth Token` under the `OAuth Tokens for Your Workspace` section. Save it somewhere for later. Scroll down to `Scopes` and click **Add an OAuth Scope**. Enable the `chat:write` scope for your bot.
3. Find and/or create a channel in Slack and note its Channel ID (at the very bottom of the modal when you view channel details). Add the bot you just created to the channel via `View channel details > Integrations > Apps > Add apps`.
4. Install validator and/or upgrade your validator Helm release, configuring `values.sink` accordingly.
## Development
You’ll need a Kubernetes cluster to run against. You can use [kind](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster.
**Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).
### Running on the cluster
1. Install Instances of Custom Resources:
```sh
kubectl apply -f config/samples/
```
2. Build and push your image to the location specified by `IMG`:
```sh
make docker-build docker-push IMG=/validator:tag
```
3. Deploy the controller to the cluster with the image specified by `IMG`:
```sh
make deploy IMG=/validator:tag
```
### Uninstall CRDs
To delete the CRDs from the cluster:
```sh
make uninstall
```
### Undeploy controller
UnDeploy the controller from the cluster:
```sh
make undeploy
```
## Contributing
All contributions are welcome! Feel free to reach out on the [Spectro Cloud community Slack](https://spectrocloudcommunity.slack.com/join/shared_invite/zt-g8gfzrhf-cKavsGD_myOh30K24pImLA#/shared-invite/email).
Make sure `pre-commit` is [installed](https://pre-commit.com#install).
Install the `pre-commit` scripts:
```console
pre-commit install --hook-type commit-msg
pre-commit install --hook-type pre-commit
```
### How it works
This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/).
It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/),
which provide a reconcile function responsible for synchronizing resources until the desired state is reached on the cluster.
### Test It Out
1. Install the CRDs into the cluster:
```sh
make install
```
2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running):
```sh
make run
```
**NOTE:** You can also run this in one step by running: `make install run`
### Modifying the API definitions
If you are editing the API definitions, generate the manifests such as CRs or CRDs using:
```sh
make manifests
```
**NOTE:** Run `make --help` for more information on all potential `make` targets
More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)