Helm Deployment

Deploy AgentWeave agents using Helm charts

Edit on GitHub

Helm Deployment Guide

This guide covers deploying AgentWeave agents using Helm charts for templated, reproducible Kubernetes deployments.

Table of Contents

  1. Helm Deployment Guide
    1. Prerequisites
    2. Installing Helm
    3. Adding the AgentWeave Helm Repository
    4. Chart Structure
    5. values.yaml Reference
      1. Complete values.yaml
    6. Installing the Chart
      1. Basic Installation
      2. Custom values.yaml
      3. Command-Line Overrides
    7. Common Configurations
      1. Configuration 1: Single Agent (Development)
      2. Configuration 2: Production Multi-Agent
      3. Configuration 3: With SPIRE Stack
      4. Configuration 4: With OPA Sidecar
    8. Managing Releases
      1. Viewing Releases
      2. Upgrading Releases
      3. Rollback Procedures
      4. Uninstalling Releases
    9. Customizing Templates
      1. Adding Custom Annotations
      2. Adding Sidecars
      3. Custom Init Containers
    10. Testing Chart Changes
      1. Linting
      2. Template Rendering
      3. Dry-Run Installation
    11. Chart Development
      1. Creating Custom Chart
      2. Testing Locally
      3. Chart Dependencies
    12. Troubleshooting
      1. Chart Installation Fails
      2. Values Not Being Applied
      3. Template Rendering Issues
    13. Best Practices
      1. Version Pinning
      2. Values Organization
      3. Secrets Management
    14. Next Steps

Prerequisites

  • Kubernetes cluster 1.24+
  • Helm 3.8+
  • kubectl configured
  • Cluster-admin access for initial setup

Installing Helm

If you don't have Helm installed:

1
2
3
4
5
6
7
8

# macOS
brew install helm

# Linux
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# Verify installation
helm version

Adding the AgentWeave Helm Repository

1
2
3
4
5
6
7
8

# Add the official AgentWeave Helm repository
helm repo add agentweave https://charts.agentweave.io

# Update repository index
helm repo update

# Search for available charts
helm search repo agentweave

Expected output:

1
2
3
4

NAME                            CHART VERSION   APP VERSION     DESCRIPTION
agentweave/agentweave           1.0.0           1.0.0           AgentWeave secure agent SDK
agentweave/spire                1.9.0           1.9.0           SPIRE identity infrastructure
agentweave/agentweave-stack     1.0.0           1.0.0           Complete AgentWeave stack

Chart Structure

The AgentWeave Helm chart has the following structure:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

agentweave/
├── Chart.yaml              # Chart metadata
├── values.yaml             # Default configuration values
├── templates/
│   ├── NOTES.txt           # Post-installation notes
│   ├── _helpers.tpl        # Template helpers
│   ├── configmap.yaml      # Agent configuration
│   ├── deployment.yaml     # Agent deployment
│   ├── service.yaml        # Service definition
│   ├── serviceaccount.yaml # RBAC resources
│   ├── networkpolicy.yaml  # Network policies
│   ├── hpa.yaml            # Horizontal pod autoscaler
│   ├── pdb.yaml            # Pod disruption budget
│   └── spire/              # SPIRE-specific resources
│       ├── entries.yaml    # Registration entries
│       └── configmap.yaml  # SPIRE configuration
└── values.schema.json      # Values validation schema

values.yaml Reference

Complete values.yaml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333

# AgentWeave Helm Chart Values
# This file contains all configurable parameters

# Agent configuration
agent:
  # Agent name (required)
  name: "my-agent"

  # SPIFFE trust domain
  trustDomain: "agentweave.io"

  # Agent description
  description: "Example AgentWeave agent"

  # Agent capabilities
  capabilities:
    - name: "process"
      description: "Process data"
      inputModes:
        - "application/json"
      outputModes:
        - "application/json"

