AGENTS.md Template: Kubernetes Ingress Architecture

Overview

Direct answer: This AGENTS.md template governs the Kubernetes ingress architecture for multi-agent orchestration, including Ingress Controller selection, TLS management, DNS resolution, and routing rules. It provides an operating manual for both single-agent and multi-agent workflows, ensuring clear handoffs and source-of-truth rules.

The AGENTS.md template explains the roles of agents, memory context, tool access, and governance that enable reliable, auditable ingress operations in Kubernetes clusters.

When to Use This AGENTS.md Template

• When you need a standardized operating context for designing, deploying, and operating a Kubernetes ingress architecture.
• When coordinating multiple agents (planner, implementer, tester, reviewer, researcher, domain specialist) around ingress resources, TLS, and traffic routing.
• When enforcing tool governance, access controls, and escalation paths for production-grade ingress implementations.
• When you require a documented handoff protocol between agents to avoid context drift and ensure auditable decisions.

Copyable AGENTS.md Template

# AGENTS.md

Project: Kubernetes Ingress Architecture – Multi-Agent Orchestration

Agent roster and responsibilities:
  - Planner: designs ingress topology, TLS strategy, DNS routing, and high-level success criteria.
  - Implementer: translates planner decisions into manifests, Helm charts, and controller configuration.
  - Reviewer: validates security, compliance, and architecture drift; approves changes for staging.
  - Tester: executes ingress-related tests, including connectivity, TLS, wss, and path-based routing.
  - Researcher: collects telemetry data, evaluates new controllers, and benchmarks performance.
  - Domain Specialist: provides Kubernetes networking domain expertise (DNS, TLS, service mesh if applicable).

Supervisor / Orchestrator behavior:
  - The Orchestrator maintains a single source of truth for ingress policies and coordinates handoffs via explicit context sharing.
  - Any change requires a planner-approved ticket, a reviewer sign-off, and passing tests before deployment.
  - Handoffs between agents follow the memory/context rules and are updated in the shared context.

Handoff rules between agents:
  - Planner -> Implementer: provide topology, TLS, certificate requirements, and controller config.
  - Implementer -> Tester: provide manifests, chart values, and secret handling notes; ensure environment mapping.
  - Tester -> Reviewer: deliver test results and risk assessment; request approval for staging deployment.
  - Researcher -> Domain Specialist: share performance data and DNS resolution findings; suggest optimizations.

Context, memory, and source-of-truth rules:
  - All decisions are recorded in AGENTS.md as the canonical source of truth.
  - Context must include ingress class, hostname, paths, TLS certs, and controller version.
  - Secrets never leave the cluster; secrets are referenced via Kubernetes Secrets and external secret managers if used.

Tool access and permission rules:
  - Implementer and Tester require read access to manifests and cluster credentials via a controlled vault.
  - No direct production changes without Planner + Reviewer approval.
  - Access to DNS provider and certificate management is restricted to Domain Specialist or a designated operator.

Architecture rules:
  - Use a primary ingress controller (e.g., NGINX Ingress or Traefik) with defined TLS termination strategy.
  - Prefer path-based routing for microservices; support host-based routing where appropriate.
  - Align with corporate security posture: mTLS for inter-service calls, audit logging enabled.

File structure rules:
  - k8s-ingress-architecture/
    - manifests/
      - ingress.yaml
      - tls/
    - charts/
    - docs/
    - agents/
      - planner.md
      - implementer.md
      - reviewer.md
      - tester.md
      - researcher.md
      - domain-specialist.md
    - templates/
    - README.md

Data, API, or integration rules:
  - Ingress manifests must reference existing Secrets in the cluster; do not embed secrets in files.
  - Use external DNS providers via DNS01 challenges for TLS certificates where supported.
  - Validate API server interactions; minimize custom API access beyond kubectl/cluster API clients.

Validation rules:
  - All changes must pass unit tests (syntax), integration tests (routing and TLS), and dry-run deployments.
  - Validate TLS termination, certificate validity, and DNS resolution in staging.

Security rules:
  - Do not expose insecure endpoints; require TLS 1.2+; disable endpoint exposure by default.
  - Do not commit plaintext secrets; use Kubernetes Secrets or external secret management.
  - Enforce RBAC least privilege for all agents.

Testing rules:
  - Include connectivity tests, TLS handshake verification, and path-based routing tests.
  - Run end-to-end ingress tests in a staging namespace before production deployment.

