Install kspec

Get started with kspec in your Kubernetes cluster

Prerequisites

Kubernetes cluster (v1.24+)
kubectl configured with cluster access
cert-manager installed (for webhook certificates)
Kyverno installed (policy engine)

Step 1: Install Dependencies

Install cert-manager

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.3/cert-manager.yaml

# Wait for cert-manager to be ready
kubectl wait --for=condition=Available deployment/cert-manager -n cert-manager --timeout=120s

Install Kyverno (via Helm)

Important: You must install Kyverno using Helm, not raw manifests.

helm repo add kyverno https://kyverno.github.io/kyverno/
helm repo update

helm install kyverno kyverno/kyverno \
  --namespace kyverno \
  --create-namespace \
  --wait \
  --timeout=5m

Step 2: Install kspec Operator

Option A: Using kubectl

# Install CRDs
kubectl apply -f https://raw.githubusercontent.com/cloudcwfranck/kspec/main/config/crd/bases/kspec.io_clusterspecifications.yaml
kubectl apply -f https://raw.githubusercontent.com/cloudcwfranck/kspec/main/config/crd/bases/kspec.io_clustertargets.yaml
kubectl apply -f https://raw.githubusercontent.com/cloudcwfranck/kspec/main/config/crd/bases/kspec.io_compliancereports.yaml
kubectl apply -f https://raw.githubusercontent.com/cloudcwfranck/kspec/main/config/crd/bases/kspec.io_driftreports.yaml

# Install operator
kubectl apply -k https://github.com/cloudcwfranck/kspec/config/default

# Verify installation
kubectl get pods -n kspec-system -l control-plane=controller-manager

Option B: Using kustomize

# Clone the repository
git clone https://github.com/cloudcwfranck/kspec.git
cd kspec

# Build and apply
kubectl apply -k config/default

# Verify installation
kubectl get deployment -n kspec-system kspec-operator-controller-manager

Step 3: Create Your First ClusterSpecification

Create a ClusterTarget to reference your cluster, then define a ClusterSpecification with policies.

Create ClusterTarget

cat <<EOF | kubectl apply -f -
apiVersion: kspec.io/v1alpha1
kind: ClusterTarget
metadata:
  name: production-cluster
  namespace: kspec-system
spec:
  inCluster: true
  platform: eks
  version: "1.28.0"
EOF

Create ClusterSpecification

cat <<EOF | kubectl apply -f -
apiVersion: kspec.io/v1alpha1
kind: ClusterSpecification
metadata:
  name: production-spec
  namespace: kspec-system
spec:
  targetClusterRef:
    name: production-cluster
  enforcementMode: monitor  # Start in monitor mode
  policies:
    - id: "pod-security-baseline"
      title: "Pod Security Standards - Baseline"
      description: "Enforce baseline pod security requirements"
      severity: high
      checks:
        - id: "require-run-as-non-root"
          title: "Require runAsNonRoot"
          kyvernoPolicy: |
            apiVersion: kyverno.io/v1
            kind: ClusterPolicy
            metadata:
              name: require-run-as-non-root
            spec:
              validationFailureAction: audit
              background: true
              rules:
              - name: check-runAsNonRoot
                match:
                  any:
                  - resources:
                      kinds:
                      - Pod
                validate:
                  message: "Containers must run as non-root user"
                  pattern:
                    spec:
                      securityContext:
                        runAsNonRoot: true
EOF

Step 4: Verify Installation

# Check operator logs
kubectl logs -n kspec-system -l control-plane=controller-manager --tail=20

# Check that policies were created
kubectl get clusterpolicy

# Check compliance reports
kubectl get compliancereport -n kspec-system

# Switch to enforce mode when ready
kubectl patch clusterspecification production-spec -n kspec-system \
  --type='json' \
  -p='[{"op": "replace", "path": "/spec/enforcementMode", "value": "enforce"}]'

Next Steps

Need help? Open an issue on GitHub