README
¶
EarlyWatch
EarlyWatch is a Kubernetes admission controller that implements change safety — it ensures that changes to Kubernetes resources are safe before they occur.
For example, EarlyWatch can prevent you from deleting a Service while there are still Pods running that match the Service's label selector.
How It Works
EarlyWatch introduces a ChangeValidator custom resource. Each ChangeValidator watches a specific Kubernetes resource type and defines a set of safety rules. When an admission request matches a guard's subject and operations, the EarlyWatch webhook evaluates the rules against the current cluster state. If any rule is violated the request is denied with a clear error message.
User/CI → kubectl delete service my-svc
│
▼
Kubernetes API Server
│
│ ValidatingWebhookConfiguration
▼
EarlyWatch Webhook
│
│ lists ChangeValidator rules for "services"
│ queries cluster for matching Pods
▼
DENY: "This Service cannot be deleted because Pods that
match its label selector are still running."
Quick Start
# Build the CLI
go build -o watchctl ./cmd/watchctl/...
# Install EarlyWatch onto your cluster
./watchctl install
# Apply a sample ChangeValidator
kubectl apply -f config/samples/protect_service.yaml
See docs/getting-started.md for a full walkthrough.
Documentation
Change Validator Summaries
| Validator Type | Summary | Sample YAML |
|---|---|---|
ExistingResources |
Denies a request when dependent resources still exist (for example, matching Pods behind a Service). | docs/examples/existing-resources.yaml |
NameReferenceCheck |
Denies a request when the subject is still referenced by name in other resources. | docs/examples/name-reference-check.yaml |
AnnotationCheck |
Denies a request unless a required annotation (optionally with a required value) is present. | docs/examples/annotation-check.yaml |
ApprovalCheck |
Denies a request unless the resource carries a valid RSA-PSS approval signature annotation. | docs/examples/approval-check.yaml |
CheckLock |
Denies DELETE (and optionally UPDATE) when earlywatch.io/lock is set with a non-empty value. |
docs/examples/check-lock.yaml |
ExpressionCheck |
Denies a request when a configured expression against operation/namespace/name evaluates to true. | docs/examples/expression-check.yaml |
ManualTouchCheck |
Denies a request when a recent manual touch event exists within the configured time window. | docs/examples/manual-touch-check.yaml |
ServicePodSelectorCheck |
Denies a Service UPDATE when the old selector matched Pods but the new selector would match none. | docs/examples/service-pod-selector-check.yaml |
Interactive Demo Matrix
Run a specific validator demo with:
bash scripts/demo.sh --demos=<key>
| Validator Type | Demo Key (--demos) |
Demo Script |
|---|---|---|
ExistingResources |
service |
scripts/demo-service.sh |
NameReferenceCheck |
configmap |
scripts/demo-configmap.sh |
AnnotationCheck |
annotation |
scripts/demo-annotation-check.sh |
ApprovalCheck |
approval |
scripts/demo-approval-check.sh |
CheckLock |
checklock |
scripts/demo-check-lock.sh |
ExpressionCheck |
expression |
scripts/demo-expression-check.sh |
ManualTouchCheck |
manualtouch |
scripts/demo-manual-touch-check.sh |
ServicePodSelectorCheck |
servicepodselector |
scripts/demo-service-pod-selector-check.sh |
| Topic | Link |
|---|---|
| Getting started | docs/getting-started.md |
| Architecture and source tree | docs/architecture.md |
| ChangeValidator CRD reference | docs/custom-resources/change-validator.md |
| ManualTouchMonitor CRD reference | docs/custom-resources/manual-touch-monitor.md |
| Rule types | docs/rule-types/ |
| CLI reference (watchctl) | docs/cli/watchctl.md |
| Manual cluster deployment | docs/deployment/cluster-setup.md |
| TLS and cert-manager | docs/deployment/tls-and-cert-manager.md |
| Contributing and development | docs/contributing/development.md |
| Go style guide | docs/style-guide.md |
License
See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
audit-monitor
command
Package main is the entry point for the EarlyWatch audit monitor server.
|
Package main is the entry point for the EarlyWatch audit monitor server. |
|
watchctl
command
Package main is the entry point for the watchctl command-line tool.
|
Package main is the entry point for the watchctl command-line tool. |
|
webhook
command
Package main is the entry point for the EarlyWatch admission webhook server.
|
Package main is the entry point for the EarlyWatch admission webhook server. |
|
pkg
|
|
|
add
Package add provides the core logic for applying ChangeValidator YAML manifests from a file or directory path onto a Kubernetes cluster.
|
Package add provides the core logic for applying ChangeValidator YAML manifests from a file or directory path onto a Kubernetes cluster. |
|
apis/earlywatch/v1alpha1
Package v1alpha1 contains API Schema definitions for the earlywatch.io v1alpha1 API group.
|
Package v1alpha1 contains API Schema definitions for the earlywatch.io v1alpha1 API group. |
|
approve
Package approve provides the core logic for signing a Kubernetes resource's canonical path with an RSA private key and writing the resulting signature as an annotation on the resource.
|
Package approve provides the core logic for signing a Kubernetes resource's canonical path with an RSA private key and writing the resulting signature as an annotation on the resource. |
|
auditmonitor
Package auditmonitor implements an HTTP sink for Kubernetes audit log webhooks.
|
Package auditmonitor implements an HTTP sink for Kubernetes audit log webhooks. |
|
install
Package install provides the core logic for applying the EarlyWatch infrastructure manifests (CRD, RBAC, webhook) onto a Kubernetes cluster.
|
Package install provides the core logic for applying the EarlyWatch infrastructure manifests (CRD, RBAC, webhook) onto a Kubernetes cluster. |
|
internal/apply
Package apply provides shared utilities for applying Kubernetes manifests via Server-Side Apply, used by both the install and add commands.
|
Package apply provides shared utilities for applying Kubernetes manifests via Server-Side Apply, used by both the install and add commands. |
|
listtouches
Package listtouches provides the core logic for listing ManualTouchEvent resources from a Kubernetes cluster.
|
Package listtouches provides the core logic for listing ManualTouchEvent resources from a Kubernetes cluster. |
|
webhook
Package webhook implements the EarlyWatch admission webhook handler.
|
Package webhook implements the EarlyWatch admission webhook handler. |
Click to show internal directories.
Click to hide internal directories.