Operations

@nx/asset is not deployed on its own. It ships inside whichever host application mounts it. Operational concerns below are scoped to the asset surface within those hosts.

1. Deployment

Property	Value
Image	N/A — bundled into host images (commerce / finance / ledger)
Replicas	N/A — follows the host deployment
Resources	N/A — accounted in the host
Probes	N/A — host healthchecks cover it
Snowflake ID range	N/A — issues no IDs
Migration mode	None — no schema/migrations
Build	bun run rebuild (depends on @nx/core only)

Traefik labels

N/A — routed through the host service's existing router. Asset routes appear under the host base path (e.g. /v1/api/commerce/assets).

2. Observability

Signal	Source	Where to look
Logs	host stdout (structured key-value)	kubectl logs <host-pod> / Loki, scope AssetController / BanksVNController
Metrics	host /metrics (no asset-specific metrics)	host Grafana dashboard
Traces	inherited from host	—
Health	host GET /healthz, GET /readyz	Gateway portal

Key log lines

Line	Source	Notes
Failed to create MetaLink for %s	AssetController UPLOAD	MetaLink create failed but object stored — captured into response, not thrown
Failed to delete MetaLink for %s/%s	AssetController DELETE_OBJECT	Object removed but MetaLink cleanup failed (async, best-effort)
banks-vn.logo.not_found	BanksVNController	Requested PNG missing on disk → 404

3. Security

Concern	Mitigation
AuthN	Mutating /assets routes (upload/delete/list) + /meta-links require BASIC or JWT (host's verifier); read/download + banks-vn are public
AuthZ	MetaLinkController sets authorize: { skip: true } on all routes today — Casbin checks disabled for MetaLink
Path traversal	isValidPath/isValidName (max depth 2) on object names; bank logo regex ^[A-Za-z0-9]+\.png$
Content sniffing	x-content-type-options: nosniff on all object/logo streams
Secrets	S3 creds via host env (APP_ENV_S3_*); never in code
Caching	bank registry max-age=3600; bank logos max-age=604800, immutable
Object naming	Random UUID8 object names prevent client-controlled keys (except i18n.json)

4. Runbook

4.1 Alert classes

Alert	Trigger	Check	Fix	Escalate
Upload 5xx spike	host 5xx on /assets/upload	logs Failed to create MetaLink / S3 errors	verify S3 reachability + credentials	on-call backend
Orphaned objects	object present, no MetaLink	Failed to create MetaLink log lines	re-create MetaLink or re-upload	on-call backend
Bank logo 404s	banks-vn.logo.not_found	filename vs resources/banks-vn/*.png	add missing PNG to bundle + redeploy host	platform

4.2 Common operations

Operation	Command / action
Tail asset logs	kubectl logs -n <ns> -f deploy/<host> and filter AssetController
Verify S3 connectivity	check APP_ENV_S3_ENDPOINT reachable from the host pod
Inspect a MetaLink	GET <host>/meta-links?filter=... (JWT/Basic)
List bucket objects	GET <host>/assets/objects?prefix=... (JWT/Basic)

5. Related Pages

• Configuration
• /runbook/ — central runbook for cross-service incidents
• Decisions