diff --git a/.env b/.env index c9f5fa2..9030b15 100644 --- a/.env +++ b/.env @@ -8,12 +8,14 @@ EKSCTL_VERSION=v0.191.0 EKS_CLUSTER_K8_VERSION=1.31 EKS_INSTANCE_TYPE=m5.2xlarge EKS_INSTANCE_TYPE_ARM64=c6g.4xlarge -SPLUNK_ENTERPRISE_RELEASE_IMAGE=splunk/splunk:9.4.1 -RELATED_IMAGE_SPLUNK_ENTERPRISE=splunk/splunk:9.2.3 +SPLUNK_ENTERPRISE_RELEASE_IMAGE=splunk/splunk:10.2.0 +RELATED_IMAGE_SPLUNK_ENTERPRISE=splunk/splunk:10.2.0 RELATED_IMAGE_RAY_HEAD=667741767953.dkr.ecr.us-west-2.amazonaws.com/ml-platform/ray/ray-head:build-5 RELATED_IMAGE_RAY_WORKER=667741767953.dkr.ecr.us-west-2.amazonaws.com/ml-platform/ray/ray-worker-gpu:build-6 RELATED_IMAGE_WEAVIATE=semitechnologies/weaviate:stable-v1.28-007846a RELATED_IMAGE_POST_INSTALL_HOOK=667741767953.dkr.ecr.us-west-2.amazonaws.com/vivek/ml-platform/saia/ai-helm-post-hook:0.0.5 +RELATED_IMAGE_SAIA_API=667741767953.dkr.ecr.us-west-2.amazonaws.com/ml-platform/saia/saia-api:build-1 +SPLUNK_OPERATOR_FOR_KUBERNETES=3.0.0 CLUSTER_NAME=sok-ml-platform MODEL_VERSION=v0.3.14-36-g1549f5a RAY_VERSION=2.44.0 \ No newline at end of file diff --git a/.github/workflows/release-package-helm.yml b/.github/workflows/release-package-helm.yml index 40a2459..97ad719 100644 --- a/.github/workflows/release-package-helm.yml +++ b/.github/workflows/release-package-helm.yml @@ -205,6 +205,44 @@ jobs: echo "Manifest preview (first 50 lines):" head -50 dist/install-v$VERSION.yaml + - name: Generate Bill of Materials (BOM) + run: | + VERSION="${{ steps.version.outputs.version }}" + + echo "Generating custom BOM for version $VERSION..." + make generate-bom VERSION=$VERSION + + echo "" + echo "Generated BOM files:" + ls -lh dist/bom-v$VERSION.* + + echo "" + echo "BOM Summary:" + cat dist/bom-v$VERSION.txt + + - name: Install Syft for SBOM generation + uses: anchore/sbom-action/download-syft@ab5d7b5f48981941c4c5d6bf33aeb98fe3bae38c # v0.15.10 + + - name: Generate SBOM for operator image + run: | + VERSION="${{ steps.version.outputs.version }}" + OPERATOR_IMAGE="ghcr.io/splunk/splunk-ai-operator:v$VERSION" + + echo "Generating SBOM for operator image: $OPERATOR_IMAGE" + + # Generate SBOM in multiple formats + syft "$OPERATOR_IMAGE" -o cyclonedx-json=dist/sbom-operator-v$VERSION.cyclonedx.json + syft "$OPERATOR_IMAGE" -o spdx-json=dist/sbom-operator-v$VERSION.spdx.json + syft "$OPERATOR_IMAGE" -o syft-json=dist/sbom-operator-v$VERSION.syft.json + + echo "" + echo "Generated SBOM files:" + ls -lh dist/sbom-operator-v$VERSION.* + + echo "" + echo "SBOM Statistics:" + jq -r '.artifacts // .packages // [] | length' dist/sbom-operator-v$VERSION.syft.json || echo "SBOM contains package inventory" + - name: Package Helm charts run: | mkdir -p .helm-releases @@ -267,6 +305,13 @@ jobs: .helm-releases/*.tgz .helm-releases/index.yaml dist/install-v${{ steps.version.outputs.version }}.yaml + compatibility-matrix.yaml + dist/bom-v${{ steps.version.outputs.version }}.json + dist/bom-v${{ steps.version.outputs.version }}.yaml + dist/bom-v${{ steps.version.outputs.version }}.txt + dist/sbom-operator-v${{ steps.version.outputs.version }}.cyclonedx.json + dist/sbom-operator-v${{ steps.version.outputs.version }}.spdx.json + dist/sbom-operator-v${{ steps.version.outputs.version }}.syft.json generate_release_notes: true draft: false prerelease: false @@ -298,12 +343,27 @@ jobs: ### Release Assets - **GitHub Release:** + **Kubernetes Manifests:** - **install-v${{ steps.version.outputs.version }}.yaml** - Complete Kubernetes manifests (CRDs + Operator) + + **Helm Charts:** - **splunk-ai-operator-${{ steps.version.outputs.version }}.tgz** - Operator Helm chart - **splunk-ai-platform-${{ steps.version.outputs.version }}.tgz** - Platform Helm chart (includes dependencies) - **index.yaml** - Helm repository index + **Compatibility Matrix:** + - **compatibility-matrix.yaml** - Version compatibility information, supported platforms, and dependencies + + **Bill of Materials (BOM):** + - **bom-v${{ steps.version.outputs.version }}.txt** - Human-readable BOM with all container images + - **bom-v${{ steps.version.outputs.version }}.yaml** - Kubernetes-friendly YAML BOM + - **bom-v${{ steps.version.outputs.version }}.json** - CycloneDX format BOM + + **Software Bill of Materials (SBOM):** + - **sbom-operator-v${{ steps.version.outputs.version }}.cyclonedx.json** - CycloneDX SBOM + - **sbom-operator-v${{ steps.version.outputs.version }}.spdx.json** - SPDX SBOM + - **sbom-operator-v${{ steps.version.outputs.version }}.syft.json** - Syft native format SBOM + **OCI Registry (GHCR):** - `oci://ghcr.io/${{ github.repository_owner }}/charts/splunk-ai-operator:${{ steps.version.outputs.version }}` - `oci://ghcr.io/${{ github.repository_owner }}/charts/splunk-ai-platform:${{ steps.version.outputs.version }}` diff --git a/Makefile b/Makefile index c2302f0..203cb3d 100644 --- a/Makefile +++ b/Makefile @@ -244,6 +244,13 @@ build-installer: manifests generate kustomize ## Generate a consolidated YAML wi cd config/manager && $(KUSTOMIZE) edit set image controller=${IMG} $(KUSTOMIZE) build config/default > dist/install.yaml +.PHONY: generate-bom +generate-bom: ## Generate Bill of Materials (BOM) for release + @echo "Generating Bill of Materials..." + @mkdir -p dist + @./scripts/generate-bom.sh $(VERSION) dist + @echo "✅ BOM generated in dist/ directory" + ##@ Deployment ifndef ignore-not-found diff --git a/compatibility-matrix.yaml b/compatibility-matrix.yaml new file mode 100644 index 0000000..a5062af --- /dev/null +++ b/compatibility-matrix.yaml @@ -0,0 +1,251 @@ +apiVersion: operator.splunk.com/v1 +kind: CompatibilityMatrix +metadata: + name: splunk-ai-operator + version: 0.1.0 # Operator version this matrix applies to + lastUpdated: "2025-11-18" + description: "Compatibility matrix for Splunk AI Operator - defines supported versions of platform dependencies and managed components" + +operator: + name: splunk-ai-operator + version: 0.1.0 + +# Platform Requirements +platform: + kubernetes: + minVersion: "1.28.0" + maxVersion: "1.31.99" + tested: # Versions explicitly tested + - "1.28" + - "1.29" + - "1.30" + - "1.31" + notes: "Operator tested on EKS, AKS, GKE, and vanilla Kubernetes" + + splunkOperatorForKubernetes: # SOK + version: "3.0.0" + minVersion: "3.0.0" + maxVersion: "3.99.99" + optional: true + url: "https://github.com/splunk/splunk-operator" + notes: "Splunk Operator for Kubernetes - manages Splunk Enterprise deployments" + + go: + version: "1.23.0" + notes: "Go version used to build the operator" + + splunkEnterprise: + minVersion: "9.2.0" + maxVersion: "10.2.99" + recommended: "10.2.0" + notes: "Operator can manage Splunk Enterprise instances" + +# Required External Dependencies +requiredServices: + certManager: + name: cert-manager + minVersion: "1.13.0" + recommended: "1.14.0" + required: true + url: "https://cert-manager.io/" + notes: "Required for TLS certificate management" + + vaultInjector: + name: vault-injector + minVersion: "0.25.0" + recommended: "0.26.0" + required: false + url: "https://www.vaultproject.io/" + notes: "Optional - for secrets management integration" + +# Managed Components (what the operator deploys and manages) +managedComponents: + ray: + displayName: "Ray ML Runtime" + description: "Distributed ML runtime for AI workloads" + url: "https://www.ray.io/" + versions: + - version: "2.44.0" + status: recommended + releaseDate: "2024-11" + images: + head: "667741767953.dkr.ecr.us-west-2.amazonaws.com/ml-platform/ray/ray-head:build-5" + worker: "667741767953.dkr.ecr.us-west-2.amazonaws.com/ml-platform/ray/ray-worker-gpu:build-6" + resources: + head: + cpu: "2" + memory: "8Gi" + worker: + cpu: "4" + memory: "16Gi" + gpu: "1" + + weaviate: + displayName: "Weaviate Vector Database" + description: "Vector database for AI/ML applications" + url: "https://weaviate.io/" + versions: + - version: "1.28.0" + status: recommended + releaseDate: "2024-10" + image: "semitechnologies/weaviate:stable-v1.28-007846a" + resources: + cpu: "2" + memory: "8Gi" + + splunkEnterprise: + displayName: "Splunk Enterprise" + description: "Data platform for security and observability" + url: "https://www.splunk.com/" + versions: + - version: "9.2.3" + status: supported + releaseDate: "2024-Q2" + image: "splunk/splunk:9.2.3" + notes: "Minimum supported version" + - version: "9.4.1" + status: supported + releaseDate: "2024-Q3" + image: "splunk/splunk:9.4.1" + notes: "Previous stable version" + - version: "10.2.0" + status: recommended + releaseDate: "2024-Q4" + image: "splunk/splunk:10.2.0" + notes: "Latest tested and recommended version" + + saiaApi: + displayName: "SAIA API Service" + description: "Splunk AI API service for AI operations" + versions: + - version: "build-1" + status: recommended + image: "667741767953.dkr.ecr.us-west-2.amazonaws.com/ml-platform/saia/saia-api:build-1" + resources: + cpu: "1" + memory: "2Gi" + + saiaDataLoader: + displayName: "SAIA Data Loader" + description: "Post-installation data loading hooks" + versions: + - version: "0.0.5" + status: recommended + image: "667741767953.dkr.ecr.us-west-2.amazonaws.com/vivek/ml-platform/saia/ai-helm-post-hook:0.0.5" + notes: "Post-install hook for data initialization" + + fluentBit: + displayName: "Fluent Bit" + description: "Lightweight log processor and forwarder" + url: "https://fluentbit.io/" + versions: + - version: "1.9.6" + status: recommended + releaseDate: "2023-Q3" + image: "fluent/fluent-bit:1.9.6" + notes: "Stable version validated with current deployment" + resources: + cpu: "100m" + memory: "128Mi" + +# Inter-Operator Dependencies +interOperatorCompatibility: + securityOperator: + name: "Splunk Security Operator" + minVersion: "2.1.0" + maxVersion: "2.99.99" + required: false + notes: "Optional - for enhanced security features" + + sokOperator: + name: "Splunk Operator Kit" + minVersion: "4.0.0" + maxVersion: "4.99.99" + required: false + notes: "Optional - for advanced operator features" + +# BOM Integration +bom: + family: splunk-ai-platform + compatibleVersions: + - "0.1.x" + - "0.2.x" + + # Reference to generated BOM files + generatedBomFiles: + - "bom-v0.1.0.json" + - "bom-v0.1.0.yaml" + - "bom-v0.1.0.txt" + + sbomFiles: + - "sbom-operator-v0.1.0.cyclonedx.json" + - "sbom-operator-v0.1.0.spdx.json" + - "sbom-operator-v0.1.0.syft.json" + +# Upgrade Paths +upgradePaths: + - from: "0.0.x" + to: "0.1.x" + automatic: true + breaking: false + notes: "Initial pre-GA release" + + - from: "0.1.x" + to: "0.2.x" + automatic: true + breaking: false + notes: "Future upgrade path" + +# Known Issues and Limitations +knownIssues: + - issue: "Ray worker GPU support requires NVIDIA GPU operator" + severity: info + workaround: "Install NVIDIA GPU operator before deploying AI workloads" + affectedVersions: ["0.1.0"] + + - issue: "Weaviate persistence requires storage class with ReadWriteMany" + severity: info + workaround: "Configure appropriate storage class in values.yaml" + affectedVersions: ["0.1.0"] + +# Testing and Validation +testing: + environments: + - name: "AWS EKS" + kubernetesVersion: "1.31" + status: tested + notes: "Primary testing environment" + + - name: "Local k0s" + kubernetesVersion: "1.30" + status: tested + notes: "Development and testing" + + - name: "Azure AKS" + kubernetesVersion: "1.29" + status: planned + notes: "Planned for future testing" + + - name: "Google GKE" + kubernetesVersion: "1.28" + status: planned + notes: "Planned for future testing" + + validationCriteria: + - "All CRDs install successfully" + - "Operator pod starts and becomes ready" + - "Sample AI workloads deploy successfully" + - "Ray cluster scales up and down" + - "Weaviate persistence works across pod restarts" + - "Logs forwarded to Splunk Enterprise" + +# Support and Documentation +support: + documentation: "https://github.com/splunk/splunk-ai-operator/tree/main/docs" + issues: "https://github.com/splunk/splunk-ai-operator/issues" + discussions: "https://github.com/splunk/splunk-ai-operator/discussions" + + deprecationPolicy: + kubernetesVersions: "Support kubernetes versions N-3 (current and 3 previous minor versions)" + componentVersions: "Support component versions for 12 months after release" + noticePeriod: "90 days notice before deprecating support" diff --git a/docs/bill-of-materials.md b/docs/bill-of-materials.md new file mode 100644 index 0000000..9223eb3 --- /dev/null +++ b/docs/bill-of-materials.md @@ -0,0 +1,327 @@ +# Bill of Materials (BOM) + +The Splunk AI Operator provides comprehensive Bill of Materials (BOM) and Software Bill of Materials (SBOM) for each release to support supply chain security and transparency. + +## Overview + +Each release includes multiple artifact types to meet different compliance and security requirements: + +1. **Custom BOM** - Lists all container images managed by the operator +2. **SBOM** - Complete software dependencies of the operator binary +3. **Attestations** - Cryptographic proof of build provenance + +## BOM Artifacts + +### Custom Bill of Materials + +The custom BOM tracks all container images that the operator deploys and manages: + +#### Available Formats + +| Format | Filename | Use Case | +|--------|----------|----------| +| **Text** | `bom-vX.Y.Z.txt` | Human-readable, easy to review | +| **YAML** | `bom-vX.Y.Z.yaml` | Kubernetes-native, machine-readable | +| **JSON** | `bom-vX.Y.Z.json` | CycloneDX format, tool integration | + +#### What's Included + +The BOM includes: + +- **Operator Image**: The operator controller image +- **Managed Images**: All container images deployed by the operator: + - Splunk Enterprise + - Ray Head (ML runtime) + - Ray Worker (GPU-enabled ML workers) + - Weaviate (Vector database) + - SAIA API (AI services) + - Post-install hooks + - Fluent Bit (Logging) +- **Dependency Versions**: Model versions, framework versions + +#### Example BOM Output + +```text +================================================================================ +Bill of Materials (BOM) +Splunk AI Operator v0.1.0 +Generated: 2025-11-18T19:34:23Z +================================================================================ + +OPERATOR IMAGE +-------------- +ghcr.io/splunk/splunk-ai-operator:v0.1.0 + +MANAGED CONTAINER IMAGES +------------------------ +splunk-enterprise: splunk/splunk:9.2.3 +ray-head: example.ecr.us-west-2.amazonaws.com/ray/ray-head:build-5 +ray-worker: example.ecr.us-west-2.amazonaws.com/ray/ray-worker-gpu:build-6 +weaviate: semitechnologies/weaviate:stable-v1.28-007846a +fluent-bit: fluent/fluent-bit:1.9.6 +... + +DEPENDENCY VERSIONS +------------------- +Model Version: v0.3.14-36-g1549f5a +Ray Version: 2.44.0 +``` + +### Software Bill of Materials (SBOM) + +The SBOM provides a complete inventory of all software dependencies in the operator binary: + +#### Available Formats + +| Format | Filename | Standard | +|--------|----------|----------| +| **CycloneDX** | `sbom-operator-vX.Y.Z.cyclonedx.json` | CycloneDX 1.4+ | +| **SPDX** | `sbom-operator-vX.Y.Z.spdx.json` | SPDX 2.3+ | +| **Syft** | `sbom-operator-vX.Y.Z.syft.json` | Syft native | + +#### What's Included + +The SBOM catalogs: + +- Go packages and dependencies +- System libraries +- Third-party dependencies +- License information +- Package versions and hashes + +#### Tools Integration + +SBOMs can be used with security scanning tools: + +```bash +# Grype (vulnerability scanning) +grype sbom:./sbom-operator-v0.1.0.cyclonedx.json + +# Trivy (security scanning) +trivy sbom --scanners vuln sbom-operator-v0.1.0.spdx.json + +# Dependency-Track (component analysis platform) +# Upload the CycloneDX file to Dependency-Track +``` + +## Accessing BOM/SBOM Files + +### From GitHub Releases + +All BOM and SBOM files are attached to each GitHub release: + +```bash +VERSION="0.1.0" +BASE_URL="https://github.com/splunk/splunk-ai-operator/releases/download/v${VERSION}" + +# Download custom BOM (human-readable) +curl -LO "${BASE_URL}/bom-v${VERSION}.txt" + +# Download SBOM (CycloneDX) +curl -LO "${BASE_URL}/sbom-operator-v${VERSION}.cyclonedx.json" + +# Download SBOM (SPDX) +curl -LO "${BASE_URL}/sbom-operator-v${VERSION}.spdx.json" +``` + +### Generate Locally + +You can generate the custom BOM locally: + +```bash +# Generate BOM for current version +make generate-bom VERSION=0.1.0 + +# Output files created in dist/ +ls -l dist/bom-* +``` + +## Verification and Security + +### Verify Image Digests + +To verify the exact images used in a release: + +```bash +# Pull image and get digest +docker pull ghcr.io/splunk/splunk-ai-operator:v0.1.0 --platform linux/amd64 +docker inspect ghcr.io/splunk/splunk-ai-operator:v0.1.0 --format='{{.RepoDigests}}' +``` + +### Verify Build Attestations + +Each operator image includes cryptographic attestations: + +```bash +# View attestation using GitHub CLI +gh attestation verify oci://ghcr.io/splunk/splunk-ai-operator:v0.1.0 \ + --owner splunk + +# Verify with cosign (SLSA provenance) +cosign verify-attestation \ + --type slsaprovenance \ + --certificate-identity-regexp="^https://github.com/splunk/splunk-ai-operator" \ + --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \ + ghcr.io/splunk/splunk-ai-operator:v0.1.0 +``` + +### Security Scanning + +Scan operator image for vulnerabilities: + +```bash +# Using Trivy +trivy image ghcr.io/splunk/splunk-ai-operator:v0.1.0 + +# Using Grype +grype ghcr.io/splunk/splunk-ai-operator:v0.1.0 + +# Scan all managed images from BOM +while read -r line; do + if [[ $line =~ ^[a-z-]+:[[:space:]]+([^[:space:]]+)$ ]]; then + image="${BASH_REMATCH[1]}" + echo "Scanning: $image" + trivy image "$image" + fi +done < bom-v0.1.0.txt +``` + +## Compliance Use Cases + +### Software Supply Chain Security + +The BOM/SBOM artifacts support compliance with: + +- **SLSA** (Supply chain Levels for Software Artifacts) +- **SSDF** (Secure Software Development Framework) +- **Executive Order 14028** (Cybersecurity requirements) +- **NTIA Minimum Elements** for SBOM + +### Vulnerability Management + +Use SBOMs for continuous vulnerability monitoring: + +1. Upload SBOM to vulnerability management platform (e.g., Dependency-Track) +2. Receive alerts when new CVEs affect your dependencies +3. Track remediation across releases + +### License Compliance + +Extract license information from SBOM: + +```bash +# Using jq to extract licenses from CycloneDX SBOM +jq -r '.components[] | select(.licenses) | "\(.name): \(.licenses[].license.id // .licenses[].license.name)"' \ + sbom-operator-v0.1.0.cyclonedx.json | sort -u +``` + +### Audit Trail + +The BOM provides an audit trail showing: + +- Which versions of components were deployed +- When the release was built (timestamp) +- What dependencies were included +- Build provenance (via attestations) + +## Integration with CI/CD + +### Automated Scanning + +Integrate BOM/SBOM into your CI/CD pipeline: + +```yaml +# Example GitHub Actions workflow +- name: Download SBOM + run: | + VERSION="0.1.0" + curl -LO "https://github.com/splunk/splunk-ai-operator/releases/download/v${VERSION}/sbom-operator-v${VERSION}.cyclonedx.json" + +- name: Scan for vulnerabilities + uses: anchore/scan-action@v3 + with: + sbom: "sbom-operator-v0.1.0.cyclonedx.json" + fail-build: true + severity-cutoff: high +``` + +### Policy Enforcement + +Use BOM to enforce organizational policies: + +```bash +#!/bin/bash +# Example: Verify all images are from approved registries + +APPROVED_REGISTRIES=( + "ghcr.io/splunk" + "splunk" + "semitechnologies" + "fluent" +) + +while read -r line; do + if [[ $line =~ image:[[:space:]]+([^[:space:]]+) ]]; then + image="${BASH_REMATCH[1]}" + approved=false + + for registry in "${APPROVED_REGISTRIES[@]}"; do + if [[ $image == $registry* ]]; then + approved=true + break + fi + done + + if [ "$approved" = false ]; then + echo "ERROR: Unapproved registry for image: $image" + exit 1 + fi + fi +done < bom-v0.1.0.yaml + +echo "✅ All images from approved registries" +``` + +## Best Practices + +1. **Store BOM/SBOM**: Archive BOM/SBOM files for each deployed version +2. **Automate Scanning**: Integrate vulnerability scanning into deployment pipelines +3. **Track Changes**: Compare BOMs across versions to identify dependency changes +4. **Verify Signatures**: Always verify attestations before deployment +5. **Monitor CVEs**: Use SBOM with vulnerability databases for continuous monitoring +6. **Document Exceptions**: Maintain records of approved security exceptions + +## Updating Image Versions + +When updating managed image versions: + +1. Update `.env` file with new image tags: + ```bash + RELATED_IMAGE_RAY_HEAD=example.ecr.aws.com/ray/ray-head:build-6 + RELATED_IMAGE_RAY_WORKER=example.ecr.aws.com/ray/ray-worker-gpu:build-7 + ``` + +2. Update `config/manager/kustomization.yaml` if needed + +3. Generate new BOM to verify: + ```bash + make generate-bom VERSION=0.2.0 + cat dist/bom-v0.2.0.txt + ``` + +4. Release workflow automatically generates BOM/SBOM + +## Support and Resources + +- **CycloneDX**: https://cyclonedx.org/ +- **SPDX**: https://spdx.dev/ +- **SLSA**: https://slsa.dev/ +- **Syft**: https://github.com/anchore/syft +- **Grype**: https://github.com/anchore/grype +- **Trivy**: https://github.com/aquasecurity/trivy + +## Questions? + +For questions about BOM/SBOM: +- Open an issue: https://github.com/splunk/splunk-ai-operator/issues +- Security concerns: See [SECURITY.md](../SECURITY.md) diff --git a/docs/bom-quick-reference.md b/docs/bom-quick-reference.md new file mode 100644 index 0000000..d3a4040 --- /dev/null +++ b/docs/bom-quick-reference.md @@ -0,0 +1,142 @@ +# BOM & Compatibility Matrix - Quick Reference Card + +## 📥 Download Files + +```bash +VERSION="0.1.0" +BASE_URL="https://github.com/splunk/splunk-ai-operator/releases/download/v${VERSION}" + +# Essential files +curl -LO "${BASE_URL}/compatibility-matrix.yaml" +curl -LO "${BASE_URL}/bom-v${VERSION}.txt" +curl -LO "${BASE_URL}/bom-v${VERSION}.yaml" +``` + +## 🔍 Quick Checks + +### Check if My Cluster is Compatible +```bash +# Your cluster version +kubectl version --short + +# Required version range +yq '.platform.kubernetes | "min: \(.minVersion) max: \(.maxVersion)"' compatibility-matrix.yaml +``` + +### List All Container Images +```bash +yq '.spec.containerImages[].image' bom-v${VERSION}.yaml +``` + +### Check Splunk Enterprise Version +```bash +yq '.spec.dependencies.splunkEnterpriseVersion' bom-v${VERSION}.yaml +``` + +## 🛡️ Security Scanning + +### Scan Operator for Vulnerabilities +```bash +trivy image ghcr.io/splunk/splunk-ai-operator:v${VERSION} +``` + +### Scan Using SBOM +```bash +curl -LO "${BASE_URL}/sbom-operator-v${VERSION}.cyclonedx.json" +grype sbom:./sbom-operator-v${VERSION}.cyclonedx.json +``` + +### Scan All Managed Images +```bash +yq '.spec.containerImages[].image' bom-v${VERSION}.yaml | while read img; do + echo "Scanning: $img" + trivy image "$img" --severity HIGH,CRITICAL +done +``` + +## 📋 What Each File Contains + +| File | Contains | Use For | +|------|----------|---------| +| `compatibility-matrix.yaml` | K8s versions, required services, component versions | Pre-deployment checks | +| `bom-v0.1.0.txt` | All images + dependency versions | Quick review | +| `bom-v0.1.0.yaml` | Machine-readable BOM | Automation, scripts | +| `sbom-operator-v0.1.0.cyclonedx.json` | Software dependencies | Vulnerability scanning | + +## 🎯 Common Tasks + +### Pre-Deployment Checklist +```bash +# 1. Check Kubernetes compatibility +yq '.platform.kubernetes' compatibility-matrix.yaml + +# 2. Verify cert-manager installed +kubectl get deployment -n cert-manager cert-manager + +# 3. Scan for vulnerabilities +trivy image ghcr.io/splunk/splunk-ai-operator:v${VERSION} + +# 4. Review managed components +yq '.managedComponents | keys' compatibility-matrix.yaml +``` + +### Verify Deployed Version +```bash +# Expected version +yq '.spec.operatorImage' bom-v${VERSION}.yaml + +# Actual deployed version +kubectl get deployment -n splunk-ai-operator-system \ + splunk-ai-operator-controller-manager \ + -o jsonpath='{.spec.template.spec.containers[0].image}' +``` + +### Create Compliance Report +```bash +# Download files +curl -sLO "${BASE_URL}/bom-v${VERSION}.txt" + +# Print report +cat bom-v${VERSION}.txt +``` + +## 🔧 Required Tools + +```bash +# Install tools (macOS) +brew install yq jq grype trivy + +# Verify installation +yq --version +grype version +trivy --version +``` + +## 📖 Full Documentation + +- **Detailed Guide:** [docs/using-bom-compatibility.md](./using-bom-compatibility.md) +- **BOM Overview:** [docs/bill-of-materials.md](./bill-of-materials.md) +- **Issues:** https://github.com/splunk/splunk-ai-operator/issues + +## 💡 Pro Tips + +1. **Save locally:** Keep BOM for each deployed version + ```bash + mkdir -p ~/bom-archive/v${VERSION} + cd ~/bom-archive/v${VERSION} + curl -LO "${BASE_URL}/bom-v${VERSION}.yaml" + curl -LO "${BASE_URL}/compatibility-matrix.yaml" + ``` + +2. **Automated checks:** Add to CI/CD pipeline + ```yaml + - run: yq '.platform.kubernetes.minVersion' compatibility-matrix.yaml + - run: grype sbom:./sbom-operator-v${VERSION}.cyclonedx.json + ``` + +3. **Monitor CVEs:** Upload SBOM to Dependency-Track for continuous monitoring + +4. **Air-gap deployments:** Extract all images from BOM before mirroring + ```bash + yq '.spec.containerImages[].image' bom-v${VERSION}.yaml > images.txt + ``` diff --git a/docs/using-bom-compatibility.md b/docs/using-bom-compatibility.md new file mode 100644 index 0000000..34b74a9 --- /dev/null +++ b/docs/using-bom-compatibility.md @@ -0,0 +1,546 @@ +# Using the BOM and Compatibility Matrix + +This guide shows you how to practically use the Bill of Materials (BOM) and Compatibility Matrix for deployment planning, security scanning, and compliance. + +## Quick Reference + +| File | Purpose | When to Use | +|------|---------|-------------| +| `compatibility-matrix.yaml` | Version compatibility info | **Before deployment** - Check if your environment meets requirements | +| `bom-vX.Y.Z.txt` | Human-readable BOM | **Quick review** - See all images at a glance | +| `bom-vX.Y.Z.yaml` | Machine-readable BOM | **Automation** - Parse with tools, CI/CD integration | +| `bom-vX.Y.Z.json` | CycloneDX BOM | **Tool integration** - Dependency-Track, compliance tools | +| `sbom-*.json` | Software Bill of Materials | **Security scanning** - Vulnerability analysis | + +## Common Use Cases + +### 1. Pre-Deployment: Check Compatibility + +**Scenario:** You want to deploy Splunk AI Operator v0.1.0 on your Kubernetes cluster. + +**Steps:** + +```bash +# Download the compatibility matrix +VERSION="0.1.0" +curl -LO "https://github.com/splunk/splunk-ai-operator/releases/download/v${VERSION}/compatibility-matrix.yaml" + +# Check Kubernetes compatibility +yq '.platform.kubernetes' compatibility-matrix.yaml +``` + +**Output:** +```yaml +minVersion: "1.28.0" +maxVersion: "1.31.99" +tested: + - "1.28" + - "1.29" + - "1.30" + - "1.31" +notes: "Operator tested on EKS, AKS, GKE, and vanilla Kubernetes" +``` + +**Decision:** +- ✅ Your cluster is 1.30.x → **Compatible** +- ❌ Your cluster is 1.27.x → **Not supported** (below minVersion) +- ⚠️ Your cluster is 1.32.x → **Not tested** (above maxVersion, may work but untested) + +**Check required services:** +```bash +# What services do I need? +yq '.requiredServices' compatibility-matrix.yaml +``` + +**Output:** +```yaml +certManager: + name: cert-manager + minVersion: "1.13.0" + required: true + +vaultInjector: + name: vault-injector + minVersion: "0.25.0" + required: false +``` + +**Action:** +```bash +# Verify cert-manager is installed and meets minimum version +kubectl get deployment -n cert-manager cert-manager -o jsonpath='{.metadata.labels.app\.kubernetes\.io/version}' +# Should be >= 1.13.0 +``` + +### 2. Security Scanning: Check for Vulnerabilities + +**Scenario:** You need to scan all images before deployment for security vulnerabilities. + +#### Option A: Scan Operator Image + +```bash +VERSION="0.1.0" + +# Download SBOM +curl -LO "https://github.com/splunk/splunk-ai-operator/releases/download/v${VERSION}/sbom-operator-v${VERSION}.cyclonedx.json" + +# Scan using Grype +grype sbom:./sbom-operator-v${VERSION}.cyclonedx.json + +# Or scan using Trivy +trivy sbom ./sbom-operator-v${VERSION}.cyclonedx.json +``` + +#### Option B: Scan All Managed Images + +```bash +# Download BOM +curl -LO "https://github.com/splunk/splunk-ai-operator/releases/download/v${VERSION}/bom-v${VERSION}.yaml" + +# Extract all images and scan them +yq '.spec.containerImages[].image' bom-v${VERSION}.yaml | while read image; do + echo "Scanning: $image" + trivy image "$image" --severity HIGH,CRITICAL +done +``` + +**Example Output:** +``` +Scanning: ghcr.io/splunk/splunk-ai-operator:v0.1.0 +✅ No HIGH or CRITICAL vulnerabilities + +Scanning: splunk/splunk:10.2.0 +⚠️ Found 2 MEDIUM vulnerabilities +... +``` + +### 3. Upgrade Planning: Compare Versions + +**Scenario:** You're on v0.0.5 and want to upgrade to v0.1.0. What changed? + +```bash +# Download both BOMs +curl -LO "https://github.com/splunk/splunk-ai-operator/releases/download/v0.0.5/bom-v0.0.5.yaml" +curl -LO "https://github.com/splunk/splunk-ai-operator/releases/download/v0.1.0/bom-v0.1.0.yaml" + +# Compare Splunk Enterprise versions +echo "Old version:" +yq '.spec.dependencies.splunkEnterpriseVersion' bom-v0.0.5.yaml + +echo "New version:" +yq '.spec.dependencies.splunkEnterpriseVersion' bom-v0.1.0.yaml + +# Check if upgrade is safe +yq '.upgradePaths[] | select(.from == "0.0.x" and .to == "0.1.x")' compatibility-matrix.yaml +``` + +**Output:** +```yaml +from: "0.0.x" +to: "0.1.x" +automatic: true +breaking: false +notes: "Initial pre-GA release" +``` + +**Decision:** ✅ Safe to upgrade, no breaking changes + +### 4. Compliance: Export Dependency List + +**Scenario:** Audit team needs a complete list of all software dependencies. + +```bash +VERSION="0.1.0" + +# Download all compliance files +curl -LO "https://github.com/splunk/splunk-ai-operator/releases/download/v${VERSION}/bom-v${VERSION}.txt" +curl -LO "https://github.com/splunk/splunk-ai-operator/releases/download/v${VERSION}/sbom-operator-v${VERSION}.spdx.json" + +# Human-readable summary +cat bom-v${VERSION}.txt + +# SPDX format for compliance tools +# Upload sbom-operator-v${VERSION}.spdx.json to your compliance platform +``` + +### 5. Policy Enforcement: Verify Approved Registries + +**Scenario:** Company policy requires all images from approved registries only. + +Create a validation script: + +```bash +#!/bin/bash +# check-registry-policy.sh + +VERSION="0.1.0" +APPROVED_REGISTRIES=( + "ghcr.io/splunk" + "splunk" + "semitechnologies" + "fluent" +) + +# Download BOM +curl -sLO "https://github.com/splunk/splunk-ai-operator/releases/download/v${VERSION}/bom-v${VERSION}.yaml" + +echo "Checking registry policy compliance..." + +# Extract and check each image +yq '.spec.containerImages[].image' bom-v${VERSION}.yaml | while read image; do + approved=false + + for registry in "${APPROVED_REGISTRIES[@]}"; do + if [[ "$image" == ${registry}/* ]] || [[ "$image" == ${registry}:* ]]; then + approved=true + echo "✅ $image" + break + fi + done + + if [ "$approved" = false ]; then + echo "❌ POLICY VIOLATION: $image" + echo " Image from unapproved registry!" + exit 1 + fi +done + +echo "" +echo "✅ All images comply with registry policy" +``` + +Run it: +```bash +chmod +x check-registry-policy.sh +./check-registry-policy.sh +``` + +### 6. CI/CD Integration: Automated Checks + +**Scenario:** Integrate BOM/compatibility checks into your deployment pipeline. + +#### GitHub Actions Example + +```yaml +name: Pre-Deployment Validation + +on: + workflow_dispatch: + inputs: + operator_version: + description: 'Operator version to deploy' + required: true + default: '0.1.0' + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - name: Download BOM and Compatibility Matrix + run: | + VERSION="${{ github.event.inputs.operator_version }}" + curl -LO "https://github.com/splunk/splunk-ai-operator/releases/download/v${VERSION}/bom-v${VERSION}.yaml" + curl -LO "https://github.com/splunk/splunk-ai-operator/releases/download/v${VERSION}/compatibility-matrix.yaml" + curl -LO "https://github.com/splunk/splunk-ai-operator/releases/download/v${VERSION}/sbom-operator-v${VERSION}.cyclonedx.json" + + - name: Check Kubernetes Version Compatibility + run: | + K8S_VERSION=$(kubectl version --short | grep Server | awk '{print $3}' | sed 's/v//') + MIN_VERSION=$(yq '.platform.kubernetes.minVersion' compatibility-matrix.yaml) + MAX_VERSION=$(yq '.platform.kubernetes.maxVersion' compatibility-matrix.yaml) + + echo "Cluster K8s version: $K8S_VERSION" + echo "Required: $MIN_VERSION - $MAX_VERSION" + + # Version comparison logic here + # Fail if out of range + + - name: Scan for Vulnerabilities + uses: anchore/scan-action@v3 + with: + sbom: "sbom-operator-v${{ github.event.inputs.operator_version }}.cyclonedx.json" + fail-build: true + severity-cutoff: high + + - name: Verify Required Services + run: | + # Check cert-manager + if ! kubectl get deployment -n cert-manager cert-manager; then + echo "❌ cert-manager not found (required)" + exit 1 + fi + + CERT_MANAGER_VERSION=$(kubectl get deployment -n cert-manager cert-manager -o jsonpath='{.metadata.labels.app\.kubernetes\.io/version}') + MIN_CERT_MANAGER=$(yq '.requiredServices.certManager.minVersion' compatibility-matrix.yaml) + + echo "cert-manager: $CERT_MANAGER_VERSION (required: >= $MIN_CERT_MANAGER)" + + - name: Generate Deployment Report + run: | + cat < deployment-report.md + ## Pre-Deployment Validation Report + + **Operator Version:** ${{ github.event.inputs.operator_version }} + **Date:** $(date -u +"%Y-%m-%d %H:%M:%S UTC") + + ### Compatibility Checks + - ✅ Kubernetes version compatible + - ✅ Required services present + - ✅ No HIGH/CRITICAL vulnerabilities + + ### Managed Components + $(yq '.managedComponents | to_entries | .[] | "- " + .key + ": " + .value.versions[0].version' compatibility-matrix.yaml) + + ### Next Steps + Proceed with deployment using: + \`\`\`bash + helm install splunk-ai-operator oci://ghcr.io/splunk/charts/splunk-ai-operator --version ${{ github.event.inputs.operator_version }} + \`\`\` + EOF + + cat deployment-report.md +``` + +### 7. Continuous Monitoring: Track CVEs + +**Scenario:** Monitor for new vulnerabilities in deployed components. + +#### Using Dependency-Track + +```bash +VERSION="0.1.0" + +# Download CycloneDX SBOM +curl -LO "https://github.com/splunk/splunk-ai-operator/releases/download/v${VERSION}/sbom-operator-v${VERSION}.cyclonedx.json" + +# Upload to Dependency-Track (replace with your instance) +DTRACK_URL="https://dependency-track.example.com" +DTRACK_API_KEY="your-api-key" +PROJECT_NAME="splunk-ai-operator" +PROJECT_VERSION="${VERSION}" + +curl -X POST "${DTRACK_URL}/api/v1/bom" \ + -H "X-API-Key: ${DTRACK_API_KEY}" \ + -H "Content-Type: multipart/form-data" \ + -F "project=${PROJECT_NAME}" \ + -F "projectVersion=${PROJECT_VERSION}" \ + -F "bom=@sbom-operator-v${VERSION}.cyclonedx.json" +``` + +Dependency-Track will: +- Continuously monitor for new CVEs +- Alert when vulnerabilities are discovered +- Track remediation across versions + +### 8. Air-Gapped Deployments: Image Mirror Planning + +**Scenario:** You need to mirror all images to a private registry for air-gapped deployment. + +```bash +VERSION="0.1.0" +PRIVATE_REGISTRY="registry.internal.company.com" + +# Download BOM +curl -LO "https://github.com/splunk/splunk-ai-operator/releases/download/v${VERSION}/bom-v${VERSION}.yaml" + +# Create mirror script +cat > mirror-images.sh <<'EOF' +#!/bin/bash +VERSION="0.1.0" +PRIVATE_REGISTRY="registry.internal.company.com" +BOM_FILE="bom-v${VERSION}.yaml" + +echo "Mirroring images to ${PRIVATE_REGISTRY}..." + +yq '.spec.containerImages[].image' "${BOM_FILE}" | while read source_image; do + # Extract image name without registry + image_name=$(echo "$source_image" | awk -F'/' '{print $NF}') + target_image="${PRIVATE_REGISTRY}/splunk-ai/${image_name}" + + echo "" + echo "Source: $source_image" + echo "Target: $target_image" + + # Pull, tag, and push + docker pull "$source_image" + docker tag "$source_image" "$target_image" + docker push "$target_image" + + echo "✅ Mirrored: $image_name" +done + +echo "" +echo "All images mirrored successfully!" +echo "Update your values.yaml to use: ${PRIVATE_REGISTRY}/splunk-ai/" +EOF + +chmod +x mirror-images.sh +./mirror-images.sh +``` + +### 9. Troubleshooting: Version Mismatch Issues + +**Scenario:** Deployment failing, need to verify actual vs expected versions. + +```bash +VERSION="0.1.0" +NAMESPACE="splunk-ai-operator-system" + +# Download expected BOM +curl -LO "https://github.com/splunk/splunk-ai-operator/releases/download/v${VERSION}/bom-v${VERSION}.yaml" + +# Check deployed operator version +DEPLOYED_IMAGE=$(kubectl get deployment -n ${NAMESPACE} splunk-ai-operator-controller-manager -o jsonpath='{.spec.template.spec.containers[0].image}') +EXPECTED_IMAGE=$(yq '.spec.operatorImage' bom-v${VERSION}.yaml) + +echo "Expected: $EXPECTED_IMAGE" +echo "Deployed: $DEPLOYED_IMAGE" + +if [ "$DEPLOYED_IMAGE" = "$EXPECTED_IMAGE" ]; then + echo "✅ Operator version matches" +else + echo "❌ Version mismatch detected!" +fi + +# Check all managed workloads +echo "" +echo "Checking managed components..." + +# Check Ray deployment +kubectl get deployment -n splunk-ai ray-head -o jsonpath='{.spec.template.spec.containers[0].image}' +# Compare with: yq '.spec.containerImages[] | select(.name == "ray-head") | .image' bom-v${VERSION}.yaml +``` + +### 10. Generating Reports: Executive Summary + +**Scenario:** Create an executive summary for stakeholders. + +```bash +VERSION="0.1.0" + +# Download files +curl -LO "https://github.com/splunk/splunk-ai-operator/releases/download/v${VERSION}/bom-v${VERSION}.yaml" +curl -LO "https://github.com/splunk/splunk-ai-operator/releases/download/v${VERSION}/compatibility-matrix.yaml" + +# Generate summary +cat > executive-summary.md < "${BOM_JSON}" <> "${BOM_JSON}" + fi + + # Extract image parts + if [[ "$image" == *":"* ]]; then + image_name="${image%:*}" + image_tag="${image##*:}" + else + image_name="$image" + image_tag="latest" + fi + + cat >> "${BOM_JSON}" <> "${BOM_JSON}" < "${BOM_YAML}" <> "${BOM_YAML}" < "${BOM_TXT}" <> "${BOM_TXT}" + fi +done + +cat >> "${BOM_TXT}" < --platform linux/amd64 + docker inspect --format='{{.RepoDigests}}' + +SECURITY +-------- +For security scanning, use: + grype + trivy image + +================================================================================ +EOF + +echo "✅ Generated BOM files:" +echo " - ${BOM_JSON} (CycloneDX format)" +echo " - ${BOM_YAML} (Kubernetes-friendly YAML)" +echo " - ${BOM_TXT} (Human-readable text)" + +# Print summary +echo "" +echo "Summary of images included in v${VERSION}:" +echo "----------------------------------------" +for name in "${!IMAGES[@]}"; do + printf "%-25s %s\n" "${name}:" "${IMAGES[$name]}" +done +echo "----------------------------------------" +echo "Total images: ${#IMAGES[@]}"