Inserting Configurations

Once you have your configurations defined and validated, you can insert them into your key-value store using the protoconf insert command. This command enables protoconf to manage your configurations in a distributed manner, making them available to your applications wherever they are running.

Basic Usage

The basic usage of the protoconf insert command is as follows:

protoconf insert -store <store> -store-address <store-address> <config>...

The <store> parameter specifies the type of key-value store you are using: consul, zookeeper, etcd, or — since v0.2.0 — configmaps. The <store-address> parameter is the address of your key-value store.

The <config>... parameters are one or more configuration paths that you want to insert. These paths correspond to the paths that your applications will use when requesting configurations from the protoconf agent.

For example, to insert the default and debug configurations for the myproject/server_config into an Etcd store:

protoconf insert -store etcd -store-address etcd:2379 myproject/server_config/default myproject/server_config/debug

Note that the user running this command needs to have access to the key-value store.

Metadata

Each insertion records where the configuration came from: the commit, the committer and author, and when it was committed, authored and inserted. The agent reports that metadata as labels on its config version metric, which is what lets you answer "which commit is this host actually running?" during an incident.

The inserter reads this from the git repository it is run in, so run protoconf insert from a checkout rather than from a bare copy of materialized_config/.

Staged Rollouts

A configuration compiled with a ConfigRollout is not inserted all at once. protoconf insert publishes each stage in turn, waits out its cooldown, and promotes the config to stable only after the last stage. The command stays in the foreground for the whole plan, and interrupting it rolls every agent back to the stable config.

See Staged Rollouts.

Deleting Configurations

You can also delete configurations from your key-value store using the -d option:

protoconf insert -d -store <store> -store-address <store-address> <config>...

This command will remove the specified configurations from your store.

Webhook Usage

In many cases, you may want to insert or update configurations in response to events like commits or merges in your version control system. Protoconf supports this use case by providing a container that can accept webhooks from GitHub or GitLab.

By configuring your repository to send webhooks to this container, you can ensure that your configurations are always up-to-date with your latest code changes. This can be particularly useful in a continuous integration/continuous delivery (CI/CD) workflow.