Deploy with the Wanaku Operator

Overview

The Wanaku Operator manages the following custom resource definitions (CRDs):

• WanakuRouter — deploys and configures the Wanaku execution proxy: the Wanaku router engine and, optionally, Wanaku Barn
• WanakuServiceCatalog — deploys packaged service catalogs (Camel routes and their dependencies) to the Barn backend of a router
• WanakuSemanticRouter — runs one Wanaku Semantic Router (WSR) runtime and registers it with a router as an MCP forward
• WanakuIntegration — runs one Camel Integration Capability (CIC) runtime and registers its MCP tools with a router as an MCP forward

NOTE

The WanakuCapability, WanakuCamelRoute and WanakuCamelCodeExecutionEngine CRDs were removed. Capability services (such as the Camel Integration Capability) are now deployed as regular Deployment resources and registered with the router using wanaku forwards add (see Forward MCP servers).

When you create these custom resources, the operator automatically provisions:

• Deployments with health probes
• Services for internal and external access
• ConfigMaps for configuration
• Secrets for OIDC credentials
• Ingress resources, when spec.exposure is set and enabled
• ServiceAccounts and RBAC policies

For a WanakuRouter named wanaku-dev, the operator creates (among others) the wanaku-dev-server Deployment, the server-wanaku-dev external service, the wanaku-dev-barn Deployment and barn-wanaku-dev internal service when spec.barn.enabled is true, and — when spec.auth.enabled is true — an oauth2-proxy Deployment and service. WanakuServiceCatalog resources require the referenced router to have spec.barn.enabled: true, so that Wanaku Barn is deployed for the catalogs to register against.