# Container image configuration
image:
  # Image repository
  repository: agentweave/agent

  # Image pull policy
  pullPolicy: IfNotPresent

  # Image tag (defaults to chart appVersion)
  tag: ""

# Image pull secrets
imagePullSecrets: []

# Number of replicas
replicaCount: 3

# ServiceAccount configuration
serviceAccount:
  # Create service account
  create: true

  # Service account annotations
  annotations: {}

  # Service account name
  name: ""

# Pod annotations
podAnnotations:
  prometheus.io/scrape: "true"
  prometheus.io/port: "9090"
  prometheus.io/path: "/metrics"

# Pod security context
podSecurityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 1000
  seccompProfile:
    type: RuntimeDefault

# Container security context
securityContext:
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: true
  runAsNonRoot: true
  runAsUser: 1000
  capabilities:
    drop:
      - ALL

# SPIFFE/SPIRE configuration
spiffe:
  # Enable SPIFFE identity
  enabled: true

  # SPIRE agent socket path
  socketPath: "/run/spire/sockets/agent.sock"

  # Allowed trust domains
  allowedTrustDomains:
    - "agentweave.io"

  # SPIRE registration entry
  registration:
    # Create registration entry
    create: true

    # Parent SPIFFE ID
    parentID: "spiffe://agentweave.io/spire/agent/k8s-node"

    # Selectors
    selectors:
      - "k8s:ns:"
      - "k8s:sa:"
      - "k8s:pod-label:app.kubernetes.io/name:"

    # DNS names
    dnsNames:
      - ""
      - "."
      - "..svc.cluster.local"

# Authorization configuration
authorization:
  # OPA provider
  provider: "opa"

  # OPA endpoint
  opaEndpoint: "http://opa:8181"

  # OPA policy path
  policyPath: "agentweave/authz"

  # Default action
  defaultAction: "deny"

  # Audit logging
  audit:
    enabled: true
    destination: "stdout"

  # OPA sidecar configuration
  sidecar:
    # Enable OPA sidecar
    enabled: true

    # OPA image
    image: "openpolicyagent/opa:0.62.0"

    # Resources
    resources:
      requests:
        cpu: 100m
        memory: 128Mi
      limits:
        cpu: 500m
        memory: 512Mi

# Transport configuration
transport:
  # Minimum TLS version
  tlsMinVersion: "1.3"

  # Peer verification
  peerVerification: "strict"

  # Connection pool
  connectionPool:
    maxConnections: 100
    idleTimeoutSeconds: 60

  # Circuit breaker
  circuitBreaker:
    failureThreshold: 5
    recoveryTimeoutSeconds: 30

# Server configuration
server:
  # Listen host
  host: "0.0.0.0"

  # Listen port
  port: 8443

  # Protocol
  protocol: "a2a"

# Observability configuration
observability:
  # Metrics
  metrics:
    enabled: true
    port: 9090

  # Tracing
  tracing:
    enabled: true
    exporter: "otlp"
    endpoint: "http://otel-collector:4317"

  # Logging
  logging:
    level: "INFO"
    format: "json"

# Service configuration
service:
  # Service type
  type: ClusterIP

  # HTTPS port
  port: 8443

  # Metrics port
  metricsPort: 9090

  # Annotations
  annotations: {}

# Ingress configuration
ingress:
  # Enable ingress
  enabled: false

  # Ingress class
  className: "nginx"

  # Annotations
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

  # Hosts
  hosts:
    - host: my-agent.example.com
      paths:
        - path: /
          pathType: Prefix

  # TLS
  tls:
    - secretName: my-agent-tls
      hosts:
        - my-agent.example.com

# Resource limits and requests
resources:
  requests:
    cpu: 500m
    memory: 512Mi
  limits:
    cpu: 2000m
    memory: 2Gi

