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 (agent or opamp) 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 agent 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. Publish config-as-code from CI

LinkMesh stores generated collector config in a git working tree. A deploy pipeline commits the pending changes, then publishes them — pushing the production clone out to every affected collector.

# Commit the pending working-tree changes with a traceable message.
auth -X POST "$LINKMESH/commit" \
  -d '{"message":"ci: deploy '"$CI_COMMIT_SHORT_SHA"'"}'

# Push the generated config to collectors (whole fleet)…
auth -X POST "$LINKMESH/publish"

# …or scope the push to a single collector.
auth -X POST "$LINKMESH/publish/$COLLECTOR_ID"

Poll rollout progress with GET /publish/status. 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. Bulk-rotate certificates on a tagged group

There’s no single bulk endpoint — list the collectors you care about, then loop the per-collector renew. This re-offers a fresh client certificate over each collector’s existing session.

# Renew certs for every collector tagged team=platform.
auth "$LINKMESH/collectors" \
  | jq -r '.items[] | select(.tags.team == "platform") | .id' \
  | while read -r id; do
      echo "renewing $id"
      auth -X POST "$LINKMESH/collectors/$id/renew-cert"
    done

Check rotation outcomes afterwards via GET /ca/certificates (serials + expiry per collector) or GET /collectors/{id}/certificate.

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.