Skip to content

docs: Migrate /docs items to website #825

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
agardnerIT wants to merge 26 commits into from
Closed

docs: Migrate /docs items to website #825

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
0271c2f
add menu items and pages. point docs/configuration/configuration.md t…
agardnerIT Aug 9, 2023
d31d1f3
markdown lint
agardnerIT Aug 9, 2023
d5131de
move otel to reference
agardnerIT Aug 9, 2023
b70fa31
update link
agardnerIT Aug 9, 2023
1ecc2db
update docs/flagd_start.md
agardnerIT Aug 9, 2023
f459e5d
update
agardnerIT Aug 9, 2023
dc5afaf
update pointers
agardnerIT Aug 9, 2023
fc9527d
revert change. Handled in different PR
agardnerIT Aug 9, 2023
da92715
update
agardnerIT Aug 9, 2023
15d922d
update
agardnerIT Aug 9, 2023
ecb1778
make md lint happy
agardnerIT Aug 9, 2023
fb98149
Revert "make md lint happy"
agardnerIT Aug 9, 2023
c89a1b8
make mdlint happy
agardnerIT Aug 9, 2023
43b4788
Merge branch 'main' into docs/824
agardnerIT Aug 11, 2023
03ec1a0
Merge branch 'main' into docs/824
beeme1mr Aug 14, 2023
b87489a
Merge branch 'main' into docs/824
Kavindu-Dodan Aug 25, 2023
a93c5cd
flagd_version
agardnerIT Sep 7, 2023
9a69fdc
fractional evaluation page move
agardnerIT Sep 7, 2023
da22536
reusable targeting rules
agardnerIT Sep 7, 2023
b9881a3
add contributing page
agardnerIT Sep 7, 2023
53f032d
move flag configuration docs
agardnerIT Sep 7, 2023
9e6037b
systemd updates
agardnerIT Sep 7, 2023
c1def1b
fix mkdocs error
agardnerIT Sep 13, 2023
fccb8ff
Merge branch 'main' into docs/824
agardnerIT Sep 13, 2023
7ffa0b5
fix formatting for markdownlint
agardnerIT Sep 13, 2023
252b382
Merge branch 'docs/824' of https://github.com/agardnerIT/flagd into d…
agardnerIT Sep 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 3 additions & 109 deletions CONTRIBUTING.md
View file
Open in desktop
Copy link
Copy Markdown
Member

@beeme1mr beeme1mr Sep 18, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this file should be moved to the website. A CONTRIBUTING file has special meeting in GitHub and anyone contributing would expect the content to live there.

Original file line number Diff line number Diff line change
@@ -1,111 +1,5 @@
# Welcome

There are a few things to consider before contributing to flagd.

Firstly, there's [a code of conduct](https://github.com/open-feature/.github/blob/main/CODE_OF_CONDUCT.md).
TLDR: be respectful.

Any contributions are expected to include unit tests.
These can be validated with `make test` or the automated github workflow will run them on PR creation.

This project uses a go workspace, to setup the project run

```shell
make workspace-init
```

The go version in the `go.work` is the currently supported version of go.

The project uses remote buf packages, changing the remote generation source will require a one-time registry configuration:

```shell
export GOPRIVATE=buf.build/gen/go
```

## DCO Sign-Off

A DCO (Developer Certificate of Origin) sign-off is a line placed at the end of
a commit message containing a contributor's "signature." In adding this, the
contributor certifies that they have the right to contribute the material in
question.

Here are the steps to sign your work:

