diff --git a/docs/ocis/config.md b/docs/ocis/config.md new file mode 100644 index 0000000000..56690d3119 --- /dev/null +++ b/docs/ocis/config.md @@ -0,0 +1,126 @@ +--- +title: "Configuration" +date: "2021-11-09T00:03:16+0100" +weight: 2 +geekdocRepo: https://github.com/owncloud/ocis +geekdocEditPath: edit/master/ocis/templates +geekdocFilePath: config.md +--- + +{{< toc >}} + +## Configuration Framework + +In order to simplify deployments and development the configuration model from oCIS aims to be simple yet flexible. + +## Overview of the approach + +{{< svg src="ocis/static/ocis-config-redesign.drawio.svg" >}} + +## In-depth configuration + +Since we include a set of predefined extensions within the single binary, configuring an extension can be done in a variety of ways. Since we work with complex types, having as many cli per config value scales poorly, so we limited the options to config files and environment variables, leaving cli flags for shared values, such as config file sources (`--config-file`) or logging (`--log-level`, `--log-pretty`, `--log-file` or `--log-color`). + +The hierarchy is clear enough, leaving us with a clear: + +_(each element above overwrites its precedent)_ + +1. env variables +2. extension config +3. ocis config + +This is manifested in the previous diagram. We can then speak about "configuration file arithmetics", where resulting config transformations happen through a series of steps with the sources mentioned previously. An administrator must be aware of this sources, since mis-managing them can be a source of confusion, having undesired transformations on config files believed not to be applied. + +## Flows + +Let's explore the various flows with examples and workflows. + +### Examples + +Let's explore with examples this approach. + +#### Only config files + +The following config files are present in the default loading locations: + +_ocis.yaml_ +```yaml +proxy: + http: + addr: localhost:1111 + log: + pretty: false + color: false + level: info +accounts: + http: + addr: localhost:2222 + log: + level: debug + color: false + pretty: false +log: + pretty: true + color: true + level: info +``` + +_proxy.yaml_ +```yaml +http: + addr: localhost:3333 +``` + +_accounts.yaml_ +```yaml +http: + addr: localhost:4444 +``` + +Note that the extension files will overwrite values from the main `ocis.yaml`, causing `ocis server` to run with the following configuration: + +```yaml +proxy: + http: + addr: localhost:3333 +accounts: + http: + addr: localhost:4444 +log: + pretty: true + color: true + level: info +``` + +#### Using ENV variables + +The logging configuration if defined in the main ocis.yaml is inherited by all extensions. It can be, however, overwritten by a single extension file if desired. The same example can be used to demonstrate environment values overwrites. With the same set of config files now we have the following command `PROXY_HTTP_ADDR=localhost:5555 ocis server`, now the resulting config looks like: + +```yaml +proxy: + http: + addr: localhost:5555 +accounts: + http: + addr: localhost:4444 +log: + pretty: true + color: true + level: info +``` + +### Workflows + +Since one can run an extension using the runtime (supervised) or not (unsupervised), we ensure correct behavior in both modes, expecting the same outputs. + +#### Supervised + +You are using the supervised mode whenever you issue the `ocis server` command. We start the runtime on port `9250` (by default) that listens for commands regarding the lifecycle of the supervised extensions. When an extension runs supervised and is killed, the only way to provide / overwrite configuration values will be through an extension config file. This is due to the parent process has already started, and it already has its own environment. This is a living design document, and if the need arise where we want to stick to the loading defaults, we could. + +#### Unsupervised + +All the points from the priority section hold true. An unsupervised extension can be started with the format: `ocis [extension]` i.e: `ocis proxy`. First, `ocis.yaml` are parsed, the `proxy.yaml` and finally any environment variables. + +## Default config values (in yaml) + +TBD. Needs to be generated and merged with the env mappings. diff --git a/docs/ocis/static/ocis-config-redesign.drawio.svg b/docs/ocis/static/ocis-config-redesign.drawio.svg new file mode 100644 index 0000000000..ff2ee40fac --- /dev/null +++ b/docs/ocis/static/ocis-config-redesign.drawio.svg @@ -0,0 +1,4 @@ + + + +
> ocis server
> ocis server
# global logging config
log:
  pretty: true
  color: true
  level: info
proxy:
  http:
    addr: localhost:9200
  log:
    pretty: false
    color: false
    level: info
accounts:
  log:
    level: debug
    color: false
    pretty: false

# global logging config...
ocis.yaml
ocis.yaml
  http:
    addr: localhost:1234
  log:
    pretty: false
    color: false
    level: info

http:...
proxy.yaml
proxy.yaml
  http:
    addr: localhost:5678


http:...
accounts.yaml
accounts.yaml
resulting proxy config values
resulting proxy config values
resulting accounts config values
resulting accounts config values
  http:
    addr: localhost:1234
  log:
    pretty: false
    color: false
    level: info


http:...
notice how even if ocis supplies
with logging configuration, the values
from the extension overwrite the inherited
values. This can also be achieved using an
environment variable.
notice how even if ocis supplies...
  http:
    addr: localhost:5678
  log:
    pretty: true
    color: true
    level: info


http:...
on the other hand here we see the extension
inherited the logging information from the parent.
The same holds true from any value. Values from
ocis.yaml are carried down to their respective
extensions.
on the other hand here we see the extension...Viewer does not support full SVG 1.1 \ No newline at end of file diff --git a/glauth/pkg/command/root.go b/glauth/pkg/command/root.go index 18ada7b921..4d68ded216 100644 --- a/glauth/pkg/command/root.go +++ b/glauth/pkg/command/root.go @@ -4,11 +4,11 @@ import ( "context" "os" - "github.com/owncloud/ocis/ocis-pkg/shared" - "github.com/owncloud/ocis/glauth/pkg/config" ociscfg "github.com/owncloud/ocis/ocis-pkg/config" "github.com/owncloud/ocis/ocis-pkg/log" + oclog "github.com/owncloud/ocis/ocis-pkg/log" + "github.com/owncloud/ocis/ocis-pkg/shared" "github.com/owncloud/ocis/ocis-pkg/version" "github.com/thejerf/suture/v4" "github.com/urfave/cli/v2" @@ -52,13 +52,7 @@ func Execute(cfg *config.Config) error { // NewLogger initializes a service-specific logger instance. func NewLogger(cfg *config.Config) log.Logger { - return log.NewLogger( - log.Name("glauth"), - log.Level(cfg.Log.Level), - log.Pretty(cfg.Log.Pretty), - log.Color(cfg.Log.Color), - log.File(cfg.Log.File), - ) + return oclog.LoggerFromConfig("glauth", cfg.Log) } // ParseConfig loads glauth configuration from known paths. diff --git a/ocis-pkg/config/config_test.go b/ocis-pkg/config/config_test.go new file mode 100644 index 0000000000..6a77d3cda9 --- /dev/null +++ b/ocis-pkg/config/config_test.go @@ -0,0 +1,17 @@ +package config + +import ( + "fmt" + "testing" + + "gopkg.in/yaml.v2" +) + +func TestDefaultConfig(t *testing.T) { + cfg := DefaultConfig() + yBytes, err := yaml.Marshal(cfg) + if err != nil { + panic(err) + } + fmt.Println(string(yBytes)) +}