Telecraft

Guides

Each guide is a task. It starts from a state you can reproduce, gives you commands to run, and ends with a result you can check.

The guides explain as little as they can. For the model behind the vocabulary (Tier, Blueprint, Service Class, Intended, Effective, Observed), read the concepts section. For every flag, field, and file schema, read the reference section.

Before you start

You need git, and the CLI, which is one downloaded file with no toolchain behind it. Every guide runs against the public demo estate, telecraft-dev/estate-demo, so you can follow along before you have an estate of your own. The quickstart sets up both, and offers two ways in: an Instance on your own machine, and the command line for CI.

Choose a starting point

Telecraft has three rungs. You can adopt them separately, in any order. Pick the one that matches the problem you have today, and ignore the other two until you want them.

Rung The problem it solves What it costs you Start here
Conformance You can't tell which Services deliver the telemetry they are configured to deliver A connection string to your telemetry backend Check conformance
Authoring Teams copy collector configuration from each other, and nobody can say who owns a given processor Nothing in your delivery path changes Author and render
Serving Rendered configuration has to reach collectors, and you want a path you can audit An OpAMP Supervisor beside each served collector Serve configurations

No rung puts Telecraft in your telemetry path. If Telecraft stops, telemetry keeps flowing.

The Conformance path

  1. Quickstart builds the CLI and gets you a first verdict.
  2. Check conformance reads a backend, judges every Service against its requirements, and wires the check into CI.
  3. Write an Exemption waives a finding's count, with an owner and an expiry, without hiding the diagnosis.
  4. Activate a version moves the estate onto a new Catalogue or Schema Registry version, after showing you what changes.

The Authoring path

  1. Quickstart builds the CLI.
  2. Author and render composes Blueprints from governed Components, inspects a team's effective palette, and renders plain otelcol YAML into git.
  3. Activate a version moves the estate onto a new Catalogue version, after showing you what changes.

The Serving path

  1. Author and render comes first: the server serves what the renderer wrote, so there is nothing to serve until you have rendered.
  2. Serve configurations runs the OpAMP endpoint from a local estate or a git URL, and installs a collector against it.
  3. Run an Instance opens the second address on the same process: the console, the API behind it, and sign-in.
  4. Run the container image is that same process as an image you pull, configure, and carry across an air gap.
  5. Deploy with Compose puts that image on one host behind a terminator, over an estate the host keeps current.
  6. Deploy on Kubernetes installs that image from a chart, with the estate checkout kept current beside it and TLS terminated in front.
  7. Stage a Rollout moves one Tier's population onto a new Blueprint version in cohorts, advancing and aborting by pull request.

See it running first

If you would rather look before you build, explore the demo is a guided tour of https://demo.telecraft.dev, a read-only console rebuilt from the demo estate on every push.