> ## Documentation Index
> Fetch the complete documentation index at: https://developer.onetrust.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes Deployment

AI Guard is deployed as a Kubernetes pod within the OneTrust Workernode namespace alongside existing Data Discovery services. This guide covers the Helm integration, configuration, and operational considerations.

## Prerequisites

* A running OneTrust Workernode Kubernetes cluster
* TLS certificates (PEM format) for the AI Guard service
* Network connectivity to the OneTrust tenant for token validation
* The AI Guard Docker image available in your container registry

## Helm Integration

The AI Guard installer uses the existing OneTrust on-prem installer framework (`ot-onprem-installer-v2`). Follow the pattern established by other Workernode services.

### 1. Define Environment Variables

Add AI Guard environment variables to `data-discovery/shared/utils/all_envs.yaml` with appropriate defaults:

* `AI_GUARD_SERVICE_PORT`
* `OT_SERVICE_BASE_URL`
* `JOB_EXECUTOR_BASE_URL`
* `DATADISCOVERY_ONPREM_AGENT_URI`
* `TLS_KEY_PATH`
* `CERTIFICATE_PATH`
* `RUST_LOG`

### 2. Create a ConfigMap

Map Helm `.Values` to the environment variables:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: ai-guard-config
  namespace: {{ .Values.OT_NAMESPACE_DD }}
  labels:
    app: ai-guard
data:
  AI_GUARD_SERVICE_PORT: "{{ .Values.AI_GUARD_SERVICE_PORT }}"
  OT_SERVICE_BASE_URL: "{{ .Values.OT_SERVICE_BASE_URL }}"
  JOB_EXECUTOR_BASE_URL: "{{ .Values.JOB_EXECUTOR_BASE_URL }}"
  DATADISCOVERY_ONPREM_AGENT_URI: "{{ .Values.DATADISCOVERY_ONPREM_AGENT_URI }}"
  TLS_KEY_PATH: "{{ .Values.TLS_KEY_PATH }}"
  CERTIFICATE_PATH: "{{ .Values.CERTIFICATE_PATH }}"
  RUST_LOG: "{{ .Values.RUST_LOG }}"
```

### 3. Create a Deployment

Create a Deployment template for the `ai-guard` pod, referencing the ConfigMap and mounting TLS secrets:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ai-guard
  namespace: {{ .Values.OT_NAMESPACE_DD }}
spec:
  replicas: 1
  selector:
    matchLabels:
      app: ai-guard
  template:
    metadata:
      labels:
        app: ai-guard
    spec:
      containers:
        - name: ai-guard
          image: docker.onetrust.dev/ai-guard:latest
          ports:
            - containerPort: 4443
          envFrom:
            - configMapRef:
                name: ai-guard-config
          volumeMounts:
            - name: tls-certs
              mountPath: /etc/ssl/litenode
              readOnly: true
          livenessProbe:
            httpGet:
              path: /health
              port: 4443
              scheme: HTTPS
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /health
              port: 4443
              scheme: HTTPS
            initialDelaySeconds: 5
            periodSeconds: 10
      volumes:
        - name: tls-certs
          secret:
            secretName: ai-guard-tls
```

### 4. Create a Service

Expose port `4443` within the cluster and, if required, externally:

```yaml
apiVersion: v1
kind: Service
metadata:
  name: ai-guard
  namespace: {{ .Values.OT_NAMESPACE_DD }}
spec:
  selector:
    app: ai-guard
  ports:
    - port: 4443
      targetPort: 4443
      protocol: TCP
  type: ClusterIP  # Or LoadBalancer/NodePort for external access
```

## Configuration Reference

All configuration is managed through environment variables set via the ConfigMap. See [Service Configuration](https://developer.onetrust.com/onetrust/docs/ai-guard-service-configuration) for the full reference.

| Config Path                                 | Env Var                          | Default                                  | Description                   |
| ------------------------------------------- | -------------------------------- | ---------------------------------------- | ----------------------------- |
| `service.listen`                            | `AI_GUARD_SERVICE_PORT`          | `0.0.0.0:4443`                           | Listen address and port       |
| `service.authorization.validation-endpoint` | `OT_SERVICE_BASE_URL`            | —                                        | OneTrust token validation URL |
| `service.tls.key-path`                      | `TLS_KEY_PATH`                   | `/etc/ssl/litenode/tls.key`              | TLS private key               |
| `service.tls.certificate-path`              | `CERTIFICATE_PATH`               | `/etc/ssl/litenode/tls.crt`              | TLS certificate               |
| `classification.client.classifier-base-url` | `JOB_EXECUTOR_BASE_URL`          | `http://scan-job-manager:8080`           | Classification profiles URL   |
| `metrics.exporter.collector-endpoint`       | `DATADISCOVERY_ONPREM_AGENT_URI` | `http://datadiscovery-onprem-agent:8080` | Metrics endpoint              |
| `metrics.exporter.interval`                 | `METRICS_EXPORT_INTERVAL`        | `hour`                                   | Export interval               |
| —                                           | `RUST_LOG`                       | `info`                                   | Log verbosity                 |

## Observability

### Logging

AI Guard emits structured JSON logs in [Elastic Common Schema (ECS)](https://www.elastic.co/guide/en/ecs/current/index.html) format to stdout. Logs fall into three categories:

| Category      | Description                                 | Examples                                                 |
| ------------- | ------------------------------------------- | -------------------------------------------------------- |
| **Lifecycle** | Startup, shutdown, and configuration events | `server not configured for TLS`, `server shutdown clean` |
| **Request**   | HTTP request/response logging               | Method, path, status, latency in ms                      |
| **Error**     | Fatal errors causing process exit           | Missing config, TLS failures, crypto provider errors     |

Log severity is based on response status: INFO for 2xx/3xx, WARN for 4xx, ERROR for 5xx.

### Graceful Shutdown

On SIGTERM or SIGINT:

1. The signal name is logged
2. The HTTP server stops accepting new connections
3. The metrics exporter is flushed and shut down
4. The process exits with code 0

## What's Next?

* [Networking Requirements](https://developer.onetrust.com/onetrust/docs/ai-guard-networking) — Required network connectivity for Kubernetes
* [Service Configuration](https://developer.onetrust.com/onetrust/docs/ai-guard-service-configuration) — Full configuration reference
* [Troubleshooting](https://developer.onetrust.com/onetrust/docs/ai-guard-troubleshooting) — Common deployment issues