# Proxy on-prem Helm chart deployment

Use this Helm chart to deploy Espresso AI's Proxy Service into an existing Kubernetes cluster.

## Prerequisites

* Kubernetes cluster access (`kubectl` context points to the target cluster).
* An existing Kubernetes Secret containing `ESPRESSO_AI_API_KEY`.
* If using ingress, AWS Load Balancer Controller installed and an ACM certificate ARN.
* In the [Espresso AI dashboard](https://dashboard.espressocomputing.com/), go to `Proxy Onboarding` and:
  * Enter your AWS account ID so we can grant ECR access for the Proxy image.
  * Copy your customer name.
  * Generate an API key for Espresso API authentication.

## Required values

* `image.repository`
* `image.tag`
* `customer` (required, non-empty)
* `env.PROXY_HOST` (required, non-empty)
* `apiKeySecret.name` (must reference an existing Kubernetes Secret)
* API key secret key is fixed to `ESPRESSO_AI_API_KEY` and is not configurable.

Optional for ingress-based exposure:

* `ingress.enabled`
* `ingress.alb.certificateArn`

## Example values: existing VPC/EKS + secret + ALB

```yaml
customer: "value from Dashboard"

image:
  repository: 123456789012.dkr.ecr.us-east-1.amazonaws.com/proxy
  tag: "0.1-dev-bc733866794f8bc1d40395463ab8151bee52b8bbdc5d41768d02e4e0094b9da8"

env:
  PROXY_HOST: proxy.customer.example.com

apiKeySecret:
  name: espresso-api

service:
  type: ClusterIP
  port: 5050

ingress:
  enabled: true
  className: alb
  host: proxy.customer.example.com
  alb:
    certificateArn: arn:aws:acm:us-east-1:123456789012:certificate/11111111-2222-3333-4444-555555555555
    scheme: internet-facing
    annotations: {}

autoscaling:
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70
```

## Core configuration

### Image

| Field              | Description                               | Required | Default        |
| ------------------ | ----------------------------------------- | -------- | -------------- |
| `image.repository` | Container image repository for the proxy. | Yes      | None           |
| `image.tag`        | Container image tag.                      | Yes      | `latest`       |
| `image.pullPolicy` | Kubernetes image pull policy.             | No       | `IfNotPresent` |

### Environment

| Field                             | Description                                                                              | Required | Default                                     |
| --------------------------------- | ---------------------------------------------------------------------------------------- | -------- | ------------------------------------------- |
| `customer`                        | Customer identifier used by the proxy.                                                   | Yes      | None                                        |
| `env.PROXY_HOST`                  | Hostname injected as `PROXY_HOST`.                                                       | Yes      | None                                        |
| `apiUrl`                          | Base API URL used to derive runtime `API_URL` (`<apiUrl>/<customer>` unless overridden). | No       | `https://api.espressocomputing.com:25831`   |
| `env.API_URL`                     | Optional full override for `API_URL`.                                                    | No       | `<apiUrl>/<customer>`                       |
| `env.OTEL_EXPORTER_OTLP_ENDPOINT` | Optional telemetry OTLP endpoint override.                                               | No       | `https://metrics.espressocomputing.com:443` |

### API key secret

| Field                 | Description                                                    | Required             | Default |
| --------------------- | -------------------------------------------------------------- | -------------------- | ------- |
| `apiKeySecret.name`   | Existing Kubernetes Secret name that stores the proxy API key. | Yes                  | None    |
| `ESPRESSO_AI_API_KEY` | Fixed key the chart reads from the Kubernetes Secret.          | Yes (in Secret data) | Fixed   |

Create secret (example):

```bash
kubectl -n proxy create secret generic espresso-ai \
  --from-literal=ESPRESSO_AI_API_KEY='<api-key>'
```

### Ingress (ALB)

| Field                        | Description                             | Required                               | Default           |
| ---------------------------- | --------------------------------------- | -------------------------------------- | ----------------- |
| `ingress.enabled`            | Enable ALB-backed ingress.              | No                                     | `false`           |
| `ingress.alb.certificateArn` | ACM certificate ARN for HTTPS listener. | Conditional (`ingress.enabled = true`) | None              |
| `ingress.host`               | Optional host rule for ingress routing. | No                                     | None              |
| `ingress.alb.scheme`         | ALB scheme.                             | No                                     | `internet-facing` |

### Autoscaling

HPA is always enabled.

| Field                                        | Description                                          | Required | Default |
| -------------------------------------------- | ---------------------------------------------------- | -------- | ------- |
| `replicaCount`                               | Initial deployment replica count before HPA adjusts. | No       | `2`     |
| `autoscaling.minReplicas`                    | Minimum replicas for HPA.                            | No       | `2`     |
| `autoscaling.maxReplicas`                    | Maximum replicas for HPA.                            | No       | `10`    |
| `autoscaling.targetCPUUtilizationPercentage` | CPU utilization target for HPA scaling decisions.    | No       | `70`    |

## Managed secret note

This chart does not create AWS Secrets Manager or External Secrets resources by itself. For managed secret sync from AWS Secrets Manager, provision External Secrets separately and set:

* `apiKeySecret.name` to the Kubernetes Secret generated by External Secrets (key must be `ESPRESSO_AI_API_KEY`).

## How to deploy

Add/update chart repository:

```bash
helm repo add espresso-ai-proxy-chart https://espressocomputing.github.io/espresso-ai-proxy-chart
helm repo update
```

Install/upgrade:

```bash
helm upgrade --install proxy ./helm-charts/proxy \
  --namespace proxy \
  --create-namespace \
  -f values.yaml
```

## Validation checklist

* Pods are running: `kubectl -n proxy get pods`
* Service exists: `kubectl -n proxy get svc`
* HPA exists: `kubectl -n proxy get hpa`
* Ingress exists (if enabled): `kubectl -n proxy get ingress`
* App health endpoint responds on `/healthcheck`