Kubernetes Cluster Architecture Review Prompt

This prompt is designed for platform engineers and cloud architects who need a structured, evidence-based review of a Kubernetes cluster's design before it reaches production or during a major lifecycle upgrade. The job-to-be-done is not to generate a generic best-practices checklist, but to produce a specific, actionable assessment of a real cluster's topology, multi-tenancy isolation, networking policies, upgrade strategy, and resource governance. The ideal user has access to the cluster's design documents, node pool configurations, network policies, and security context, and needs to identify concrete risks—such as a lack of etcd backup coverage or a single point of failure in the control plane—before they become incidents.

Use this prompt when you have a concrete cluster specification to review and you need a report that can be shared with a wider engineering or security team. The prompt is most effective when the input includes specific details: the number and type of node pools, the CNI plugin in use, the configured pod and network policies, the etcd backup schedule, and the cluster upgrade strategy. Do not use this prompt for a high-level, introductory explanation of Kubernetes concepts, for generating a cluster from scratch, or for reviewing application-level code running inside the cluster. It is a design review tool, not a tutorial or a deployment script.

The prompt is built to enforce a rigorous, risk-aware output. It requires the model to cite specific evidence from the provided input for every finding, to flag missing information as a risk in itself, and to prioritize issues by blast radius. Before relying on the output, you must validate that the model's findings are grounded in the provided configuration data. For high-stakes production clusters, always pair this automated review with a manual peer review by a second platform engineer. The next section provides the copy-ready prompt template you can adapt for your own cluster specifications.

This section provides the core prompt template you can copy, adapt, and embed into your internal platform tools or CI/CD pipelines. The prompt is designed to ingest a description of a Kubernetes cluster architecture and produce a structured assessment. It uses square-bracket placeholders for all variable inputs, allowing you to swap in different cluster specifications, risk profiles, and output format requirements without rewriting the core instructions.

textCopy
You are a senior platform architect reviewing a Kubernetes cluster design. Your task is to produce a structured, evidence-based assessment of the proposed architecture.

## INPUT
[CLUSTER_ARCHITECTURE_DESCRIPTION]

## CONTEXT
- Organization type: [ORGANIZATION_TYPE, e.g., startup, enterprise, regulated-industry]
- Primary workloads: [WORKLOAD_TYPES, e.g., stateless APIs, stateful databases, batch jobs]
- Compliance requirements: [COMPLIANCE_FRAMEWORKS, e.g., SOC2, HIPAA, PCI-DSS, none]
- Team size and SRE maturity: [TEAM_CONTEXT]

## CONSTRAINTS
- Do not invent details not present in the input. If critical information is missing, flag it as an assumption gap.
- Distinguish between best-practice recommendations and hard requirements driven by the stated compliance or workload context.
- For each finding, provide a rationale grounded in Kubernetes operational principles.

## OUTPUT_SCHEMA
Return a valid JSON object with the following structure:
{
  "summary": "A 2-3 sentence executive summary of the architecture's overall health.",
  "findings": [
    {
      "id": "F-001",
      "category": "multi-tenancy | networking | security | resource-governance | upgrade-strategy | backup-dr | observability",
      "severity": "critical | high | medium | low",
      "title": "Short finding title",
      "description": "Detailed description of the finding.",
      "rationale": "Why this matters, referencing Kubernetes internals or operational failure modes.",
      "recommendation": "Specific, actionable recommendation."
    }
  ],
  "assumption_gaps": ["List any critical missing information that prevented a full assessment."],
  "overall_risk_score": "high | medium | low"
}

## EVALUATION CRITERIA
Before outputting, verify your response against these checks:
1. Control plane resilience: Is the API server availability and etcd quorum explicitly addressed?
2. etcd backup coverage: Are backup frequency, retention, and restore testing mentioned or flagged as gaps?
3. Multi-tenancy isolation: Is the blast radius between teams or applications clearly defined at the network, namespace, and node level?
4. Upgrade strategy: Is there a documented process for version skew, node cordon/drain, and rollback?
5. Resource governance: Are LimitRanges, ResourceQuotas, and node pool taints/tolerations configured to prevent noisy-neighbor problems?

To adapt this template, replace the square-bracket placeholders with your specific inputs. The [CLUSTER_ARCHITECTURE_DESCRIPTION] should be a detailed text dump from your internal design doc, architecture diagram, or kubectl output summary. The [OUTPUT_SCHEMA] can be modified to match your internal ticketing system's fields. For high-risk environments, such as those under PCI-DSS or HIPAA, always route the final JSON output to a human reviewer and archive it alongside the cluster's configuration repository as an audit artifact.

This prompt is designed to be called programmatically as part of a design review pipeline, not as a one-off chat interaction. The typical integration point is a CI/CD check, a pull request review for infrastructure-as-code changes, or a scheduled audit of live cluster configurations. The application layer is responsible for gathering the required inputs—cluster topology, node pool definitions, networking policies, and security configurations—and assembling them into the [CLUSTER_SPEC] and [SECURITY_POLICIES] placeholders before invoking the model.

Input assembly and validation: Before calling the model, validate that the assembled [CLUSTER_SPEC] contains at minimum: control plane configuration (managed vs. self-hosted), node pool definitions with taints and labels, CNI plugin and network policy status, and etcd backup configuration. If any required field is missing, return a structured error to the user rather than sending an incomplete prompt to the model. The [SECURITY_POLICIES] input should include Pod Security Standards (or PSP replacement), network policies, and RBAC bindings. For live cluster reviews, extract these from kubectl and the cloud provider API; for IaC reviews, parse the Terraform or Pulumi state. Use a pre-processing step to redact secrets and sensitive values before they enter the prompt context.

Model choice and invocation: Use a model with strong reasoning capabilities and a large context window (e.g., GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro). The prompt's structured output requirement demands reliable JSON generation, so prefer models with proven schema-following performance. Set temperature to 0.1–0.2 for deterministic assessments. Implement a retry wrapper with exponential backoff (3 attempts max) that catches JSON parse failures and schema validation errors. On retry, append the validation error message to the prompt as additional context so the model can self-correct malformed output.

Output validation and human review gate: After receiving the model response, validate the JSON against the expected schema: findings must be an array, each finding must have severity (one of CRITICAL, HIGH, MEDIUM, LOW), category, description, and recommendation fields. Reject and retry outputs with missing required fields. For any finding with severity CRITICAL or HIGH, route the assessment to a human reviewer queue (e.g., a Jira ticket or Slack notification) before the review is considered complete. Log every invocation—inputs, outputs, validation results, and reviewer decisions—to an audit table for governance and prompt improvement analysis.

Avoid shipping without these checks: Do not bypass the input completeness validator; an incomplete cluster spec produces dangerously shallow reviews. Do not skip the human review gate for CRITICAL findings—control plane resilience and etcd backup gaps can cause data loss. Do not use this prompt against production clusters without first testing against a staging or sandbox environment to calibrate severity thresholds and verify that the model's recommendations align with your organization's specific operational policies and compliance requirements.