Kubernetes Networking AGENTS.md Template - AGENTS.md Template

Overview

Direct answer: This AGENTS.md template codifies a Kubernetes networking design workflow for single-agent and multi-agent orchestration, with defined roles, handoffs, tool governance, and security checks.

It provides a practical, copyable operating manual that can be dropped into a project to govern both isolated agent tasks and coordinated multi-agent runs for Kubernetes networking design, including policy creation, CNI configuration, network policy enforcement, and validation steps.

When to Use This AGENTS.md Template

• When starting a Kubernetes networking design project requiring traceable, repeatable agent behavior
• When multiple agents (planner, implementer, reviewer, tester, researcher, domain specialist) must coordinate changes to network policies, CNI configurations, and service networking
• When you need clear handoff points, source-of-truth rules, and auditable rollbacks for production-grade clusters
• When compliance and security checks must be embedded in the workflow

Copyable AGENTS.md Template

# AGENTS.md
# Kubernetes Networking AGENTS.md Template
# Purpose
This file defines a repeatable, auditable workflow for Kubernetes networking design using AI coding agents and multi-agent orchestration.

Project Role
Platform Engineer (Lead Architect of Kubernetes networking in this project)

Agent Roster and Responsibilities
- planner: defines strategy, constraints, milestones, and communicates the high-level design to implementer
- implementer: translates design into Kubernetes manifests, CNI config, and policy
- reviewer: reviews manifests, policies, and security controls
- tester: validates networking changes in a test or staging cluster
- researcher: captures requirements, references, and traces decisions
- domain specialist: handles CNI and network policy specifics (Calico/Kindnet/Cilium, etc.)

Supervisor/Orchestrator Behavior
- Orchestrator monitors progress, enforces handoffs, and ensures the documentation remains the source of truth
- Orchestrator triggers handoffs on completion of tasks or when blockers are removed

Handoff Rules
- Planner -> Implementer: deliver high-level design, constraints, and success criteria
- Implementer -> Reviewer: share manifests, Helm values, and tests
- Reviewer -> Tester: grant approval for testing and validation
- Tester -> Orchestrator: report test results and gating status
- Orchestrator -> Planner: update design based on test outcomes

Context, Memory, and Source of Truth
- Context is passed between agents in a transient working memory
- Source of Truth is the Git repository containing manifests, policies, and docs
- Cluster state can be queried via kubectl in non-production environments

Tool Access and Permission Rules
- Access to kubectl in designated namespaces
- Access to container registries and image pull secrets
- Secrets management through a vault or CI secret store
- No direct production changes without orchestration gate

Architecture Rules
- Use idempotent, declarative manifests
- Prefer Helm or Kustomize overlays for environments
- Apply Kubernetes NetworkPolicy for pod isolation
- Ensure CNI plugin compatibility with cluster version

File Structure Rules
- Repositories/organization/project/k8s/networking/
- agents/planner/
- agents/implementer/
- agents/reviewer/
- agents/tester/
- agents/researcher/
- agents/domain-specialist/
- policies/
- manifests/
- tests/
- docs/

Data, API, or Integration Rules
- Changes must go through Kubernetes API
- Validate with policy checks and schema
- Use Git for versioning

Validation Rules
- Lint manifests and policies
- Validate network policy syntax and CNI config
- Test under staging with simulated traffic

Security Rules
- Least privilege for each agent
- Secrets rotated and encrypted
- Audit logging for changes
- Do not bypass security controls

Testing Rules
- Unit tests for policy generators
- Integration tests for network policy enforcement
- End-to-end tests for service connectivity

Deployment Rules
- Canary or blue-green rollouts
- Manual gate for production
- Rollback plan with kubectl rollout undo

Human Review and Escalation Rules
- All changes must be reviewed by at least one domain specialist and one security reviewer
- Escalate to SRE if deployment impacts production traffic

Failure Handling and Rollback Rules
- Use kubectl rollout undo or Helm rollback
- Revert to last known-good configuration
- Preserve logs and state for investigations

Things Agents Must Not Do
- Do not deploy changes to production without tests
- Do not bypass policy checks
- Do not modify cluster-wide security settings without approval

Recommended Agent Operating Model

The agent roles map to a multi-agent orchestration pattern that centralizes responsibility while enabling specialization:

• Planner: designs the networking strategy, success criteria, and constraints
• Implementer: converts strategy into manifests, CNI config, and policies
• Reviewer: ensures alignment with security and policy standards
• Tester: exercises network scenarios and validates connectivity
• Researcher: records requirements, references, and rationale
• Domain Specialist: provides CNIs and policy-specific expertise

Recommended Project Structure

k8s-networking-design/
├── agents/
│   ├── planner/
│   ├── implementer/
│   ├── reviewer/
│   ├── tester/
│   ├── researcher/
│   └── domain-specialist/
├── orchestrator/
├── policies/
├── manifests/
├── tests/
└── docs/

Core Operating Principles

• Single source of truth
• Idempotent, deterministic actions
• Clear, auditable handoffs
• Context-limited memory per task
• Security-first, least privilege

Agent Handoff and Collaboration Rules

• Planner to Implementer: share constraints and high-level design
• Implementer to Reviewer: share manifests and tests
• Reviewer to Tester: approve tests and validation
• Tester to Orchestrator: report results and gating status
• Orchestrator to Planner: update design from test outcomes

Tool Governance and Permission Rules

• Only approved tools and APIs may be used
• Access to kubectl limited to namespaces and approved contexts
• Secrets management via vault/CI
• All changes require orchestration gate

Code Construction Rules

• All manifests must be declarative and idempotent
• Use Helm or Kustomize for environment overlays
• NetworkPolicy must be used for pod isolation
• Validate inputs and outputs at each stage

Security and Production Rules

• Least privilege for all agents
• Secrets encrypted, rotation policy in place
• Audit logging enabled
• Do not bypass production-grade review

Testing Checklist

• Unit tests for policy generators
• Integration tests for network policy enforcement
• End-to-end tests for service connectivity

Common Mistakes to Avoid

• Skipping tests before production rollout
• Overly permissive policies
• Not updating documentation after changes

FAQ

What is the purpose of this Kubernetes networking AGENTS.md Template?

It provides a practical operating manual for designing and deploying Kubernetes networking with AI agents and multi-agent orchestration, including handoffs, policy governance, and security checks.

Who should own the handoffs between planners and implementers?

The planner owns the high-level design; the implementer translates it into manifests and config, with the reviewer validating before deployment.

How are security and access controlled in this template?

Least privilege across agents, encrypted secrets, audit logging, and gated changes through orchestration gates.

How do you validate network configuration before production?

Linting, policy validation, staging tests, and controlled rollouts with observable metrics.

What happens if a deployment fails?

Rollback via kubectl rollout undo or Helm, along with state preservation for inspection.

Related implementation resources: AI Use Case for Policy Documents and Internal Question Answering and AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams.