-
Notifications
You must be signed in to change notification settings - Fork 34
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore: attempt to improve documentation (#496)
Signed-off-by: Kavindu Dodanduwa <kavindudodanduwa@gmail.com> Signed-off-by: Kavindu Dodanduwa <Kavindu-Dodan@users.noreply.github.com> Co-authored-by: Giovanni Liva <giovanni.liva@dynatrace.com> Co-authored-by: Michael Beemer <beeme1mr@users.noreply.github.com>
- Loading branch information
1 parent
1ec3183
commit 603e74e
Showing
13 changed files
with
2,024 additions
and
173 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,24 +1,41 @@ | ||
# Docs | ||
# Documentation | ||
|
||
This directory contains all OpenFeature Operator documentation, see table of contents below: | ||
This directory contains OpenFeature Operator documentation. | ||
|
||
## Usage | ||
Interested in having OpenFeature Operator up and running within 5 minutes? Follow the quick start guide found below. | ||
|
||
Follow the documentation below to deploy the open feature operator to your local cluster, followed by a simple example app using `curl` to evaluate a static flag. | ||
- [Quick Start](./quick_start.md) | ||
|
||
Follow the detailed installation guide to deploy open feature operator to your local cluster. | ||
|
||
- [Installation](./installation.md) | ||
- [Getting Started](./getting_started.md) | ||
|
||
## Configuration | ||
|
||
Configuration of the deployed sidecars is handled through the `FeatureFlagConfiguration` CRs defined in the `openfeature.dev/featureflagconfiguration` annotation of a deployed `PodSpec`. | ||
> Further configuration of the operator will be possible in the future, to help contribute [click here](https://github.com/open-feature/open-feature-operator/issues) | ||
Configuration of the deployed sidecars is handled through the `FlagSourceConfiguration` custom resources defined at`openfeature.dev/flagsourceconfiguration` annotation of the deployed `PodSpec`. | ||
|
||
The relationship between the deployment and custom resources is highlighted in the diagram below, | ||
|
||
```mermaid | ||
flowchart TD | ||
A[Pod]-->|Annotation: openfeature.dev/flagsourceconfiguration| B[FlagSourceConfiguration CR] | ||
B--> |Flag source| C[FeatureFlagConfiguration CR] | ||
B--> |Flag source| D[HTTP sync] | ||
B--> |Flag source| E[Filepath sync] | ||
B--> |Flag source| F[GRPC sync] | ||
B--> |Flag source| G[flagd-proxy] | ||
``` | ||
|
||
To configure and understand more, | ||
|
||
- [Annotations](./annotations.md) | ||
- [FeatureFlagConfigurations](./feature_flag_configuration.md) | ||
- [FlagSourceConfiguration](./flag_source_configuration.md) | ||
- Deployment configurations: [Annotations](./annotations.md) | ||
- Define flag sources for the deployment: [FlagSourceConfiguration](./flag_source_configuration.md) | ||
- Define feature flags as custom resource: [FeatureFlagConfigurations](./feature_flag_configuration.md) | ||
|
||
## Other Resources | ||
- [Permissions](./permissions.md) | ||
- [Concepts](./concepts.md) | ||
- [Development Notes](./development_notes.md) | ||
- [flagd Kube Proxy](./flagd_proxy.md) | ||
- [Threat model](./threat_model.md) | ||
- [flagd Kube Proxy](./flagd_proxy.md) | ||
- [API Reference](./crds.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,23 +1,36 @@ | ||
# Concepts | ||
|
||
This document covers some key concepts related to the OpenFeature operator (OFO). For general OpenFeature or feature flag concepts, see our [online documentation](https://openfeature.dev/docs/reference/intro). | ||
This document covers some key concepts related to the OpenFeature operator (OFO). | ||
|
||
For general OpenFeature or feature flag concepts, see our [online documentation](https://openfeature.dev/docs/reference/intro). | ||
|
||
## Architecture | ||
|
||
The high level architecture of the operator is as follows: | ||
<p align="center"> | ||
<p> | ||
<img src="../images/arch-0.png" width="650"> | ||
</p> | ||
|
||
## Modes of operation | ||
## Modes of flag syncs | ||
|
||
- Kubernetes: sync configuration which configures injected flagd sidecar instances to monitor the Kubernetes API | ||
for changes in flag configuration custom resources (`FeatureFlagConfiguration`). | ||
- filepath: sync configuration which creates and mounts ConfigMap files from flag configuration custom resources | ||
(`FeatureFlagConfiguration`) and configures injected flagd sidecar instances to monitor them. | ||
- grpc: sync configuration which listen for flagd compatible grpc stream | ||
- http: sync configuration which watch and periodically poll flagd compatible http endpoint | ||
- [flagd-proxy](./flagd_proxy.md) | ||
|
||
Each approach have their advantages and disadvantages. | ||
|
||
OFO supports two primary modes of operation for supplying flag configurations to sidecar flagd instances: | ||
The kubernetes, grpc and flagd-proxy sync configuration has the advantage of providing near real-time flag updates(on the order of seconds) to the flagd sidecar. | ||
|
||
- The `"kubernetes"` sync configuration (default), which configures injected flagd sidecar instances to monitor the Kubernetes API for changes in flag configuration custom resources (`featureflagconfiguration`). | ||
- The `"filepath"` sync configuration, which creates and mounts ConfigMap files from flag configuration custom resources (`featureflagconfiguration`) and configures injected flagd sidecar instances to monitor them. | ||
For example, Kubernetes syncs require the flagd sidecar(and consequently the workload pod) to communicate with the | ||
Kubernetes API. This may violate the security or network policies of some organizations. | ||
|
||
Both approaches have their advantages and disadvantages. The `"kubernetes"` sync configuration has the advantage of providing near-realtime flag updates (on the order of seconds) to the flagd sidecar, and therefore the associated workload. However, it also requires the flagd sidecar (and consequently the workload pod) to communicate with the Kubernetes API. This may violate the security or network policies of some organizations. The `"filepath"` provider requires no such communication, but relies on the fact that [Kubernetes automatically updates mounted ConfigMaps](https://kubernetes.io/docs/concepts/configuration/configmap/#mounted-configmaps-are-updated-automatically). The disadvantage of this approach is that flag configuration updates may take as long as two minutes to propagate, depending on cluster configuration: | ||
The `"filepath"` provider requires no such communication, but relies on the fact that [Kubernetes automatically updates mounted ConfigMaps](https://kubernetes.io/docs/concepts/configuration/configmap/#mounted-configmaps-are-updated-automatically). | ||
The disadvantage of this approach is that flag configuration updates may take as long as two minutes to propagate, depending on cluster configuration: | ||
|
||
> "the total delay from the moment when the ConfigMap is updated to the moment when new keys are projected to the Pod can be as long as the kubelet sync period + cache propagation delay" | ||
Consider your individual requirements and select the configuration most appropriate for your needs. Note that the sync provider configuration to use can be configured globally and overridden per `featureflagconfiguration`. For details, see [the sync provider documentation](./feature_flag_configuration.md#syncprovider). | ||
Consider your individual requirements and select the configuration most appropriate for your needs. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.