» Plugin Internals

Sentinel is built on a plugin-based architecture to support imports. This allows anybody to extend Sentinel to support new sources of data for making policy decisions as well as to expose new functions for working with data. This page documents the internals of how plugins work, not how to write them.

If you're interested in developing an import plugin, please see the developing an import plugin page.

» Basics

Sentinel plugins are built on top of the HashiCorp go-plugin system. This is the same plugin system powering all pluggable HashiCorp tools such as Terraform, Vault, and more. go-plugin is a system that has been used in production for millions of users for over 5 years.

Plugins are executable binaries. Sentinel is responsible for launching and managing the lifecycle of plugins. Once a plugin is running, Sentinel communicates with the plugin via gRPC. The protocol is open source to allow anyone to write a Sentinel plugin.

» Lifecycle

Sentinel launches plugins and is responsible for plugin lifecycle.

The runtime optimizes for latency by launching the plugin as soon as it is configured, rather than when a policy requires it. This ensures that the plugin is ready to be used immediately. A plugin is only closed when Sentinel is reconfigured to no longer allow that plugin or if the Sentinel-enabled application is closing.

When a plugin is removed from the configuration, Sentinel may wait to shut down the plugin until all currently executing policies that are using that plugin complete. New policy executions will not be allowed to use the old plugins.

Plugins are automatically restarted if they shut down unexpectedly. Policies that were executing while this happens may fail. The Sentinel system is improving to more gracefully understand locations where it is safe to retry an execution.

» Communication

An initial handshake is done via stdout to determine the main communication location. Following the handshake, communication will either occur on a local Unix domain socket or via a local-only TCP socket.