fix: limit secrets encryption to BoltDB-backed deployments

Author: alespour

CHANGELOG.md

@@ -5,6 +5,7 @@
 1. [#6211](https://github.com/influxdata/chronograf/pull/6211): Harden secrets-at-rest protections for persisted source and server credentials using envelope encryption.
    * Add startup migration for legacy plaintext secrets when a secrets master key is configured.
    * Add `chronoctl` commands for master-key generation, rewrap, and disable workflows.
+   * Secrets encryption is supported only for BoltDB-backed deployments.
 
 ## v1.11.3 [2026-05-27]
 

cmd/chronoctl/README.md

@@ -14,7 +14,7 @@ Available commands:
 
 ### Secrets Encryption Commands
 
-Use these commands when Chronograf secret-at-rest encryption is enabled.
+Use these commands when Chronograf secret-at-rest encryption is enabled with BoltDB storage.
 
 ##### Generate Secrets Master Key
 Generate a base64-encoded 32-byte key:
@@ -58,12 +58,15 @@ After successful disable:
 Important:
 - `rewrap-secrets-master-key` changes only master-key wrapping and does not re-encrypt secret records.
 - `disable-secrets-encryption` decrypts encrypted secrets and stores them as plaintext.
+- Secrets encryption management supports BoltDB only; etcd-backed deployments should rely on etcd encryption-at-rest or platform-level disk encryption.
 
 
 ### Migrate
 
 The `migrate` command allows you to migrate your chronograf configuration store. It is highly recommended that you make a backup of all databases involved before running a migration as there is no guarantee that there will be no data loss. When specifying an etcd endpoint, the URI must begin with `etcd://`. It is preferred that you prefix `bolt://` to an absolute path when specifying a local bolt db file, but a lone relative path is also accepted without the prefix. If there is authentication on etcd, use the standard URI format to define a username/password: `[scheme:][//[userinfo@]host][/]path`.
 There is currently no cleanup for a failed migration, so keep that in mind before migrating to a db that contains other important data.
+If migrating from an encrypted BoltDB, first run `disable-secrets-encryption`.
+The `migrate` command does not initialize a secrets DEK and cannot read encrypted source or server secrets.
 
 
 ##### Usage

server/server.go

@@ -151,8 +151,8 @@ type Server struct {
 	ReportingDisabled    bool           `short:"r" long:"reporting-disabled" description:"Disable reporting of usage stats (os,arch,version,cluster_id,uptime) once every 24hr" env:"REPORTING_DISABLED"`
 	CustomAutoRefresh    string         `long:"custom-auto-refresh" description:"Adds custom auto refresh options using semicolon separated list of label=milliseconds pairs" env:"CUSTOM_AUTO_REFRESH"`
 	LogLevel             string         `short:"l" long:"log-level" value-name:"choice" choice:"debug" choice:"info" choice:"error" default:"info" description:"Set the logging level" env:"LOG_LEVEL"`
-	SecretsMasterKey     string         `long:"secrets-master-key" description:"Base64-encoded 32-byte master key used to wrap/unwrap the data encryption key for secret-field encryption" env:"SECRETS_MASTER_KEY"`
-	SecretsMasterKeyFile flags.Filename `long:"secrets-master-key-file" description:"Path to file containing a base64-encoded 32-byte master key used to wrap/unwrap the data encryption key for secret-field encryption" env:"SECRETS_MASTER_KEY_FILE"`
+	SecretsMasterKey     string         `long:"secrets-master-key" description:"Base64-encoded 32-byte master key used to wrap/unwrap the data encryption key for secret-field encryption (BoltDB storage only)" env:"SECRETS_MASTER_KEY"`
+	SecretsMasterKeyFile flags.Filename `long:"secrets-master-key-file" description:"Path to file containing a base64-encoded 32-byte master key used to wrap/unwrap the data encryption key for secret-field encryption (BoltDB storage only)" env:"SECRETS_MASTER_KEY_FILE"`
 	Basepath             string         `short:"p" long:"basepath" description:"A URL path prefix under which all chronograf routes will be mounted. (Note: PREFIX_ROUTES has been deprecated. Now, if basepath is set, all routes will be prefixed with it.)" env:"BASE_PATH"`
 	ShowVersion          bool           `short:"v" long:"version" description:"Show Chronograf version info"`
 	BuildInfo            chronograf.BuildInfo
@@ -649,6 +649,12 @@ func (s *Server) loadSecretsMasterKey() ([]byte, error) {
 		return nil, errors.New("secrets master key must be provided by either --secrets-master-key or --secrets-master-key-file, not both")
 	}
 
+	// Storage topology is validated here because this is the last common point
+	// before Serve opens either BoltDB or etcd; secrets encryption is BoltDB-only.
+	if len(s.EtcdEndpoints) > 0 && (s.SecretsMasterKey != "" || s.SecretsMasterKeyFile != "") {
+		return nil, errors.New("--secrets-master-key/--secrets-master-key-file are supported only with BoltDB storage; remove them, or rely on etcd encryption-at-rest or platform-level disk encryption")
+	}
+
 	if s.SecretsMasterKey == "" && s.SecretsMasterKeyFile == "" {
 		return nil, nil
 	}

server/server_test.go

@@ -145,6 +145,13 @@ func Test_loadSecretsMasterKey(t *testing.T) {
 		require.Nil(t, got)
 	})
 
+	t.Run("etcd config without key returns nil", func(t *testing.T) {
+		s := Server{EtcdEndpoints: []string{"localhost:2379"}}
+		got, err := s.loadSecretsMasterKey()
+		require.NoError(t, err)
+		require.Nil(t, got)
+	})
+
 	t.Run("fails when both direct and file are set", func(t *testing.T) {
 		s := Server{
 			SecretsMasterKey:     validB64,
@@ -155,6 +162,25 @@ func Test_loadSecretsMasterKey(t *testing.T) {
 		require.Contains(t, err.Error(), "either --secrets-master-key or --secrets-master-key-file")
 	})
 
+	t.Run("fails when direct key is set with etcd", func(t *testing.T) {
+		s := Server{
+			EtcdEndpoints:    []string{"localhost:2379"},
+			SecretsMasterKey: validB64,
+		}
+		_, err := s.loadSecretsMasterKey()
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "supported only with BoltDB storage")
+	})
+
+	t.Run("fails when key file is set with etcd", func(t *testing.T) {
+		f := t.TempDir() + "/master-key.txt"
+		require.NoError(t, os.WriteFile(f, []byte(validB64+"\n"), 0600))
+		s := Server{EtcdEndpoints: []string{"localhost:2379"}, SecretsMasterKeyFile: flags.Filename(f)}
+		_, err := s.loadSecretsMasterKey()
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "supported only with BoltDB storage")
+	})
+
 	t.Run("fails on invalid base64", func(t *testing.T) {
 		s := Server{SecretsMasterKey: "not-base64"}
 		_, err := s.loadSecretsMasterKey()