[nellshamrell]

Summary

Make the PostgreSQL tutorial explicitly choose the certificate-free development mode introduced by radius-project/resource-types-contrib#394: database tls: 'disabled' and client PGSSLMODE=disable.

Document the resulting plaintext traffic, unchanged password authentication, certificate requirements for the other modes, and Azure's rejection of disabled. Update the generated TLS reference and explain which compatible artifacts must be adopted before using the tutorial.

Replace the direct PostgreSQL AVM example with Azure Blob Storage. The page still teaches how to reuse an existing module, without showing a PostgreSQL recipe that bypasses the TLS policy guard.

Reason for change

The corrected recipes enforce the default required policy. A certificate-free demo must therefore select disabled explicitly rather than rely on the recipe accepting plaintext despite its configuration. This mode is for private, disposable Kubernetes environments only.

Keep this PR in draft. Compatible schema/extension/recipes must be published and adopted, and the final sample must match samples edge. The reduced sample now contains only the two TLS settings; its image parameter and password-description changes were removed. It no longer matches the broader samples candidate until that source is reconciled.

Issue closure: N/A.

Unrelated improvements were removed and tracked separately: password delivery, tutorial accuracy and deployment checks, storage and cleanup guidance, Bicep validation, and radius-project/samples#2697 for the image override and sample coordination.

How to test

Results after the scope reduction at 2bd16a3:

Command / check	Result
npm --prefix docs run build	Passed: 243 pages, 58 static files; existing Docsy deprecation warning.
npx --yes cspell lint --config .github/configs/.cspell.yml --no-progress --dot '**/*.md'	Passed: 184 files, zero issues.
python -B .github/scripts/validate_bicep.py	Failed with the existing local extension: BCP037 rejects tls. Compatible artifacts remain required. The validator is restored to its original behavior.
Rendered tutorial and sample-byte assertions	Passed: both TLS settings render, removed verification/password-file sections are absent, and served sample bytes match the source file.
git diff --check d67dc7d -- docs .github	Passed for the reduced PR diff. The inverse commit restores one pre-existing whitespace-only line in the unchanged validator.
Public tutorial and clean upstream sample sync	Not run for this reduced revision; blocked by artifact adoption and upstream sample reconciliation.

Additional checks for the storage example in be36c5a0:

Command / check	Result
npm --prefix docs run build	Passed in the working tree: 243 pages, 58 static files; existing Docsy warning. Uncommitted getting-started edits were present but are not part of this commit.
npx --yes cspell lint --config .github\configs\.cspell.yml --no-progress docs\content\management\existing-recipes\_index.md	Passed: one file, zero issues.
bicep.exe build recipe-pack.bicep --stdout	Passed using Bicep 0.42.1 and the exact extracted example.
bicep.exe build module-contract.bicep --stdout	Passed using Bicep 0.42.1: a direct module call checked the documented inputs and outputs against Storage Account AVM 0.32.1. Both compilation fixtures are local validation artifacts, not repository files.
Rendered storage-example assertions	Passed: storage mappings and context expressions render; the PostgreSQL example and warning are absent.
git diff --check -- docs\content\management\existing-recipes\_index.md	Passed before committing.
Azure deployment	Not run. Compilation is not live deployment evidence.

The generated reference is still based on the contrib candidate, not a released schema. Earlier live tests exercised the broader candidate with local artifacts and CLI adaptations; they do not establish acceptance of this reduced revision or the public tutorial.

File change summary

File	Summary of change
docs/static/samples/demo/app-postgresql.bicep	Add only tls: 'disabled' and PGSSLMODE=disable.
docs/content/getting-started/add-connection/_index.md	Explain the selected policy, risks and client setting; update sample highlights.
docs/content/getting-started/install-radius/_index.md	Add TLS compatibility and adoption prerequisites.
docs/content/reference/resources/radius.data/2025-08-01-preview/postgresqldatabases/index.md	Update the candidate-generated TLS policy row.
docs/content/management/existing-recipes/_index.md	Replace the direct PostgreSQL AVM example with Azure Blob Storage, including container inputs, secret output mappings and naming/network constraints.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[nellshamrell]

That sentence covers the practical changes that make the tutorial match the PostgreSQL demo and make its results easier to verify:

• Replace stale Redis text. The overview and deployment page still told readers they would add Redis. The sample actually adds PostgreSQL and an authored password Secret, with a separate connection to each. The text now describes those resources.

• Keep the password out of command arguments. The deployment block generates a random, URL-safe hexadecimal password and writes it to an ARM JSON parameter file. A restrictive umask gives the temporary directory mode 0700 and the file mode 0600. rad deploy receives the file path rather than the password itself. An exit trap removes the file and directory when the command succeeds or fails. This reduces exposure through shell history and process listings; it does not encrypt database traffic.

• Find the namespace instead of assuming it. A Recipe's Kubernetes runtime namespace can differ from the Environment's configured namespace. The tutorial finds the actual demo and database Deployments by their Radius labels, then uses their namespaces for rollout checks, port forwarding and database queries.

• Wait for both workloads. A successful Radius deployment is not enough to show that the current demo and PostgreSQL pods are ready. The tutorial waits for both Deployment rollouts before testing, so an old pod cannot quietly stand in for the new configuration.

• Verify storage and the actual connection. Readers create a todo, mark it complete, refresh, and query PostgreSQL to confirm the completed row exists. They then delete it and confirm the row is gone. Separately, SHOW ssl checks the server setting, while pg_stat_ssl checks the connection from the current demo pod's IP. An empty session query is not a pass, and a separate test client would not prove how the demo connects.

• Explain the risks and limit cleanup. Password authentication remains enabled, but disabled TLS leaves credentials and queries exposed in transit. The demo belongs only on a private, disposable cluster. The database Recipe has no explicit durable volume, so pod replacement can lose data. Cleanup deletes the tutorial application and its database/Secret resources, not entire namespaces or unrelated resources. Radius purge is optional and only appropriate for a dedicated disposable installation.

The local candidate run verified the deployment, CRUD, actual plaintext connection and scoped deletion. It also found that three tutorial commands still use a retired --preview flag, so the unchanged tutorial is not yet ready to call fully working. This candidate run does not establish published-artifact acceptance.