Common automation recipes

These recipes drive the LinkMesh REST API from scripts, CI, and infrastructure-as-code. Each is a runnable curl flow you can lift into a pipeline. For the full endpoint catalogue with request/response schemas and a “Try it” console, see the API reference.

Before you start

Every call authenticates with a service-account token — see Authenticate with a service account to mint one. Export your server URL and token once:

export LINKMESH="https://linkmesh.example.com/api/v1"
export LMSAT="lmsat_…"           # the token you minted
auth() { curl -fsS -H "Authorization: Bearer $LMSAT" -H "Content-Type: application/json" "$@"; }

The auth helper adds the bearer header and content type to every call below.

Note

Tokens carry the permissions of their service account. Give each automation the minimum scope it needs — a monitoring sync needs only collectors:read and health:read; a deploy pipeline that publishes config needs writes too.

1. Provision a collector and wire its data flow

A Terraform-friendly flow: register a placeholder, hand the host an install snippet, then activate the sources and destinations it should run.

1. Create the collector record. name is the only required field; environment and managementMode (opamp or alloy-remotecfg) are optional.

   COLLECTOR=$(auth -X POST "$LINKMESH/collectors" \
     -d '{"name":"edge-eu-01","environment":"production","managementMode":"opamp"}')
   COLLECTOR_ID=$(echo "$COLLECTOR" | jq -r '.id')

2. Fetch the install snippet and run it on the target host — it enrols the collector against this server:

   auth "$LINKMESH/collectors/snippet" | jq -r '.snippet'

3. Activate a source and a destination on the collector. Reference existing source / destination IDs (create them via POST /sources and POST /destinations — see the API reference for their schemas). configOverrides lets you tune per-collector settings.

   auth -X POST "$LINKMESH/collectors/$COLLECTOR_ID/sources" \
     -d '{"sourceId":"'$SOURCE_ID'","configOverrides":{}}'
   
   auth -X POST "$LINKMESH/collectors/$COLLECTOR_ID/destinations" \
     -d '{"destinationId":"'$DEST_ID'","configOverrides":{},"tags":{"team":"platform"}}'

Tip

Wrap steps 1–3 in a Terraform local-exec or a small provider module: the whole lifecycle is idempotent reads + creates against stable IDs.

2. Drive config from CI

Every write your pipeline makes — creating a route, activating a destination, changing a pipeline — is live as soon as the call returns, and is recorded as its own version, attributed to the service account that made it. There is no commit or deploy step to call afterwards.

# The version that is live now — record it before a change, to know what to
# roll back to.
LIVE=$(auth "$LINKMESH/settings/git" | jq -r .data.liveSha)

# …make your changes with the normal create/update calls…

# Undo them: roll back to the version you recorded. This adds a new version
# equal to $LIVE and makes it live.
auth -X POST "$LINKMESH/config-as-code/rollback" -d '{"sha":"'"$LIVE"'"}'

# Re-send the live config to one collector that missed a push (recovery only).
auth -X POST "$LINKMESH/config-as-code/publish/$COLLECTOR_ID"

To roll a single collector back to its previous pushed config, use POST /collectors/{id}/rollback; its push history is at GET /collectors/{id}/config-history.

Tip

Preview what would ship before committing with GET /collectors/$COLLECTOR_ID/config/preview — handy as a CI diff gate.

3. Sync fleet health to external monitoring

Pull health on a schedule (cron, a Datadog/Grafana sync job) and forward it to your monitoring system.

# Overall control-plane health.
auth "$LINKMESH/system/health"

# Per-collector status across the fleet.
auth "$LINKMESH/collectors" \
  | jq -r '.items[] | [.id, .name, .status, .lastSeen] | @tsv'

# Live per-component throughput for one collector (records/sec, errors/sec).
auth "$LINKMESH/collectors/$COLLECTOR_ID/throughput"

Emit the status / throughput values as gauges into your monitoring backend. This needs only collectors:read + health:read scope.

4. Rotate a collector’s credential across a tagged group

Every collector — OpAMP-mode and Alloy alike — authenticates with its enrollment Bearer token over the server’s TLS front door; there is no client certificate on the collector connection. To roll the credential for a group of collectors, re-mint their per-collector token and update the runtime’s config. Drive this from your config-management tooling (the token lives in supervisor.yaml for OpAMP collectors and config.alloy for Alloy), then restart the runtime so it reconnects with the new token.

# Mint a fresh OTLP/control token for every collector tagged team=platform.
auth "$LINKMESH/collectors" \
  | jq -r '.items[] | select(.tags.team == "platform") | .id' \
  | while read -r id; do
      echo "rotating token for $id"
      auth -X POST "$LINKMESH/collectors/$id/otlp-token"
    done

Each mint revokes the collector’s prior token, so push the new value into the host’s config in the same run to avoid a gap.

5. Export topology for backup or audit

Snapshot each pipeline’s topology (nodes/edges) and the generated Alloy config — useful for change review or disaster-recovery backups.

# Save every pipeline's topology graph.
for pid in $(auth "$LINKMESH/pipelines" | jq -r '.items[].id'); do
  auth "$LINKMESH/pipelines/$pid/topology" > "topology-$pid.json"
done

# Render the generated Alloy config a pipeline's topology produces.
auth -X POST "$LINKMESH/pipelines/$PIPELINE_ID/topology/preview" \
  -d @"topology-$PIPELINE_ID.json" | jq -r '.config'

Commit the exported files to a backup repo for an auditable history of how your processing graph changed over time.

---

Every endpoint above is documented with full schemas in the API reference.