Skip to content

docs: add a data centre onboarding tutorial - #138

Merged
uniqueg merged 3 commits into
mainfrom
docs/113-data-centre-tutorial
Nov 13, 2026
Merged

uniqueg merged 3 commits into
mainfrom
docs/113-data-centre-tutorial

Conversation

@uniqueg

@uniqueg uniqueg commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Summary

Second part of the onboarding tutorials of #113 (D4.5: "tutorials for onboarding compute and/or data centres"). #125 added the Node (compute centre) tutorial with a short section for data centres; this PR turns that section into a tutorial of its own and brings the Node tutorial up to date with the TESK release.

  • New: docs/operators/data-centre-onboarding-tutorial.md ("Tutorial: Onboard a Data Centre"), for sites that offer storage, tools or workflows but don't run tasks, on any Kubernetes or OpenShift cluster:
    1. Prerequisites (cluster and rights, tools, storage class, Ingress and HTTPS, a way to restrict writes, LS Login)
    2. Offer storage for tasks (S3/FTP, links the existing "Deploy storage" steps; storage isn't registered in the registry)
    3. Deploy TRS-Filer 0.5.0: MongoDB credentials Secret, download and check of the released chart (attestation and cosign), the service info overlay (the chart has no value yet, trs-filer#135), restriction of writes (no authentication yet, trs-filer#7), values for Ingress with cert-manager, install, and checks (service info, refused POST)
    4. Register by import with sync on; 5. Get verified; 6. Add tools
    • "Planned": DRS-Filer (no release), write tokens, the chart value for the service info
  • Node tutorial: TESK chart 0.3.0 is released (2026-11-12), so the "not released yet" box and the checkout of a commit are replaced by the download and check of the released chart (as in TESK's "From a release"); paths now refer to the unpacked chart (./tesk, tesk/s3-config/); the test task is inlined (no checkout needed any more); the stale anchor configuration/#service-info of the TESK docs is fixed (#service-info-serviceinfo); the "Data centres" section points to the new tutorial.
  • Links: nav (one line under "Architects & Operators", after the Node tutorial), the section index, Onboarding and the TRS-Filer page.

Refs #113

Acceptance not met by this PR: #113 asks for the tutorials to be tested by an operator who didn't write them. That stays open on the issue, as for #125, so this PR uses "Refs".

Light lane: docs only (Markdown pages and one nav line); no code, CI or configuration. I reviewed the diff myself against the product sources below.

Sources (released versions, read-only)

  • TRS-Filer v0.5.0: deployment/README.md (quick start, values, security notes, ingress and route, configuration overlay, MongoDB authentication), deployment/templates/trs-filer-deploy.yaml, docs/configuration.md#service-info, docs/access-control.md, docs/operations.md#verifying-images-and-charts, trs_filer/config.yaml (service info type org.ga4gh/trs/2.0.1, environment dev)
  • TESK v0.3.0: docs/deployment.md ("From a release", requirements, auth), charts/tesk/values.yaml, examples/success/hello.json; release assets tesk-0.3.0.tgz and .sigstore.json
  • This repo: onboarding.md, service-info.md, using-cloud-registry.md

Verification

  • python scripts/check_names.py: no findings

  • mkdocs build --strict: built without warnings (after rebasing on main with docs: add the Krini user guide #137)

  • pytest: 25 passed, 100% coverage

  • External links of both tutorials: fetched, all 200, and their anchors exist on the rendered pages (one stale TESK anchor found and fixed)

  • Chart checks, as written on the pages: gh release download, gh attestation verify and cosign verify-blob succeed for tesk-0.3.0.tgz and trs-filer-0.5.0.tgz (and gh attestation verify fails with a wrong --source-ref, as expected)

  • helm lint and helm template (Helm 3.22.1, offline) of the unpacked released charts with the values of the tutorials: both render; TESK gets the service info, the LS Login user info URL and the claim settings; TRS-Filer gets the Ingress for the host with the cert-manager issuer and the overlay ConfigMap

  • TRS-Filer steps on a throwaway local minikube cluster (Kubernetes 1.34, deleted afterwards): namespace and Secret as on the page, the unpacked chart with the overlay ConfigMap and the deploy edits of TRS-Filer's "Configuration", helm upgrade --install: MongoDB, the configuration Job and the app came up; GET /ga4gh/trs/v2/service-info served the values of the overlay (id: org.example.trs, environment: prod, type org.ga4gh/trs/2.0.1), and an unrestricted POST /tools with {} reached the app and returned 400, as the page says

  • CI: all checks pass (CI passed, Docs, Test, PR title, CodeQL, Read the Docs preview)

What's unverified

  • No Ingress controller, cert-manager or TLS in the local run: the Ingress was rendered, not served, and the restriction of writes at an Ingress controller wasn't tested (the page links TRS-Filer's examples and asks operators to check it with a POST)
  • TESK wasn't installed (only rendered): its install needs LS Login values to be useful, and the rest of the Node tutorial is unchanged from docs: add a Node onboarding tutorial #125
  • Registration and verification in the Cloud Registry of the deployment, and whether the TRS type is registered there (the page says to ask the admins if it is missing)

Declined review findings

Light lane, no reviewer subagents. Sourcery (round 1, 6 findings), fixed in 890bad5: TRS-Filer is now installed without Ingress or Route first and exposed only with the restriction of writes in the values, then checked with a POST that must print 403; the NetworkPolicy is required on clusters shared with untrusted workloads; the prerequisites list every object kind of the chart, and openssl and curl. Declined:

  • Passwords on the kubectl create secret command line: kept as in TRS-Filer's own quick start, which the page follows; visible only while kubectl runs on the operator's machine.
  • Stop on empty openssl output: only partly done (openssl listed as a tool); the commands stay as in TRS-Filer's docs.

Open questions

None.

🤖 Generated with Claude Code

uniqueg and others added 2 commits November 13, 2026 09:33
Add a tutorial for data centres that offer storage for tasks, or tools
and workflows through TRS-Filer 0.5.0: MongoDB credentials, download
and check of the released chart, the service info overlay, the
restriction of writes, the installation, and the registration and
verification in the Cloud Registry. DRS-Filer, write tokens and the
service info value of the chart are marked as planned.

Update the Node tutorial for the release of TESK chart 0.3.0: install
from the release after checking its attestation and signature, inline
the test task, fix the anchor of the service info link, and point data
centres to the new tutorial. Link it from the nav, the section index,
Onboarding and the TRS-Filer page.

Refs #113

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sourcery-ai

sourcery-ai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Reviewer's Guide

Configuration

Add the data-centre tutorial to the operator navigation so readers can find it alongside the Node tutorial.

  • mkdocs.yml L93

Documentation

Add the data-centre onboarding tutorial and link it from the operator index, onboarding checklist, and TRS-Filer page.

  • docs/operators/data-centre-onboarding-tutorial.md L1-335
  • docs/operators/index.md L42
  • docs/operators/onboarding.md L8-9
  • docs/operators/services/trsfiler.md L16-17

Update the Node tutorial for the released TESK chart and direct data-centre operators to their dedicated tutorial.

  • docs/operators/node-onboarding-tutorial.md L8-11, L92-111, L276-292 (+6 small edits)

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@read-the-docs-community

read-the-docs-community Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

@uniqueg
uniqueg marked this pull request as ready for review November 13, 2026 08:39

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 6 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="docs/operators/data-centre-onboarding-tutorial.md" line_range="212" />
<code_context>
+      issuer: letsencrypt-prod
+    # The restriction of writes of your Ingress controller, e.g., the
+    # annotations of the example in "Ingress and Route"
+    annotations: {}
+```
+
</code_context>
<issue_to_address>
**Public TRS writes remain open**

When the operator copies the sample values unchanged and the Ingress controller has no separate write restriction, `helm upgrade --install` creates the public Ingress with no write-restriction annotations, so unauthenticated clients can register, replace, and delete tools until the later POST check detects the problem.

Provide a working restrictive configuration for a supported Ingress, or keep the Ingress disabled until the operator has configured and verified the restriction.
</issue_to_address>

### Comment 2
<location path="docs/operators/data-centre-onboarding-tutorial.md" line_range="187" />
<code_context>
+  Route][trsfiler-ingress] has examples for ingress-nginx and the
+  OpenShift router; with other controllers or the Gateway API, use their
+  means.
+- If your cluster enforces NetworkPolicies, let only the Ingress controller
+  or router connect to the app (`trs_filer.networkPolicy`), and trust
+  forwarded headers only from them (`trs_filer.forwardedAllowIps`; see
</code_context>
<issue_to_address>
**Cluster traffic bypasses ingress controls**

When TRS-Filer runs on a shared cluster with untrusted workloads and no effective NetworkPolicy limiting access to the app, pods in other namespaces can call the TRS-Filer service directly, bypassing the Ingress method restrictions; because TRS-Filer has no authentication, their write requests can register, replace, or delete tools.

Require an effective policy that permits connections only from the Ingress or router, or explicitly require an isolated cluster with no untrusted workloads able to reach the service.
</issue_to_address>

### Comment 3
<location path="docs/operators/data-centre-onboarding-tutorial.md" line_range="103-105" />
<code_context>
+kubectl create namespace trs
+kubectl create secret generic trs-filer-mongodb-credentials -n trs \
+    --from-literal=root-username=root \
+    --from-literal=root-password="$(openssl rand -hex 24)" \
+    --from-literal=username=trs-filer \
+    --from-literal=password="$(openssl rand -hex 24)"
+```
+
</code_context>
<issue_to_address>
**MongoDB passwords leak to local users**

When another user can inspect process arguments on the operator's host while `kubectl create secret` is running, the shell expands both generated passwords into `kubectl` command-line arguments, so a local user who can inspect process arguments while the command runs can capture the MongoDB credentials and use them wherever the database is reachable.

Create the Secret from password files with restrictive permissions, then securely remove those files after creation.
</issue_to_address>

### Comment 4
<location path="docs/operators/data-centre-onboarding-tutorial.md" line_range="46-47" />
<code_context>
+
+- **A cluster.** A Kubernetes or OpenShift cluster, a namespace of your
+  own for TRS-Filer, e.g., `trs`, and the right to create Deployments,
+  Services, ConfigMaps, Secrets, Jobs, Roles and RoleBindings in it (the
+  chart's configuration Job gets a Role in the namespace, see [Security
+  notes][trsfiler-security-notes]).
+- **Tools:** `kubectl`, [Helm](https://helm.sh/) 3, and, to check the
</code_context>
<issue_to_address>
**Installation fails for missing permissions**

When the operator is granted only the permissions listed in the prerequisites, helm cannot create the chart's persistent volume claim, StatefulSet, or enabled Ingress or OpenShift Route, so installation fails with authorization errors and TRS-Filer does not come up.

List the permissions needed to create the chart's persistent volume claim, StatefulSet, and enabled Ingress or OpenShift Route in the prerequisites.
</issue_to_address>

### Comment 5
<location path="docs/operators/data-centre-onboarding-tutorial.md" line_range="103-105" />
<code_context>
+kubectl create namespace trs
+kubectl create secret generic trs-filer-mongodb-credentials -n trs \
+    --from-literal=root-username=root \
+    --from-literal=root-password="$(openssl rand -hex 24)" \
+    --from-literal=username=trs-filer \
+    --from-literal=password="$(openssl rand -hex 24)"
+```
+
</code_context>
<issue_to_address>
**Generated credentials leave MongoDB unusable**

When openSSL is unavailable or password generation fails, `openssl rand` produces empty command substitutions, but `kubectl create secret` still succeeds with those values, leaving MongoDB with unusable credentials and TRS-Filer unable to connect.

List OpenSSL as a prerequisite and make the commands stop if password generation fails or produces an empty value.
</issue_to_address>

### Comment 6
<location path="docs/operators/data-centre-onboarding-tutorial.md" line_range="234-235" />
<code_context>
+writes are refused from an address that isn't trusted:
+
+```bash
+curl -X POST https://trs.example.org/ga4gh/trs/v2/tools \
+    -H 'Content-Type: application/json' -d '{}'
+```
+
</code_context>
<issue_to_address>
**HTTP errors appear to pass the check**

When the POST receives an HTTP error response, `curl` prints the response body without showing the HTTP status or exiting unsuccessfully, so operators cannot distinguish the required 403 from an application-level 400 and the check appears to succeed.

Make the command display the HTTP status and explicitly verify that it is 403.
</issue_to_address>

Sourcery assessment

Approval pending. 6 findings to address first.

Blocking findings: docs/operators/data-centre-onboarding-tutorial.md:212, docs/operators/data-centre-onboarding-tutorial.md:187, docs/operators/data-centre-onboarding-tutorial.md:105, docs/operators/data-centre-onboarding-tutorial.md:47, docs/operators/data-centre-onboarding-tutorial.md:105, and 1 more


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Install TRS-Filer without an Ingress or Route first, check it through a
port forward, and expose it only with the restriction of writes in the
values, then check that a POST prints 403. Require a NetworkPolicy on
clusters shared with untrusted workloads, list all object kinds the
chart creates, and add openssl and curl to the tools.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg
uniqueg merged commit 823d494 into main Nov 13, 2026
17 checks passed
@uniqueg
uniqueg deleted the docs/113-data-centre-tutorial branch November 13, 2026 09:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant