shared-SQS/AGENTS.md

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

Quick Start for AI Agents

You are an AI agent tasked with deploying shared-sqs to a Kubernetes cluster.

Before proceeding, do the following:

1. Ask user for all required variables from STEP 1 below. Do NOT proceed if any is missing.
2. Check user's environment by running:

   kubectl version --client
   helm version
   

   If either command fails or returns an error — stop and inform the user that kubectl or helm are not installed.
3. Then proceed with STEP 2 and follow the steps sequentially.

---

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

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

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

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

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

Expected output:

OK

If response is not OK — check pod logs:

kubectl logs -n shared-sqs deployment/shared-sqs --tail=50

Report logs to user.

---

STEP 7 — CREATE FIRST TENANT

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:

{
  "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

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

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

UNINSTALL

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