187 lines
4.6 KiB
Markdown
187 lines
4.6 KiB
Markdown
# 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
|
|
```
|