feat(operator): oabctl ingress for Telegram/LINE (API Gateway + VPC Link + Cloud Map)

[chaodu-agent]

Summary

Adds an optional spec.ingress block to the oab.dev/v2 manifest so oabctl apply provisions inbound webhook ingress in one shot — the exact "Option 1" architecture (API Gateway HTTP API → VPC Link → Cloud Map → ECS task) documented in the Telegram/LINE-on-AWS reference architecture (#1274). This collapses the ~7 manual aws apigatewayv2 / servicediscovery / ecs commands from that doc into declarative manifest fields.

Motivation: #1274 recommends the API Gateway + VPC Link + Cloud Map path as the cheapest AWS-native ingress (~$5–10/mo), but blessing it as "recommended" while it requires 7 hand-run CLI steps — including a delete-and-recreate of the ECS service — is a lot of error-prone plumbing. oabctl already owns this layer (bootstrap + apply), so ingress is the missing piece.

What it does

With spec.ingress present (ECS runtime only), apply reconciles idempotently (all resources looked up/reused by name):

1. Cloud Map private DNS namespace + a per-service A record
2. ECS service registry wiring — attached at service creation
3. VPC Link (shared oab-vpc-link), waited until AVAILABLE
4. API Gateway HTTP API (oab-webhook) + HTTP_PROXY integration over the VPC Link
5. one route per path + a prod auto-deploy stage
6. a self-referencing security-group inbound rule on containerPort

Then it prints the stable webhook URL(s) to register with BotFather / the LINE console.

spec:
  # ... image / resources / configFrom / runtime.networking ...
  ingress:
    type: apigateway          # only supported type (default)
    cloudMapNamespace: oab    # reused across bots in the VPC (default: oab)
    containerPort: 8080       # default
    paths:
      - /webhook/telegram
      - /webhook/line

Backward compatibility

ingress is optional and defaults to absent. Existing outbound-only (Discord) deployments create no ingress resources and behave exactly as before. Covered by a unit test.

Notes / caveats (called out in code + README)

• Service registries are create-only. apply attaches the registry on create. For a pre-existing service without service discovery it provisions the ingress resources and prints how to recreate the service — it does not auto-delete anything.
• Transport is unauthenticated. The API Gateway endpoint is public; requests are authenticated at the app layer (LINE signature via LINE_CHANNEL_SECRET, Telegram token in the path). Documented explicitly.

Testing

Built on an M4 (macmini):

• cargo build — OK
• cargo clippy --all-targets -- -D warnings — clean
• cargo test — 7 passed (schema parse/defaults, validation failures, k8s rejection, backward-compat, fleet passthrough)
• schema/oabservice-v2.json — valid JSON; ingress added to serviceSpec / fleetTemplate / agentOverride

Live AWS reconciliation (real Cloud Map / VPC Link / API Gateway calls) has not been exercised end-to-end yet — the SDK call shapes compile and follow the refarch, but a real apply against an account is the recommended next validation step before docs promote it.

Follow-up

Once merged, #1274's Option 1 can add a "Recommended: provision with oabctl" section that replaces the manual aws steps with the ingress: block, keeping the manual commands as an under-the-hood appendix.

Refs #1274

[chaodu-agent]

LGTM ✅ — declarative webhook ingress for oabctl, converged through multiple review rounds; current commit (70a920c) has no outstanding 🔴 or 🟡 findings and CI is green.

What This PR Does

Adds an optional spec.ingress block to the oab.dev/v2 manifest so oabctl apply provisions inbound webhook ingress (Telegram/LINE) in one shot — API Gateway HTTP API → VPC Link → Cloud Map → ECS task — replacing ~7 manual aws CLI steps described in the companion reference-architecture doc (#1274).

How It Works

• apply reconciles Cloud Map (private DNS namespace + a per-bot SRV service record) before the ECS create/update-service call. An SRV record is required — a plain A record carries no port, and API Gateway's private integration needs one to resolve the target via DiscoverInstances.
• Adding or fixing service discovery on an existing ECS service uses UpdateService directly (not delete-and-recreate) — ECS has supported mutating serviceRegistries on a running service since March 2022, confirmed against AWS's own API reference. This was a correction from an earlier round of this PR, which had assumed registries were create-only and documented a manual delete/recreate flow that itself turned out to rotate the webhook's public URL.
• Removing ingress from a manifest tears down the per-bot Cloud Map service and HTTP API routes/integration/stage, and explicitly detaches the ECS service's serviceRegistries with an empty list — an earlier round of this PR omitted the field instead, which (per AWS's documented semantics) leaves the existing registry attached rather than clearing it, silently pointing the service at a Cloud Map service that had just been deleted.
• The Cloud Map service targeted for teardown is resolved from the ECS service's own registry ARN rather than a name-only account-wide scan, avoiding a cross-VPC/environment collision risk where two isolated bots share the same namespace/name.
• VPC Link and Cloud Map namespace are scoped per-VPC; the HTTP API is scoped per-bot, so multiple bots can safely share a webhook path (e.g. /webhook/telegram) or a VPC without colliding.
• Backward compatible by construction — ingress is Option, defaults to None, and existing outbound-only (Discord) manifests provision zero new resources, covered by a dedicated unit test.

Findings (current commit)

#	Severity	Finding	Location
1	🟢	SRV record + Cloud Map ARN as the API Gateway integration URI matches AWS's documented private-integration pattern exactly	operator/src/ingress.rs
2	🟢	Correctly distinguishes "omitted serviceRegistries" (AWS treats as unchanged) from "explicit empty list" (detaches) when ingress is removed from a manifest	operator/src/apply.rs
3	🟢	Cloud Map teardown resolves the exact service via the ECS service's registry ARN instead of a name-only scan, avoiding cross-VPC/environment collisions	operator/src/ingress.rs
4	🟢	Cloud Map service deletion retries for ~25s to absorb ECS's async instance-deregistration lag rather than failing on first attempt	operator/src/ingress.rs
5	🟢	HTTP API resource is preserved (only routes/integration/stage are cleared) when ingress is removed via apply, so the webhook URL survives if ingress is re-added later; full deletion only happens via oabctl delete, where there's no URL left to preserve	operator/src/ingress.rs, operator/src/delete.rs
6	🟢	Good test coverage: schema parsing/defaults, validation failures, ECS-only runtime restriction, fleet template/override inheritance, backward compatibility	operator/src/manifest.rs, operator/src/ingress.rs

No 🔴 or 🟡 findings remain open. CI (cargo build, clippy --all-targets -D warnings, cargo test) is green on 70a920c.

Review History Summary

This PR went through many review rounds before converging; each round surfaced and fixed one substantive issue rather than accumulating unresolved debt:

1. Shared HTTP API across bots → cross-bot webhook path collisions → fixed with a per-bot API.
2. Plain A-record Cloud Map wiring → 503/BadRequest against a live AWS account → fixed with an SRV record + service-ARN integration.
3. VPC-agnostic shared VPC Link/namespace → breakage when bots span multiple VPCs → fixed by scoping both per-VPC.
4. Documented delete-and-recreate flow for adding service discovery to an existing service → silently rotated the webhook's public URL, breaking any already-registered Telegram/LINE webhook → root-caused as a false assumption (UpdateService has supported serviceRegistries since March 2022) and fixed by removing the recreate path entirely.
5. The resulting ingress-removal path (dropping spec.ingress from a manifest) had two gaps not exercised by the ingress-addition path: an omitted (vs. explicitly emptied) serviceRegistries field left a stale registry attached after its Cloud Map service was deleted, and the teardown call for that path fell back to an account-wide name-only Cloud Map scan with a cross-VPC collision risk. Both fixed in 70a920c by capturing the ECS service's real registry ARN up front and using it for both the explicit detach and the exact-match teardown lookup.

Baseline Check

• Main branch has no ingress concept anywhere in the operator crate — this is fully net-new functionality.
• Net-new value: the entire spec.ingress reconciliation path (Cloud Map, VPC Link, API Gateway, security-group rule) plus teardown/detach handling on removal — nothing pre-existing is duplicated.

What's Good (🟢)

• Idempotent reconciliation throughout — every resource is looked up by name/ARN and reused, so repeated apply runs converge rather than duplicate.
• README is thorough and self-critical: manifest schema, an IAM permission table for apply/delete callers, teardown/detach semantics, and explicit callouts for known edge cases (VPC Link subnet/security-group immutability after creation, stale-route pruning on path rename).
• The unauthenticated-transport tradeoff (API Gateway endpoint is public) is explicitly documented alongside the actual app-layer mitigations in place (Telegram secret-token header + IP allowlist, LINE HMAC signature) rather than silently left unaddressed.
• Multiple rounds of this review validated specific claims against AWS's official API documentation rather than accepting assumptions at face value — this is what caught both the recreate-path webhook URL bug and the registry-detach semantics bug before merge.