Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.
Rust
docs(relay): clarify stable plugin bundle installation and validation (#746)
Bryan Bednarski3ddea9d30174
diff --git a/crates/switchyard-nemo-relay-plugin/README.md b/crates/switchyard-nemo-relay-plugin/README.mdindex fa1aaedd9..ff4d43b8c 100644--- a/crates/switchyard-nemo-relay-plugin/README.md+++ b/crates/switchyard-nemo-relay-plugin/README.md@@ -14,18 +14,35 @@ The plugin requires NeMo Relay `>=0.8.0, <1.0.0`.### Install a released bundle-Released bundles are published in the+Official plugin bundles are distributed through the[NeMo Relay Plugins repository](https://github.com/NVIDIA/NeMo-Relay-Plugins/releases).-Find the `switchyard-plugin` release that corresponds to the Switchyard version-or source commit you need. The release's `.json` sidecar records the exact-Switchyard source commit and Relay version used to validate each platform-artifact.--Download the archive and matching `.sha256` file for your platform, verify the-checksum, extract the archive into a directory you plan to keep, then register-the extracted `relay-plugin.toml` with Relay using step 3 below. The release-version is independent of the Switchyard workspace version, so use the release-metadata rather than assuming that version numbers match.+Each bundle includes the native library, a completed `relay-plugin.toml`, the+configuration schema, and license notices. Installing a bundle requires no+Rust build or separate `switchyard-nemo-relay-plugin` crate installation.++The repository currently requires NVIDIA GitHub repository access. Sign in+with an account that has access and complete organization SSO/SAML authorization+where required, including for credentials used by `gh`. An HTTP 404 can mean+that your account or credentials lack access; it does not prove that a bundle+is missing.++1. Select a published `switchyard-plugin-<version>` release for Switchyard+ `0.3.0`. Plugin versions are managed separately and can match the Switchyard+ version. Confirm the source commit in the release notes and `.json` metadata+ rather than relying on the version number alone. A Switchyard release does+ not itself publish a plugin bundle. If no matching published bundle is+ available, use [Build from source](#build-from-source).+2. Download the archive for your platform and its matching `.sha256` and `.json`+ sidecars. For Linux x86_64, the archive is named+ `switchyard-plugin-<version>-linux-x86_64.tar.gz`. Check the metadata's+ `source_commit`, `platform`, and `relay` fields for the source and tested host.+3. Verify the downloaded archive against its `.sha256` file before extracting+ it. On Linux, run `sha256sum -c <archive>.sha256` from the download directory,+ replacing `<archive>` with the archive's filename.+4. Extract the archive into a directory you plan to keep, then follow+ [Register and enable the plugin](#register-and-enable-the-plugin). Use the+ actual path to the extracted `relay-plugin.toml`; the examples below use+ `./plugins/switchyard/relay-plugin.toml`.### Build from source@@ -68,7 +85,11 @@ python crates/switchyard-nemo-relay-plugin/scripts/package_bundle.py \Pass `--archive switchyard-plugin.tar.gz` (or `.zip`) to also produce anarchive for distribution.-**3. Register the plugin.**+### Register and enable the plugin++These steps apply to both a downloaded bundle and a bundle built from source.++**1. Register the plugin.**```bashnemo-relay plugins validate ./plugins/switchyard/relay-plugin.toml@@ -80,10 +101,10 @@ nemo-relay plugins add --user ./plugins/switchyard/relay-plugin.tomlThe plugin is not enabled yet; enabling before the deployment is configuredfails validation because the plugin requires a Switchyard configuration.-**4. Configure the deployment and trust policy** in that `plugins.toml`, as+**2. Configure the deployment and trust policy** in that `plugins.toml`, asdescribed in [Configure Relay](#configure-relay).-**5. Enable and validate the plugin**, then restart Relay. The manifest ships+**3. Enable and validate the plugin**, then restart Relay. The manifest shipswith `enabled = false`; Relay validates a disabled plugin but never loads it.```bashdiff --git a/docs/integrations/nemo_relay.md b/docs/integrations/nemo_relay.mdindex be96a9da5..aec8465c7 100644--- a/docs/integrations/nemo_relay.md+++ b/docs/integrations/nemo_relay.md@@ -125,11 +125,27 @@ and## Set Up the Plugin-Follow the [plugin README](../../crates/switchyard-nemo-relay-plugin/README.md)-to install a released bundle from the-[NeMo Relay Plugins repository](https://github.com/NVIDIA/NeMo-Relay-Plugins/releases)-or build and package the native library from source, then register and enable-it in Relay and configure its deployment. Relay documents how to+For Switchyard `0.3.0`, select a matching published `switchyard-plugin` bundle+from the+[NeMo Relay Plugins releases](https://github.com/NVIDIA/NeMo-Relay-Plugins/releases).+Confirm its Switchyard source commit in the release metadata. Plugin versions+are managed separately and can match the Switchyard version. The bundle+includes the native library, completed manifest, schema, and license notices;+no separate plugin crate installation is needed.++The repository currently requires NVIDIA GitHub repository access and+organization SSO/SAML authorization where required. An HTTP 404 can indicate+missing access. A Switchyard release does not guarantee that a matching plugin+bundle has been published.++Follow the+[bundle installation steps](../../crates/switchyard-nemo-relay-plugin/README.md#install-a-released-bundle)+to download the archive and sidecars, verify the checksum, and extract the+bundle. If a matching published bundle is unavailable or you need a custom+build, follow+[Build from source](../../crates/switchyard-nemo-relay-plugin/README.md#build-from-source).+Then register the manifest, configure the deployment and trust policy, enable+the plugin, and restart Relay. Relay documents how to[add and enable a discoverable plugin](https://docs.nvidia.com/nemo/relay/configure-plugins/discoverable-plugins#add-and-enable-a-plugin)and how it[validates the package before loading code](https://docs.nvidia.com/nemo/relay/configure-plugins/discoverable-plugins#validate-before-loading-code).diff --git a/docs/internal/release_workflow.md b/docs/internal/release_workflow.mdindex 10285724b..0d0ae38ed 100644--- a/docs/internal/release_workflow.md+++ b/docs/internal/release_workflow.md@@ -102,6 +102,42 @@ can publish all seven crates and create new crates. The job waits for each versicrates.io index before publishing its dependents. If publication stops partway through, useGitHub's **Re-run failed jobs** action so successful crate jobs are not repeated.+## Relay Plugin Bundles++Official Relay plugin bundles are built and distributed by+[NeMo Relay Plugins](https://github.com/NVIDIA/NeMo-Relay-Plugins/releases).+They contain the native library, completed manifest, schema, and license+notices. This delivery path does not require publishing+`switchyard-nemo-relay-plugin` to crates.io or adding it to the crate list above.++For Switchyard `0.3.0`, coordinate a plugin release pinned to the intended+Switchyard release commit. The plugin's `release.toml` records its own version+and `source.sha`. Versions can match, but the source pin establishes which+Switchyard code is bundled. Follow the plugin repository's+[release process](https://github.com/NVIDIA/NeMo-Relay-Plugins/blob/main/RELEASE.md)+to review and publish its draft. A Switchyard tag alone does not publish it.++Keep source-build validation and published-bundle validation as separate QA+results. Before publication, build and package the exact source revision under+test. Passing that path does not validate the eventual downloaded archive,+sidecars, or repository access. Keep published-bundle validation pending until+the official release is available.++After publication, validate the delivery path from+[the user installation guide](../../crates/switchyard-nemo-relay-plugin/README.md#install-a-released-bundle):++1. Confirm the intended users can access the published release. Verify the+ documented repository access and SSO/SAML requirements.+2. Download each supported platform's archive and matching `.sha256` and+ `.json` sidecars from that release. Verify the archive checksum and check+ the metadata's source commit, platform, and tested Relay version.+3. Extract the downloaded archive into a fresh installation directory. Follow+ the documented registration, deployment configuration, trust policy, and+ enablement steps using a supported official Relay runtime.+4. Restart Relay and run a routed-request smoke test with the installed bundle.+ Record the release tag, source commit, archive checksum, platform, Relay+ version, and result. A local rebuild is not a substitute for this check.+## Local Metadata HelperTo preview the metadata stamp locally: