API Reference

Complete API documentation for kspec Custom Resource Definitions

API Reference

This document provides detailed API documentation for all kspec Custom Resource Definitions (CRDs).

ClusterSpecification

Defines the desired security and compliance posture for a Kubernetes cluster.

API Version: kspec.io/v1alpha1

Spec Fields

targetClusterRef (Object, Required) Reference to the target cluster

enforcementMode (String, Required) Enforcement mode: monitor or enforce

policies (Array, Required) List of policy definitions

Example

apiVersion: kspec.io/v1alpha1
kind: ClusterSpecification
metadata:
  name: production-spec
  namespace: kspec-system
spec:
  targetClusterRef:
    name: production-cluster
  enforcementMode: enforce
  policies:
    - id: "pod-security"
      title: "Pod Security Standards"
      description: "Baseline pod security requirements"
      severity: high
      checks:
        - id: "require-non-root"
          title: "Require runAsNonRoot"
          kyvernoPolicy: |
            apiVersion: kyverno.io/v1
            kind: ClusterPolicy
            # ... policy definition

Status Fields

conditions (Array) Current state of the specification

observedGeneration (Integer) Latest generation observed

phase (String) Current phase: Pending, Active, or Failed

ClusterTarget

Represents a Kubernetes cluster to apply policies to.

API Version: kspec.io/v1alpha1

Spec Fields

inCluster (Boolean, Optional) Whether this is the current cluster

kubeconfig (Object, Optional) Kubeconfig for remote cluster

platform (String, Optional) Cloud platform: eks, gke, aks, kind, etc.

version (String, Required) Kubernetes version

Example: In-Cluster

apiVersion: kspec.io/v1alpha1
kind: ClusterTarget
metadata:
  name: local-cluster
  namespace: kspec-system
spec:
  inCluster: true
  platform: kind
  version: "1.28.0"

Example: Remote Cluster

apiVersion: kspec.io/v1alpha1
kind: ClusterTarget
metadata:
  name: remote-cluster
  namespace: kspec-system
spec:
  inCluster: false
  kubeconfig:
    secretRef:
      name: remote-kubeconfig
      key: kubeconfig
  platform: eks
  version: "1.28.0"

ComplianceReport

Generated automatically by kspec to track compliance status.

API Version: kspec.io/v1alpha1

Spec Fields

clusterRef (Object) Reference to the target cluster

specRef (Object) Reference to the ClusterSpecification

timestamp (String) When the report was generated

Status Fields

totalPolicies (Integer) Total number of policies

compliantPolicies (Integer) Number of compliant policies

violationCount (Integer) Total violations found

complianceScore (Float) Overall compliance percentage

policyResults (Array) Detailed results per policy

Example

apiVersion: kspec.io/v1alpha1
kind: ComplianceReport
metadata:
  name: production-spec-report
  namespace: kspec-system
spec:
  clusterRef:
    name: production-cluster
  specRef:
    name: production-spec
  timestamp: "2025-12-30T10:00:00Z"
status:
  totalPolicies: 10
  compliantPolicies: 8
  violationCount: 15
  complianceScore: 80.0
  policyResults:
    - policyID: "pod-security"
      status: "compliant"
      violations: []
    - policyID: "network-policies"
      status: "violation"
      violations:
        - namespace: "default"
          resource: "Namespace/default"
          message: "Missing NetworkPolicy"

DriftReport

Tracks configuration drift between desired and actual policies.

API Version: kspec.io/v1alpha1

Spec Fields

clusterRef (Object) Reference to the target cluster

specRef (Object) Reference to the ClusterSpecification

timestamp (String) When drift detection ran

Status Fields

driftDetected (Boolean) Whether drift was detected

driftEvents (Array) List of drift events

Drift Event Types

  • missing: Expected policy not found in cluster
  • modified: Policy exists but differs from specification
  • extra: Unexpected policy found in cluster

Example

apiVersion: kspec.io/v1alpha1
kind: DriftReport
metadata:
  name: production-drift-report
  namespace: kspec-system
spec:
  clusterRef:
    name: production-cluster
  specRef:
    name: production-spec
  timestamp: "2025-12-30T10:15:00Z"
status:
  driftDetected: true
  driftEvents:
    - type: "modified"
      policyID: "pod-security"
      resourceName: "require-run-as-non-root"
      message: "Policy validationFailureAction changed"
      detectedAt: "2025-12-30T10:15:00Z"

Policy Specification

Policies are defined within ClusterSpecification resources.

Policy Fields

id (String, Required) Unique policy identifier

title (String, Required) Human-readable title

description (String, Optional) Detailed description

severity (String, Required) Policy severity: critical, high, medium, or low

checks (Array, Required) List of validation checks

Check Fields

id (String, Required) Unique check identifier

title (String, Optional) Human-readable title

kyvernoPolicy (String, Required) Kyverno policy YAML

Metrics

kspec exposes Prometheus metrics for monitoring.

Available Metrics

kspec_compliance_score (Gauge) Overall compliance percentage

kspec_policy_violations_total (Counter) Total policy violations

kspec_drift_events_total (Counter) Total drift events detected

kspec_reconciliation_duration_seconds (Histogram) Controller reconciliation time

Example Prometheus Query

# Average compliance score across all clusters
avg(kspec_compliance_score)

# Policy violations in last hour
increase(kspec_policy_violations_total[1h])

# Drift detection rate
rate(kspec_drift_events_total[5m])

RBAC

Required permissions for kspec operator.

ClusterRole Example

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kspec-operator
rules:
  - apiGroups: ["kspec.io"]
    resources: ["*"]
    verbs: ["*"]
  - apiGroups: ["kyverno.io"]
    resources: ["clusterpolicies", "policies"]
    verbs: ["*"]
  - apiGroups: [""]
    resources: ["pods", "services", "configmaps"]
    verbs: ["get", "list", "watch"]

Next Steps

Found an issue? Edit this page on GitHub