Deployment rules:
  - Deploy via controlled pipelines; require Planner approval and CI/CD checks.
  - Rollback plan must be defined and tested in staging.

Human review and escalation rules:
  - Escalate security or reliability concerns to the Domain Specialist and Reviewer.
  - All production changes require a formal sign-off from Planner and Reviewer.

Failure handling and rollback rules:
  - On ingress misrouting or certificate errors, revert to previous known-good ingress configuration and rerun tests.
  - Maintain an incident runbook for ingress outages; include contact paths and remediation steps.

Things Agents must not do:
  - Do not bypass approvals or run changes in production without sign-off.
  - Do not store secrets in plaintext in code or git history.
  - Do not alter cluster-wide DNS or TLS configurations without planner and domain specialist review.

Recommended Agent Operating Model

In this Kubernetes ingress architecture workflow, agents operate within a bounded decision space with explicit escalation paths. The Planner defines ingress topology and success criteria; the Implementer translates the topology into manifests and controller config; the Reviewer ensures security and architectural integrity; the Tester confirms routing and TLS behavior; the Researcher analyzes performance and reliability; the Domain Specialist ensures DNS and TLS alignment with external services. Handoffs are driven by canonical context stored in AGENTS.md; agents must reference the same source of truth to prevent divergence.

Recommended Project Structure

kubernetes-ingress-architecture/
  manifests/
    ingress.yaml
    tls/
  charts/
  docs/
  agents/
    planner.md
    implementer.md
    reviewer.md
    tester.md
    researcher.md
    domain-specialist.md
  templates/
  README.md

Core Operating Principles

• Single source of truth within AGENTS.md and linked manifests.
• Idempotent changes and reproducible deployments.
• Clear separation of concerns among planner, implementer, tester, reviewer, researcher, and domain specialist.
• Predictable escalation paths and documented handoffs.
• Strict tool governance and secret handling.

Agent Handoff and Collaboration Rules

• Planner to Implementer: provide topology, TLS strategy, and controller configuration.
• Implementer to Tester: deliver manifests, values files, and secret handling notes; map to environment.
• Tester to Reviewer: present test results and risk assessment; request staging approval.
• Researcher to Domain Specialist: share telemetry findings and DNS/TLS considerations.

Tool Governance and Permission Rules

• Access to kubectl and cluster APIs is granted through a controlled vault; production changes require Planner & Reviewer approvals.
• DNS provider and certificate management access is restricted to Domain Specialist or designated operator.
• Secret access must be through Kubernetes Secrets or external secret managers; never plaintext in code.

Code Construction Rules

• Ingress resources must be defined declaratively with clear annotations for the chosen ingress controller.
• SSL/TLS certificates must be managed via automated renewals and stored securely.
• Environment-specific values must be isolated and parameterized via charts or config maps.

Security and Production Rules

• Enforce TLS, restrict public exposure, and enable audit logging on all ingress traffic.
• Implement mTLS for service-to-service calls where applicable.
• Follow RBAC least privilege and monitor for unusual access patterns.

Testing Checklist

• Unit tests for manifest generation; linting for YAML.
• Integration tests for routing, TLS handshake, and hostname resolution.
• End-to-end tests in a staging namespace; verify failover and rollback mechanisms.

Common Mistakes to Avoid

• Skipping planner reviews or bypassing sign-off gates.
• Embedding secrets in manifests or code history.
• Neglecting DNS validation or TLS renewal automation.

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.

FAQ

What is the purpose of this AGENTS.md Template for Kubernetes ingress architecture?

This AGENTS.md template provides a structured, repeatable operating manual for coordinating multiple AI coding agents around Kubernetes ingress architecture, ensuring clear roles, handoffs, and governance.

Who are the intended agents and their responsibilities?

The Planner designs topology; the Implementer creates manifests; the Reviewer validates security and architecture; the Tester verifies routing and TLS; the Researcher analyzes performance; the Domain Specialist handles DNS and certificate considerations.

How are handoffs between agents managed?

Handoffs follow a canonical context stored in AGENTS.md; each transition includes the necessary artifacts, environment map, and verification steps, with explicit approvals required for production changes.

What security controls apply to Kubernetes ingress in this template?

TLS is mandatory; secrets are managed securely, not embedded in code; RBAC least privilege is enforced; audit logging is enabled; production changes require planner and reviewer approval.

How is validation performed before deployment?

Validation includes YAML lint/unit tests, integration tests for routing/TLS in staging, and dry-run deployments with a rollback plan.