This toolkit allows you to easily access configuration variables from a variety of different sources based on a pre-defined schema.
There are a few built-in config sources that you can use, but you can also easily create your own. The sources available out the box are:
- Environment variables
- YAML files
- Directory of plain text files
Just add the gem to your Gemfile as normal.
gem 'konfig-config', '~> 2.0'
It's fairly easy to get started with Konfig. The block below shows the key things you need to know.
# Begin by defining a schema which you wish to use for your application. # This should be configured globally. schema = Konfig::Schema.draw do group :app do string :hostname do description "The hostname for the application" end integer :port do description "The port for the application" default 8080 end string :extra_hostnames do array description "Additional hosts to be permitted to receive requests" transform { |v| v.downcase } end end # You can also define things more succicntly if you wish. group :mysql do string :hostname, default: 'localhost' integer :port, default: 3306 string :username, default: 'root' string :password string :database_name, default: 'my_database' string :roles, array: true end end # Create a source object. In this example, we're using the environment # variables source and providing `ENV` which contains all the environment # variables provided to the process. source = Konfig::Sources::Environment.new(ENV) # Create your final configuration object by providing an array of sources. config = Konfig::Config.build(schema, sources: [source]) config.app.hostname = "localhost" config.app.port = 8080 config.app.extra_hostnames = ["example.com", "example.org"]
- All configuration is evaluated when the config is built.
- There is no nesting of configuration other than adding all attributes into a group at present.
- When config is built, values will be used from the sources in the order they are provided. If a value is not found in a source, the next source will be used otherwise the value will come from the default configured in the schema.
You can use the following types in your schema:
stringintegerfloatboolean
You can transform the value of an attribute by providing a block to the transform method. The block will be passed the value of the attribute and should return the transformed value.
group :app do string :trusted_ipds do array transform { |ip| IPAddr.new(ip) } end end
The values provided as default will also be passed through the transform block. For example, the block below will result an default being returned as an array of IPAddr objects.
group :app do string :trusted_ipds do array default ['1.2.3.4', '5.5.5.5'] transform { |ip| IPAddr.new(ip) } end end
If you have your configuration in environment variables, you can load that in as shown. Environment variables are the most common source of configuration. The config value will be taken by uppercasing the group and attribute name and joining them with an underscore. For example, the config value for web.hostname will be taken from the environment variable WEB_HOSTNAME.
source = Konfig::Sources::Environment.new(ENV) # If your attribute is an array, by default, it will be split based on commas. # You can override this if you wish. source = Konfig::Sources::Environment.new(ENV, array_seperator: /\s+/)
If you have your configuration in a YAML file, you can load that in as shown.
source = Konfig::Sources::YAML.new(File.read('config.yml'))
If you have a directory of plain text files, you can load that in as shown. This is likely if you are mounting a config map on a Kubernetes cluster, for example. The path to the config file will be determined by joining the group name and the attribute name with a .. For example, the config value for web.hostname will be taken from the file /config/web.hostname (where /config is the path you provide to the directory).
source = Konfig::Sources::Directory.new('/config') # By default, the contents of the file read will be stripped. You can disable # this if you wish. source = Konfig::Sources::Directory.new('/config', strip_contents: false) # If your attribute is an array, by default, it will be split based on # new line characters. You can override this if you wish. source = Konfig::Sources::Directory.new('/config', array_seperator: /,ε/)
You can export your configuration schema to various formats as needed. Right now, the only built in option is Markdown.
require 'konfig/exporters/env_vars_as_markdown' output = Konfig::Exporters::EnvVarsAsMarkdown.new(schema).export File.write("CONFIG.md", output)