Sync configuration

See syncs for a conceptual overview.

URI patterns

Any URI passed to flagd via the --uri (-f) flag must follow one of the 6 following patterns with prefixes to ensure that it is passed to the correct implementation:

Implied Sync Provider	Prefix	Example
`kubernetes`	`core.openfeature.dev`	`core.openfeature.dev/default/my-crd`
`file`	`file:`	`file:etc/flagd/my-flags.json`
`http`	`http(s)://`	`https://my-flags.com/flags`
`grpc`	`grpc(s)://`	`grpc://my-flags-server`
grpc	`[ envoy \\| dns \\| uds\\| xds ]://`	`envoy://localhost:9211/test.service`
`gcs`	`gs://`	`gs://my-bucket/my-flags.json`
`azblob`	`azblob://`	`azblob://my-container/my-flags.json`

Custom gRPC Target URI

Apart from default dns resolution, Flagd also support different resolution method e.g. xds. Currently, we are supporting all core resolver and one custom resolver for envoy proxy resolution. For more details, please refer the RFC document.

./bin/flagd start -x --uri envoy://localhost:9211/test.service

Source Configuration

While a URI may be passed to flagd via the --uri (-f) flag, some implementations may require further configurations. In these cases the --sources flag should be used.

The flagd accepts a string argument, which should be a JSON representation of an array of SourceConfig objects.

Alternatively, these configurations can be passed to flagd via config file, specified using the --config flag.

Field	Type	Note
uri	required `string`	Flag configuration source of the sync
provider	required `string`	Provider type - `file`, `fsnotify`, `fileinfo`, `kubernetes`, `http`, `grpc`, `gcs` or `azblob`
authHeader	optional `string`	Used for http sync; set this to include the complete `Authorization` header value for any authentication scheme (e.g., "Bearer token_here", "Basic base64_credentials", etc.). Cannot be used with `bearerToken`
bearerToken	optional `string`	(Deprecated) Used for http sync; token gets appended to `Authorization` header with bearer schema. Cannot be used with `authHeader`
interval	optional `uint32`	Used for http, gcs and azblob syncs; requests will be made at this interval. Defaults to 5 seconds.
tls	optional `boolean`	Enable/Disable secure TLS connectivity. Currently used only by gRPC sync. Default (ex: if unset) is false, which will use an insecure connection
providerID	optional `string`	Value binds to grpc connection's providerID field. gRPC server implementations may use this to identify connecting flagd instance
selector	optional `string`	Value binds to grpc connection's selector field. gRPC server implementations may use this to filter flag configurations
certPath	optional `string`	Used for grpcs sync when TLS certificate is needed. If not provided, system certificates will be used for TLS connection
maxMsgSize	optional `int`	Used for gRPC sync to set max receive message size (in bytes) e.g. 5242880 for 5MB. If not provided, the default is 4MB

The uri field values do not follow the URI patterns. The provider type is instead derived from the provider field. Only exception is the remote provider where http(s):// is expected by default. Incorrect URIs will result in a flagd start-up failure with errors from the respective sync provider implementation.

The file provider type uses either an fsnotify notification (on systems that support it), or a timer-based poller that relies on os.Stat and fs.FileInfo. The moniker: file defaults to using fsnotify when flagd detects it is running in kubernetes and fileinfo in all other cases, but you may explicitly select either polling back-end by setting the provider value to either fsnotify or fileinfo.

Given below are example sync providers, startup command and equivalent config file definition:

Sync providers:

file - config/samples/example_flags.json
fsnotify - config/samples/example_flags.json
fileinfo - config/samples/example_flags.json
http - http://my-flag-source.json/
https - https://my-secure-flag-source.json/
kubernetes - default/my-flag-config
grpc(insecure) - grpc-source:8080
grpcs(secure) - my-flag-source:8080
grpc(envoy) - envoy://localhost:9211/test.service
gcs - gs://my-bucket/my-flags.json
azblob - azblob://my-container/my-flags.json

Startup command:

./bin/flagd start
--sources='[{"uri":"config/samples/example_flags.json","provider":"file"},
            {"uri":"config/samples/example_flags.json","provider":"fsnotify"},
            {"uri":"config/samples/example_flags.json","provider":"fileinfo"},
            {"uri":"http://my-flag-source.json","provider":"http","bearerToken":"bearer-dji34ld2l"},
            {"uri":"https://secure-remote/bearer-auth","provider":"http","authHeader":"Bearer bearer-dji34ld2l"},
            {"uri":"https://secure-remote/basic-auth","provider":"http","authHeader":"Basic dXNlcjpwYXNz"},
            {"uri":"default/my-flag-config","provider":"kubernetes"},
            {"uri":"grpc-source:8080","provider":"grpc"},
            {"uri":"my-flag-source:8080","provider":"grpc", "maxMsgSize": 5242880},
            {"uri":"envoy://localhost:9211/test.service", "provider":"grpc"},
            {"uri":"my-flag-source:8080","provider":"grpc", "certPath": "/certs/ca.cert", "tls": true, "providerID": "flagd-weatherapp-sidecar", "selector": "source=database,app=weatherapp"},
            {"uri":"gs://my-bucket/my-flag.json","provider":"gcs"},
            {"uri":"azblob://my-container/my-flag.json","provider":"azblob"}]'

Configuration file,

sources:
  - uri: config/samples/example_flags.json
    provider: file
  - uri: config/samples/example_flags.json
    provider: fsnotify
  - uri: config/samples/example_flags.json
    provider: fileinfo
  - uri: http://my-flag-source.json
    provider: http
    bearerToken: bearer-dji34ld2l
  - uri: default/my-flag-config
    provider: kubernetes
  - uri: my-flag-source:8080
    provider: grpc
  - uri: my-flag-source:8080
    provider: grpc
    maxMsgSize: 5242880
  - uri: envoy://localhost:9211/test.service
    provider: grpc
  - uri: my-flag-source:8080
    provider: grpc
    certPath: /certs/ca.cert
    tls: true
    providerID: flagd-weatherapp-sidecar
    selector: "source=database,app=weatherapp"
  - uri: gs://my-bucket/my-flag.json
    provider: gcs
  - uri: azblob://my-container/my-flags.json
    provider: azblob