1. Verify the contribution in your commit complies with the
[terms of the DCO](https://developercertificate.org/).

1. Add a line like the following to your commit message:

```shell
Signed-off-by: Joe Smith <joe.smith@example.com>
```

You MUST use your legal name -- handles or other pseudonyms are not
permitted.

While you could manually add DCO sign-off to every commit, there is an easier
way:

1. Configure your git client appropriately. This is one-time setup.

```shell
git config user.name <legal name>
git config user.email <email address you use for GitHub>
```
<!-- markdownlint-disable-file -->

If you work on multiple projects that require a DCO sign-off, you can
configure your git client to use these settings globally instead of only
for Brigade:

```shell
git config --global user.name <legal name>
git config --global user.email <email address you use for GitHub>
```

1. Use the `--signoff` or `-s` (lowercase) flag when making each commit.
For example:

```shell
git commit --message "<commit message>" --signoff
```

If you ever make a commit and forget to use the `--signoff` flag, you
can amend your commit with this information before pushing:

```shell
git commit --amend --signoff
```

1. You can verify the above worked as expected using `git log`. Your latest
commit should look similar to this one:

```shell
Author: Joe Smith <joe.smith@example.com>
Date: Thu Feb 2 11:41:15 2018 -0800

Update README

Signed-off-by: Joe Smith <joe.smith@example.com>
```

Notice the `Author` and `Signed-off-by` lines match. If they do not, the
PR will be rejected by the automated DCO check.

## Conventional PR Titles

When raising PRs, please format according to [conventional commit standards](https://www.conventionalcommits.org/en/v1.0.0/#summary)

For example: `docs: some PR title here...`

Thanks!
Issues and pull requests following these guidelines are welcome.

## Markdown Lint and Markdown Lint Fix

PRs are expected to conform to markdown lint rules.

Therefore, run `make markdownlint-fix` to auto-fix _most_ issues.
Then commit the results.
# Welcome

For those issues that cannot be auto-fixed, run `make markdownlint`
then manually fix whatever it warns about.
This content has moved. See [contributing to flagd](https://flagd.dev/contributing)
171 changes: 1 addition & 170 deletions docs/configuration/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,172 +1,3 @@
# Configuration

<!-- TOC -->
- [Configuration](#configuration)
- [Sync providers](#sync-providers)
- [Kubernetes provider](#kubernetes-provider)
- [Filepath provider](#filepath-provider)
- [Remote provider](#remote-provider)
- [GRPC provider](#grpc-provider)
- [Sync provider configurations](#sync-provider-configurations)
- [URI patterns](#uri-patterns)
- [Source Configuration](#source-configuration)
<!-- TOC -->

`flagd` supports configuration via config file, environment variables and start-up flags. In cases of a conflict,
start-up flags have the highest priority, followed by environment variables and config file.

Supported start-up flags are documented (auto-generated) [here](./flagd_start.md).

Environment variable keys are uppercase, prefixed with `FLAGD_` and all `-` are replaced with `_`. For example,
`metrics-port` flag in environment variable form is `FLAGD_METRICS_PORT`.

The config file expects the keys to have the exact naming as startup-flags flags.

## Sync providers

Sync providers are a core part of flagd; they are the abstraction that enables different sources for feature flag configurations.
flagd currently support the following sync providers:

- [Configuration](#configuration)
- [Sync providers](#sync-providers)
- [Kubernetes provider](#kubernetes-provider)
- [Filepath provider](#filepath-provider)
- [Remote provider](#remote-provider)
- [GRPC provider](#grpc-provider)
- [Sync provider configurations](#sync-provider-configurations)
- [URI patterns](#uri-patterns)
- [Source Configuration](#source-configuration)

### Kubernetes provider

The Kubernetes sync provider allows flagd to connect to a Kubernetes cluster and evaluate flags against a specified
FeatureFlagConfiguration resource as defined within
the [open-feature-operator](https://github.com/open-feature/open-feature-operator/blob/main/apis/core/v1alpha1/featureflagconfiguration_types.go)
spec.

To use an existing FeatureFlagConfiguration custom resource, start flagD with the following command:

```shell
flagd start --uri core.openfeature.dev/default/my_example
```

In this example, `default/my_example` expected to be a valid FeatureFlagConfiguration resource, where `default` is the
namespace and `my_example` being the resource name.

### Filepath provider

The file path sync provider reads and watch the source file for updates(ex:- changes and deletions).

```shell
flagd start --uri file:etc/featureflags.json
```

In this example, `etc/featureflags.json` is a valid feature flag configuration file accessible by the flagd runtime.

### Remote provider

The HTTP sync provider fetch flags from a remote source and periodically poll the source for flag configuration updates.

```shell
flagd start --uri https://my-flag-source.json
```

In this example, `https://my-flag-source.json` is a remote endpoint responding valid feature flag configurations when
invoked with **HTTP GET** request.

### GRPC provider

The GRPC sync provider streams flag configurations from a grpc sync provider implementation. This stream connection is ruled
by
the [sync service protobuf definition](https://github.com/open-feature/schemas/blob/main/protobuf/sync/v1/sync_service.proto).

```shell
flagd start --uri grpc://grpc-sync-source
```

In this example, `grpc-sync-source` is a grpc target implementing flagd protobuf definition.

There are two mechanisms to provide configurations of sync providers,

- [URI patterns](#uri-patterns)
- [Source Configuration](#source-configuration)

## Sync provider configurations

### URI patterns

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

| Sync | Prefix | Example |
| ---------- | ---------------------- | ------------------------------------- |
| Kubernetes | `core.openfeature.dev` | `core.openfeature.dev/default/my-crd` |
| Filepath | `file:` | `file:etc/flagd/my-flags.json` |
| Remote | `http(s)://` | `https://my-flags.com/flags` |
| Grpc | `grpc(s)://` | `grpc://my-flags-server` |

### Source Configuration

While a URI may be passed to flagd via the `--uri` 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 provider |
| provider | required `string` | Provider type - `file`, `kubernetes`, `http` or `grpc` |
| bearerToken | optional `string` | Used for http sync; token gets appended to `Authorization` header with [bearer schema](https://www.rfc-editor.org/rfc/rfc6750#section-2.1) |
| interval | optional `uint32` | Used for http sync; 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 |

The `uri` field values **do not** follow the [URI patterns](#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.

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

Sync providers,

- `file` - config/samples/example_flags.json
- `http` - <http://my-flag-source.json/>
- `kubernetes` - default/my-flag-config
- `grpc`(insecure) - grpc-source:8080
- `grpc`(secure) - my-flag-source:8080

Startup command,

```sh
./bin/flagd start
--sources='[{"uri":"config/samples/example_flags.json","provider":"file"},
{"uri":"http://my-flag-source.json","provider":"http","bearerToken":"bearer-dji34ld2l"},
{"uri":"default/my-flag-config","provider":"kubernetes"},
{"uri":"grpc-source:8080","provider":"grpc"},
{"uri":"my-flag-source:8080","provider":"grpc", "certPath": "/certs/ca.cert", "tls": true, "providerID": "flagd-weatherapp-sidecar", "selector": "source=database,app=weatherapp"}]'
```

Configuration file,

```yaml
sources:
- uri: config/samples/example_flags.json
provider: file
- 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
certPath: /certs/ca.cert
tls: true
providerID: flagd-weatherapp-sidecar
selector: 'source=database,app=weatherapp'
```
The content of this page has moved. See [flagd configuration](https://flagd.dev/reference/configuration)
Loading