Merge branch 'main' into konflux/mintmaker/main/redis-7.x

Author: IlonaShishov

.env.example

@@ -15,11 +15,19 @@ GOOGLE_API_KEY=your_google_api_key_here
 
 # Vertex AI Configuration (required if GOOGLE_GENAI_USE_VERTEXAI=TRUE)
 GOOGLE_CLOUD_PROJECT=your_gcp_project_id
-GOOGLE_CLOUD_LOCATION=us-central1
+GOOGLE_CLOUD_LOCATION=global
 
 # Model to use (default: gemini-2.5-flash)
 GEMINI_MODEL=gemini-2.5-flash
 
+# Gemini HTTP retries (google-genai SDK: exponential backoff + jitter for 429/408/5xx)
+# See: https://cloud.google.com/vertex-ai/generative-ai/docs/retry-strategy
+# GEMINI_HTTP_RETRY_ATTEMPTS=5
+# GEMINI_HTTP_RETRY_INITIAL_DELAY=1.0
+# GEMINI_HTTP_RETRY_MAX_DELAY=60.0
+# GEMINI_HTTP_RETRY_EXP_BASE=2.0
+# GEMINI_HTTP_RETRY_JITTER=1.0
+
 # -----------------------------------------------------------------------------
 # Red Hat SSO / OAuth 2.0 Configuration
 # -----------------------------------------------------------------------------
@@ -154,6 +162,11 @@ LOG_FORMAT=json
 #   detailed - Also logs tool arguments and truncated results (may contain user data)
 AGENT_LOGGING_DETAIL=basic
 
+# Maximum character length for MCP tool results sent to the LLM.
+# Oversized results are replaced with a message advising the user to
+# narrow down their query or use pagination. Set to 0 to disable.
+TOOL_RESULT_MAX_CHARS=51200
+
 # Audit logging (automatic when LOG_FORMAT=json):
 # JSON log records automatically include user_id, org_id, order_id, and
 # request_id fields for every log entry.  These fields are populated from

.tekton/google-lightspeed-agent-pull-request.yaml

@@ -351,6 +351,8 @@ spec:
         value: $(tasks.prefetch-dependencies.results.SOURCE_ARTIFACT)
       - name: CACHI2_ARTIFACT
         value: $(tasks.prefetch-dependencies.results.CACHI2_ARTIFACT)
+      - name: ARGS
+        value: "--project-name=google-lightspeed-agent --report --org=d152f68c-67b3-4efa-a5da-207d8219ca59"
       runAfter:
       - build-image-index
       taskRef:

.tekton/google-lightspeed-agent-push.yaml

@@ -348,6 +348,8 @@ spec:
         value: $(tasks.prefetch-dependencies.results.SOURCE_ARTIFACT)
       - name: CACHI2_ARTIFACT
         value: $(tasks.prefetch-dependencies.results.CACHI2_ARTIFACT)
+      - name: ARGS
+        value: "--project-name=google-lightspeed-agent --report --org=d152f68c-67b3-4efa-a5da-207d8219ca59"
       runAfter:
       - build-image-index
       taskRef:

.tekton/google-marketplace-handler-pull-request.yaml

@@ -353,6 +353,8 @@ spec:
         value: $(tasks.prefetch-dependencies.results.SOURCE_ARTIFACT)
       - name: CACHI2_ARTIFACT
         value: $(tasks.prefetch-dependencies.results.CACHI2_ARTIFACT)
+      - name: ARGS
+        value: "--project-name=google-marketplace-handler --report --org=d152f68c-67b3-4efa-a5da-207d8219ca59"
       runAfter:
       - build-image-index
       taskRef:

.tekton/google-marketplace-handler-push.yaml

@@ -350,6 +350,8 @@ spec:
         value: $(tasks.prefetch-dependencies.results.SOURCE_ARTIFACT)
       - name: CACHI2_ARTIFACT
         value: $(tasks.prefetch-dependencies.results.CACHI2_ARTIFACT)
+      - name: ARGS
+        value: "--project-name=google-marketplace-handler --report --org=d152f68c-67b3-4efa-a5da-207d8219ca59"
       runAfter:
       - build-image-index
       taskRef:

CLAUDE.md

@@ -155,6 +155,7 @@ All configuration is via environment variables, managed through Pydantic setting
 **LLM / Google Cloud:**
 - `GOOGLE_API_KEY` or `GOOGLE_CLOUD_PROJECT` + `GOOGLE_GENAI_USE_VERTEXAI=TRUE` (LLM access)
 - `GEMINI_MODEL` (model selection, default: `gemini-2.5-flash`)
+- Optional Gemini HTTP retries (Google Gen AI SDK exponential backoff + jitter): `GEMINI_HTTP_RETRY_ATTEMPTS`, `GEMINI_HTTP_RETRY_INITIAL_DELAY`, `GEMINI_HTTP_RETRY_MAX_DELAY`, `GEMINI_HTTP_RETRY_EXP_BASE`, `GEMINI_HTTP_RETRY_JITTER` (see `docs/configuration.md`)
 
 **Database:**
 - `DATABASE_URL` / `SESSION_DATABASE_URL` (PostgreSQL or SQLite)