# Autoscaling
autoscaling:
  # Enable HPA
  enabled: true

  # Minimum replicas
  minReplicas: 2

  # Maximum replicas
  maxReplicas: 10

  # Target CPU utilization
  targetCPUUtilizationPercentage: 70

  # Target memory utilization
  targetMemoryUtilizationPercentage: 80

# Pod disruption budget
podDisruptionBudget:
  # Enable PDB
  enabled: true

  # Minimum available pods
  minAvailable: 1

# Node selector
nodeSelector: {}

# Tolerations
tolerations: []

# Affinity rules
affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchLabels:
              app.kubernetes.io/name: agentweave
          topologyKey: kubernetes.io/hostname

# Network policy
networkPolicy:
  # Enable network policy
  enabled: true

  # Ingress rules
  ingress:
    # Allow from same namespace
    - from:
        - namespaceSelector:
            matchLabels:
              name: ""

  # Egress rules
  egress:
    # Allow to SPIRE
    - to:
        - namespaceSelector:
            matchLabels:
              name: spire-system
      ports:
        - protocol: TCP
          port: 8081
    # Allow to OPA
    - to:
        - podSelector:
            matchLabels:
              app: opa
      ports:
        - protocol: TCP
          port: 8181
    # Allow DNS
    - to:
        - namespaceSelector: {}
          podSelector:
            matchLabels:
              k8s-app: kube-dns
      ports:
        - protocol: UDP
          port: 53

# Extra environment variables
extraEnv: []

# Extra volumes
extraVolumes: []

# Extra volume mounts
extraVolumeMounts: []

# Config overrides
configOverrides: {}

Installing the Chart

Basic Installation

Install with default values:

1
2
3

helm install my-agent agentweave/agentweave \
  --namespace agentweave \
  --create-namespace

Custom values.yaml

Create a custom values.yaml:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# my-values.yaml
agent:
  name: "search-agent"
  trustDomain: "company.com"
  capabilities:
    - name: "search"
      description: "Search documents"

replicaCount: 5

resources:
  requests:
    cpu: 1000m
    memory: 1Gi
  limits:
    cpu: 4000m
    memory: 4Gi

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 20

Install with custom values:

1
2
3
4

helm install search-agent agentweave/agentweave \
  --namespace agentweave \
  --create-namespace \
  --values my-values.yaml

Command-Line Overrides

Override specific values via command line:

1
2
3
4
5
6
7
8

helm install my-agent agentweave/agentweave \
  --namespace agentweave \
  --create-namespace \
  --set agent.name=my-agent \
  --set agent.trustDomain=example.com \
  --set replicaCount=5 \
  --set resources.requests.cpu=1000m \
  --set resources.requests.memory=1Gi

Common Configurations

Configuration 1: Single Agent (Development)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# dev-values.yaml
agent:
  name: "dev-agent"
  trustDomain: "dev.local"

replicaCount: 1

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

autoscaling:
  enabled: false

podDisruptionBudget:
  enabled: false

observability:
  logging:
    level: "DEBUG"

Deploy:

1
2
3

helm install dev-agent agentweave/agentweave \
  -f dev-values.yaml \
  -n dev

Configuration 2: Production Multi-Agent

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

# prod-values.yaml
agent:
  name: "prod-agent"
  trustDomain: "company.com"

replicaCount: 3

resources:
  requests:
    cpu: 1000m
    memory: 1Gi
  limits:
    cpu: 4000m
    memory: 4Gi

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 20
  targetCPUUtilizationPercentage: 70

podDisruptionBudget:
  enabled: true
  minAvailable: 2

affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchLabels:
            app.kubernetes.io/name: agentweave
        topologyKey: kubernetes.io/hostname

observability:
  logging:
    level: "INFO"
  tracing:
    enabled: true
    endpoint: "http://jaeger-collector:4317"

Deploy:

1
2
3

helm install prod-agent agentweave/agentweave \
  -f prod-values.yaml \
  -n production

Configuration 3: With SPIRE Stack

