Klaudia Blueprint Knowledge

Introduction

Blueprint knowledge is a concise document that captures what Klaudia can't learn from your Kubernetes manifests alone the architectural decisions, business constraints, and tribal knowledge that live in your senior engineers' heads.

Kubernetes tells Klaudia what is deployed. Org Blueprint tells her why it's configured that way, what depends on what, and what rules must never be broken.

This includes:

• Business-critical dependencies that aren't visible in K8s (e.g., "payments-service requires the fraud-detection external API to be reachable before processing any transactions").
• Infrastructure context outside the cluster your Crossplane-managed cloud resources, ClusterAPI provisioned clusters, external databases, third-party services.
• Cross-cluster and multi-region logic failover rules, data residency requirements, and traffic routing decisions that span beyond a single cluster.
• Organizational constraints compliance rules, SLOs tied to business impact, scaling limits driven by cost or licensing, not just resources.
• The "why" behind configurations why a service has a specific resource request, why a PDB exists, and why certain namespaces have special treatment.

Without Org Blueprint, Klaudia sees your cluster. With it, she understands your system.

Knowledge Base vs Org Blueprint

The relationship: Knowledge Base tells Klaudia how to do things. Org Blueprint tells Klaudia how your system actually works. Use both, they're complementary.

What Should be Included?

Your Org Blueprint should read like the briefing doc you'd give a senior SRE on their first day, the critical context they need before touching anything.

Infrastructure Beyond the Cluster

Our production databases are managed via Crossplane. The primary Postgres instance (db-prod-primary) is an AWS RDS instance in us-east-1. Klaudia should know that database issues may not be visible in Kubernetes check the Crossplane Claim status and AWS health. Our Redis cluster is ElastiCache, also Crossplane-managed. The connection string is injected via External Secrets Operator from AWS Secrets Manager.

Multi-Cluster & Multi-Region Topology

We run three production clusters provisioned via ClusterAPI: prod-us-east (primary), prod-eu-west (EU data residency), and prod-ap-south (latency optimization). User data for EU customers must never leave prod-eu-west this is a GDPR requirement, not a preference. Global services (auth, feature-flags) run in prod-us-east and are replicated read-only to other regions. If prod-us-east is down, other clusters operate in degraded mode auth falls back to cached tokens valid for 1 hour.

Scaling Constraints & Resource Context

The ML-recommendation service requests 16Gi of memory not because of load, but because model loading requires it at startup. Don't reduce these pods will OOMKill during initialization even at zero traffic. We're capped at 8 replicas due to GPU node licensing (we pay per-node, max 8 g4dn.xlarge). The scale-down delay is 30 minutes because model warm-up takes 20 minutes, and scaling down and back up is extremely expensive.

External Dependencies & Failure Modes

All outbound API calls route through our egress-proxy service. If egress-proxy is down, no external integrations work (Stripe, Twilio, SendGrid, Datadog). This is intentional for security auditing. The proxy itself depends on Vault for mTLS certificates if Vault is unhealthy, new proxy pods cannot start. This is our most critical dependency chain: Vault → egress-proxy → all external integrations.

Compliance & Operational Rules

PCI workloads run only in the pci-workloads namespace. These pods must never be scheduled on nodes that run non-PCI workloads (enforced via taints, but Klaudia should know the why). Any changes to services in this namespace require a 24-hour CAB approval window Klaudia should flag this if recommending changes. Our SOC2 audit requires that we maintain 99.9% uptime on auth-service this is not just an SLO, it's a contractual obligation.

Best Practices

Keep it high-level and structural. This isn't a runbook. Don't write "run kubectl delete pod", use instead "this service can be safely restarted without data loss, but requires 5 minutes for cache warm-up."

Focus on what's NOT in Kubernetes. If Klaudia can figure it out from your manifests, labels, or annotations, you don't need to repeat it here. Document the invisible: business logic, external dependencies, cross-system relationships, the why behind configurations.

Write for a smart person who doesn't know your system. A senior engineer from another company should be able to read your Blueprint and understand your architecture. If it requires insider knowledge to parse, it's too terse.

Keep it scannable. Org Blueprint loads in full every session. If it becomes a novel, it dilutes attention. Aim for "comprehensive but concise" every sentence should earn its place.

Update on architecture changes, not incidents. If an incident reveals a documentation gap, add it. But don't let the Blueprint become an incident log; that's what the Knowledge Base is for.

Uploading and Managing Your Organization Blueprint

To add or update your Organization Blueprint in Komodor:

Step 1: Uploading your Blueprint Navigate to Klaudia Settings and find the Organization Blueprint section. Click the Upload button and select your file. Your Blueprint should be under 10KB—keep it concise since it's loaded in full into every Klaudia session.

Step 2: Review process Once uploaded, your Blueprint enters Review status. Komodor will manually review the file to ensure it's properly formatted and suitable for use.

Step 3: Activation After approval, your Blueprint moves to Active status. Klaudia will now load it in full into every session, using it to understand your system's architecture, dependencies, and constraints. The old version will have a Deprecated status. 

Managing versions Komodor maintains two versions of your Blueprint—allowing you to upload a new version for review, while your current active Blueprint continues to serve Klaudia. This ensures an uninterrupted context for Klaudia while you iterate on updates.

Note: Currently, Organization Blueprint is limited to a single file that applies across all clusters.