|
| 1 | +# External Services Inventory |
| 2 | + |
| 3 | +A comprehensive list of all external services used by the Google Lightspeed Agent. |
| 4 | + |
| 5 | +## LLM Models |
| 6 | + |
| 7 | +The agent uses Google Gemini models by default, but Vertex AI supports deploying other models as well. Two access paths are supported: |
| 8 | + |
| 9 | +| Access Path | Description | Key Config | |
| 10 | +|-------------|-------------|------------| |
| 11 | +| **Google AI Studio** (default) | Direct API key access to Gemini | `GOOGLE_API_KEY` | |
| 12 | +| **Vertex AI** | Enterprise access via GCP project | `GOOGLE_GENAI_USE_VERTEXAI=true`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION` | |
| 13 | + |
| 14 | +| Setting | Default | Description | |
| 15 | +|---------|---------|-------------| |
| 16 | +| `GEMINI_MODEL` | `gemini-2.5-flash` | Model used for agent responses | |
| 17 | +| `GOOGLE_GENAI_USE_VERTEXAI` | `false` | Switch between AI Studio and Vertex AI | |
| 18 | +| `GOOGLE_CLOUD_LOCATION` | `us-central1` | Region for Vertex AI | |
| 19 | + |
| 20 | +The model is configured in `src/lightspeed_agent/config/settings.py` and used via the Google Agent Development Kit (ADK) `LlmAgent` in `src/lightspeed_agent/core/agent.py`. |
| 21 | + |
| 22 | +## Google Cloud Services |
| 23 | + |
| 24 | +| Service | Purpose | Required | Key Config | |
| 25 | +|---------|---------|----------|------------| |
| 26 | +| **Gemini (AI Studio / Vertex AI)** | LLM for agent responses | Yes | `GOOGLE_API_KEY`, `GOOGLE_GENAI_USE_VERTEXAI`, `GEMINI_MODEL` | |
| 27 | +| **Cloud Run** | Production serverless deployment (2 services: agent + handler) | For production | `deploy/cloudrun/` | |
| 28 | +| **Cloud Pub/Sub** | Receives marketplace provisioning events asynchronously | For marketplace | Topic: `marketplace-entitlements` | |
| 29 | +| **Commerce Procurement API** | Approve/manage marketplace accounts & entitlements | For marketplace | `https://cloudcommerceprocurement.googleapis.com/v1` | |
| 30 | +| **Service Control API** | Usage metering & billing reporting to GCP Marketplace | For marketplace | `SERVICE_CONTROL_SERVICE_NAME`, `SERVICE_CONTROL_ENABLED` | |
| 31 | +| **Cloud IAM** | Service account management, role bindings, token creation | For deployment | `deploy/cloudrun/setup.sh` | |
| 32 | +| **Cloud Build** | Container image builds | For deployment | `deploy/cloudrun/deploy.sh` | |
| 33 | +| **Container Registry (gcr.io)** | Container image storage | For deployment | `gcr.io/{PROJECT_ID}/...` | |
| 34 | + |
| 35 | +### Managed GCP Infrastructure |
| 36 | + |
| 37 | +These services are required for production Cloud Run deployments and are configured in `deploy/cloudrun/setup.sh`: |
| 38 | + |
| 39 | +| Service | Purpose | Required | Reference | |
| 40 | +|---------|---------|----------|-----------| |
| 41 | +| **Cloud SQL** | Managed PostgreSQL for production databases | For production | `setup.sh:322`, IAM role `roles/cloudsql.client` | |
| 42 | +| **Secret Manager** | Stores API keys, database URLs, Redis URL, and other secrets | For production | `setup.sh:157-187` | |
| 43 | +| **Cloud Scheduler** | Schedules usage reporting jobs | For marketplace | `setup.sh:80` | |
| 44 | +| **Cloud Logging** | Centralized log collection | For production | IAM role `roles/logging.logWriter` | |
| 45 | +| **Cloud Monitoring** | Metrics and alerting | For production | IAM role `roles/monitoring.metricWriter` | |
| 46 | +| **Cloud Memorystore** | Managed Redis instance for rate limiting | For production | `setup.sh:85` | |
| 47 | +| **Cloud Storage** | Stores the agent card JSON file for agent publishing | For production | Required for Agent Builder | |
| 48 | +| **Serverless VPC Access** | Connects Cloud Run to Cloud Memorystore (Redis) | For production | `setup.sh:85`, `service.yaml:37` | |
| 49 | + |
| 50 | +## Red Hat Services |
| 51 | + |
| 52 | +| Service | Purpose | Required | Key Config | |
| 53 | +|---------|---------|----------|------------| |
| 54 | +| **Red Hat SSO (Keycloak)** | OAuth 2.0 auth, token introspection, Dynamic Client Registration | Yes | `RED_HAT_SSO_ISSUER` (default: `https://sso.redhat.com/auth/realms/redhat-external`) | |
| 55 | +| **console.redhat.com (Lightspeed APIs)** | Advisor, Inventory, Vulnerability, Remediations, Patch, Image Builder, RBAC, RHSM | Yes (via MCP) | `MCP_SERVER_URL`, JWT forwarded via MCP headers (see `mcp_headers.py`) | |
| 56 | +| **Red Hat Lightspeed MCP Server** | Sidecar gateway to Lightspeed APIs | Yes | `MCP_SERVER_URL`, `MCP_TRANSPORT_MODE` | |
| 57 | + |
| 58 | +## Databases |
| 59 | + |
| 60 | +| Service | Purpose | Required | Key Config | |
| 61 | +|---------|---------|----------|------------| |
| 62 | +| **PostgreSQL** | Marketplace data (orders, entitlements, DCR clients) + agent sessions | Yes (production) | `DATABASE_URL`, `SESSION_DATABASE_URL` | |
| 63 | +| **SQLite** | Development/testing fallback database | Dev only | Default in `DATABASE_URL` | |
| 64 | + |
| 65 | +## Caching / Rate Limiting |
| 66 | + |
| 67 | +| Service | Purpose | Required | Key Config | |
| 68 | +|---------|---------|----------|------------| |
| 69 | +| **Redis** | Distributed rate limiting across agent replicas | Yes (production) | `RATE_LIMIT_REDIS_URL` (default: `redis://localhost:6379/0`) | |
| 70 | + |
| 71 | +## Observability (Optional) |
| 72 | + |
| 73 | +| Service | Purpose | Required | Key Config | |
| 74 | +|---------|---------|----------|------------| |
| 75 | +| **OpenTelemetry Collector** | Distributed tracing export (gRPC or HTTP) | No | `OTEL_ENABLED`, `OTEL_EXPORTER_OTLP_ENDPOINT` | |
| 76 | +| **Jaeger** | Trace storage/visualization backend | No | `OTEL_EXPORTER_TYPE=jaeger` | |
| 77 | +| **Zipkin** | Trace storage/visualization backend | No | `OTEL_EXPORTER_TYPE=zipkin` | |
| 78 | + |
| 79 | +## Container Registries |
| 80 | + |
| 81 | +| Registry | Image | Purpose | |
| 82 | +|----------|-------|---------| |
| 83 | +| `registry.access.redhat.com` | `ubi9/python-312-minimal` | Base image for agent & handler | |
| 84 | +| `registry.redhat.io` | `rhel9/postgresql-16` | PostgreSQL for Podman deployments | |
| 85 | +| `quay.io` | `redhat-services-prod/insights-management-tenant/insights-mcp/red-hat-lightspeed-mcp:latest` | MCP server sidecar (source registry, Podman deployments) | |
| 86 | +| `gcr.io` | `{PROJECT_ID}/red-hat-lightspeed-mcp:latest` | MCP server sidecar (uploaded from quay.io for Cloud Run deployments) | |
| 87 | +| `quay.io` | `fedora/redis-7` | Redis for rate limiting (production uses Cloud Memorystore) | |
| 88 | + |
| 89 | +## Google JWT Validation Endpoint |
| 90 | + |
| 91 | +| Endpoint | Purpose | |
| 92 | +|----------|---------| |
| 93 | +| `https://www.googleapis.com/service_accounts/v1/metadata/x509/cloud-agentspace@system.gserviceaccount.com` | Fetches public keys to validate DCR software_statement JWTs. This URL also serves as the expected `iss` (issuer) claim in the JWT for verification (see `google_jwt.py:20-23`) | |
| 94 | + |
| 95 | +## Key Architectural Notes |
| 96 | + |
| 97 | +1. **Two-service architecture**: The agent (port 8000) and marketplace handler (port 8001) are separate services with separate databases for security isolation. |
| 98 | +2. **All external connections are configurable** via environment variables defined in `src/lightspeed_agent/config/settings.py`. |
| 99 | +3. **Development can run with minimal services**: SQLite replaces PostgreSQL, JWT validation can be skipped, and the MCP server is optional for limited functionality. |
| 100 | +4. **Production requires**: Gemini API, Red Hat SSO, PostgreSQL (x2), Redis, MCP server, and the Google Marketplace services (Pub/Sub, Procurement, Service Control) if marketplace integration is enabled. |
0 commit comments