Skip to content

Run your first recorded probe

This procedure uses an existing Urth deployment, an account administrator, urthctl, jq, and a Worker host. Use an isolated development deployment for this early preview. See Installation for a local stack.

Before you start

Open the Urth preview. For that deployment, use --api-server-address=https://urth.sre-norns.com during CLI login and --client.api-server-address=https://urth.sre-norns.com for the Worker. The examples below retain the configured https://urth.example.org default.

Obtain an account from the service operator or accept an invitation from your account administrator. If registration is offered, follow the browser instructions. Otherwise, ask the operator for access; installing the tools does not create an account.

For this walkthrough, request account administrator access to create the project, register a Runner, and issue its token. Confirm that you can manage the project and grant it Runner access. You also need a Worker host with outbound API and broker access and connectivity to the test target.

Install the CLI and Worker first. Use a disposable target with no credentials for the public preview.

1. Sign in and create a project

This guide assumes that the control plane runs at https://urth.example.org and that both tools are configured to use that address by default. See Override the control-plane address if your deployment uses another endpoint.

urthctl auth login
urthctl projects create quickstart --use

Open the browser URL printed by the login command. Sign in and approve the request. If you already have a project, select it with urthctl context use PROJECT instead of creating another one. urthctl auth status shows the current session.

2. Register a Runner

Save this manifest as runner.yaml. The location label identifies this probe vantage point. It does not configure network access.

apiVersion: urth.sre-norns.com/v1
kind: runners
metadata:
  name: quickstart-runner
  labels:
    location: lab
spec:
  active: true
  description: HTTP probes from the lab network
  jobRequirements:
    probeKinds: [http]
  workerRequirements: {}

Apply it:

urthctl apply runner.yaml

jobRequirements.probeKinds explicitly permits HTTP jobs on this channel. An empty list accepts no jobs. Workers must support every permitted probe kind.

A Runner is an account resource. It still needs a project grant and a running Worker before it can execute this project's probes.

3. Authorize the Runner for the project

The following command uses the current project's context. It grants that project permission to use the Runner:

urthctl apply - <<YAML
apiVersion: urth.sre-norns.com/v1
kind: runner-authorizations
metadata:
  name: quickstart-runner
spec:
  runnerRef: $(urthctl get runner quickstart-runner -o json | jq -r .metadata.uid)
  roles: [runner]
YAML

Registration, Worker enrollment, and project authorization are separate steps. A token alone does not grant the Runner permission to serve a project.

4. Start a Worker in the lab network

Run token issuance as an account administrator. Store the output in a private file:

URTH_QUICKSTART_TOKEN_FILE=$(mktemp)
chmod 600 "$URTH_QUICKSTART_TOKEN_FILE"
urthctl runners tokens issue quickstart-runner lab-runner-token \
  > "$URTH_QUICKSTART_TOKEN_FILE"

quickstart-runner is the Runner name. lab-runner-token is an arbitrary name you assign to this token so you can identify it later. Choose a name that identifies its purpose or installation. The command prints the secret once; the private file above stores it for Worker enrollment.

Use urthctl runners tokens list quickstart-runner to find the token by name. The get and revoke commands take its token ID from that list, not its name.

Transfer the file securely to the Worker host if necessary. On that host, use the actual private file path:

install -d -m 700 "$HOME/.local/state/urth-worker/work"
urth-worker --token-file /secure/path/runner-token \
  --working-directory="$HOME/.local/state/urth-worker/work"

Keep the process running. It needs outbound access to both the API and the NATS broker addresses supplied by the control plane. It also needs access to the probe target. See Connect probers for TLS and key storage.

5. Define an HTTP probe

Save this as scenario.yaml. Replace https://service.example.org/health with a non-sensitive endpoint that you are authorized to test and that the Worker can reach. The location selector matches the Runner created above.

apiVersion: urth.sre-norns.com/v1
kind: scenarios
metadata:
  name: service-http-lab
spec:
  active: true
  description: Check an HTTP response from the lab network
  requirements:
    matchLabels:
      location: lab
  prob:
    kind: http
    timeout: 5s
    spec:
      target: https://service.example.org/health
      http:
        method: GET

Apply and trigger it:

urthctl apply scenario.yaml
urthctl trigger service-http-lab
urthctl get results service-http-lab

Wait for the Result to reach a terminal state. Confirm that it reports a successful probe, identifies the lab Runner and its Worker, and records timing. Inspect its status, execution location, timing, and available artifacts in the web interface. A successful HTTP check establishes only what this probe tests. It does not prove that a complete customer workflow succeeds.

If the run does not execute

Check the project context and Runner grant. Check that the Runner is active. Check that its labels match the Scenario requirements. Check that a compatible Worker has enrolled and can reach both the API and broker. Then inspect the Result and dispatch diagnostics before triggering another run.

Do not wait for a Scenario schedule. Recurring execution is not implemented. For additional perspectives, follow Probe from several locations.

Next steps

  • Create test scenarios for a walkthrough of probe types, expected responses, the web form, and manual Worker runs.
  • Run scenarios locally to develop or troubleshoot without adding Results or Artifacts to server history.