Install complete SPIRE + Agent stack:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# spire-stack-values.yaml
# Install SPIRE dependencies
spire:
  enabled: true
  server:
    enabled: true
    trustDomain: "company.com"
  agent:
    enabled: true
    daemonset: true

# Agent configuration
agent:
  name: "my-agent"
  trustDomain: "company.com"

spiffe:
  enabled: true
  registration:
    create: true

Deploy:

1
2
3

helm install agentweave-stack agentweave/agentweave-stack \
  -f spire-stack-values.yaml \
  -n agentweave

Configuration 4: With OPA Sidecar

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# opa-sidecar-values.yaml
agent:
  name: "secure-agent"
  trustDomain: "company.com"

authorization:
  provider: "opa"
  sidecar:
    enabled: true
    policies:
      authz.rego: |
        package agentweave.authz

        import rego.v1

        default allow := false

        allow if {
            input.caller_spiffe_id == "spiffe://company.com/agent/orchestrator"
            input.action in ["search", "process"]
        }

Deploy:

1
2
3

helm install secure-agent agentweave/agentweave \
  -f opa-sidecar-values.yaml \
  -n agentweave

Managing Releases

Viewing Releases

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# List all releases
helm list -A

# List releases in specific namespace
helm list -n agentweave

# Get release status
helm status my-agent -n agentweave

# Get release values
helm get values my-agent -n agentweave

# Get all release information
helm get all my-agent -n agentweave

Upgrading Releases

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# Upgrade with new values
helm upgrade my-agent agentweave/agentweave \
  -f new-values.yaml \
  -n agentweave

# Upgrade to specific chart version
helm upgrade my-agent agentweave/agentweave \
  --version 1.1.0 \
  -n agentweave

# Upgrade with reuse of existing values
helm upgrade my-agent agentweave/agentweave \
  --reuse-values \
  --set image.tag=1.1.0 \
  -n agentweave

# Dry-run upgrade
helm upgrade my-agent agentweave/agentweave \
  -f new-values.yaml \
  --dry-run \
  -n agentweave

Rollback Procedures

1
2
3
4
5
6
7
8
9
10
11

# View release history
helm history my-agent -n agentweave

# Rollback to previous revision
helm rollback my-agent -n agentweave

# Rollback to specific revision
helm rollback my-agent 3 -n agentweave

# Dry-run rollback
helm rollback my-agent 3 --dry-run -n agentweave

Uninstalling Releases

1
2
3
4
5
6
7
8
9

# Uninstall release
helm uninstall my-agent -n agentweave

# Keep history
helm uninstall my-agent -n agentweave --keep-history

# Delete namespace too
helm uninstall my-agent -n agentweave
kubectl delete namespace agentweave

Customizing Templates

Adding Custom Annotations

1
2
3
4
5
6
7
8

# values.yaml
podAnnotations:
  custom.io/annotation: "value"
  prometheus.io/scrape: "true"

deployment:
  annotations:
    deployment.custom.io/annotation: "value"

Adding Sidecars

1
2
3
4
5
6
7
8
9
10
11

# values.yaml
sidecars:
  - name: log-forwarder
    image: fluent/fluent-bit:latest
    volumeMounts:
      - name: logs
        mountPath: /var/log

extraVolumes:
  - name: logs
    emptyDir: {}

Custom Init Containers

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# values.yaml
initContainers:
  - name: wait-for-spire
    image: busybox:latest
    command:
      - sh
      - -c
      - |
        until [ -S /run/spire/sockets/agent.sock ]; do
          echo "Waiting for SPIRE socket..."
          sleep 1
        done
    volumeMounts:
      - name: spire-agent-socket
        mountPath: /run/spire/sockets
        readOnly: true

Testing Chart Changes

Linting

1
2
3
4
5

# Lint chart
helm lint agentweave/

# Lint with custom values
helm lint agentweave/ -f my-values.yaml

