Wanaku

Appearance

Service Catalogs Guide ​

This guide covers everything you need to know about service catalogs in Wanaku: what they are, how they differ from service templates, their structure, and how to create, package, and deploy them.

What Are Service Catalogs? ​

Service catalogs are packaged bundles of integration services that include:

  • Camel routes — the integration logic (YAML-based route definitions)
  • Wanaku rules — MCP tool definitions that expose routes to AI agents
  • Optional dependencies — Maven coordinates for required libraries

They're packaged as a single ZIP file and deployed to the Wanaku router as a unit. This makes them ideal for:

  • Sharing pre-built integrations across teams
  • Automating deployment of complex multi-route services
  • Versioning and distributing integration packages
  • Bundling related routes with their configurations

NOTE

Service catalogs are independent of any specific capability or underlying service implementation. Apache Camel is natively supported as the integration runtime, but the service catalog format is open — other integration runtimes or custom implementations can be added to support additional technologies.

Service Catalogs vs Service Templates ​

It's important to understand the relationship between these two concepts:

  • Service Catalogs are concrete, deployable packages containing actual routes, rules, and dependencies. They're ready to deploy as-is.

  • Service Templates are parameterized blueprints that use Camel Property Placeholders ( syntax) for values that should be filled in by users. Templates are not directly deployable.

Workflow:

text
Service Template (with {{placeholders}})
    ↓  (user provides values via instantiate)
Service Catalog (ready to deploy)
    ↓  (deploy to router)
Running integration services

When you instantiate a service template with user-provided parameters, the result is a service catalog that can be deployed immediately.

TIP

For full details on creating and using parameterized templates, see the Service Templates Guide.

Service Catalog Structure ​

A service catalog is a directory with the following structure:

text
my-service/
├── index.properties              # Manifest describing the catalog
├── system-a/
│   ├── system-a.camel.yaml       # Camel routes for system-a
│   ├── system-a.wanaku-rules.yaml  # Wanaku rules (auto-generated)
│   └── system-a.dependencies.txt   # Optional Maven dependencies
└── system-b/
    ├── system-b.camel.yaml
    ├── system-b.wanaku-rules.yaml
    └── system-b.dependencies.txt

The Manifest File: index.properties ​

The index.properties file is the catalog's manifest. It describes the catalog metadata and maps service names to their files:

properties
catalog.name=my-service
catalog.description=Service catalog for my-service
catalog.services=system-a,system-b

# Routes mapping
catalog.routes.system-a=system-a/system-a.camel.yaml
catalog.routes.system-b=system-b/system-b.camel.yaml

# Rules mapping
catalog.rules.system-a=system-a/system-a.wanaku-rules.yaml
catalog.rules.system-b=system-b/system-b.wanaku-rules.yaml

# Dependencies mapping (optional)
catalog.dependencies.system-a=system-a/system-a.dependencies.txt
catalog.dependencies.system-b=system-b/system-b.dependencies.txt

Key fields:

  • catalog.name — unique identifier for the catalog
  • catalog.description — human-readable description
  • catalog.services — comma-separated list of service names
  • catalog.routes.<service> — path to Camel routes file
  • catalog.rules.<service> — path to Wanaku rules file
  • catalog.dependencies.<service> — path to dependencies file (optional)

Camel Routes Files ​

Each service has a Camel routes file (*.camel.yaml) containing integration routes. Example:

yaml
- route:
    id: get-employee-information
    description: Retrieve employee basic information
    from:
      uri: direct:employee-information
      steps:
        - setHeader:
            name: CamelHttpMethod
            constant: GET
        - to:
            uri: "http://employee-service/api/employees"

The route id field is critical — it's used by the expose command to generate MCP tool definitions.

Wanaku Rules Files ​

Rules files (*.wanaku-rules.yaml) define MCP tools that expose routes to AI agents. These are typically auto-generated by the wanaku service expose command. Example:

yaml
rules:
  - id: get-employee-information
    description: Retrieve employee basic information
    tool:
      name: get_employee_information
      type: direct
      endpoint: direct:employee-information

NOTE

While you can write rules manually, the recommended workflow is to define route IDs in your Camel routes and use wanaku service expose to generate the rules automatically.

