Skip to content

[proof of concept] Add _reload directive support for config reload framework.#13110

Draft
brbzull0 wants to merge 2 commits intoapache:masterfrom
brbzull0:config_reload_add_directives
Draft

[proof of concept] Add _reload directive support for config reload framework.#13110
brbzull0 wants to merge 2 commits intoapache:masterfrom
brbzull0:config_reload_add_directives

Conversation

@brbzull0
Copy link
Copy Markdown
Contributor

Add _reload directive support to config reload framework

TL;DR

Adds a generic way to pass operational parameters to config reload handlers.
Instead of per-config flags like --virtualhost, handlers now receive directives
via a reserved _reload key that the framework extracts automatically.

traffic_ctl config reload -D virtualhost.id=myhost.example.com

Handlers read directives with ctx.reload_directives()["id"], while
ctx.supplied_yaml() stays clean (content only, no directives). Also fixes a bug
where stale RPC-supplied config data could replay on subsequent file-based reloads.


Summary

Config handlers sometimes need operational parameters that modify how a reload
is performed — for example, scoping a reload to a single entry by ID, or some other key to pass.
Currently there's no standard way to pass these parameters;
PR #13108 (virtualhost) works around this by adding a per-config --virtualhost flag
to traffic_ctl.

This PR adds a generic reload directive mechanism:

  • A reserved _reload key inside each config's YAML node carries directives
  • The framework extracts _reload before invoking the handler
  • traffic_ctl gains a --directive (-D) flag with dot-notation syntax
  • Handlers access directives via ConfigContext::reload_directives()

Motivation

The virtualhost PR (#13108) needs to tell the handler which virtualhost to reload
from file. Without a generic mechanism, every config that needs parameters would require
its own traffic_ctl flag and custom parsing — leading to flag proliferation and
duplicated code.

The _reload directive solves this once for all handlers.

Usage

traffic_ctl CLI

# Reload a specific virtualhost from file
traffic_ctl config reload -D virtualhost.id=myhost

# Multiple directives (space-separated after single -D)
traffic_ctl config reload -D virtualhost.id=myhost virtualhost.foo=bar

# Directives for different handlers in the same reload
traffic_ctl config reload -D virtualhost.id=myhost sni.fqdn=example.com

# Complex directives via -d (full YAML)
traffic_ctl config reload -d 'virtualhost: { _reload: { id: myhost } }'

Wire format

-D virtualhost.id=myhost produces:

{
  "configs": {
    "my_config": {
      "_reload": { "id": "myhost" }
    }
  }
}

Handler API

void MyConfig::reconfigure(ConfigContext &ctx) {
    ctx.in_progress();

    if (auto directives = ctx.reload_directives()) {
        if (directives["id"]) {
            std::string id = directives["id"].as<std::string>();
            if (!reload_single_entry(id)) {
                ctx.fail("Unknown entry: " + id);
                return;
            }
            ctx.complete("Reloaded entry: " + id);
            return;
        }
    }

    if (!load_from_file(config_filename)) {
        ctx.fail("Failed to parse " + config_filename);
        return;
    }
    ctx.complete("Loaded from file");
}

Key behavior:

  • reload_directives() returns the extracted _reload YAML map
  • supplied_yaml() is clean — never contains _reload keys
  • Child contexts inherit directives from their parent
  • If _reload is not a YAML map, a warning is logged and directives are ignored

Changes

Framework (src/mgmt/config/)

  • ConfigContext: Added reload_directives() getter, set_reload_directives()
    setter, and propagation to child contexts via add_dependent_ctx()
  • ConfigRegistry::execute_reload(): Extracts _reload from the config's YAML
    node before passing content to the handler. Also fixes a bug where _passed_configs
    entries were not erased after consumption, causing stale RPC data to replay on
    subsequent file-based reloads

CLI (src/traffic_ctl/)

  • traffic_ctl.cc: Added --directive (-D) option to config reload
  • CtrlCommands.cc: Added parse_directive() helper that parses
    config_key.directive_key=value and injects into configs[key]["_reload"][dir] = val

Damian Meden added 2 commits April 21, 2026 14:02
Config handlers need a way to receive operational parameters (e.g.
scoping a reload to a single entry) without conflating them with
config content. This adds a reserved _reload key inside the configs
YAML node that the framework extracts before invoking handlers.

Framework: ConfigContext gains reload_directives() getter; the
_reload node is extracted in ConfigRegistry::execute_reload() and
stripped from supplied_yaml(). Fixes stale _passed_configs entries
not being erased after consumption.

CLI: traffic_ctl config reload gains --directive (-D) flag using
dot-notation (config_key.directive_key=value). Multiple directives
are space-separated after a single -D.

Tests: unit tests for parse_directive and ConfigContext directive
propagation; autest coverage for directive RPC structure handling.

Docs: developer guide and traffic_ctl reference updated.
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