Repository navigation
docs: add a data centre onboarding tutorial - #138
Conversation
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>
Reviewer's GuideConfigurationAdd the data-centre tutorial to the operator navigation so readers can find it alongside the Node tutorial.
DocumentationAdd the data-centre onboarding tutorial and link it from the operator index, onboarding checklist, and TRS-Filer page.
Update the Node tutorial for the released TESK chart and direct data-centre operators to their dedicated tutorial.
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Documentation build overview
5 files changed ·
|
There was a problem hiding this comment.
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
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>
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.
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:POST)./tesk,tesk/s3-config/); the test task is inlined (no checkout needed any more); the stale anchorconfiguration/#service-infoof the TESK docs is fixed (#service-info-serviceinfo); the "Data centres" section points to the new tutorial.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)
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 typeorg.ga4gh/trs/2.0.1, environmentdev)docs/deployment.md("From a release", requirements, auth),charts/tesk/values.yaml,examples/success/hello.json; release assetstesk-0.3.0.tgzand.sigstore.jsononboarding.md,service-info.md,using-cloud-registry.mdVerification
python scripts/check_names.py: no findingsmkdocs build --strict: built without warnings (after rebasing on main with docs: add the Krini user guide #137)pytest: 25 passed, 100% coverageExternal 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 verifyandcosign verify-blobsucceed fortesk-0.3.0.tgzandtrs-filer-0.5.0.tgz(andgh attestation verifyfails with a wrong--source-ref, as expected)helm lintandhelm 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 ConfigMapTRS-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-infoserved the values of the overlay (id: org.example.trs,environment: prod, typeorg.ga4gh/trs/2.0.1), and an unrestrictedPOST /toolswith{}reached the app and returned400, as the page saysCI: all checks pass (
CI passed, Docs, Test, PR title, CodeQL, Read the Docs preview)What's unverified
POST)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
POSTthat must print403; the NetworkPolicy is required on clusters shared with untrusted workloads; the prerequisites list every object kind of the chart, andopensslandcurl. Declined:kubectl create secretcommand line: kept as in TRS-Filer's own quick start, which the page follows; visible only while kubectl runs on the operator's machine.openssloutput: only partly done (openssl listed as a tool); the commands stay as in TRS-Filer's docs.Open questions
None.
🤖 Generated with Claude Code