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

# Install Tyk AI Studio on Kubernetes

> Installation guide for the Tyk AI Studio on Kubernetes

## Availability

| Edition | Deployment Type |
| :- | :- |
| [Enterprise](https://tyk.io/docs/ai-management/ai-studio/overview.md#enterprise-edition) | Self-Managed |

> [!NOTE]
>
> This guide focuses on the Enterprise Edition of Tyk AI Studio. For the Community Edition, please refer to the [Tyk AI Studio GitHub repository](https://github.com/TykTechnologies/ai-studio/blob/main/docs/site/docs/deployment-helm-k8s.md). The Community Edition uses different Docker images (`tykio/tyk-ai-studio` and `tykio/tyk-microgateway`) and does not require a license key.

This guide explains how to deploy Tyk AI Studio (control plane), an Edge Gateway (data plane), and PostgreSQL on Kubernetes using Helm. AI Studio manages configuration centrally and the Edge Gateway processes AI requests, receiving configuration via gRPC.

> [!NOTE]
>
> The Helm chart uses the older name `microgateway` for the Edge Gateway component. Examples are the `microgateway:` values block and the `tykio/tyk-microgateway-ent` image. This guide uses "Edge Gateway" in prose for the same component.

## Prerequisites

* Kubernetes 1.16+
* Helm 3.0+
* `kubectl` configured with access to your cluster
* A Tyk AI License key (contact [support@tyk.io](mailto:support@tyk.io) or your account manager to obtain)
* For production with TLS: cert-manager installed in your cluster

> [!NOTE]
>
> Running on Podman, containerd, or another container runtime? See [Container Runtimes](https://tyk.io/docs/deployment-and-operations/container-runtimes.md).

## Generate Secrets

Before installing, generate three secret keys to secure communication and encrypt data:

```bash expandable theme={null}
# Secret key for encryption (used for secrets management and SSO)
openssl rand -hex 16
# Example output: a35b3f7b0fb4dd3a048ba4fc6e9fe0a8

# Encryption key for Edge Gateway communication (must be exactly 32 hex chars)
openssl rand -hex 16
# Example output: 822d3d1e0e2d849263e45fc7bb842364

# gRPC auth token (for hub-spoke communication)
openssl rand -hex 16
# Example output: 9f2c4a6b8d0e1f3a5c7d9e1b3a5c7d9e
```

Save these values — you will substitute them into the values file below.

***

## Option 1: Testing / Quickstart

For local development or test clusters. Uses NodePort services, internal PostgreSQL, and no ingress.

### 1. Add the Helm Chart

The Helm chart is in the [Tyk AI Studio GitHub repository](https://github.com/TykTechnologies/ai-studio).

```bash theme={null}
git clone https://github.com/TykTechnologies/ai-studio.git
cd ai-studio/helm
helm dependency update .
```

### 2. Create `values-testing.yaml`

Replace the placeholder secrets with your generated values. The `grpcAuthToken` / `edgeAuthToken` and `microgatewayEncryptionKey` / `encryptionKey` pairs **must match**.

```yaml Expandable expandable theme={null}
midsommar:
  image:
    repository: tykio/tyk-ai-studio-ent
    tag: v2.2.2
  service:
    type: NodePort
    ports:
      - name: http
        port: 8080
        targetPort: 8080
        nodePort: 32580
      - name: gateway
        port: 9090
        targetPort: 9090
        nodePort: 32590
      - name: grpc
        port: 50051
        targetPort: 50051

config:
  allowRegistrations: "true"
  siteUrl: "http://localhost:32580"                       # Update post-install if not localhost
  fromEmail: "noreply@localhost"
  devMode: "true"                                       # Required for login over plain HTTP
  databaseType: "postgres"
  tykAiSecretKey: "CHANGE-ME-first-secret"
  tykAiLicense: "your-license-key"
  ociCacheDir: "./data/cache/plugins"
  ociRequireSignature: "false"
  gatewayMode: "control"
  grpcPort: "50051"
  grpcHost: "0.0.0.0"
  grpcTlsInsecure: "true"
  grpcAuthToken: "CHANGE-ME-third-secret"
  microgatewayEncryptionKey: "CHANGE-ME-second-secret"
  # proxyUrl auto-resolves to the Edge Gateway k8s service — no need to set it

database:
  internal: true
  user: "tyk"
  password: "your-db-password"
  name: "tyk_ai_studio"

postgres:
  persistence:
    enabled: true
    size: 1Gi

microgateway:
  enabled: true
  image:
    repository: tykio/tyk-microgateway-ent
    tag: v2.2.2
  service:
    type: NodePort
    port: 8080
    nodePort: 32591
  config:
    edgeNamespace: "default"
  secrets:
    edgeAuthToken: "CHANGE-ME-third-secret"             # Must match config.grpcAuthToken
    encryptionKey: "CHANGE-ME-second-secret"             # Must match config.microgatewayEncryptionKey
    tykAiLicense: "your-license-key"
```

### 3. Install

```bash theme={null}
helm install midsommar . -f values-testing.yaml
```

### 4. Set External Gateway URL

The Edge Gateway's internal service URL is used for routing by default, but the AI Portal needs to display the correct external URL for tools and datasources. After install, patch the config with your cluster's node IP:

```bash theme={null}
# Get the node IP and set the gateway URL
NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')
GATEWAY_URL="http://${NODE_IP}:32591"

# Patch the configmap with correct URLs and restart AI Studio
STUDIO_URL="http://${NODE_IP}:32580"
kubectl patch configmap midsommar-config -p \
  "{\"data\":{\"SITE_URL\":\"${STUDIO_URL}\",\"TOOL_DISPLAY_URL\":\"${GATEWAY_URL}\",\"DATASOURCE_DISPLAY_URL\":\"${GATEWAY_URL}\"}}"
kubectl rollout restart deployment midsommar
```

> [!NOTE]
>
> **Tip:** If you know your cluster's external IP or hostname upfront, you can skip this step by setting `config.toolDisplayUrl` and `config.datasourceDisplayUrl` in your values file instead.

### 5. Verify

```bash theme={null}
# Check all pods are running
kubectl get pods

# Check AI Studio health (via NodePort)
curl -s http://${NODE_IP}:32580/health

# Check Edge Gateway health (via NodePort)
curl -s http://${NODE_IP}:32591/health
```

> [!NOTE]
>
> If you cannot reach the node IP from your machine (for example, with kind or Docker Desktop on macOS), use `kubectl port-forward` instead:
>
> ```bash theme={null}
> kubectl port-forward svc/midsommar 8080:8080
> ```
>
> Then open `http://localhost:8080`. In step 4, set `SITE_URL` to `http://localhost:8080`.

### Access Points

| Port | URL | Purpose |
| - | - | - |
| 32580 | `http://<node-ip>:32580` | AI Studio UI + REST API |
| 32590 | `http://<node-ip>:32590` | Embedded AI Gateway |
| 32591 | `http://<node-ip>:32591` | Edge Gateway |

***

## Option 2: Production with TLS

For production deployments with Ingress, TLS via cert-manager, and an external database.

### 1. Create `values-production.yaml`

Replace all placeholder values with your actual configuration.

```yaml Expandable expandable theme={null}
midsommar:
  image:
    repository: tykio/tyk-ai-studio-ent
    tag: v2.2.2
  ingress:
    enabled: true
    certificateEnabled: true
    className: nginx
    certManager:
      issuer: letsencrypt-prod
    hosts:
      - host: studio.yourdomain.com
        paths:
          - path: /
            pathType: Prefix
            port: 8080
    tls:
      - secretName: studio-tls-secret
        hosts:
          - studio.yourdomain.com
  service:
    ports:
      - name: http
        port: 8080
        targetPort: 8080
      - name: gateway
        port: 9090
        targetPort: 9090
      - name: grpc
        port: 50051
        targetPort: 50051

config:
  allowRegistrations: "true"
  siteUrl: "https://studio.yourdomain.com"
  fromEmail: "noreply@yourdomain.com"
  devMode: "false"
  databaseType: "postgres"
  tykAiSecretKey: "CHANGE-ME-first-secret"
  tykAiLicense: "your-license-key"
  ociCacheDir: "./data/cache/plugins"
  ociRequireSignature: "false"
  gatewayMode: "control"
  grpcPort: "50051"
  grpcHost: "0.0.0.0"
  grpcTlsInsecure: "true"                               # Set to "false" with TLS certs
  grpcAuthToken: "CHANGE-ME-third-secret"
  microgatewayEncryptionKey: "CHANGE-ME-second-secret"
  # proxyUrl, toolDisplayUrl, datasourceDisplayUrl auto-resolve from Edge Gateway ingress config

database:
  internal: false
  url: "postgres://user:password@your-db-host:5432/tyk_ai_studio?sslmode=require"

microgateway:
  enabled: true
  image:
    repository: tykio/tyk-microgateway-ent
    tag: v2.2.2
  ingress:
    enabled: true
    certificateEnabled: true
    className: nginx
    certManager:
      issuer: letsencrypt-prod
    hosts:
      - host: gateway.yourdomain.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: gateway-tls-secret
        hosts:
          - gateway.yourdomain.com
  config:
    edgeNamespace: "default"
    allowInsecure: "false"
    tlsEnabled: "false"                                  # gRPC client TLS to AI Studio
  secrets:
    edgeAuthToken: "CHANGE-ME-third-secret"
    encryptionKey: "CHANGE-ME-second-secret"
    tykAiLicense: "your-license-key"
```

### 2. Install

Run these commands from the `ai-studio/helm` directory. To get the chart, follow [step 1 of Option 1](#1-add-the-helm-chart).

```bash theme={null}
helm dependency update .
helm install midsommar . -f values-production.yaml
```

### 3. Verify

```bash theme={null}
kubectl get pods
kubectl get ingress
curl -s https://studio.yourdomain.com/health
curl -s https://gateway.yourdomain.com/health
```

***

## After Deployment

### First User Registration

After you start the services, create the first user:

1. Open your configured `siteUrl` (for example, `https://studio.yourdomain.com`) in your browser.
2. Select **Sign up**, then enter a name, an email address, and a password.
3. Log in with the new account.

> [!NOTE]
>
> The first user who registers becomes the administrator. You can use any email address. Other users must verify their email address before they can log in, so configure SMTP before you invite them. AI Studio ignores the deprecated `ADMIN_EMAIL` variable.

### Add Your API Keys

AI Studio pre-populates OpenAI and Anthropic LLM configurations on first startup with placeholder secrets (`OPENAI_KEY` and `ANTHROPIC_KEY`). To start using them:

1. Open AI Studio at the `siteUrl` you configured and log in with your admin account
2. Navigate to **Settings → Secrets** in the sidebar
3. Click on **`OPENAI_KEY`** and edit it to add your OpenAI API key
4. Click on **`ANTHROPIC_KEY`** and edit it to add your Anthropic API key

### Push Configuration to the Edge Gateway

1. Navigate to **AI Portal → Edge Gateways** in the sidebar
2. Verify that your Edge Gateway shows as **Connected**. Its Edge ID is the pod name, for example `midsommar-microgateway-64b5f9879d-mf5p2`.
3. Click **Push Configuration** to sync the latest settings to the Edge Gateway

Once the sync status shows **Synced**, the Edge Gateway is ready to proxy LLM requests.

For further setup (additional LLMs, users, applications), see the **[Initial Configuration](https://tyk.io/docs/ai-management/ai-studio/configuration.md)** guide.

***

## Shared Secrets Reference

These values **must match** between AI Studio and Edge Gateway configuration:

| AI Studio Config | Edge Gateway Config | Purpose |
| - | - | - |
| `config.grpcAuthToken` | `microgateway.secrets.edgeAuthToken` | Authenticates the gRPC connection |
| `config.microgatewayEncryptionKey` | `microgateway.secrets.encryptionKey` | Encrypts synced configuration data |
| `config.tykAiLicense` | `microgateway.secrets.tykAiLicense` | Enterprise license |

## Port Reference

| Port | Component | Purpose |
| - | - | - |
| 8080 | AI Studio | Admin UI + REST API |
| 9090 | AI Studio | Embedded AI Gateway |
| 50051 | AI Studio | gRPC control server (internal) |
| 8080 | Edge Gateway | Edge AI Gateway |
| 5432 | PostgreSQL | Database |

***

## Advanced Configuration

### Message Queue (NATS)

For distributed deployments with message persistence, add NATS configuration to your values file:

```yaml theme={null}
config:
  queueType: "nats"
  natsUrl: "nats://nats-server:4222"
  natsStorageType: "file"
  natsRetentionPolicy: "interest"
  natsMaxAge: "4h"
  natsTlsEnabled: true
  natsCredentialsFile: "/etc/nats/user.creds"
```

### Optional Components

#### Reranker Service

Improves RAG result relevance:

```yaml theme={null}
reranker:
  enabled: true
  image:
    repository: tykio/reranker_cpu
    tag: latest
  resources:
    requests:
      cpu: 500m
      memory: 1Gi
```

#### Transformer Server

Handles embedding generation:

```yaml theme={null}
transformer-server:
  enabled: true
  image:
    repository: tykio/transformer_server_cpu
    tag: latest
  resources:
    requests:
      cpu: 500m
      memory: 1Gi
```

### Scaling Edge Gateways

Each Edge Gateway pod registers with AI Studio under its own pod name as its Edge ID. To deploy Edge Gateways for different regions, deploy a separate Helm release for each region and set a different `edgeNamespace`:

```yaml theme={null}
microgateway:
  config:
    edgeNamespace: "eu-west"
```

Each Edge Gateway receives only the configuration assigned to its namespace.

> [!NOTE]
>
> A Deployment gives each pod a new name after a restart, and AI Studio removes the stale entries. For stable Edge IDs (for example, `midsommar-microgateway-0`), set `microgateway.kind: StatefulSet`.

### Database Options

**Internal PostgreSQL** (testing/small deployments):

```yaml expandable theme={null}
database:
  internal: true
  user: "tyk"
  password: "secure-password"
  name: "tyk_ai_studio"

postgres:
  persistence:
    enabled: true
    size: 10Gi
    storageClass: "standard"
```

**External Database** (production):

```yaml theme={null}
database:
  internal: false
  url: "postgres://user:password@your-db-host:5432/tyk_ai_studio?sslmode=require"
```

***

## Maintenance

### Upgrading

```bash theme={null}
helm upgrade midsommar . -f your-values.yaml
```

From v2.2.1, the AI Studio Deployment uses the `Recreate` strategy (`midsommar.strategy`). Kubernetes stops the old AI Studio pod before it starts the new one, so two AI Studio instances never run at the same time. During an upgrade, AI Studio is not available for a short time. Edge Gateways continue to serve traffic.

### Uninstalling

```bash theme={null}
helm uninstall midsommar
```

### Viewing Logs

```bash theme={null}
# AI Studio logs
kubectl logs -l app.kubernetes.io/name=midsommar

# Edge Gateway logs
kubectl logs -l app=microgateway

# Database logs (internal postgres)
kubectl logs -l app=postgres
```

## Troubleshooting

> [accordion] Check pod and ingress status
>
> ```bash theme={null}
> kubectl get pods
> kubectl get ingress
> kubectl describe pod <pod-name>
> ```

> [accordion] Common Issues
>
> * **Database connection failures**: Check credentials and network access
> * **Ingress not working**: Verify DNS records and TLS configuration
> * **Login fails on HTTP**: Set `devMode: "true"` — session cookies require this when not using HTTPS
> * **Marketplace page is empty**: Set `ociCacheDir: "./data/cache/plugins"` in your config values — the marketplace service will not start without it
> * **Plugin signature verification**: Docker images use distroless bases without cosign. Set `ociRequireSignature: "false"` to disable signature verification

> [accordion] Pods restart during the first install
>
> On the first install, the AI Studio pod can restart until PostgreSQL is ready. The Edge Gateway pod can restart until the AI Studio gRPC server is ready. These restarts are normal. The pods recover without action. Check that all pods show `Running` and `READY 1/1`:
>
> ```bash theme={null}
> kubectl get pods
> ```

> [accordion] Registration fails with an unexpected error
>
> In AI Studio v2.1.x, over plain HTTP, the CSRF check accepts browser requests only from `localhost:3000`. Registration from any other address fails with `403 Forbidden - origin invalid`. Upgrade to v2.2.0 or later. From v2.2.0, AI Studio also accepts requests from the host in `SITE_URL`.

> [accordion] Edge Gateway cannot connect to AI Studio
>
> * Verify the Edge Gateway pod logs:
>
> ```bash theme={null}
> kubectl logs -l app=microgateway
> ```
>
> * Check that `CONTROL_ENDPOINT` resolves to the AI Studio service (default: `midsommar:50051`)
> * Verify `edgeAuthToken` matches `grpcAuthToken` exactly
> * Verify `encryptionKey` matches `microgatewayEncryptionKey` exactly
> * Check that `GATEWAY_MODE=control` is set in AI Studio config