# AGENTS.md — Machine-readable deployment instructions for AI agents

## YOUR TASK

Deploy `shared-sqs` to a Kubernetes cluster using the Helm chart in `./deploy/`.

---

## STEP 1 — COLLECT REQUIRED INFORMATION FROM USER

Ask the user for ALL of the following before doing anything else.
Do NOT proceed if any required value is missing.

### Required

| Variable | Description | Example |
|----------|-------------|---------|
| `REDIS_ADDR` | Redis address, format `host:port` | `redis.default.svc.cluster.local:6379` |
| `REDIS_PASSWORD` | Redis password | `mysecretpassword` |
| `ADMIN_TOKEN` | Admin API token, any random string | output of `openssl rand -hex 20` |
| `INGRESS_HOST` | Domain pointing to cluster ingress IP | `sqs.example.com` |

### Optional

| Variable | Default | Description |
|----------|---------|-------------|
| `REDIS_USER` | `default` | Redis username, change only if using Redis ACL |
| `NAMESPACE` | `shared-sqs` | Kubernetes namespace |
| `IMAGE_TAG` | `v0.1.24` | Service image version |
| `SEED_DEMO` | `true` | Create demo tenant on first start |
| `BILLING_ENABLED` | `false` | Enable billing to PostgreSQL |
| `PG_HOST` | — | Required only if BILLING_ENABLED=true |
| `PG_PORT` | `5432` | Required only if BILLING_ENABLED=true |
| `PG_DATABASE` | — | Required only if BILLING_ENABLED=true |
| `PG_USER` | — | Required only if BILLING_ENABLED=true |
| `PG_PASSWORD` | — | Required only if BILLING_ENABLED=true |
| `PG_SSLMODE` | `require` | Required only if BILLING_ENABLED=true |

---

## STEP 2 — CLONE REPOSITORY

```bash
git clone https://gitea.services.ngcloud.ru/Nail/shared-SQS.git
cd shared-SQS
```

---

## STEP 3 — EDIT deploy/values.yaml

Replace placeholder values with values collected in Step 1.

Mandatory substitutions:
- `your-redis-host:6379` → value of `REDIS_ADDR`
- `your-redis-password` → value of `REDIS_PASSWORD`
- `your-admin-token` → value of `ADMIN_TOKEN`
- `sqs.your-domain.com` → value of `INGRESS_HOST`

If `BILLING_ENABLED=true`, also set `billing.enabled: true` and fill all `billing.postgres.*` fields.

---

## STEP 4 — DEPLOY

```bash
helm install shared-sqs ./deploy -n shared-sqs --create-namespace
```

Expected output must contain:
```
STATUS: deployed
```

If output contains `Error:` — stop and report the error to the user.

---

## STEP 5 — WAIT FOR POD READY

```bash
kubectl rollout status deployment/shared-sqs -n shared-sqs --timeout=90s
```

Expected output:
```
deployment "shared-sqs" successfully rolled out
```

If timeout or error — run `kubectl describe pod -n shared-sqs` and report to user.

---

## STEP 6 — VERIFY SERVICE IS RESPONDING

```bash
curl -s https://<INGRESS_HOST>/health
```

Expected output:
```
OK
```

If response is not `OK` — check pod logs:
```bash
kubectl logs -n shared-sqs deployment/shared-sqs --tail=50
```
Report logs to user.

---

## STEP 7 — CREATE FIRST TENANT

```bash
curl -s -X POST https://<INGRESS_HOST>/admin/tenants \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-tenant"}'
```

Expected response contains `access_key` and `secret_key`:
```json
{
  "id": "t-...",
  "name": "my-tenant",
  "access_key": "SSAK-...",
  "secret_key": "...",
  ...
}
```

**Save `secret_key` — it is shown only once.**

If response contains `"error"` — report the full response to user.

---

## STEP 8 — VERIFY SQS WORKS

```bash
export AWS_ACCESS_KEY_ID="<access_key from step 7>"
export AWS_SECRET_ACCESS_KEY="<secret_key from step 7>"
export AWS_DEFAULT_REGION="us-east-1"
ENDPOINT="--endpoint-url https://<INGRESS_HOST>"

aws sqs create-queue --queue-name test-queue $ENDPOINT
```

Expected output contains `QueueUrl`.

---

## SUCCESS CRITERIA

Deployment is complete and correct when ALL of the following are true:

- [ ] `curl /health` returns `OK`
- [ ] Tenant created, `access_key` and `secret_key` received
- [ ] `aws sqs create-queue` returns a `QueueUrl`

---

## KNOWN ISSUES

| Problem | Cause | Fix |
|---------|-------|-----|
| Pod stuck in `Pending` | Not enough cluster resources | Check `kubectl describe pod` for resource limits |
| Pod in `CrashLoopBackOff` | Wrong Redis address or password | Check `kubectl logs`, fix `redis.addr` / `redis.password` in values.yaml, then `helm upgrade` |
| `curl /health` times out | DNS not pointing to ingress IP | Ask user to check DNS A-record for `INGRESS_HOST` |
| Admin API returns 401 | Wrong `ADMIN_TOKEN` | Token in `Authorization: Bearer` must match `admin.token` in values.yaml |

---

## UPGRADE

```bash
helm upgrade shared-sqs ./deploy -n shared-sqs
```

## UNINSTALL

```bash
helm uninstall shared-sqs -n shared-sqs
kubectl delete namespace shared-sqs
```