# Setting Up KubernetesDeployer with GovernanceConfig for Agent Deployment

> Learn to set up KubernetesDeployer with GovernanceConfig for agent deployment. Mount policy files via Helm for live enforcement without redeployment.

- Repository: [Microsoft/agent-governance-toolkit](https://github.com/microsoft/agent-governance-toolkit)
- Tags: how-to-guide
- Published: 2026-05-29

---

**Setting up the KubernetesDeployer with GovernanceConfig requires mounting a Kubernetes ConfigMap containing YAML policy files into the Policy Server via Helm, enabling live policy enforcement across the Agent Mesh without cluster redeployment.**

The Microsoft Agent Governance Toolkit (AGT) ships a production-ready Kubernetes deployment flow that couples the **Agent Mesh** runtime with a declarative **GovernanceConfig**. By configuring the KubernetesDeployer to reference policy ConfigMaps, operators can enforce governance rules on agent workloads while allowing the Policy Server to hot-reload policies at runtime.

## Architecture Overview

The KubernetesDeployer provisions three stateless core components through Helm charts located in `agent-governance-python/agent-mesh/charts/agentmesh/`. Because these components lack local state, horizontal scaling is achieved by adjusting replica counts in the Helm values file.

- **Policy Server** ([`deployment-policy-server.yaml`](https://github.com/microsoft/agent-governance-toolkit/blob/main/deployment-policy-server.yaml)): Stores and evaluates governance policies (YAML) for agents at runtime. It mounts the Governance ConfigMap read-only and reloads policies on change.
- **Trust Engine** ([`deployment-trust-engine.yaml`](https://github.com/microsoft/agent-governance-toolkit/blob/main/deployment-trust-engine.yaml)): Enforces policy decisions by injecting them into the agent’s execution context.
- **Agent Mesh API Gateway** ([`deployment-api-gateway.yaml`](https://github.com/microsoft/agent-governance-toolkit/blob/main/deployment-api-gateway.yaml)): Exposes the agent-service API and forwards calls through the Trust Engine.

## Prerequisites

Before configuring the KubernetesDeployer, ensure you have:
- A running Kubernetes cluster (1.24+).
- Helm 3.12+ installed locally.
- `kubectl` configured with cluster-admin privileges for the target namespace.

## Step-by-Step Deployment

### 1. Create the Governance ConfigMap

The GovernanceConfig lives as a standard Kubernetes ConfigMap containing one or more policy YAML files. Create a manifest that references the AGT policy schema, as seen in [`examples/smolagents-governed/policies/research_governance_policy.yaml`](https://github.com/microsoft/agent-governance-toolkit/blob/main/examples/smolagents-governed/policies/research_governance_policy.yaml):

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: agent-governance-policies
  namespace: agt
data:
  research_governance_policy.yaml: |
    policy:
      name: "ResearchSafety"
      description: "Enforce safe-search for research agents"
      rules:
        - id: "no-malicious-url"
          type: "url-allowlist"
          allow:
            - "https://arxiv.org/**"
            - "https://pubmed.ncbi.nlm.nih.gov/**"
        - id: "max-tokens"
          type: "quota"
          maxTokens: 2048
  loan_governance.yaml: |
    # Additional policy files can be added here

```

Apply the ConfigMap:

```bash
kubectl apply -f governance-configmap.yaml

```

### 2. Configure Helm Values

In [`agent-governance-python/agent-mesh/charts/agentmesh/values.yaml`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent-governance-python/agent-mesh/charts/agentmesh/values.yaml), reference the ConfigMap name and set the reload interval. The Trust Engine and API Gateway replicas can be adjusted for workload size:

```yaml
policyServer:
  configMapName: agent-governance-policies
  reloadIntervalSeconds: 30

trustEngine:
  replicaCount: 2

apiGateway:
  replicaCount: 2
  env:
    - name: AGENT_GOVERNANCE_URL
      value: "http://policy-server.agt.svc.cluster.local:8080"

```

### 3. Deploy the Agent Mesh

Run `helm upgrade` to render the three deployments and inject the ConfigMap into the Policy Server pod:

```bash
helm upgrade --install agt-mesh \
  ./agent-governance-python/agent-mesh/charts/agentmesh \
  -f values.yaml \
  --namespace agt --create-namespace

```

Helm templates located at [`agent-governance-python/agent-mesh/charts/agentmesh/templates/deployment-policy-server.yaml`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent-governance-python/agent-mesh/charts/agentmesh/templates/deployment-policy-server.yaml) handle mounting the ConfigMap as a read-only volume, while [`deployment-trust-engine.yaml`](https://github.com/microsoft/agent-governance-toolkit/blob/main/deployment-trust-engine.yaml) and [`deployment-api-gateway.yaml`](https://github.com/microsoft/agent-governance-toolkit/blob/main/deployment-api-gateway.yaml) establish the enforcement and ingress layers.

### 4. Launch Governed Agents

Agents connect to the Policy Server via the `AGENT_GOVERNANCE_URL` environment variable. Deploy an agent workload that points to the internal service endpoint:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: claude-desktop-agent
  namespace: agt
spec:
  replicas: 1
  selector:
    matchLabels:
      app: claude-desktop
  template:
    metadata:
      labels:
        app: claude-desktop
    spec:
      containers:
        - name: agent
          image: ghcr.io/microsoft/agent-clause-desktop:latest
          env:
            - name: AGENT_GOVERNANCE_URL
              value: "http://policy-server.agt.svc.cluster.local:8080"
          ports:
            - containerPort: 8080

```

Agents automatically query the Trust Engine for policy decisions on each request. As implemented in [`agent-governance-python/agent-os/examples/integrations/governance_quickstart.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent-governance-python/agent-os/examples/integrations/governance_quickstart.py), this integration requires no code changes beyond the environment variable configuration.

## Validating Policies

Before loading policies into the cluster, validate YAML syntax and schema compliance using the governance gate script:

```bash
python scripts/governance_gate.py --policy-file examples/smolagents-governed/policies/research_governance_policy.yaml

```

This utility checks for malformed rules or missing required fields that would cause the Policy Server to fail startup, preventing deployment-time errors in production environments.

## Summary

- **KubernetesDeployer** relies on Helm charts in `agent-governance-python/agent-mesh/charts/agentmesh/` to provision the Policy Server, Trust Engine, and API Gateway.
- **GovernanceConfig** is implemented as a Kubernetes ConfigMap mounted into the Policy Server, supporting live policy reloads without pod restarts.
- The Policy Server merges multiple policy files from a single ConfigMap at startup, enabling complex multi-domain governance.
- Agents consume governance decisions via the `AGENT_GOVERNANCE_URL` environment variable pointing to the Policy Server service.
- All mesh components are stateless, allowing horizontal scaling by adjusting `replicaCount` in [`values.yaml`](https://github.com/microsoft/agent-governance-toolkit/blob/main/values.yaml).

## Frequently Asked Questions

### How does the Policy Server detect policy updates without restarting?

The Policy Server watches the mounted ConfigMap volume for filesystem changes. When `reloadIntervalSeconds` (configured in [`values.yaml`](https://github.com/microsoft/agent-governance-toolkit/blob/main/values.yaml)) elapses or an inotify event fires, the server re-parses the YAML policies and updates its in-memory rule engine. Because the ConfigMap is mounted read-only from the node’s filesystem, Kubernetes updates propagate naturally when `kubectl apply` modifies the ConfigMap object.

### Can I run multiple governance policies simultaneously?

Yes. The Governance ConfigMap can contain multiple policy YAML files under different keys in the `data` section. The Policy Server, as defined in [`deployment-policy-server.yaml`](https://github.com/microsoft/agent-governance-toolkit/blob/main/deployment-policy-server.yaml), loads all files from the mount path and merges them into a unified policy set. Each policy file follows the AGT schema demonstrated in [`examples/smolagents-governed/policies/research_governance_policy.yaml`](https://github.com/microsoft/agent-governance-toolkit/blob/main/examples/smolagents-governed/policies/research_governance_policy.yaml), allowing heterogeneous rule sets (e.g., URL allowlists and token quotas) to coexist.

### What network address should agents use to reach the Policy Server?

Agents should target the internal Kubernetes DNS name `http://policy-server.agt.svc.cluster.local:8080`, where `agt` is the namespace deployed via the Helm chart. This endpoint is injected into the Agent Mesh API Gateway and agent pods via the `AGENT_GOVERNANCE_URL` environment variable. Traffic remains inside the cluster, minimizing latency and avoiding external exposure of the governance control plane.

### How do I scale the Trust Engine and Policy Server horizontally?

Because the components are stateless, scaling requires only updating the `replicaCount` field in [`agent-governance-python/agent-mesh/charts/agentmesh/values.yaml`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent-governance-python/agent-mesh/charts/agentmesh/values.yaml) and running `helm upgrade`. The Trust Engine pods share no session state, so load balancing across replicas is handled automatically by the Kubernetes Service. Note that while the Policy Server supports multiple replicas for availability, all instances serve the same synchronized ConfigMap data.