From 32e168939e1549daeb4cd597bea76698fa99f5d8 Mon Sep 17 00:00:00 2001 From: Shahar Mintz Date: Thu, 3 Sep 2026 02:52:21 +0000 Subject: [PATCH 01/11] docs: prepare the site for the v0.2.0 release Cut the docs version and document everything v0.2.0 adds over v0.1.7. Versioning: - Rename vesrions.json to versions.json. The typo meant Docusaurus never loaded versioned_docs/, so the archived 0.1.7 tree was dead weight and the version dropdown had nothing to switch to. - Snapshot the current docs as version-0.1.7 and move "current" to v0.2.0, served at /docs/0.2.0. Point the homepage and footer links at it. New pages: - What's New in v0.2.0, including the two upgrade-affecting changes (config precedence, telemetry now opt-in). - Remote Modules: CONFIGSPACE, protoconf.lock, protoconf mod, @repo// loads. - Staged Rollouts: ConfigRollout/RolloutStage, channel and percentile targeting, cooldowns and expiry. - Running on Kubernetes: the configmaps backend, RBAC, key-to-ConfigMap mapping. - Observability: Prometheus metrics, opt-in OTel, structured logging. - Formatting Starlark Sources: protoconf fmt. - CLI Configuration Reference: precedence, and the flag/env pair for every option on every component. Updated pages: - consume-config-updates: current service definition, GetConfig, and the plain-HTTP GET /v1/config/... endpoint. - validation: protovalidate constraints alongside the Starlark validators. - getting-started: install options, fmt, devserver, next steps; fix the missing duration.proto import and the materialized_config path. - running-in-production: configmaps, correct -http-address default (:4380, was documented as :9143), rollout/otel/log flags. - inserting-configurations, production-architecture: configmaps, metadata, rollouts. Also bump @mdx-js/react to ^3.0.0. Docusaurus 3 needs it; on v1 the theme's Heading component never loaded, so no page had anchor links and every build reported its own headings as broken anchors. Both are gone now. Add the v0.2.0 release announcement to the blog. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01JvFenuqwiFW5vS3kf1Ezo8 --- README.md | 2 +- blog/2026-09-03-protoconf-0-2-0.mdx | 118 ++++++++++ docs/advanced-usage/_category_.json | 4 +- docs/advanced-usage/formatting.mdx | 60 +++++ docs/advanced-usage/modules.mdx | 112 ++++++++++ docs/cli-reference.mdx | 208 ++++++++++++++++++ docs/consume-config-updates.mdx | 89 +++++++- docs/getting-started.mdx | 61 ++++- docs/integrations/_category_.json | 4 +- docs/intro.md | 6 + docs/production/_category_.json | 4 +- docs/production/inserting-configurations.mdx | 24 +- docs/production/kubernetes.mdx | 149 +++++++++++++ docs/production/observability.mdx | 106 +++++++++ docs/production/production-architecture.mdx | 7 +- docs/production/rollouts.mdx | 129 +++++++++++ docs/production/running-in-production.mdx | 31 ++- docs/validation.mdx | 62 +++++- docs/whats-new-0.2.0.mdx | 141 ++++++++++++ docusaurus.config.js | 9 +- package.json | 2 +- src/pages/index.module.css | 2 + src/pages/index.tsx | 11 +- .../version-0.1.7/getting-started.mdx | 2 +- versions.json | 3 + vesrions.json | 3 - yarn.lock | 5 - 27 files changed, 1313 insertions(+), 41 deletions(-) create mode 100644 blog/2026-09-03-protoconf-0-2-0.mdx create mode 100644 docs/advanced-usage/formatting.mdx create mode 100644 docs/advanced-usage/modules.mdx create mode 100644 docs/cli-reference.mdx create mode 100644 docs/production/kubernetes.mdx create mode 100644 docs/production/observability.mdx create mode 100644 docs/production/rollouts.mdx create mode 100644 docs/whats-new-0.2.0.mdx create mode 100644 versions.json delete mode 100644 vesrions.json diff --git a/README.md b/README.md index aaba2fa..0c6c2c2 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Website -This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. +This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. ### Installation diff --git a/blog/2026-09-03-protoconf-0-2-0.mdx b/blog/2026-09-03-protoconf-0-2-0.mdx new file mode 100644 index 0000000..ca4dfeb --- /dev/null +++ b/blog/2026-09-03-protoconf-0-2-0.mdx @@ -0,0 +1,118 @@ +--- +slug: protoconf-0-2-0 +title: Protoconf v0.2.0 +authors: [smintz] +tags: [protoconf, release] +--- + +Protoconf v0.2.0 is out — the first feature release since v0.1.7. It brings +remote proto modules, staged rollouts, a Kubernetes ConfigMaps backend, one-shot +config reads over gRPC and plain HTTP, opt-in OpenTelemetry, a formatter, and a +single consistent configuration story across every command. + +{/* truncate */} + +## Remote modules + +Configuration repositories can now depend on protos and Starlark that live +somewhere else. Declare the dependency in a `CONFIGSPACE` file, pin it to a tag, +branch, commit or checksum, and let `protoconf mod tidy` resolve it into +`protoconf.lock` and a local cache: + +```python title=CONFIGSPACE +platform_protos = remote_repo( + url = "github.com/acme/platform-protos", + tag = "v1.4.0", +) +``` + +```python title=./src/myproject/server_config.pconf +load("@platform_protos//platform/v1/service.proto", "Service") +``` + +The lock file is what makes a compile reproducible — commit it next to your +configs. [Remote Modules →](/docs/0.2.0/advanced-usage/modules) + +## Staged rollouts + +A configuration change is a deploy, and v0.2.0 lets you treat it like one. Wrap +a config in a `ConfigRollout` and it reaches a canary channel first, then a +percentage of your fleet, with a cooldown between each stage: + +```python +def main(): + return ConfigRollout( + value = ServerConfiguration(max_connections = 2000), + default_cooldown_time = Duration(seconds = 300), + stages = [ + RolloutStage(channel = "canary"), + RolloutStage(percentile = 10), + RolloutStage(percentile = 50), + ], + ) +``` + +Agents started with `-enable-rollout` pick the first stage they match, hashing +their own identity so the same host lands in the same bucket every time. +Interrupting `protoconf insert` mid-rollout clears the plan and returns every +agent to the stable config. [Staged Rollouts →](/docs/0.2.0/production/rollouts) + +## Kubernetes ConfigMaps + +`configmaps` is a new key-value backend for both the agent and the inserter, so +a cluster can distribute protoconf configs without running Consul, etcd or +ZooKeeper alongside it: + +```bash +protoconf agent -store configmaps -namespace protoconf +``` + +[Running on Kubernetes →](/docs/0.2.0/production/kubernetes) + +## One-shot reads, including over HTTP + +Not every consumer is a long-running service. `GetConfig` is the unary +counterpart to `SubscribeForConfig`, for jobs, scripts and init containers. The +agent also transcodes it onto its admin HTTP listener, so anything that can make +an HTTP request can read a config: + +```bash +curl http://localhost:4380/v1/config/myproject/server_config +``` + +[Consuming Configuration Updates →](/docs/0.2.0/consume-config-updates#one-shot-reads) + +## Telemetry you opt into + +OpenTelemetry export is now off by default and enabled with `-enable-otel`. An +agent that is not asked to export traces installs no-op providers and contacts +nothing. Prometheus metrics stay where they were, on `/metrics`, no flag +required. [Observability →](/docs/0.2.0/production/observability) + +## `protoconf fmt` + +One canonical layout for `.pconf`, `.mpconf`, `.pinc`, `.proto-validator` and +`.star` files, and a `-l` mode to fail CI when something is unformatted: + +```bash +protoconf fmt -w . +``` + +[Formatting →](/docs/0.2.0/advanced-usage/formatting) + +## Two things to check when upgrading + +**Configuration precedence.** Every command now resolves configuration as +`flags > environment variables > config file > proto defaults`. `protoconf +agent` used to let a config file override `PROTOCONF_AGENT_*` environment +variables; it no longer does. With repeated `-config-file` flags, the later file +now wins. + +**Telemetry is off by default.** An agent that used to reach your collector +automatically needs `-enable-otel` now. + +The full list is in +[What's New in v0.2.0](/docs/0.2.0/whats-new-0.2.0), and the complete changelog +is on the [release page](https://github.com/protoconf/protoconf/releases/tag/v0.2.0). + +As always, we're on [Discord](https://discord.protoconf.sh) if you hit anything. diff --git a/docs/advanced-usage/_category_.json b/docs/advanced-usage/_category_.json index 97d1339..d160208 100644 --- a/docs/advanced-usage/_category_.json +++ b/docs/advanced-usage/_category_.json @@ -1,8 +1,8 @@ { "label": "Advanced Usage", - "position": 5, + "position": 6, "link": { "type": "generated-index", "description": "Learn more advanced techniques to use protoconf." } -} \ No newline at end of file +} diff --git a/docs/advanced-usage/formatting.mdx b/docs/advanced-usage/formatting.mdx new file mode 100644 index 0000000..cc394e9 --- /dev/null +++ b/docs/advanced-usage/formatting.mdx @@ -0,0 +1,60 @@ +--- +id: formatting +title: Formatting Starlark Sources +sidebar_position: 6 +--- + +# Formatting Starlark Sources + +:::info New in v0.2.0 +::: + +`protoconf fmt` formats protoconf's Starlark sources the way `gofmt` formats +Go — one canonical layout, no configuration, no debate in code review. + +It handles every Starlark extension protoconf uses: + +- `.pconf` — configuration files +- `.mpconf` — multi-output configuration files +- `.pinc` — shared includes +- `.proto-validator` — validation rules +- `.star` — plain Starlark + +## Usage + +```bash +# Print the formatted result of any file that is not already formatted, +# without changing anything on disk +protoconf fmt + +# Rewrite files in place +protoconf fmt -w . + +# Show what would change +protoconf fmt -d . + +# List only the files that are not formatted — useful in CI +protoconf fmt -l . +``` + +With no path arguments, `protoconf fmt` walks the current directory +recursively. You can also pass individual files or directories: + +```bash +protoconf fmt -w src/myproject/server_config.pconf src/shared/ +``` + +## In continuous integration + +`-l` prints the files whose formatting differs and is the check to run in CI: + +```yaml title=.github/workflows/protoconf.yml +- name: Check formatting + run: | + unformatted="$(protoconf fmt -l .)" + if [ -n "$unformatted" ]; then + echo "These files need 'protoconf fmt -w':" + echo "$unformatted" + exit 1 + fi +``` diff --git a/docs/advanced-usage/modules.mdx b/docs/advanced-usage/modules.mdx new file mode 100644 index 0000000..fc80746 --- /dev/null +++ b/docs/advanced-usage/modules.mdx @@ -0,0 +1,112 @@ +--- +id: modules +title: Remote Modules +sidebar_position: 5 +--- + +# Remote Modules + +:::info New in v0.2.0 +::: + +A configuration repository rarely owns every schema it needs. Remote modules +let a protoconf repository depend on `.proto` and Starlark files that live in +another repository or archive, pinned to an exact revision and cached locally — +the same shape as Go modules or Bazel external repositories. + +## Declaring dependencies + +Dependencies are declared in a file named `CONFIGSPACE` at the root of your +protoconf directory. It is a Starlark file with one builtin, `remote_repo`: + +```python title=CONFIGSPACE +platform_protos = remote_repo( + url = "github.com/acme/platform-protos", + tag = "v1.4.0", +) + +vizceral_repo = remote_repo( + label = "vizceral_repo", + url = "./internal/vizceral.tgz", + checksum = "896b13d56bd1787089ca5767656c7ef1", +) +``` + +Each `remote_repo` accepts: + +| Argument | Description | +| --- | --- | +| `url` | Where to fetch from — a Git repository, an archive URL, or a local path | +| `tag` / `branch` / `commit` / `checksum` | How the dependency is pinned. Provide exactly one | +| `label` | The name used to reference the module. Derived from the URL when omitted | +| `source_path` | Directory inside the repository holding the protos. Defaults to `src` | +| `additional_proto_dirs` | Extra directories to add to the proto import path | +| `exclude_file_regexps` | Patterns for files to skip | + +Pinning is not optional in practice: a `remote_repo` with no `tag`, `branch`, +`commit` or `checksum` resolves against a moving target, and protoconf prints a +warning telling you so. + +## Resolving and downloading + +`protoconf mod` turns `CONFIGSPACE` into a lock file and a local cache: + +```bash +# Resolve CONFIGSPACE into protoconf.lock +protoconf mod init + +# Download everything protoconf.lock pins into .protoconf_cache/ +protoconf mod sync + +# Both, in one step — the usual command +protoconf mod tidy +``` + +`protoconf.lock` records the resolved fetch URL and content hashes for every +dependency, including transitive ones: + +```json title=protoconf.lock +{ + "url": ".", + "deps": { + "vizceral_repo": { + "label": "vizceral_repo", + "url": "./internal/vizceral.tgz", + "checksum": "896b13d56bd1787089ca5767656c7ef1", + "sourcePath": "src", + "fileDescriptorSetSum": "039f1e1023250b34054894cc58bc8b2b" + } + } +} +``` + +Commit `protoconf.lock` alongside your configs — it is what makes a compile +reproducible. The `.protoconf_cache/` directory is derived and belongs in +`.gitignore`. + +## Loading from a module + +Inside a `.pconf`, `.mpconf` or `.pinc` file, reference a module with +`@