This is an automated email from the ASF dual-hosted git repository. yasith pushed a commit to branch feat/grpc-armeria-migration in repository https://gitbox.apache.org/repos/asf/airavata.git
commit 6b1227991cfa532b61f217e276a65cc56273e7ec Author: yasithdev <[email protected]> AuthorDate: Wed Apr 1 00:39:13 2026 -0400 docs: update all documentation for gRPC+Armeria architecture Remove Thrift references, update port numbers (single port 9090), reflect Armeria-based gRPC+REST transcoding architecture, and update SDK connection model from Thrift to gRPC. --- README.md | 80 +++++++++++------------------------- airavata-agent/README.md | 6 +-- airavata-python-sdk/README.md | 14 +++---- dev-tools/ansible/DEVELOPER_GUIDE.md | 2 +- dev-tools/ansible/SETUP_FLOW.md | 15 ++----- 5 files changed, 36 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index 27d05100bc..7021671b8b 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ Apache Airavata is composed of modular components spanning core services, data m ## 🔄 How Airavata Works -Airavata runs as a **single unified JVM** (Spring Boot) that hosts Thrift, REST, and gRPC transports plus background workers. +Airavata runs as a **single unified JVM** (Spring Boot + Armeria) that serves gRPC and REST (HTTP/JSON transcoding) on a single port, plus background workers. ```mermaid graph TB @@ -69,44 +69,35 @@ graph TB subgraph "Unified Airavata Server (single JVM)" direction TB - MUX["Thrift :8930<br/>9 multiplexed services"] - REST["REST :18889<br/>Swagger UI + Actuator"] - GRPC["gRPC :19900<br/>Agent + Research"] + ARMERIA["Armeria :9090<br/>gRPC + REST transcoding"] SVC["Service Layer<br/>(airavata-api module)"] BG["Background Services<br/>12 workers"] - MON["Monitoring :9097<br/>/metrics /health/services"] end - SDK[Python SDK] -->|TMultiplexedProtocol| MUX - Portal[Web Portal] -->|REST| REST - MUX --> SVC - REST --> SVC - GRPC --> SVC + SDK[Python SDK] -->|gRPC| ARMERIA + Portal[Web Portal] -->|REST| ARMERIA + ARMERIA --> SVC SVC --> DB SVC --> RMQ BG --> ZK BG --> KFK BG --> RMQ SVC -.->|auth| KC - MON -.->|tracks| BG ``` ### 1. Unified Airavata Server `(airavata-server)` > Entry point: `org.apache.airavata.server.AiravataServerMain` > Started via: `tilt up` or `java -jar > airavata-server/target/airavata-server-0.21-SNAPSHOT.jar` -The unified server hosts all transports (Thrift, REST, gRPC), Spring Boot services (Research, Agent, File Server), and background workers in a single JVM. On startup it: +The unified server hosts gRPC and REST (via Armeria HTTP/JSON transcoding) on a single port, Spring Boot services (Research, Agent, File Server), and background workers in a single JVM. On startup it: 1. Initializes the unified `airavata` database -2. Starts the REST server on port **18889** (Swagger UI + Actuator health) -3. Registers 9 Thrift services on a single `TMultiplexedProcessor` (port **8930**) -4. Starts gRPC server on port **19900** -5. Starts background `IServer` workers -6. Starts monitoring server on port **9097** +2. Starts Armeria server on port **9090** (gRPC + REST transcoding + DocService at `/docs`) +3. Starts background `IServer` workers -#### Architecture: Service Layer + Thrift Transport +#### Architecture: Service Layer + gRPC Transport -All business logic lives in a transport-agnostic **service layer** (`org.apache.airavata.service.*`). Thrift handlers are thin adapters that delegate to services via `ThriftAdapter`, translating between Thrift types and service exceptions. This decoupling enables future REST/gRPC transports without duplicating logic. +All business logic lives in a transport-agnostic **service layer** (`org.apache.airavata.service.*`). gRPC service implementations delegate to services. Proto definitions with `google.api.http` annotations provide automatic REST transcoding via Armeria. | Service | Responsibility | |---|---| @@ -127,20 +118,6 @@ All business logic lives in a transport-agnostic **service layer** (`org.apache. Shared utilities: `SharingHelper` (sharing operations), `EventPublisher` (messaging), `RequestContext` (transport-agnostic identity). -#### Thrift Services (all on port 8930, multiplexed) - -| Service name | Handler | Responsibility | -|---|---|---| -| `Airavata` | `AiravataServerHandler` | Public API — delegates to service layer | -| `RegistryService` | `RegistryServerHandler` | Metadata and definitions for tasks and applications | -| `CredentialStore` | `CredentialStoreServerHandler` | Secure storage and retrieval of compute credentials | -| `SharingRegistry` | `SharingRegistryServerHandler` | Sharing and permissioning of Airavata resources | -| `UserProfile` | `UserProfileServiceHandler` | User profile management | -| `TenantProfile` | `TenantProfileServiceHandler` | Tenant/gateway management | -| `IamAdminServices` | `IamAdminServicesHandler` | IAM administration | -| `GroupManager` | `GroupManagerServiceHandler` | Group and role management | -| `Orchestrator` | `OrchestratorServerHandler` | Workflow DAG construction and task dispatch | - #### Background Services (IServer lifecycle, same JVM) | Service | Responsibility | @@ -177,15 +154,13 @@ stateDiagram-v2 graph LR subgraph "Startup Sequence" direction TB - A[1. DB Init] --> B[2. Thrift Handlers] - B --> C[3. TMultiplexedProcessor :8930] - C --> D[4. DBEventManager] - D --> E[5. MonitoringServer :9097] - E --> F[6. HelixController] - F --> G{waitForHelixCluster} - G --> H[7. HelixParticipant] - H --> I[8. Pre/Post/Parser WF Managers] - I --> J[9. Email/Realtime Monitors] + A[1. DB Init] --> B[2. Armeria Server :9090] + B --> C[3. DBEventManager] + C --> D[4. HelixController] + D --> E{waitForHelixCluster} + E --> F[5. HelixParticipant] + F --> G[6. Pre/Post/Parser WF Managers] + G --> H[7. Email/Realtime Monitors] end ``` @@ -225,7 +200,7 @@ tilt up This starts: - **Infrastructure**: MariaDB, RabbitMQ, ZooKeeper, Kafka, Keycloak (via `compose.yml`) -- **Unified Airavata Server**: Thrift (:8930), REST (:18889), gRPC (:19900), Monitoring (:9097) +- **Unified Airavata Server**: gRPC + REST on port 9090, API docs at `/docs` Open the Tilt UI at `http://localhost:10350` to monitor all resources. Integration tests can be triggered manually from the Tilt UI. @@ -246,25 +221,19 @@ Or use the helper scripts: ### Health Monitoring -The monitoring server on port **9097** exposes: +The Armeria server on port **9090** exposes: | Endpoint | Method | Description | |----------|--------|-------------| -| `/metrics` | GET | Prometheus metrics | -| `/health/services` | GET | JSON status of all background services (UP/DOWN/DISABLED) | -| `/admin/restart/{name}` | POST | Restart a background service by name | - -Spring Boot services expose `/actuator/health` on their respective ports. +| `/internal/actuator/health` | GET | Health check | +| `/docs` | GET | Armeria DocService (API documentation) | ### Configuration The main configuration file is `airavata-server/src/main/resources/application.yml`. Key settings: -* `airavata.servers` — List of transports to activate: `[thrift, rest, grpc]` * `spring.datasource.url` — JDBC URL (default: `jdbc:mariadb://localhost:13306/airavata`) -* `airavata.thrift.port` — Thrift port (default: `8930`) -* `server.port` — REST port (default: `18889`) -* `grpc.server.port` — gRPC port (default: `19900`) +* `armeria.server.port` — Armeria server port (default: `9090`) * `airavata.security.openid-url` — Keycloak realm URL ### Integration Tests @@ -277,10 +246,7 @@ mvn test -pl airavata-api -Dgroups=runtime | Transport | Port | Purpose | |-----------|------|---------| -| Thrift | 8930 | 9 multiplexed services (Python SDK, Thrift clients) | -| REST | 18889 | Swagger UI, Actuator health, REST APIs | -| gRPC | 19900 | Agent + Research service gRPC | -| Monitoring | 9097 | Prometheus metrics, `/health/services` | +| Armeria | 9090 | gRPC + REST (HTTP/JSON transcoding), DocService at `/docs`, health at `/internal/actuator/health` | ## 🤝 Contributing diff --git a/airavata-agent/README.md b/airavata-agent/README.md index 72686ee90e..bf45d6874d 100644 --- a/airavata-agent/README.md +++ b/airavata-agent/README.md @@ -66,7 +66,7 @@ chmod +x airavata-agent ### Run the agent ``` ./airavata-agent \ - --server <connection_server_url>:19900 \ + --server <connection_server_url>:9090 \ --agent <agent_id> \ --environ <environment_id> \ --lib "python=3.10,pip,<packages>" \ @@ -77,7 +77,7 @@ Replace placeholders with your actual configuration values. #### Example: ``` ./airavata-agent ---server loalhost:19900 +--server loalhost:9090 --agent agent_dd9667fe-78d1-4ffa-a0d2-19074e41dd45 --environ base --lib "python=3.10,pip,mattersim,torchmetrics,numpy" @@ -108,7 +108,7 @@ go run agent.go <connection_server_url> --agent <agent_id> --environ <env> #### Example ``` -go run agent.go --server localhost:19900 --agent agent1 --environ base +go run agent.go --server localhost:9090 --agent agent1 --environ base ``` ## Build the agent diff --git a/airavata-python-sdk/README.md b/airavata-python-sdk/README.md index 66b71b5dbb..2ea95bfc16 100644 --- a/airavata-python-sdk/README.md +++ b/airavata-python-sdk/README.md @@ -4,16 +4,16 @@ The Apache Airavata Python SDK for third party clients to integrate with Airavat ### Folder Structure - `airavata` - Includes thrift stubs generated by a thrift compiler. + Includes gRPC generated stubs (protobuf models and service clients). Mainly contains data model and functions. You may need to import data model packages to integrate with clients. - `airavata_sdk` - `clients` Includes integration clients, which you want to import and integrate with your code to access airavata middleware. - `samples` - Includes set of sample implementation of integration clients to demonastrate the integration with airavata middleware + Includes set of sample implementation of integration clients to demonstrate the integration with airavata middleware - `transport` - Includes connection handling classes and connection pool implementations + Includes connection handling classes for gRPC channels - `airavata_experiments` Python APIs to run experiments from anywhere. Handles uploading data, running experiments, tracking progress, and fetching data from past runs. @@ -22,10 +22,8 @@ The Apache Airavata Python SDK for third party clients to integrate with Airavat ### Connection Model -All Thrift services (Airavata, RegistryService, CredentialStore, SharingRegistry, UserProfile, -TenantProfile, IamAdminServices, GroupManager, Orchestrator) are served on a **single port** (default `8930`) -using `TMultiplexedProcessor`. The SDK uses `TMultiplexedProtocol` to route each client call to the -correct service by name. No separate per-service port configuration is needed. +The SDK connects to Airavata via **gRPC** (using `grpcio`) on a single port (default `9090`). +All API services are served by an Armeria server that provides both gRPC and REST (HTTP/JSON transcoding). The default server settings are in `airavata_sdk/__init__.py` (`Settings` class) and can be overridden with environment variables (e.g., `API_SERVER_HOSTNAME`, `API_SERVER_PORT`). @@ -46,7 +44,7 @@ with environment variables (e.g., `API_SERVER_HOSTNAME`, `API_SERVER_PORT`). ``` - Configure server connection via environment variables or the `Settings` class defaults: - `API_SERVER_HOSTNAME` (default: `api.gateway.cybershuttle.org`) - - `API_SERVER_PORT` (default: `8930`) + - `API_SERVER_PORT` (default: `9090`) - `AUTH_SERVER_URL`, `AUTH_REALM`, `AUTH_CLIENT_ID` for Keycloak authentication ### Generating Distribution Archives (Optional) diff --git a/dev-tools/ansible/DEVELOPER_GUIDE.md b/dev-tools/ansible/DEVELOPER_GUIDE.md index 93b8358c3c..3415991c94 100644 --- a/dev-tools/ansible/DEVELOPER_GUIDE.md +++ b/dev-tools/ansible/DEVELOPER_GUIDE.md @@ -284,7 +284,7 @@ ansible-playbook -i inventories/my-env start_services.yml --ask-vault-pass ```bash # Check ports ansible airavata-server -i inventories/my-env -m shell \ - -a "ss -tuln | grep -E '8930|8940|8962|8970|8960|7878|18880|18899|8050|8082'" + -a "ss -tuln | grep -E '9090'" # Check processes ansible airavata-server -i inventories/my-env -m shell \ diff --git a/dev-tools/ansible/SETUP_FLOW.md b/dev-tools/ansible/SETUP_FLOW.md index f78bb1387f..36143a98c4 100644 --- a/dev-tools/ansible/SETUP_FLOW.md +++ b/dev-tools/ansible/SETUP_FLOW.md @@ -118,7 +118,7 @@ This document explains the setup flow and how to configure Airavata components a **Purpose**: HAProxy for API server SSL termination - Installs HAProxy - Configures SSL termination -- Proxies to API server on port 8930 +- Proxies to API server on port 9090 - **Runs on**: `airavata_servers` - **Condition**: Only runs if `api_server_public_hostname` is defined @@ -127,7 +127,7 @@ This document explains the setup flow and how to configure Airavata components a - Builds Airavata from source (Maven) - Generates configuration files from templates - Deploys services to `deployment_dir` -- Starts the consolidated `AiravataServer` (all Thrift services + background workers on port 8930) plus the Spring Boot microservices (Agent Service, File Server, Research Service, REST Proxy) +- Starts the consolidated `AiravataServer` (gRPC + REST via Armeria on port 9090, background workers, embedded Agent Service, File Server, and Research Service) - **Runs on**: `airavata_servers` only - **Become user**: `{{ user }}` (non-root) @@ -312,16 +312,7 @@ The playbook will automatically skip roles that don't apply to the target host b - **DNS**: `keycloak_vhost_servername` must resolve to Keycloak server IP ### Airavata Server -- **Port 8930**: API Server (or via HAProxy on 443) -- **Port 8940**: Orchestrator -- **Port 8962**: Profile Service -- **Port 8970**: Registry -- **Port 8960**: Credential Store -- **Port 7878**: Sharing Registry -- **Port 18880**: Agent Service -- **Port 18899**: Research Service -- **Port 8050**: File Server -- **Port 8082**: REST Proxy +- **Port 9090**: Unified API (gRPC + REST via Armeria, or via HAProxy on 443) - **Port 2181**: Zookeeper - **Port 9092**: Kafka - **Port 5672**: RabbitMQ