Template Rendering

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Render templates
helm template my-agent agentweave/agentweave \
  -f my-values.yaml \
  -n agentweave

# Render specific template
helm template my-agent agentweave/agentweave \
  -s templates/deployment.yaml \
  -f my-values.yaml

# Debug template rendering
helm template my-agent agentweave/agentweave \
  -f my-values.yaml \
  --debug

Dry-Run Installation

1
2
3
4
5
6
7
8
9
10
11

# Dry-run install
helm install my-agent agentweave/agentweave \
  -f my-values.yaml \
  -n agentweave \
  --dry-run \
  --debug

# Diff against running release (requires helm-diff plugin)
helm diff upgrade my-agent agentweave/agentweave \
  -f new-values.yaml \
  -n agentweave

Chart Development

Creating Custom Chart

1
2
3
4
5
6

# Create new chart based on AgentWeave
helm create my-custom-agent

# Or fork the official chart
git clone https://github.com/aj-geddes/helm-charts.git
cd helm-charts/charts/agentweave

Testing Locally

1
2
3
4
5
6
7
8
9
10
11

# Install from local directory
helm install my-agent ./agentweave \
  -f values.yaml \
  -n agentweave

# Package chart
helm package agentweave/

# Install from package
helm install my-agent agentweave-1.0.0.tgz \
  -n agentweave

Chart Dependencies

1
2
3
4
5
6
7
8
9
10

# Chart.yaml
dependencies:
  - name: spire
    version: "1.9.0"
    repository: "https://charts.agentweave.io"
    condition: spire.enabled
  - name: opa
    version: "0.62.0"
    repository: "https://charts.agentweave.io"
    condition: opa.enabled

Update dependencies:

1
2

helm dependency update agentweave/
helm dependency list agentweave/

Troubleshooting

Chart Installation Fails

1
2
3
4
5
6
7
8

# Check chart validity
helm lint agentweave/ -f values.yaml

# Render templates to check for errors
helm template my-agent agentweave/agentweave -f values.yaml --debug

# Check Kubernetes events
kubectl get events -n agentweave --sort-by='.lastTimestamp'

Values Not Being Applied

1
2
3
4
5
6
7
8
9
10
11

# Verify applied values
helm get values my-agent -n agentweave

# Compare with all values (including defaults)
helm get values my-agent -n agentweave --all

# Re-apply with debug
helm upgrade my-agent agentweave/agentweave \
  -f values.yaml \
  --debug \
  -n agentweave

Template Rendering Issues

1
2
3
4
5
6
7
8
9

# Render specific template
helm template my-agent agentweave/agentweave \
  -s templates/deployment.yaml \
  --debug

# Check for syntax errors in values
helm template my-agent agentweave/agentweave \
  -f values.yaml \
  --validate

Best Practices

Version Pinning

Always pin chart versions in production:

1
2
3
4
5
6
7

# Install specific version
helm install my-agent agentweave/agentweave \
  --version 1.0.0 \
  -n agentweave

# Lock versions in requirements
helm dependency update --skip-refresh

Values Organization

Organize values by environment:

1
2
3
4
5

values/
├── values.yaml          # Common values
├── dev-values.yaml      # Development overrides
├── staging-values.yaml  # Staging overrides
└── prod-values.yaml     # Production overrides

Deploy with merged values:

1
2
3
4

helm install my-agent agentweave/agentweave \
  -f values/values.yaml \
  -f values/prod-values.yaml \
  -n production

Secrets Management

Never commit secrets to values files:

1
2
3
4
5
6
7
8
9
10
11

# Use sealed-secrets
kubectl create secret generic my-agent-secrets \
  --from-literal=api-key=secret-value \
  -n agentweave

# Or use external secrets operator
# Reference in values.yaml
externalSecrets:
  enabled: true
  backend: aws-secrets-manager
  secretName: my-agent-secrets

Next Steps

Related Documentation: