ArangoPlatformLink

The ArangoPlatformLink CRD registers a link with the platform and makes it discoverable by AI tools via /_inventory.

For the full field-by-field API reference with types and links to source code, see ArangoPlatformLink V1Beta1 API Reference.

All fields in the spec are set by the user when creating the link — none are auto-generated by the operator.

Minimal Example

The smallest valid connector only needs a deployment reference:

apiVersion: platform.arangodb.com/v1beta1
kind: ArangoPlatformLink
metadata:
  name: my-connector
spec:
  deployment:
    name: my-deployment

Full Example

apiVersion: platform.arangodb.com/v1beta1
kind: ArangoPlatformLink
metadata:
  name: aql-connector
  namespace: arangodb
spec:
  type: Active
  deployment:
    name: my-deployment
  route:
    name: aql-connector-route
  description: "Execute AQL queries on ArangoDB"
  tags:
    - database
    - aql
    - query
  schema:
    type: object
    properties:
      query:
        type: string
        description: "AQL query string"
      bindVars:
        type: object
        description: "Bind variables for the query"
    required:
      - query
  version: "1.0.0"

Spec

Field	Type	Default	Description
type	string	Active	Link pattern type. Currently only Active is supported
deployment	Object		Reference to the ArangoDeployment this connector belongs to
route	Object		Reference to the ArangoRoute that exposes this connector
description	string		Human-readable description of what the link does
tags	[]string		Labels for discovery and filtering
schema	JSONSchemaProps		JSON Schema defining the link’s input parameters
version	string		Connector version

Status

The operator sets conditions on the link as it reconciles. The connector becomes Ready only when all conditions are true.

Condition	Description
SpecValid	Spec validated — type is supported, required fields present
DeploymentFound	Referenced ArangoDeployment exists in the same namespace
RouteFound	Referenced ArangoRoute exists and is ready
Ready	All conditions met — link is visible in /_inventory

The Ready condition means the Link CRD is registered with the platform. It does not mean the link process is running or consuming resources — the link pod is managed separately by the Deployment in the Helm chart.

Checking Conditions

kubectl get arangoplatformlink aql-connector -o jsonpath='{.status.conditions}' | jq .

[
  { "type": "SpecValid", "status": "True", "reason": "Spec is valid" },
  { "type": "DeploymentFound", "status": "True", "reason": "Deployment found" },
  { "type": "RouteFound", "status": "True", "reason": "Route found" },
  { "type": "Ready", "status": "True", "reason": "Ready" }
]

Each condition has status ("True" or "False") and a reason/message explaining why. If a condition is False, the message describes what is wrong (e.g. "Deployment my-deployment not found").

You can also see the Ready status in the list view:

kubectl get arangoplatformlinks
NAME             READY
aql-connector    True

Discovery

Once Ready, the link appears in the /_inventory response on the deployment’s gateway endpoint:

{
  "connectors": {
    "aql-connector": {
      "description": "Execute AQL queries on ArangoDB",
      "tags": ["database", "aql", "query"],
      "schema": "{\"type\":\"object\",\"properties\":{\"query\":{\"type\":\"string\"},...}}",
      "version": "1.0.0"
    }
  }
}

AI tools filter connectors by tags and use schema to validate their input before submitting jobs.

Schema Validation

The schema field serves two purposes:

1. Discovery — AI tools read it from /_inventory to understand what input the link expects
2. Validation — the platform validates submitted job inputs against the schema before accepting them

Your link binary does not need to validate the schema — the platform does it for you. However, you may optionally validate for defense in depth.

Routing with ArangoRoute

Each connector should have an ArangoRoute that redirects from a user-friendly path to the link’s integration endpoint. The route is referenced in the connector spec via the route field, and the handler verifies it exists.

How Redirection Works

The ArangoRoute redirects requests from /link/<name>/ to the internal /_integration/connector/v1/ endpoint. This means:

Client request:     POST /link/aql-link/job
  ↓ (ArangoRoute redirect)
Internal endpoint:  POST /_integration/connector/v1/job

All Link API paths are relative, so the redirect works transparently:

Client path	Redirected to
/link/aql-link/job	/_integration/connector/v1/job
/link/aql-link/job/{id}	/_integration/connector/v1/job/{id}
/link/aql-link/job/{id}/cancel	/_integration/connector/v1/job/{id}/cancel

Full Example

Create the route alongside the link:

apiVersion: networking.arangodb.com/v1beta1
kind: ArangoRoute
metadata:
  name: aql-connector-route
spec:
  deployment: my-deployment
  route:
    path: /link/aql-link/
  destination:
    path: /_integration/connector/v1/
---
apiVersion: platform.arangodb.com/v1beta1
kind: ArangoPlatformLink
metadata:
  name: aql-connector
spec:
  type: Active
  deployment:
    name: my-deployment
  route:
    name: aql-connector-route
  description: "Execute AQL queries on ArangoDB"
  tags:
    - database
    - aql
  schema:
    type: object
    properties:
      query:
        type: string
    required:
      - query
  version: "1.0.0"

The handler checks the RouteFound condition — the link only becomes fully Ready when the referenced route exists and is active.

The Helm chart should create both the ArangoPlatformLink and its ArangoRoute together.

Route Naming

Each connector needs its own unique route path. If you have multiple connectors, each must have a different ArangoRoute with a different path:

Link	Route path
aql-link	/link/aql-link/
vector-link	/link/vector-link/

Route names and connector names are independent — you can name them however you like — but by convention use <connector-name>-route for the route.