Containerfile

@@ -4,7 +4,7 @@
 # =============================================================================
 # Build Stage
 # =============================================================================
-FROM registry.access.redhat.com/ubi9/python-312-minimal:latest as builder
+FROM registry.access.redhat.com/ubi10/python-312-minimal:latest as builder
 
 WORKDIR /opt/app-root/src
 
@@ -16,7 +16,7 @@ RUN pip install --no-cache-dir --upgrade pip && \
 # =============================================================================
 # Production Stage
 # =============================================================================
-FROM registry.access.redhat.com/ubi9/python-312-minimal:latest as production
+FROM registry.access.redhat.com/ubi10/python-312-minimal:latest as production
 
 # Labels for container metadata
 LABEL org.opencontainers.image.title="Red Hat Lightspeed Agent for Google Cloud"

Containerfile.marketplace-handler

@@ -5,7 +5,7 @@
 # =============================================================================
 # Build Stage
 # =============================================================================
-FROM registry.access.redhat.com/ubi9/python-312-minimal:latest as builder
+FROM registry.access.redhat.com/ubi10/python-312-minimal:latest as builder
 
 WORKDIR /opt/app-root/src
 
@@ -17,7 +17,7 @@ RUN pip install --no-cache-dir --upgrade pip && \
 # =============================================================================
 # Production Stage
 # =============================================================================
-FROM registry.access.redhat.com/ubi9/python-312-minimal:latest as production
+FROM registry.access.redhat.com/ubi10/python-312-minimal:latest as production
 
 # Labels for container metadata
 LABEL org.opencontainers.image.title="Marketplace Handler"

EXTERNAL_SERVICES.md