When spec.exposure is set, the operator creates Ingress resources, because spec.exposure.enabled defaults to true. Set spec.exposure.enabled: false to keep the router internal to the cluster. Without spec.exposure, the operator exposes nothing. With spec.exposure.host, the operator creates one Ingress named wanaku-dev. The management API uses the path /, and the MCP endpoint uses the path /default/mcp. Other Wanaku namespaces and the OAuth discovery paths (/.well-known/*, /authorize, /token and /register) require one hostname for each listener using spec.exposure.listeners (see Exposure). The operator does not create OpenShift Routes. On OpenShift, the Ingress controller creates the Routes from the Ingress resources. Earlier operator releases created Routes directly. Delete the Routes wanaku-dev and wanaku-dev-mcp manually after you upgrade. If you had spec.exposure.type: None, replace it with spec.exposure.enabled: false. The type field is no longer recognized, and enabled defaults to true. status.host contains the management URL. status.streamableEndpoint contains the default namespace MCP URL. status.sseEndpoint is deprecated and left empty because Wanaku Server has no SSE transport.

Prerequisites

Before installing the operator, ensure you have:

• Kubernetes 1.27+ or OpenShift 4.12+
• kubectl or oc CLI installed and configured
• helm CLI (version 3.x or later)
• Cluster admin or namespace admin permissions
• Keycloak instance (for authentication) — see Set up Keycloak for Wanaku

Installation

1. Create a Namespace

kubectl create namespace wanaku

2. Install the Operator via Helm

helm install wanaku-operator ./apps/wanaku-operator/deploy/helm/wanaku-operator \
  --namespace wanaku

IMPORTANT

Known limitation in 0.3.0: Helm installs the CRDs of the chart only when they do not exist in the cluster. helm upgrade does not change the CRDs, and helm uninstall does not remove them. Thus, a new install or an upgrade keeps the CRDs of the first install. Before you install or upgrade the operator on a cluster that has Wanaku CRDs, apply the CRDs of the chart. See Upgrade the CRDs and wanaku-barn#273.

By default, the operator watches only the namespace where it is installed (JOSDK_WATCH_CURRENT). To watch all namespaces, override the controller environment variables during the Helm install:

helm install wanaku-operator ./apps/wanaku-operator/deploy/helm/wanaku-operator \
  --namespace wanaku \
  --set app.envs.QUARKUS_OPERATOR_SDK_CONTROLLERS_WANAKU_ROUTER_NAMESPACES=JOSDK_ALL_NAMESPACES \
  --set app.envs.QUARKUS_OPERATOR_SDK_CONTROLLERS_WANAKU_SERVICE_CATALOG_NAMESPACES=JOSDK_ALL_NAMESPACES

Alternative: install through OLM

On clusters with the Operator Lifecycle Manager (OpenShift, or Kubernetes with OLM installed), install the operator from OperatorHub instead of Helm. The bundle supports the OwnNamespace and SingleNamespace install modes. See Wanaku Operator on OperatorHub for building and testing the bundle locally.

3. Verify the Operator

kubectl get pods -n wanaku

You should see the operator pod running. Check its logs to confirm startup:

kubectl logs -n wanaku -l app.kubernetes.io/name=wanaku-operator

For the fields of each resource, see Wanaku Operator custom resources.

Deployment Examples

Minimal Router

# router.yaml
apiVersion: "wanaku.ai/v1alpha1"
kind: WanakuRouter
metadata:
  name: wanaku-dev
spec:
  barn:
    enabled: true

Apply:

kubectl apply -f router.yaml -n wanaku
kubectl wait wanakurouter/wanaku-dev --for=condition=Ready --timeout=300s

Router with Authentication

# router-auth.yaml
apiVersion: "wanaku.ai/v1alpha1"
kind: WanakuRouter
metadata:
  name: wanaku-dev
spec:
  barn:
    enabled: true
  auth:
    enabled: true
    issuerUrl: https://keycloak.example.com/realms/wanaku
    internalIssuerUrl: http://keycloak:8080/realms/wanaku
    clientId: wanaku-mcp-router
    secretName: wanaku-oidc-secret

kubectl apply -f router-auth.yaml -n wanaku
kubectl wait wanakurouter/wanaku-dev --for=condition=Ready --timeout=300s

Router with a custom wanaku.yaml

Without a custom wanaku.yaml, the Wanaku Server denies tool calls, resource reads and prompt requests that no evaluator matches. To set your own governance posture, forwards and evaluators, put your wanaku.yaml in a ConfigMap. This example permits actions that no rule matches:

# wanaku.yaml
governance:
  default:
    mode: enforce
    no_match: allow
    on_failure: deny

kubectl create configmap wanaku-config --from-file=wanaku.yaml -n wanaku

Reference the ConfigMap from the router:

# router-config.yaml
apiVersion: "wanaku.ai/v1alpha1"
kind: WanakuRouter
metadata:
  name: wanaku-dev
spec:
  barn:
    enabled: true
  server:
    configMapRef:
      name: wanaku-config

kubectl apply -f router-config.yaml -n wanaku
kubectl wait wanakurouter/wanaku-dev --for=condition=Ready --timeout=300s

The operator adds the Barn plugin to the file and restarts the Server when the ConfigMap changes. See Server configuration.

Deploying Service Catalogs

Package a catalog with the CLI, put it in a ConfigMap, then reference it:

wanaku service package --path=employee-system -o employee-system.b64
kubectl create configmap employee-catalog-data --from-file=catalog.zip=employee-system.b64 -n wanaku

# service-catalog.yaml
apiVersion: "wanaku.ai/v1alpha1"
kind: WanakuServiceCatalog
metadata:
  name: my-catalogs
spec:
  routerRef: wanaku-dev
  catalogs:
    - name: employee-system-v2
      configMapRef: employee-catalog-data

kubectl apply -f service-catalog.yaml -n wanaku
kubectl wait wanakuservicecatalog/my-catalogs --for=condition=Ready --timeout=120s

Registering Capability Services

To run the Camel Integration Capability with registration that the operator manages, use a WanakuIntegration resource. Other capability services (for example, HTTP tools) are not managed through CRDs. Deploy them as regular Deployment resources in the same namespace and register them with the router:

# camel-integration-capability.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: camel-integration-capability
spec:
  replicas: 1
  selector:
    matchLabels:
      app: camel-integration-capability
  template:
    metadata:
      labels:
        app: camel-integration-capability
    spec:
      containers:
        - name: cic
          image: quay.io/wanaku/camel-integration-capability:latest
          env:
            # Barn base URL for data-store and service-catalog downloads
            - name: REGISTRATION_URL
              value: http://barn-wanaku-dev:8080

Then register the running service with the router as a forward:

wanaku forwards add --service="http://camel-integration-capability:9090/mcp" --name cic --namespace default

See Forward MCP servers for the forward workflow and camel-integration-capability for the service itself.

Lifecycle Operations

Check the status

List all Wanaku resources:

kubectl get wanakurouter,wanakuservicecatalog,wanakusemanticrouter,wanakuintegration -n wanaku

Get detailed status:

kubectl describe wanakurouter wanaku-dev -n wanaku
kubectl describe wanakuservicecatalog my-catalogs -n wanaku

The status section shows:

• The Ready condition (true or false). See WanakuRouter conditions
• Deployed catalogs
• Error messages (if reconciliation failed)

Troubleshoot a Ready timeout

If kubectl wait --for=condition=Ready times out, do these steps:

1. Read the conditions:

   kubectl get wanakurouter wanaku-dev -n wanaku -o jsonpath='{.status.conditions}'

2. Read the events of the custom resource:

   kubectl get events -n wanaku --field-selector involvedObject.name=wanaku-dev

3. Read the operator log:

   kubectl logs -n wanaku -l app.kubernetes.io/name=wanaku-operator | grep -iE 'forbidden|exception|error'

An empty status usually means that the installed CRD and the operator image come from different releases. The API server rejects a status update that contains fields that the CRD schema does not declare. Helm does not upgrade the CRDs in the crds/ directory of a chart. After an operator upgrade, apply the CRDs manually and restart the operator:

kubectl apply -f apps/wanaku-operator/deploy/helm/wanaku-operator/crds/
kubectl rollout restart deployment/wanaku-operator -n wanaku

The Wanaku Server startup probe allows up to 150 seconds. Image pulls add more time. Use a wait timeout of at least 300 seconds.

Check operator logs:

kubectl logs -n wanaku -l app.kubernetes.io/name=wanaku-operator

Check the managed workloads:

kubectl logs -n wanaku deployment/wanaku-dev-server
kubectl logs -n wanaku deployment/wanaku-dev-barn

Updating Resources

Edit the custom resource directly:

kubectl edit wanakurouter wanaku-dev -n wanaku

Or update your YAML and reapply:

kubectl apply -f router.yaml -n wanaku

The operator detects changes and reconciles automatically, triggering a rolling update of the managed Deployments.

Removing Resources

Delete the custom resources in reverse order (catalogs first, then router):

kubectl delete wanakuservicecatalog my-catalogs -n wanaku
kubectl delete wanakurouter wanaku-dev -n wanaku

The operator cleans up all managed Kubernetes objects (deployments, services, configmaps, routes/ingresses, etc.).

Uninstalling the Operator

helm uninstall wanaku-operator -n wanaku

WARNING

Uninstalling the operator does not delete the CRDs or existing custom resources. To fully clean up, delete the custom resources and the CRDs first:

kubectl delete wanakuservicecatalog,wanakurouter --all -n wanaku
kubectl delete wanakusemanticrouter,wanakuintegration --all -n wanaku
kubectl delete crd wanakurouters.wanaku.ai wanakuservicecatalogs.wanaku.ai \
  wanakusemanticrouters.wanaku.ai wanakuintegrations.wanaku.ai

Upgrade from earlier operator versions

Upgrade the CRDs

Helm does not update CRDs that exist in the cluster. This is a known limitation of the 0.3.0 chart (wanaku-barn#273). Do these steps before each helm install or helm upgrade on a cluster that has Wanaku CRDs:

1. Apply the CRDs of the new chart:

   kubectl apply -f apps/wanaku-operator/deploy/helm/wanaku-operator/crds/

2. Install or upgrade the operator with Helm.

3. If the operator was running during step 1, restart it:

   kubectl rollout restart deployment/wanaku-operator -n wanaku

If you do not apply the CRDs, the API server rejects the status updates of the new operator. The status of the custom resources stays empty, and kubectl wait --for=condition=Ready times out.

Upgrade from the PoC naming

Rename spec.praxis to spec.server in existing WanakuRouter manifests and install the updated CRD before applying them. The default engine image is quay.io/wanaku/wanaku-server:0.3.1.

The engine Deployment changes from <router>-praxis to <router>-server, its Service from praxis-<router> to server-<router>, and its PVC from praxis-volume-claim to server-volume-claim. Stop the old engine before starting the new one, migrate the registry data to the new PVC, and remove the old Deployment and Service after verifying the new engine. The operator does not migrate existing storage or remove the old resources automatically. Docker Compose users must also migrate the old wanaku-praxis volume to the new wanaku-server volume.

Upgrade the Barn resource names

The optional Barn Deployment is now named <router>-barn instead of <router>-mcp-router, its Service is barn-<router> instead of internal-<router>, and its PVC is <router>-barn-data instead of router-volume-claim. Stop the old Barn workload, migrate its data to the new PVC, and remove the old Deployment and Service after verification. Update any explicit Barn URLs to http://barn-<router>:8080. The operator updates the Wanaku Server and service catalog URLs automatically, but does not migrate storage or remove the old workloads. Configure Barn through spec.barn; the deprecated spec.router field still works when spec.barn is not set. A barn-volume-claim PVC that the router already owns stays in use, so existing data is kept.

Upgrade the Wanaku Server PVC name

The Wanaku Server PVC is named <router>-server-data instead of server-volume-claim. Each router in a namespace now has its own registry volume. A server-volume-claim PVC that the router already owns stays in use, so existing data is kept. The operator does not migrate storage. When you delete the old PVC, the operator creates an empty <router>-server-data PVC. Back up the registry data before you delete the old PVC, and restore it into the new PVC.

Next steps

• Wanaku Operator custom resources: the fields, ports and conditions of each resource.
• Wanaku Operator on OperatorHub: install the operator with OLM.
• Build and deploy a service catalog: package a catalog for WanakuServiceCatalog.
• Set up Keycloak for Wanaku: create the OIDC client for spec.auth.