Dependencies Files ​

Dependencies files (*.dependencies.txt) list Maven coordinates for libraries required by the routes. One dependency per line:

text
org.apache.camel:camel-http:4.4.0
org.apache.camel:camel-jackson:4.4.0

CLI Workflow ​

The wanaku service command provides a complete lifecycle for working with service catalogs.

Step 1: Initialize ​

Scaffold a new service catalog:

shell
wanaku service init --name=my-service --services=system-a,system-b

This creates:

  • A root directory my-service/ with index.properties
  • A subdirectory for each service with skeleton files

Step 2: Define Routes ​

Edit the Camel route files (*.camel.yaml) in each service directory. Define your integration routes with meaningful route IDs.

Example — hr-system/employees/employees.camel.yaml:

yaml
- route:
    id: list-employees
    description: List all employees
    from:
      uri: direct:list-employees
      steps:
        - to:
            uri: "http://hr-api/api/employees"

- route:
    id: get-employee-by-id
    description: Get employee by ID
    from:
      uri: direct:get-employee-by-id
      steps:
        - to:
            uri: "http://hr-api/api/employees/${header.employeeId}"

Step 3: Expose Routes ​

Generate Wanaku rules from your route IDs:

shell
wanaku service expose --path=my-service

This scans each service's Camel route file and generates a corresponding rules file that exposes each route as an MCP tool.

You can optionally assign a namespace to all generated rules:

shell
wanaku service expose --path=my-service --namespace=production

IMPORTANT

The expose command only extracts route-level IDs (the id field directly under - route:). Step-level IDs (on individual processors like setHeader or bean) are ignored.

Step 4: Package ​

Create a Base64-encoded ZIP package:

shell
wanaku service package --path=my-service

This creates a <catalog-name>.b64 file in the current directory. You can specify a custom output path:

shell
wanaku service package --path=my-service -o /tmp/my-service.b64

The packaged file is useful for deploying via the Kubernetes operator or storing in version control.

Step 5: Deploy ​

Deploy the service catalog directly to the Wanaku router:

shell
wanaku service deploy --path=my-service --host=http://localhost:8080

This command:

  1. Validates the catalog structure and index.properties
  2. Packages the entire directory into a ZIP archive
  3. Base64-encodes the ZIP
  4. Uploads it to the router via the REST API

Once deployed, the service catalog appears in the Wanaku admin UI under the Service Catalog page.

TIP

Use wanaku service deploy for quick iteration during development. Use the operator approach (below) for production deployments on Kubernetes.

Complete End-to-End Example ​

Here's a complete workflow for creating and deploying an HR service catalog with employee and payroll routes.

1. Initialize the Catalog ​

shell
wanaku service init --name=hr-system --services=employees,payroll

This creates:

text
hr-system/
├── index.properties
├── employees/
│   ├── employees.camel.yaml
│   ├── employees.wanaku-rules.yaml
│   └── employees.dependencies.txt
└── payroll/
    ├── payroll.camel.yaml
    ├── payroll.wanaku-rules.yaml
    └── payroll.dependencies.txt

2. Define Employee Routes ​

Edit hr-system/employees/employees.camel.yaml:

yaml
- route:
    id: list-employees
    description: List all employees
    from:
      uri: direct:list-employees
      steps:
        - setHeader:
            name: CamelHttpMethod
            constant: GET
        - to:
            uri: "http://hr-api:8080/api/employees"

- route:
    id: get-employee-by-id
    description: Get employee by ID
    from:
      uri: direct:get-employee-by-id
      steps:
        - setHeader:
            name: CamelHttpMethod
            constant: GET
        - to:
            uri: "http://hr-api:8080/api/employees/${header.employeeId}"

3. Define Payroll Routes ​

Edit hr-system/payroll/payroll.camel.yaml:

yaml
- route:
    id: calculate-payroll
    description: Calculate payroll for an employee
    from:
      uri: direct:calculate-payroll
      steps:
        - setHeader:
            name: CamelHttpMethod
            constant: POST
        - to:
            uri: "http://payroll-service:8080/api/calculate"

4. Generate Rules ​

shell
wanaku service expose --path=hr-system --namespace=hr