@@ -0,0 +1,100 @@
+# External Services Inventory
+
+A comprehensive list of all external services used by the Google Lightspeed Agent.
+
+## LLM Models
+
+The agent uses Google Gemini models by default, but Vertex AI supports deploying other models as well. Two access paths are supported:
+
+| Access Path | Description | Key Config |
+|-------------|-------------|------------|
+| **Google AI Studio** (default) | Direct API key access to Gemini | `GOOGLE_API_KEY` |
+| **Vertex AI** | Enterprise access via GCP project | `GOOGLE_GENAI_USE_VERTEXAI=true`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION` |
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `GEMINI_MODEL` | `gemini-2.5-flash` | Model used for agent responses |
+| `GOOGLE_GENAI_USE_VERTEXAI` | `false` | Switch between AI Studio and Vertex AI |
+| `GOOGLE_CLOUD_LOCATION` | `us-central1` | Region for Vertex AI |
+
+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`.
+
+## Google Cloud Services
+
+| Service | Purpose | Required | Key Config |
+|---------|---------|----------|------------|
+| **Gemini (AI Studio / Vertex AI)** | LLM for agent responses | Yes | `GOOGLE_API_KEY`, `GOOGLE_GENAI_USE_VERTEXAI`, `GEMINI_MODEL` |
+| **Cloud Run** | Production serverless deployment (2 services: agent + handler) | For production | `deploy/cloudrun/` |
+| **Cloud Pub/Sub** | Receives marketplace provisioning events asynchronously | For marketplace | Topic: `marketplace-entitlements` |
+| **Commerce Procurement API** | Approve/manage marketplace accounts & entitlements | For marketplace | `https://cloudcommerceprocurement.googleapis.com/v1` |
+| **Service Control API** | Usage metering & billing reporting to GCP Marketplace | For marketplace | `SERVICE_CONTROL_SERVICE_NAME`, `SERVICE_CONTROL_ENABLED` |
+| **Cloud IAM** | Service account management, role bindings, token creation | For deployment | `deploy/cloudrun/setup.sh` |
+| **Cloud Build** | Container image builds | For deployment | `deploy/cloudrun/deploy.sh` |
+| **Container Registry (gcr.io)** | Container image storage | For deployment | `gcr.io/{PROJECT_ID}/...` |
+
+### Managed GCP Infrastructure
+
+These services are required for production Cloud Run deployments and are configured in `deploy/cloudrun/setup.sh`:
+
+| Service | Purpose | Required | Reference |
+|---------|---------|----------|-----------|
+| **Cloud SQL** | Managed PostgreSQL for production databases | For production | `setup.sh:322`, IAM role `roles/cloudsql.client` |
+| **Secret Manager** | Stores API keys, database URLs, Redis URL, and other secrets | For production | `setup.sh:157-187` |
+| **Cloud Scheduler** | Schedules usage reporting jobs | For marketplace | `setup.sh:80` |
+| **Cloud Logging** | Centralized log collection | For production | IAM role `roles/logging.logWriter` |
+| **Cloud Monitoring** | Metrics and alerting | For production | IAM role `roles/monitoring.metricWriter` |
+| **Cloud Memorystore** | Managed Redis instance for rate limiting | For production | `setup.sh:85` |
+| **Cloud Storage** | Stores the agent card JSON file for agent publishing | For production | Required for Agent Builder |
+| **Serverless VPC Access** | Connects Cloud Run to Cloud Memorystore (Redis) | For production | `setup.sh:85`, `service.yaml:37` |
+
+## Red Hat Services
+
+| Service | Purpose | Required | Key Config |
+|---------|---------|----------|------------|
+| **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`) |
+| **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`) |
+| **Red Hat Lightspeed MCP Server** | Sidecar gateway to Lightspeed APIs | Yes | `MCP_SERVER_URL`, `MCP_TRANSPORT_MODE` |
+
+## Databases
+
+| Service | Purpose | Required | Key Config |
+|---------|---------|----------|------------|
+| **PostgreSQL** | Marketplace data (orders, entitlements, DCR clients) + agent sessions | Yes (production) | `DATABASE_URL`, `SESSION_DATABASE_URL` |
+| **SQLite** | Development/testing fallback database | Dev only | Default in `DATABASE_URL` |
+
+## Caching / Rate Limiting
+
+| Service | Purpose | Required | Key Config |
+|---------|---------|----------|------------|
+| **Redis** | Distributed rate limiting across agent replicas | Yes (production) | `RATE_LIMIT_REDIS_URL` (default: `redis://localhost:6379/0`) |
+
+## Observability (Optional)
+
+| Service | Purpose | Required | Key Config |
+|---------|---------|----------|------------|
+| **OpenTelemetry Collector** | Distributed tracing export (gRPC or HTTP) | No | `OTEL_ENABLED`, `OTEL_EXPORTER_OTLP_ENDPOINT` |
+| **Jaeger** | Trace storage/visualization backend | No | `OTEL_EXPORTER_TYPE=jaeger` |
+| **Zipkin** | Trace storage/visualization backend | No | `OTEL_EXPORTER_TYPE=zipkin` |
+
+## Container Registries
+
+| Registry | Image | Purpose |
+|----------|-------|---------|
+| `registry.access.redhat.com` | `ubi9/python-312-minimal` | Base image for agent & handler |
+| `registry.redhat.io` | `rhel9/postgresql-16` | PostgreSQL for Podman deployments |
+| `quay.io` | `redhat-services-prod/insights-management-tenant/insights-mcp/red-hat-lightspeed-mcp:latest` | MCP server sidecar (source registry, Podman deployments) |
+| `gcr.io` | `{PROJECT_ID}/red-hat-lightspeed-mcp:latest` | MCP server sidecar (uploaded from quay.io for Cloud Run deployments) |
+| `quay.io` | `fedora/redis-7` | Redis for rate limiting (production uses Cloud Memorystore) |
+
+## Google JWT Validation Endpoint
+
+| Endpoint | Purpose |
+|----------|---------|
+| `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`) |
+
+## Key Architectural Notes
+
+1. **Two-service architecture**: The agent (port 8000) and marketplace handler (port 8001) are separate services with separate databases for security isolation.
+2. **All external connections are configurable** via environment variables defined in `src/lightspeed_agent/config/settings.py`.
+3. **Development can run with minimal services**: SQLite replaces PostgreSQL, JWT validation can be skipped, and the MCP server is optional for limited functionality.
+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.

cloudbuild.yaml

@@ -15,6 +15,7 @@
 substitutions:
   _SERVICE_NAME: lightspeed-agent
   _REGION: us-central1
+  _VERTEXAI_LOCATION: global
   _IMAGE_TAG: latest
 
 options:
@@ -80,7 +81,7 @@ steps:
       - '--concurrency'
       - '80'
       - '--set-env-vars'
-      - 'GOOGLE_GENAI_USE_VERTEXAI=TRUE,GOOGLE_CLOUD_PROJECT=${PROJECT_ID},GOOGLE_CLOUD_LOCATION=${_REGION},AGENT_HOST=0.0.0.0,AGENT_PORT=8000,LOG_FORMAT=json'
+      - 'GOOGLE_GENAI_USE_VERTEXAI=TRUE,GOOGLE_CLOUD_PROJECT=${PROJECT_ID},GOOGLE_CLOUD_LOCATION=${_VERTEXAI_LOCATION},AGENT_HOST=0.0.0.0,AGENT_PORT=8000,LOG_FORMAT=json'
       - '--set-secrets'
       - 'RED_HAT_SSO_CLIENT_ID=redhat-sso-client-id:latest,RED_HAT_SSO_CLIENT_SECRET=redhat-sso-client-secret:latest,DATABASE_URL=database-url:latest,REDIS_URL=redis-url:latest'
       - '--service-account'