Design Plugin Configuration

Use this guide when a plugin needs more than a single flag or string to configure it safely.

What You Design

You will define the plugin’s configuration contract, validation rules, advanced configuration patterns, and runtime registration plan. The goal is to make plugin activation predictable for operators while keeping runtime objects and business logic inside the plugin implementation.

Plugin Shape and Requirements

A NeMo Relay plugin has four practical parts:

The top-level plugin document keeps activation consistent across bindings:

1
{
2
  "version": 1,
3
  "components": [
4
    {
5
      "kind": "header-plugin",
6
      "enabled": true,
7
      "config": {
8
        "header_name": "x-tenant",
9
        "value": "tenant-a"
10
      }
11
    }
12
  ],
13
  "policy": {
14
    "unknown_component": "warn",
15
    "unknown_field": "warn",
16
    "unsupported_value": "error"
17
  }
18
}

Keep the component config portable:

• Use JSON-compatible values only.
• Put clients, callbacks, file handles, and provider SDK objects in plugin code, not config.
• Include a component-local config version when the plugin’s own schema needs to evolve independently.
• Prefer references to secrets or endpoints over embedding sensitive values directly.
• Treat enabled: false as disabled for activation, not as a reason to skip validation.

Configuration Validation

Validation should be deterministic and side-effect free. It should inspect config and return diagnostics; it should not register middleware, open network connections, create clients, or mutate process state.

Check these areas:

• Required fields are present.
• Field types match the supported shape.
• Unknown fields are reported according to policy.
• Known fields have supported values.
• Cross-field combinations make sense.
• Environment-specific limitations are warnings unless they would make activation fail.

Diagnostics should be actionable and stable enough for tests or deployment automation:

1
[
2
  {
3
    "level": "error",
4
    "code": "header-plugin.missing_header_name",
5
    "component": "header-plugin",
6
    "field": "header_name",
7
    "message": "config.header_name is required"
8
  }
9
]

Use warning when the config can still activate but deserves operator attention. Use error when initialization should not proceed.

Advanced Configuration Patterns

These patterns help plugin authors keep configuration stable as components evolve.

Component-Local Versioning

Use a field such as config.version when the plugin’s config schema needs independent compatibility handling. Keep the top-level version for the NeMo Relay plugin document itself.

Multiple Component Instances

When a plugin can be instantiated more than once, require explicit instance identity in config:

1
{
2
  "kind": "routing-policy",
3
  "config": {
4
    "instance": "east-region",
5
    "priority": 100,
6
    "region": "us-east-1"
7
  }
8
}

Use the instance identity in logs, diagnostics, and downstream resource names. Let the NeMo Relay plugin system qualify runtime registration names; do not hand-build global names to avoid collisions.

Presets and Overrides

Presets are useful when most deployments use a known shape:

1
{
2
  "kind": "redaction-policy",
3
  "config": {
4
    "preset": "strict",
5
    "overrides": {
6
      "allow_fields": ["request_id", "tenant"]
7
    }
8
  }
9
}

Validate the resolved result, not only the literal input. Unknown preset names should be error diagnostics because the plugin cannot know what behavior to install.

Rollout Controls

For behavior that can affect execution, include explicit rollout fields:

• mode: for example observe_only, enforce, or disabled.
• priority: where middleware should run relative to other registrations.
• break_chain: whether a request intercept should stop later intercepts.
• sample_rate or tenants: when behavior should apply only to part of traffic.

Prefer observe-only defaults for new policies and execution-affecting intercepts.

Plugin Context

PluginContext is the component-scoped surface used during registration. It connects validated config to real runtime behavior.

Use PluginContext to register:

• Subscribers
• Tool guardrails
• Tool request and execution intercepts
• LLM guardrails
• LLM request, execution, and stream execution intercepts

The context gives the plugin system enough information to qualify runtime names and roll back partial setup if registration fails. Put all runtime registration work inside the registration hook so rollback can clean up correctly.

Avoid these patterns:

• Registering middleware before plugin initialization.
• Creating process-global state that is not owned by the plugin instance.
• Reusing one mutable object across component instances without tenant or request isolation.
• Encoding runtime callbacks inside JSON config.

Validation Checklist

Before publishing a plugin config contract:

1. Validate the smallest correct config.
2. Validate a config with each required field missing.
3. Validate each unsupported enum or mode.
4. Validate unknown fields under each supported policy.
5. Initialize a valid config and confirm expected middleware or subscribers are active.
6. Force a registration failure and confirm partial setup is rolled back.

Next Steps

Use these links to continue from this workflow into the next related task.

• Build the first plugin with Define a Plugin.
• Validate plugin config with Validate Plugin Configuration.
• Register runtime behavior with Register Plugin Behavior.
• Review reusable patterns in Code Examples.