Skip to main content
Version: v0.2.0

Running the protoconf agent

Running protoconf in a production environment requires careful consideration to ensure reliability, security, and ease of maintenance. This guide provides some best practices and recommendations for running protoconf in production.

Installing protoconf​

You can install protoconf directly onto your server or use Docker. On Linux and macOS hosts, the install script is the standard way to put the binary in place:

curl -s https://protoconf.dev/install | sh

In production, pin the release you qualified instead of tracking the latest one, and name the install directory explicitly so the result does not depend on which directories happen to be writable:

curl -s https://protoconf.dev/install | sh -s -- --version v0.2.0 --dir /usr/local/bin

The script verifies the download against the checksums published with the release. See Getting Started for the full set of options.

Docker images are available on Docker Hub and GitHub Container Registry:

# Docker Hub
docker pull protoconf/protoconf:v0.2.0

# GitHub Container Registry
docker pull ghcr.io/protoconf/protoconf:v0.2.0

Pin an explicit tag in production rather than tracking a floating one.

For macOS, you can also use brew to install protoconf:

brew install protoconf/tap/protoconf

Configuration Management​

Keep all configuration files in a version control system (like Git) to track changes and easily revert to previous versions if needed.

Security​

Secure sensitive configuration data using environment variables or secure storage solutions. Do not hard-code sensitive data in configuration files.

Config Backend​

In a production environment, you should use a key-value store as a config backend. Protoconf supports Consul, etcd, ZooKeeper and, since v0.2.0, Kubernetes ConfigMaps as config backends. To specify the config backend, use the -store flag and provide the address of the store with the -store-address flag. For example:

protoconf agent -store consul -store-address 10.0.0.1:8500

You can also specify a key prefix to be used in the key-value store with the -prefix flag:

protoconf agent -store consul -store-address 10.0.0.1:8500 -prefix myproject

Protoconf Agent​

In a production environment, the protoconf agent should be run as a service, either natively or within a container, depending on your infrastructure.

The agent has several configuration options:

  • -grpc-address: The address for the gRPC interface (default is :4300).
  • -http-address: The address for the admin HTTP interface, which serves /metrics, /debug/pprof and GET /v1/config/... (default is :4380).
  • -dev: Development mode. Watch a local Protoconf directory for file changes. This should not be used in production.
  • -enable-rollout: Resolve staged rollouts.
  • -enable-otel: Export OpenTelemetry traces and metrics. See Observability.
  • -log-level, -log-as-json, -log-source: Control structured logging.

For example, to start the agent with specific gRPC and HTTP addresses:

protoconf agent -grpc-address :5000 -http-address :9000

Every option is also settable through a PROTOCONF_AGENT_* environment variable or a -config-file. The full list, and the precedence between the three, is in the CLI Configuration Reference.

caution

The admin HTTP listener is unauthenticated and unencrypted, and since v0.2.0 it also serves config reads at GET /v1/config/.... Bind it to an internal interface.

Monitoring​

Scrape /metrics on the agent's admin listener with Prometheus, and monitor the agent's logs for potential issues. -log-as-json makes the logs usable by a log pipeline without extra parsing. If you run OpenTelemetry, -enable-otel exports traces and metrics to your collector. See Observability for the metrics, spans and flags.

Updates and Migrations​

When updating protoconf or migrating to new versions of your configuration, test changes in a staging environment first. Ensure that new configurations are compatible with your applications and that there are no disruptions in service.

Integrations​

Ensure protoconf integrates smoothly with your deployment pipeline. It can be used in conjunction with various CI/CD tools and platforms like Jenkins, CircleCI, Kubernetes, and others.

Troubleshooting​

Keep a record of common issues and their solutions for easy reference. Encourage open communication within your team to ensure everyone is aware of any ongoing issues and their resolutions.

Remember, each production environment is unique. Always consider your specific requirements and constraints when deciding how to run and manage protoconf in production.