Cursor Rules for Kubernetes: Manifests, Contexts, and Reviews

Cursor rules for Kubernetes tell a coding assistant how your team writes manifests, which cluster it is targeting, how to reference secrets, and which changes need a review before they are applied. Without them, an assistant treats every cluster as a fresh start and has no way to know whether a change should go through an approval step. Tools like fenbs record the operational decisions behind these rules, so the next assistant reads the same boundaries the current one worked inside.

This page gives you a working template for each concern, explains the traps to avoid, and shows how to keep the rules current as your cluster setup changes.

What Kubernetes Cursor rules need to cover

A Kubernetes project has several areas where an assistant without context will make plausible but wrong choices. Manifest style is one: resource names, label schemes, and annotation patterns vary by team. Cluster context is another: an assistant that does not know which namespace or cluster is current may generate commands for the wrong target. Secret handling is a third: references to credentials must follow your chosen pattern rather than inlining values.

How you organize the rule files matters almost as much as what they contain. Start with a single file covering all five areas. Once the rules have been refined through a few sessions, split them by concern: manifest rules scoped to **/*.yaml files, cluster context rules applied always, and secret reference rules scoped to files that reference environment variables. This keeps each file focused and easy to update independently when the cluster configuration changes. For patterns that apply across multiple Kubernetes repositories, see the Cursor rules library guide.

• Manifest conventions: resource naming, required labels, annotation patterns, and ordering of fields.
• Cluster context: which namespace is active, how to switch clusters, and what a dry-run looks like before applying.
• Secret references: how to reference a secret (a Kubernetes Secret name, an external secrets reference, or an environment variable source), never the value.
• Reviewed changes: which resource types require a human approval step before kubectl apply.
• Lint and validate: whether the project uses kube-linter, kubeconform, or another tool, and when to run it.

Manifest convention rules

Consistency matters across a cluster because a pipeline or a monitoring tool usually reads labels to find resources. If an assistant creates a Deployment without the right labels, it becomes invisible to that tooling. The rules below set the minimum your assistant needs to follow your team's conventions.

# Kubernetes manifest conventions

## Naming
- Use kebab-case for all resource names: my-app-backend, not MyAppBackend or my_app_backend.
- Prefix names with the service identifier: payments-api, payments-worker, not just api or worker.

## Required labels
Every resource must include:
  app.kubernetes.io/name: <service-name>
  app.kubernetes.io/component: <api | worker | job | cron>
  app.kubernetes.io/part-of: <product>
  app.kubernetes.io/managed-by: <helm | kustomize | kubectl>

## Field order
Prefer this order in specs: metadata, spec, then nested containers.
List containers before initContainers. List env before envFrom.

## Resource limits
Every container spec must set resources.requests and resources.limits.
Do not omit these even for one-off jobs.

Cluster context rules

An assistant that does not know the active context can generate kubectl commands that run against the wrong cluster. Add a rule that names the expected context and requires a dry-run before any apply. Pair it with a rule about namespace: many teams create resources in the default namespace by accident and only discover it when a probe fails.

# Cluster context

## Active context
The development cluster context is k8s-dev. The staging context is k8s-staging.
Production context is k8s-prod; never target it from a local environment.
Always confirm the current context with `kubectl config current-context` before generating apply commands.

## Namespace
Default namespace is not used. Every resource specifies metadata.namespace explicitly.
Development resources go in dev-<service>. Staging resources go in staging-<service>.

## Dry-run
Before generating any apply or delete command, include a dry-run step:
  kubectl apply --dry-run=server -f <file>
Present the dry-run result to the user before offering the live command.

Secret reference rules

The most important rule in a Kubernetes project is how secrets reach containers. An assistant offered a connection string may inline it as a literal value if no rule says otherwise. State clearly which pattern your team uses and require the assistant to use that pattern only. The checker for this kind of rule is simple: if the word "password", "token", or "key" appears in a manifest value, it is wrong.

# Secret references

## Never inline credentials
Do not place passwords, tokens, API keys, or certificate content directly in a manifest value.
If a credential is offered in a prompt, note the field name it belongs to and generate the
Kubernetes Secret reference instead.

## Reference pattern
This project uses Kubernetes Secrets referenced by secretKeyRef:
  env:
    - name: DATABASE_URL
      valueFrom:
        secretKeyRef:
          name: payments-db-secret
          key: connection-string

## External secrets
For secrets managed by External Secrets Operator, generate an ExternalSecret resource pointing
to the SecretStore named aws-secrets-manager-store. Do not create the Kubernetes Secret directly.

Rules for reviewed changes

Some Kubernetes changes need a human decision before they are applied: scaling a production Deployment, changing a PodDisruptionBudget, or updating a network policy. A rule that flags these resources prevents an assistant from presenting an apply command as ready when it actually needs approval. The rule does not need to know every detail of your review process; it just needs to identify the resource types and instruct the assistant to mark them as needing review.

Any change to a review-required resource that is made without following the approval step should be recorded as a lesson in the project record. A bypassed approval that becomes a habit is more dangerous than the original change, because the next session has no way to know the bypass was temporary rather than intentional. Approved exceptions belong in the rule file alongside the rule they deviate from.

# Reviewed changes

## Resources that require approval before apply
The following resource types in the staging and production namespaces need a person to approve
before `kubectl apply` is run:
  - Deployment (if replicas or image tag changes)
  - HorizontalPodAutoscaler
  - PodDisruptionBudget
  - NetworkPolicy
  - ClusterRole and ClusterRoleBinding

When generating changes to these resources, end the response with:
  "REVIEW REQUIRED: apply this only after approval in the deployment log."

Do not include the live kubectl apply command for these resources.

How to do this with fenbs

1. Create a free account and add a project for the cluster or service you are working on.
2. Add the operational decisions your team has settled on: naming conventions, secret pattern, which changes need approval. Record each one as a Decision in fenbs, with the person who decided it and the reason.
3. Connect Cursor to fenbs over MCP from Integrations. Ask Cursor to read the project context at the start of a session before making any manifest changes.
4. Keep a task in fenbs for any pending cluster change that needs review. Move it to In Progress when work starts and to Completed when the change is applied and verified. The task record carries the context a colleague needs to understand what changed.
5. When a rule changes, update the Decision in fenbs and the Cursor rule file together. The two should always agree.

For rules that apply across many Kubernetes projects, see the Cursor rules library guide for how to share rule files and keep them consistent across repositories.