README
¶
configuration-secret-files
A provider for BoRuDar's configuration package that loads configuration values from files in a given directory.
On your configuration struct, you define the secret_file tag with the name of the file that contains the value you
want to load. The provider will read the file and provide the content of the file as the value for the field.
The provider will look for files in the /run/secrets directory by default. As such specifying the secret_file tag
with the value my_secret will make the provider look for a file named /run/secrets/my_secret.
The tag and the directory can be customized when creating the provider. Please refer to the documentation for more information.
Documentation
¶
Overview ¶
This package provides a provider for github.com/BoRuDar/configuration that reads configuration values from files.
Each field in the configuration struct can be tagged with a file name. The provider reads the content of the file and sets the field value to the content of the file.
The main use-case is to provide a way to read sensitive/secret values from files, as an alternative to providing them as environment variables or command-line arguments. This is especially useful in containerized environments, where the secret values can be mounted as files. See the Docker documentation at https://docs.docker.com/engine/swarm/secrets/ or the Kubernetes documentation at https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets-as-files-from-a-pod for more information on this concept.
A new provider is created with the NewProvider function. The provider is configured with options that are passed as functions to the NewProvider function.
Options ¶
Options used to configured the provider can be set globally or per provider. Global options are applied to all new providers. They can be set with the GlobalOptions variable. Options set per provider overwrite the global options.
A selection of functions that configure the provider are available. These functions are named `With*`.
Additionally, the documentation for the Options struct provides information about the available options and their default values.
Security of the secret files ¶
The nature of this provider inevitably means that your secrets will be written in plain text to your filesystem. This is intentional, albeit not ideal. It is meant as an alternative to providing secrets as environment variables or command-line arguments. The security of the secret files is the responsibility of the user of this provider.
Please make sure to assess the environment in which you plan to handle secrets, and only use this provider if you are confident that writing the secrets to the filesystem is secure more secure than other methods.
Example ¶
package main
import (
"fmt"
"github.com/BoRuDar/configuration/v4"
configuration_secret_files "github.com/MadsRC/configuration-secret-files"
"os"
"path/filepath"
)
const Payload = `Hello, World!`
var dir string
func SetupExample() (func(), error) {
var err error
dir, err = os.MkdirTemp("", "example")
if err != nil {
return nil, err
}
fpath := filepath.Join(dir, "secret")
err = os.WriteFile(fpath, []byte(Payload), 0644)
if err != nil {
return nil, err
}
return func() {
os.RemoveAll(dir)
}, nil
}
type Config struct {
SomethingNotSecret string
TheSecret string `secret_file:"secret"`
}
func main() {
// IGNORE THIS PART OF THE EXAMPLE, WE NEED TO DO SOME SETUP
cleanup, err := SetupExample()
if err != nil {
fmt.Println(err)
return
}
defer cleanup()
// END OF THE SETUP - STOP IGNORING
cfg := &Config{}
configurator := configuration.New(cfg, configuration_secret_files.NewProvider(
// This is for the sake of the example. If we don't set the directory, the default one will be used.
configuration_secret_files.WithDirectory(filepath.Join(dir)),
))
err = configurator.InitValues()
if err != nil {
fmt.Println(err)
return
}
fmt.Printf("%+v\n", cfg)
}
Output: &{SomethingNotSecret: TheSecret:Hello, World!}
Index ¶
Examples ¶
Constants ¶
const ProviderName = `SecretFilesProvider`
Variables ¶
var GlobalOptions []Option
GlobalOptions is a list of Options that will be applied to all new providers.
Functions ¶
func NewProvider ¶
func NewProvider(options ...Option) configuration.Provider
NewProvider creates a new provider that reads secrets from files. The provider is configured with the specified options. A selection of options exists as functions that can be passed to this function. These functions are named `With*` where `*` is the name of the option. If no options are specified, the default options are used.
Additionally, it is possible to set global options that will be applied to all new providers. These options overwrite the default options, but are overwritten by the options passed to this function.
The default options are documented in the Options struct.
Types ¶
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option is an option for configuring a [Provider].
func WithDirectory ¶
WithDirectory sets the Options.Directory to the specified value.
func WithDirectoryMustExist ¶
WithDirectoryMustExist sets the Options.DirectoryMustExist to the specified value.
func WithMaxSize ¶
WithMaxSize sets the Options.MaxSize to the specified value.
type Options ¶
type Options struct {
// Directory is the directory where the secret files are located. Default is "/run/secrets".
Directory string
// Tag is the tag that is used to specify the file name in the struct field. Default is "secret_file".
Tag string
// MaxSize is the maximum size of the file that is read. Default is 4MiB.
MaxSize int64
// DirectoryMustExist specifies if the directory must exist. Default is true.
DirectoryMustExist bool
}
Options is the configuration for the provider. They are not used directly, but are passed to the provider when it is created with NewProvider, via the Option interface.
Source Files