This auto-generates employees.wanaku-rules.yaml and payroll.wanaku-rules.yaml with tool definitions for each route.

5. Deploy to Router ​

shell
wanaku service deploy --path=hr-system --host=http://localhost:8080

6. Verify in Admin UI ​

Navigate to http://localhost:8080 and open the Service Catalog page. You should see hr-system listed with its services and routes.

Deploying with the Kubernetes Operator ​

When running Wanaku on Kubernetes or OpenShift with the Wanaku Operator, you can deploy service catalogs declaratively using the WanakuServiceCatalog custom resource.

NOTE

For complete operator documentation, see the Kubernetes Operator Guide.

Before proceeding, create and package your service catalog using the CLI workflow above (steps 1 through 4). You should have a .b64 file ready.

Step 1: Create a ConfigMap ​

Store the Base64-encoded ZIP in a Kubernetes ConfigMap under the key catalog.zip:

shell
kubectl create configmap finance-catalog-data \
  --from-file=catalog.zip=finance.b64 \
  -n wanaku

Step 2: Create the WanakuServiceCatalog Resource ​

Create a file named wanaku-service-catalog.yaml:

yaml
apiVersion: "wanaku.ai/v1alpha1"
kind: WanakuServiceCatalog
metadata:
  name: my-service-catalogs
spec:
  # Reference to the WanakuRouter CR name
  routerRef: wanaku-dev
  # List of catalogs to deploy
  catalogs:
    - name: finance-catalog
      configMapRef: finance-catalog-data

Apply it:

shell
kubectl apply -f wanaku-service-catalog.yaml -n wanaku

The operator reads the ConfigMap data and deploys the catalog to the router automatically.

Step 3: Verify the Deployment ​

shell
kubectl get wanakuservicecatalog -n wanaku
kubectl describe wanakuservicecatalog my-service-catalogs -n wanaku

The status section shows the list of successfully deployed catalogs and the Ready condition.

Removing Service Catalogs ​

When you delete the WanakuServiceCatalog resource, the operator automatically removes the deployed catalogs from the router:

shell
kubectl delete wanakuservicecatalog my-service-catalogs -n wanaku

IMPORTANT

The routerRef field must match the name of an existing WanakuRouter CR in the same namespace. The operator connects to the router's internal service URL pattern: http://internal-{routerRef}:8080

REST API Reference ​

Service catalogs can be managed via the Wanaku router's REST API.

Deploy a Catalog ​

Endpoint: POST /api/v1/service-catalog/deploy

Body: Base64-encoded ZIP file (raw string, not JSON-wrapped)

Response:

json
{
  "data": {
    "catalogName": "my-service",
    "servicesCount": 2,
    "message": "Service catalog deployed successfully"
  },
  "error": null
}

Example with curl:

shell
# Package the catalog
wanaku service package --path=my-service -o my-service.b64

# Deploy via REST API
curl -X POST \
  -H "Content-Type: text/plain" \
  --data @my-service.b64 \
  http://localhost:8080/api/v1/service-catalog/deploy

List Deployed Catalogs ​

Endpoint: GET /api/v1/service-catalog

Response:

json
{
  "data": [
    {
      "catalogName": "my-service",
      "description": "Service catalog for my-service",
      "services": ["system-a", "system-b"],
      "deployedAt": "2026-05-25T10:30:00Z"
    }
  ],
  "error": null
}

Remove a Catalog ​

Endpoint: DELETE /api/v1/service-catalog/{name}

Response:

json
{
  "data": {
    "catalogName": "my-service",
    "message": "Service catalog removed successfully"
  },
  "error": null
}

NOTE

All responses use the WanakuResponse<T> wrapper format: {"data": ..., "error": ...}

Admin UI ​

Deployed service catalogs are visible in the Wanaku admin UI under the Service Catalog page at http://<router-host>:8080.

The Service Catalog page provides:

  • A searchable list of all deployed catalogs
  • Details for each catalog (name, description, services, routes)
  • Ability to remove catalogs via the UI
  • Links to view individual routes and their MCP tool definitions

TIP

The admin UI also shows service catalogs deployed via the Kubernetes operator, providing a unified view of all deployed integrations regardless of deployment method.

See Also ​