How do I attach a markdown runbook to a service so it comes back with that service’s timeline?

Tares lets you attach a markdown runbook to a service with the reference connector, so the runbook comes back whenever you read that service. Upload the file in the console or declare it in YAML, and tag it with the service’s labels such as service=tares and environment=production. Tares always surfaces the document when it correlates on that entity, whatever the read time window.

How it works

The reference connector holds documents (json, csv, md or txt) such as project notes, schemas and runbooks. It is declarative reference material, not a stream, so there is nothing to poll and no poll interval.

• The config is the data. Each attachment carries its own name, content and labels.
• The labels you tag a document with become real Tares labels. You can read on them and trigger on them.
• There is no entity key. Correlation is label-native, so a document with service=tares and environment=production belongs to the entity with those labels.
• Each attachment is materialized into one always-surfaced event. A read of that entity returns it regardless of the read time window, so a runbook does not age out of a 15-minute read.
• Editing the source re-materializes it.

The full field list is on the reference connector page.

Set it up

You can use the console or YAML.

Console path

1. Go to Sources, then Add source, then Reference documents.
2. Upload your markdown file. Tares reads json, csv, md and txt files into text.
3. Tag the document with the labels of the entity it describes, for example service=tares and environment=production.
4. Select Create.
5. To add more documents later, re-open the source and select Upload more.

YAML path

Declare the source with an attachments list. Each attachment has a name, a format, the content and its labels. The labels list in the source config declares the label names, so reads can correlate on them. Each attachment provides the values.

- name: runbooks
  connector: reference
  config:
    attachments:
      - name: restart.md
        format: md
        content: |
          1. kubectl rollout restart deploy/tares
          2. watch the pod come healthy
        labels: { service: tares, environment: production }
    labels:
      - { name: service, field: service }
      - { name: environment, field: environment }

You can also send the same object with POST /api/sources.

The attachment fields are:

• name (required): the file name or title.
• content (required): the document’s text.
• format: one of json, csv, md or txt.
• labels: the entity labels, for example { "service": "tares" }.

Verify

1. Open the source. Recent events shows one event per document, and Fields shows the labels they carry.
2. Read the entity the document describes with read({ service: tares }). The runbook comes back in the timeline, even outside the read window.

What you get

• The runbook returns in the timeline of the service it describes, every time you read that service.
• The document is available outside the read window, so a short read still includes it.
• The labels on the document are real Tares labels, so you can read on them and trigger on them.
• One event per document, which you can inspect under Recent events.
• A source you can extend: add documents in the console with Upload more, or add entries to the attachments list in YAML.

Because service and environment are declared in the source labels, the same runbook matches reads for that service and environment, and other services keep their own documents.

When something else fits

The reference connector is for static documents that describe an entity. For data that keeps arriving, such as logs, alerts or metrics, use an event connector instead, since reference documents are not a stream. If you need a document to apply to several services, give each one its own attachment with the matching labels.

Related