Plugin reconfiguration support (#5166)

* Plugin reconfiguration support Signed-off-by: Andrew Harding <azdagron@gmail.com>
spiffe · May 23, 2024 · 5539445 · 5539445
1 parent 111aa17
commit 5539445
Show file tree

Hide file tree

Showing 25 changed files with 642 additions and 187 deletions.
diff --git a/cmd/spire-agent/cli/run/run_posix_test.go b/cmd/spire-agent/cli/run/run_posix_test.go
@@ -187,28 +187,28 @@ func TestParseConfigGood(t *testing.T) {
 	// Check for plugins configurations
 	expectedPluginConfigs := catalog.PluginConfigs{
 		{
-			Type:     "plugin_type_agent",
-			Name:     "plugin_name_agent",
-			Path:     "./pluginAgentCmd",
-			Checksum: "pluginAgentChecksum",
-			Data:     data,
-			Disabled: false,
+			Type:       "plugin_type_agent",
+			Name:       "plugin_name_agent",
+			Path:       "./pluginAgentCmd",
+			Checksum:   "pluginAgentChecksum",
+			DataSource: catalog.FixedData(data),
+			Disabled:   false,
 		},
 		{
-			Type:     "plugin_type_agent",
-			Name:     "plugin_disabled",
-			Path:     "./pluginAgentCmd",
-			Checksum: "pluginAgentChecksum",
-			Data:     data,
-			Disabled: true,
+			Type:       "plugin_type_agent",
+			Name:       "plugin_disabled",
+			Path:       "./pluginAgentCmd",
+			Checksum:   "pluginAgentChecksum",
+			DataSource: catalog.FixedData(data),
+			Disabled:   true,
 		},
 		{
-			Type:     "plugin_type_agent",
-			Name:     "plugin_enabled",
-			Path:     "./pluginAgentCmd",
-			Checksum: "pluginAgentChecksum",
-			Data:     data,
-			Disabled: false,
+			Type:       "plugin_type_agent",
+			Name:       "plugin_enabled",
+			Path:       "./pluginAgentCmd",
+			Checksum:   "pluginAgentChecksum",
+			DataSource: catalog.FileData("plugin.conf"),
+			Disabled:   false,
 		},
 	}
 

diff --git a/cmd/spire-agent/cli/run/run_windows_test.go b/cmd/spire-agent/cli/run/run_windows_test.go
@@ -173,28 +173,28 @@ func TestParseConfigGood(t *testing.T) {
 	// Check for plugins configurations
 	expectedPluginConfigs := catalog.PluginConfigs{
 		{
-			Type:     "plugin_type_agent",
-			Name:     "plugin_name_agent",
-			Path:     "./pluginAgentCmd",
-			Checksum: "pluginAgentChecksum",
-			Data:     data,
-			Disabled: false,
+			Type:       "plugin_type_agent",
+			Name:       "plugin_name_agent",
+			Path:       "./pluginAgentCmd",
+			Checksum:   "pluginAgentChecksum",
+			DataSource: catalog.FixedData(data),
+			Disabled:   false,
 		},
 		{
-			Type:     "plugin_type_agent",
-			Name:     "plugin_disabled",
-			Path:     ".\\pluginAgentCmd",
-			Checksum: "pluginAgentChecksum",
-			Data:     data,
-			Disabled: true,
+			Type:       "plugin_type_agent",
+			Name:       "plugin_disabled",
+			Path:       ".\\pluginAgentCmd",
+			Checksum:   "pluginAgentChecksum",
+			DataSource: catalog.FixedData(data),
+			Disabled:   true,
 		},
 		{
-			Type:     "plugin_type_agent",
-			Name:     "plugin_enabled",
-			Path:     "c:/temp/pluginAgentCmd",
-			Checksum: "pluginAgentChecksum",
-			Data:     data,
-			Disabled: false,
+			Type:       "plugin_type_agent",
+			Name:       "plugin_enabled",
+			Path:       "c:/temp/pluginAgentCmd",
+			Checksum:   "pluginAgentChecksum",
+			DataSource: catalog.FileData("plugin.conf"),
+			Disabled:   false,
 		},
 	}
 

diff --git a/cmd/spire-server/cli/run/run_test.go b/cmd/spire-server/cli/run/run_test.go
@@ -72,28 +72,28 @@ func TestParseConfigGood(t *testing.T) {
 	// Check for plugins configurations
 	expectedPluginConfigs := catalog.PluginConfigs{
 		{
-			Type:     "plugin_type_server",
-			Name:     "plugin_name_server",
-			Path:     "./pluginServerCmd",
-			Checksum: "pluginServerChecksum",
-			Data:     data,
-			Disabled: false,
-		},
-		{
-			Type:     "plugin_type_server",
-			Name:     "plugin_disabled",
-			Path:     "./pluginServerCmd",
-			Checksum: "pluginServerChecksum",
-			Data:     data,
-			Disabled: true,
-		},
-		{
-			Type:     "plugin_type_server",
-			Name:     "plugin_enabled",
-			Path:     "./pluginServerCmd",
-			Checksum: "pluginServerChecksum",
-			Data:     data,
-			Disabled: false,
+			Type:       "plugin_type_server",
+			Name:       "plugin_name_server",
+			Path:       "./pluginServerCmd",
+			Checksum:   "pluginServerChecksum",
+			DataSource: catalog.FixedData(data),
+			Disabled:   false,
+		},
+		{
+			Type:       "plugin_type_server",
+			Name:       "plugin_disabled",
+			Path:       "./pluginServerCmd",
+			Checksum:   "pluginServerChecksum",
+			DataSource: catalog.FixedData(data),
+			Disabled:   true,
+		},
+		{
+			Type:       "plugin_type_server",
+			Name:       "plugin_enabled",
+			Path:       "./pluginServerCmd",
+			Checksum:   "pluginServerChecksum",
+			DataSource: catalog.FileData("plugin.conf"),
+			Disabled:   false,
 		},
 	}
 

diff --git a/conf/agent/agent_full.conf b/conf/agent/agent_full.conf
@@ -127,11 +127,14 @@ agent {
 #         # not needed for built-ins)
 #         plugin_checksum = <string>
 #
-#         # plugin_data: Plugin-specific data
+#         # plugin_data: Plugin-specific data (mutually exclusive with plugin_data_file)
 #         plugin_data {
 #             ...configuration options...
 #         }
 #
+#         # plugin_data_file: Path to file with plugin-specific data (mutually exclusive with plugin_data)
+#         plugin_data_file = <string>
+#
 #         # enabled: Enable or disable the plugin (enabled by default)
 #         enabled = [true | false]
 #     }

diff --git a/conf/server/server_full.conf b/conf/server/server_full.conf
@@ -210,11 +210,14 @@ server {
 #         # not needed for built-ins)
 #         plugin_checksum = <string>
 #
-#         # plugin_data: Plugin-specific data
+#         # plugin_data: Plugin-specific data (mutually exclusive with plugin_data_file)
 #         plugin_data {
 #             ...configuration options...
 #         }
 #
+#         # plugin_data_file: Path to file with plugin-specific data (mutually exclusive with plugin_data)
+#         plugin_data_file = <string>
+#
 #         # enabled: Enable or disable the plugin (enabled by default)
 #         enabled = [true | false]
 #     }

diff --git a/doc/spire_agent.md b/doc/spire_agent.md
@@ -136,14 +136,61 @@ plugins {
 
 The following configuration options are available to configure a plugin:
 
-| Configuration   | Description                                                                   |
-|-----------------|-------------------------------------------------------------------------------|
-| plugin_cmd      | Path to the plugin implementation binary (optional, not needed for built-ins) |
-| plugin_checksum | An optional sha256 of the plugin binary  (optional, not needed for built-ins) |
-| enabled         | Enable or disable the plugin (enabled by default)                             |
-| plugin_data     | Plugin-specific data                                                          |
-
-Please see the [built-in plugins](#built-in-plugins) section for information on plugins that are available out-of-the-box.
+| Configuration    | Description                                                                            |
+|------------------|----------------------------------------------------------------------------------------|
+| plugin_cmd       | Path to the plugin implementation binary (optional, not needed for built-ins)          |
+| plugin_checksum  | An optional sha256 of the plugin binary  (optional, not needed for built-ins)          |
+| enabled          | Enable or disable the plugin (enabled by default)                                      |
+| plugin_data      | Plugin-specific data (mutually exclusive with `plugin_data_file`)                      |
+| plugin_data_file | Path to a file containing plugin-specific data (mutually exclusive with `plugin_data`) |
+
+Please see the [built-in plugins](#built-in-plugins) section below for information on plugins that are available out-of-the-box.
+
+### Examples
+
+#### Built-in Plugin with Static Configuration
+
+```hcl
+plugins {
+    SomeType "some_plugin" {
+        plugin_data = {
+            option1 = "foo"
+            option2 = 3
+        }
+    }
+}
+```
+
+#### External Plugin with Dynamic Configuration
+
+In the `agent.conf`, declare the plugin using the `plugin_data_file` option to source the plugin configuration from file.
+
+```hcl
+plugins {
+    SomeType "some_plugin" {
+        plugin_cmd = "./path/to/plugin"
+        plugin_checksum = "4e1243bd22c66e76c2ba9eddc1f91394e57f9f83"
+        plugin_data_file = "some_plugin.conf"
+    }
+}
+```
+
+And then in `some_plugin.conf` you place the plugin configuration:
+
+```hcl
+option1 = "foo"
+option2 = 3
+```
+
+### Reconfiguring plugins (Posix only)
+
+Plugins that use dynamic configuration sources (i.e. `plugin_data_file`) can be reconfigured at runtime by sending a `SIGUSR1` signal to SPIRE Agent. This is true for both built-in and external plugins.
+
+SPIRE Agent, upon receipt of the signal, does the following:
+
+1. Reloads the plugin data
+2. Compares the plugin data to the previous data
+3. If changed, the plugin is reconfigured with the new data
 
 ## Telemetry configuration
 

diff --git a/doc/spire_server.md b/doc/spire_server.md
@@ -139,15 +139,64 @@ plugins {
 
 The following configuration options are available to configure a plugin:
 
-| Configuration   | Description                                                                   |
-|-----------------|-------------------------------------------------------------------------------|
-| plugin_cmd      | Path to the plugin implementation binary (optional, not needed for built-ins) |
-| plugin_checksum | An optional sha256 of the plugin binary  (optional, not needed for built-ins) |
-| enabled         | Enable or disable the plugin (enabled by default)                             |
-| plugin_data     | Plugin-specific data                                                          |
+| Configuration    | Description                                                                            |
+|------------------|----------------------------------------------------------------------------------------|
+| plugin_cmd       | Path to the plugin implementation binary (optional, not needed for built-ins)          |
+| plugin_checksum  | An optional sha256 of the plugin binary  (optional, not needed for built-ins)          |
+| enabled          | Enable or disable the plugin (enabled by default)                                      |
+| plugin_data      | Plugin-specific data (mutually exclusive with `plugin_data_file`)                      |
+| plugin_data_file | Path to a file containing plugin-specific data (mutually exclusive with `plugin_data`) |
 
 Please see the [built-in plugins](#built-in-plugins) section below for information on plugins that are available out-of-the-box.
 
+### Examples
+
+#### Built-in Plugin with Static Configuration
+
+```hcl
+plugins {
+    SomeType "some_plugin" {
+        plugin_data = {
+            option1 = "foo"
+            option2 = 3
+        }
+    }
+}
+```
+
+#### External Plugin with Dynamic Configuration
+
+In the `agent.conf`, declare the plugin using the `plugin_data_file` option to source the plugin configuration from file.
+
+```hcl
+plugins {
+    SomeType "some_plugin" {
+        plugin_cmd = "./path/to/plugin"
+        plugin_checksum = "4e1243bd22c66e76c2ba9eddc1f91394e57f9f83"
+        plugin_data_file = "some_plugin.conf"
+    }
+}
+```
+
+And then in `some_plugin.conf` you place the plugin configuration:
+
+```hcl
+option1 = "foo"
+option2 = 3
+```
+
+### Reconfiguring plugins (Posix only)
+
+Plugins that use dynamic configuration sources (i.e. `plugin_data_file`) can be reconfigured at runtime by sending a `SIGUSR1` signal to SPIRE Server. This is true for both built-in and external plugins.
+
+SPIRE Server, upon receipt of the signal, does the following:
+
+1. Reloads the plugin data
+2. Compares the plugin data to the previous data
+3. If changed, the plugin is reconfigured with the new data
+
+**Note** The DataStore is not reconfigurable even when configured with a dynamic data source (e.g. `plugin_data_file`).
+
 ## Federation configuration
 
 SPIRE Server can be configured to federate with others SPIRE Servers living in different trust domains. SPIRE supports configuring federation relationships in the SPIRE Server configuration file (static relationships) and through the [Trust Domain API](https://github.com/spiffe/spire-api-sdk/blob/main/proto/spire/api/server/trustdomain/v1/trustdomain.proto) (dynamic relationships). This section describes how to configure statically defined relationships in the configuration file.

diff --git a/pkg/agent/agent.go b/pkg/agent/agent.go
@@ -167,6 +167,7 @@ func (a *Agent) Run(ctx context.Context) error {
 		storeService.Run,
 		endpoints.ListenAndServe,
 		metrics.ListenAndServe,
+		catalog.ReconfigureTask(a.c.Log.WithField(telemetry.SubsystemName, "reconfigurer"), cat),
 		util.SerialRun(a.waitForTestDial, healthChecker.ListenAndServe),
 	}
 

diff --git a/pkg/agent/catalog/catalog.go b/pkg/agent/catalog/catalog.go
@@ -3,7 +3,6 @@ package catalog
 import (
 	"context"
 	"fmt"
-	"io"
 
 	"github.com/sirupsen/logrus"
 	"github.com/spiffe/go-spiffe/v2/spiffeid"
@@ -27,6 +26,8 @@ const (
 	workloadattestorType = "WorkloadAttestor"
 )
 
+var ReconfigureTask = catalog.ReconfigureTask
+
 type Catalog interface {
 	GetKeyManager() keymanager.KeyManager
 	GetNodeAttestor() nodeattestor.NodeAttestor
@@ -51,8 +52,8 @@ type Repository struct {
 	svidStoreRepository
 	workloadAttestorRepository
 
-	log           logrus.FieldLogger
-	catalogCloser io.Closer
+	log     logrus.FieldLogger
+	catalog *catalog.Catalog
 }
 
 func (repo *Repository) Plugins() map[string]catalog.PluginRepo {
@@ -68,9 +69,13 @@ func (repo *Repository) Services() []catalog.ServiceRepo {
 	return nil
 }
 
+func (repo *Repository) Reconfigure(ctx context.Context) {
+	repo.catalog.Reconfigure(ctx)
+}
+
 func (repo *Repository) Close() {
 	repo.log.Debug("Closing catalog")
-	if err := repo.catalogCloser.Close(); err == nil {
+	if err := repo.catalog.Close(); err == nil {
 		repo.log.Info("Catalog closed")
 	} else {
 		repo.log.WithError(err).Error("Failed to close catalog")
@@ -86,7 +91,7 @@ func Load(ctx context.Context, config Config) (_ *Repository, err error) {
 	repo := &Repository{
 		log: config.Log,
 	}
-	repo.catalogCloser, err = catalog.Load(ctx, catalog.Config{
+	repo.catalog, err = catalog.Load(ctx, catalog.Config{
 		Log: config.Log,
 		CoreConfig: catalog.CoreConfig{
 			TrustDomain: config.TrustDomain,