Skip to content

Plugin reconfiguration support #5166

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
May 23, 2024
Merged

Plugin reconfiguration support #5166

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
9075d0d
Plugin reconfiguration support
azdagron May 22, 2024
cba8c8c
fix lint on windows
azdagron May 22, 2024
912525d
address comments
azdagron May 22, 2024
d4c2041
lint markdown
azdagron May 22, 2024
3528286
address marcos comments
azdagron May 23, 2024
c684546
clarify examples
azdagron May 23, 2024
a562588
Merge branch 'main' into plugin-reconfigurable
May 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions cmd/spire-agent/cli/run/run_posix_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
},
}

Expand Down
36 changes: 18 additions & 18 deletions cmd/spire-agent/cli/run/run_windows_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
},
}

Expand Down
44 changes: 22 additions & 22 deletions cmd/spire-server/cli/run/run_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
},
}

Expand Down
77 changes: 69 additions & 8 deletions doc/spire_agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,14 +136,75 @@ 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
}
}
}
```

#### Built-in 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_data_file = "some_plugin.conf"
}
}
```

And then in `some_plugin.conf` you place the plugin configuration:

```hcl
option1 = "foo"
option2 = 3
```

#### External Plugin with Static Configuration
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we have a config for external plugins with plugin_data, it is possible that some users may not realize that plugin_data_file can also be used in external plugins. To improve clarity, we should add a minimal description indicating that this feature can be utilized in external plugins as well.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm happy to add another example if that would help, but the section above mentions that all of the plugin options apply for all plugins. What I want to avoid is having an example with every different combination?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

another example may be an overkill a comment maybe is good enough


```hcl
plugins {
SomeType "some_plugin" {
plugin_cmd = "./path/to/plugin"
plugin_checksum = "4e1243bd22c66e76c2ba9eddc1f91394e57f9f83"
plugin_data = {
option1 = "foo"
option2 = 3
}
}
}
```

### Reconfiguring plugins (Posix only)
Copy link
Member

@amartinezfayo amartinezfayo May 22, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe it's just me, but it's not super clear if the plugin configuration should include plugin_data { or not. Maybe a short example of how a plugin config file looks like would be good?


Plugins that use dynamic configuration sources (i.e. `plugin_data_file`) can be reconfigured at runtime by sending a `SIGUSR1` signal to SPIRE Agent.

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

Expand Down
75 changes: 69 additions & 6 deletions doc/spire_server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,15 +139,78 @@ 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
}
}
}
```

#### Built-in Plugin with Dynamic Configuration

In the `server.conf`, declare the plugin using the `plugin_data_file` option to
source the plugin configuration from file.

```hcl
plugins {
SomeType "some_plugin" {
plugin_data_file = "some_plugin.conf"
}
}
```

And then in `some_plugin.conf` you place the plugin configuration:

```hcl
option1 = "foo"
option2 = 3
```

#### External Plugin with Static Configuration

```hcl
plugins {
SomeType "some_plugin" {
plugin_cmd = "./path/to/plugin"
plugin_checksum = "4e1243bd22c66e76c2ba9eddc1f91394e57f9f83"
plugin_data = {
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.

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.
Expand Down
1 change: 1 addition & 0 deletions pkg/agent/agent.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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),
}

Expand Down
15 changes: 10 additions & 5 deletions pkg/agent/catalog/catalog.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@ package catalog
import (
"context"
"fmt"
"io"

"github.com/sirupsen/logrus"
"github.com/spiffe/go-spiffe/v2/spiffeid"
Expand All @@ -27,6 +26,8 @@ const (
workloadattestorType = "WorkloadAttestor"
)

var ReconfigureTask = catalog.ReconfigureTask

type Catalog interface {
GetKeyManager() keymanager.KeyManager
GetNodeAttestor() nodeattestor.NodeAttestor
Expand All @@ -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 {
Expand All @@ -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")
Expand All @@ -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,
Expand Down
Loading