Opni Agent
The Opni agent provides a secure channel for sending observability data from a downstream cluster to the central Opni cluster. The agent handles the responsibility of authenticating and connecting to the gateway, and loading plugins, wherein the majority of agent-side logic resides.
The Opni Agent attempts to have a simple architecture, with the majority of the logic residing in plugins, similar to the gateway. Unlike the gateway, it doesn't have many responsibilities outside of loading plugins and connecting to the gateway. The most complex parts of the agent are the startup and bootstrap processes, in addition to plugin synchronization.
The bootstrap process runs once, when an agent starts for the first time. The main goal is to generate a keyring, a set of secret keys and certificates. By the end of the bootstrap process, both the gateway and agent will have generated an identical keyring.
To run the bootstrap process, the agent must have:
- A valid bootstrap token generated from the Gateway Management API
- A trust strategy configured, with PKP (public key pinning) being the most common. To use PKP, you need to obtain a certificate fingerprint from the gateway. You can do this by running the command
opni certs infooropni certs pinfrom theopniCLI. There are also other trust strategies available to support less common use cases.
After the bootstrap process is complete, the agent discards the bootstrap token, and persists its keyring, which it uses to authenticate to protected gateway APIs.
The first thing the agent will do after bootstrapping is sync its plugin binaries with the gateway. There is a strict requirement that the plugins loaded on the agent must be an exact byte-for-byte match to the ones currently loaded on the gateway. Plugins can operate in either "gateway mode" or "agent mode" which will decide, among other things, the set of plugin APIs it serves.
To sync plugins, the agent connects to the a service on the gateway's public gRPC server, authenticates using its keyring, and shares its plugin manifest. The plugin manifest is a list of each plugin and its associated metadata, including a checksum of the binary. The gateway compares its own manifest with the agent's and sends updated plugins or binary patches as needed. The gateway's manifest is also used to validate plugins before loading.
The agent synchronizes its plugins with the Gateway, then validates them using the latest plugin manifest and loads them using the agent's plugin loader. The APIs served by each plugin will connect to the agent through the go-plugin system.
After loading the plugins, the final step for the agent to start is to establish an authenticated bidirectional stream to the Gateway. All subsequent communications will occur over this stream.
The performance of the agent is largely dictated by the individual plugins it loads. There are no notable performance characteristics of the agent itself to be aware of.
See Gateway Security for details.
The agent is currently designed to run a single instance per cluster.
Most of the agent's tests are integration-style located in test/integration/agent. There are also tests for most packages in pkg/ used by the agent.