Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
update docs
Browse files Browse the repository at this point in the history
Signed-off-by: odubajDT <[email protected]>
odubajDT committed Nov 14, 2023
1 parent efce742 commit f47ee7e
Showing 7 changed files with 40 additions and 40 deletions.
8 changes: 4 additions & 4 deletions docs/concepts/syncs.md
Original file line number Diff line number Diff line change
@@ -50,18 +50,18 @@ See [sync source](../reference/sync-configuration.md#source-configuration) confi
### Kubernetes sync

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)
FeatureFlag resource as defined within
the [open-feature-operator](https://github.com/open-feature/open-feature-operator/blob/main/apis/core/v1beta1/featureflag_types.go)
spec.
This configuration is best used in conjunction with the [OpenFeature Operator](https://github.com/open-feature/open-feature-operator).

To use an existing FeatureFlagConfiguration custom resource, start flagd with the following command:
To use an existing FeatureFlag 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
In this example, `default/my_example` expected to be a valid FeatureFlag resource, where `default` is the
namespace and `my_example` being the resource name.
See [sync source](../reference/sync-configuration.md#source-configuration) configuration for details.

Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# Feature Flag Configuration

The `FeatureFlagConfiguration` version `v1alpha2` CRD defines a CR with the following example structure:
The `FeatureFlag` version `v1beta1` CRD defines a CR with the following example structure:

```yaml
apiVersion: core.openfeature.dev/v1alpha2
kind: FeatureFlagConfiguration
kind: FeatureFlag
metadata:
name: featureflagconfiguration-sample
name: featureflag-sample
spec:
featureFlagSpec:
flags:
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
# FlagSourceConfigurations
# FeatureFlagSources

`FlagSourceConfiguration` support multiple flag sources. Sources are configured as a list and given below are supported sources and their configurations,
`FeatureFlagSource` support multiple flag sources. Sources are configured as a list and given below are supported sources and their configurations,

## kubernetes aka `FeatureFlagConfiguration`
## kubernetes aka `FeatureFlag`

This is `FeatureFlagConfiguration` custom resource backed flagd feature flag definition.
Read more on the custom resource at the dedicated documentation of [FeatureFlagConfiguration](https://github.com/open-feature/open-feature-operator/blob/main/docs/feature_flag_configuration.md)
This is `FeatureFlag` custom resource backed flagd feature flag definition.
Read more on the custom resource at the dedicated documentation of [FeatureFlag](https://github.com/open-feature/open-feature-operator/blob/main/docs/feature_flag_configuration.md)

To refer this custom resource in `FlagSourceConfiguration`, provider type `kubernetes` is used as below example,
To refer this custom resource in `FlagSource`, provider type `kubernetes` is used as below example,

```yaml
sources:
- source: flags/sample-flags # FeatureFlagConfiguration - namespace/custom_resource_name
provider: kubernetes # kubernetes flag source backed by FeatureFlagConfiguration custom resource
- source: flags/sample-flags # FeatureFlag - namespace/custom_resource_name
provider: kubernetes # kubernetes flag source backed by FeatureFlag custom resource
```
## flagd-proxy
`flagd-proxy` is an alternative to direct resource access on `FeatureFlagConfiguration` custom resources.
`flagd-proxy` is an alternative to direct resource access on `FeatureFlag` custom resources.
This source type is useful when there is a need for restricting workload permissions and/or to reduce k8s API load.

Read more about proxy approach to access kubernetes resources: [flagd-proxy](https://github.com/open-feature/open-feature-operator/blob/main/docs/flagd_proxy.md)
@@ -60,7 +60,7 @@ sources:

## Sidecar configurations

`FlagSourceConfiguration` further allows to provide configurations to the injected flagd sidecar.
`FeatureFlagSource` further allows to provide configurations to the injected flagd sidecar.
Table given below is non-exhaustive list of overriding options,

| Configuration | Explanation | Default |
@@ -82,16 +82,16 @@ If no namespace is provided, it is assumed that the CR is within the same namesp
namespace: test-ns
annotations:
openfeature.dev/enabled: "true"
openfeature.dev/flagsourceconfiguration: "config-A, test-ns-2/config-B"
openfeature.dev/featureflagsource: "config-A, test-ns-2/config-B"
```

In this example, 2 CRs are being used to configure the injected container (by default the operator uses the `flagd:main` image), `config-A` (which is assumed to be in the namespace `test-ns`) and `config-B` from the `test-ns-2` namespace, with `config-B` taking precedence in the configuration merge.

The `FlagSourceConfiguration` version `v1alpha3` CRD defines a CR with the following example structure, the documentation for this CRD can be found [here](https://github.com/open-feature/open-feature-operator/blob/main/docs/crds.md#flagsourceconfiguration):
The `FeatureFlagSource` version `v1alpha3` CRD defines a CR with the following example structure, the documentation for this CRD can be found [here](https://github.com/open-feature/open-feature-operator/blob/main/docs/crds.md#featureflagsource):

```yaml
apiVersion: core.openfeature.dev/v1alpha3
kind: FlagSourceConfiguration
kind: FeatureFlagSource
metadata:
name: flag-source-sample
spec:
@@ -114,15 +114,15 @@ spec:
debugLogging: false
```

The relevant `FlagSourceConfigurations` are passed to the operator by setting the `openfeature.dev/flagsourceconfiguration` annotation, and is responsible for providing the full configuration of the injected sidecar.
The relevant `FeatureFlagSources` are passed to the operator by setting the `openfeature.dev/featureflagsource` annotation, and is responsible for providing the full configuration of the injected sidecar.

## Configuration Merging

When multiple `FlagSourceConfigurations` are provided, the configurations are merged. The last `CR` takes precedence over the first, with any configuration from the deprecated `FlagDSpec` field of the `FeatureFlagConfiguration` CRD taking the lowest priority.
When multiple `FeatureFlagSources` are provided, the configurations are merged. The last `CR` takes precedence over the first, with any configuration from the deprecated `FlagDSpec` field of the `FeatureFlag` CRD taking the lowest priority.

```mermaid
flowchart LR
FlagSourceConfiguration-values -->|highest priority| environment-variables -->|lowest priority| defaults
FeatureFlagSource-values -->|highest priority| environment-variables -->|lowest priority| defaults
```

An example of this behavior:
@@ -131,14 +131,14 @@ An example of this behavior:
metadata:
annotations:
openfeature.dev/enabled: "true"
openfeature.dev/flagsourceconfiguration:"config-A, config-B"
openfeature.dev/featureflagsource:"config-A, config-B"
```

Config-A:

```yaml
apiVersion: core.openfeature.dev/v1alpha2
kind: FlagSourceConfiguration
kind: FeatureFlagSource
metadata:
name: config-A
spec:
@@ -150,7 +150,7 @@ Config-B:

```yaml
apiVersion: core.openfeature.dev/v1alpha2
kind: FlagSourceConfiguration
kind: FeatureFlagSource
metadata:
name: config-B
spec:
20 changes: 10 additions & 10 deletions docs/reference/openfeature-operator/installation.md
Original file line number Diff line number Diff line change
@@ -27,14 +27,14 @@ Create a namespace to house your flags:
kubectl create namespace flags
```

Next, define your feature flag(s) using the [FeatureFlagConfiguration](./crds/featureflagconfiguration.md) custom resource definition (CRD).
Next, define your feature flag(s) using the [FeatureFlag](./crds/featureflag.md) custom resource definition (CRD).

This example specifies one flag called `foo` which has two variants `bar` and `baz`. The `defaultVariant` is `bar`.

```bash
kubectl apply -n flags -f - <<EOF
apiVersion: core.openfeature.dev/v1alpha2
kind: FeatureFlagConfiguration
apiVersion: core.openfeature.dev/v1beta1
kind: FeatureFlag
metadata:
name: sample-flags
spec:
@@ -52,18 +52,18 @@ EOF

Next, tell the OpenFeature operator where to find flags.

Do so by creating a [FlagSourceConfiguration](./crds/flagsourceconfiguration.md) CRD.
Do so by creating a [FeatureFlagSource](./crds/featureflagsource.md) CRD.

This example specifies that the CRD called `sample-flags` (created above) can be found in the `flags` namespace and that the provider is `kubernetes`.

The `port` parameter defines the port on which the flagd API will be made available via the sidecar (more on this below).

```bash
kubectl apply -n flags -f - <<EOF
apiVersion: core.openfeature.dev/v1alpha3
kind: FlagSourceConfiguration
apiVersion: core.openfeature.dev/v1beta1
kind: FeatureFlagSource
metadata:
name: flag-source-configuration
name: feature-flag-source
spec:
sources:
- source: flags/sample-flags
@@ -77,11 +77,11 @@ EOF
The operator looks for `Deployment` objects annotated with particular annotations.

- `openfeature.dev/enabled: "true"` enables this deployment for flagd
- `openfeature.dev/flagsourceconfiguration: "flags/flag-source-configuration"` makes the given feature flag sources available to this deployment
- `openfeature.dev/featureflagsource: "flags/feature-flag-source"` makes the given feature flag sources available to this deployment

When these two annotations are added, the OpenFeature operator will inject a sidecar into your workload.

flagd will then be available via `http://localhost` the port specified in the `FlagSourceConfiguration` (e.g. `8080`)
flagd will then be available via `http://localhost` the port specified in the `FeatureFlagSource` (e.g. `8080`)

Your Deployment YAML might look like this:

@@ -102,7 +102,7 @@ spec:
annotations:
# here are the annotations for OpenFeature Operator
openfeature.dev/enabled: "true"
openfeature.dev/flagsourceconfiguration: "flags/flag-source-configuration"
openfeature.dev/featureflagsource: "flags/feature-flag-source"
spec:
containers:
- name: busybox
2 changes: 1 addition & 1 deletion docs/reference/specifications/in-process-providers.md
Original file line number Diff line number Diff line change
@@ -21,7 +21,7 @@ in-process flagd provider via a gRPC client connection to a sync server, such as

An implementation of an in-process flagd-provider must accept the following environment variables which determine the sync source:

- `FLAGD_SOURCE_URI`: The URI identifying the sync source. Depending on the sync provider type, this can be the URI of a gRPC service providing the `sync` API required by the in-process flagd provider, or the name of a [core.openfeature.dev/v1alpha2.FeatureFlagConfiguration](https://github.com/open-feature/open-feature-operator/blob/main/docs/crds.md#featureflagconfiguration-1) Custom Resource containing the flag definition.
- `FLAGD_SOURCE_URI`: The URI identifying the sync source. Depending on the sync provider type, this can be the URI of a gRPC service providing the `sync` API required by the in-process flagd provider, or the name of a [core.openfeature.dev/v1beta1.FeatureFlag](https://github.com/open-feature/open-feature-operator/blob/main/docs/crds.md#featureflag-1) Custom Resource containing the flag definition.
- `FLAGD_SOURCE_PROVIDER_TYPE`: The type of the provider. E.g. `grpc` or `kubernetes`.
- `FLAGD_SOURCE_SELECTOR`: Optional selector for the feature flag definition of interest. This is used as a `selector` for the flagd-proxie's sync API to identify a flag definition within a collection of feature flag definitions.

2 changes: 1 addition & 1 deletion flagd-proxy/README.md
Original file line number Diff line number Diff line change
@@ -2,7 +2,7 @@

[![experimental](http://badges.github.io/stability-badges/dist/experimental.svg)](http://github.com/badges/stability-badges)

The kube flagd proxy acts as a pub sub for deployed flagd sidecar containers to subscribe to change events in FeatureFlagConfiguration CRs.
The kube flagd proxy acts as a pub sub for deployed flagd sidecar containers to subscribe to change events in FeatureFlag CRs.
<!-- markdownlint-disable MD033 -->
<p align="center">
<img src="../images/flagd-proxy.png" width="650">
4 changes: 2 additions & 2 deletions mkdocs.yml
Original file line number Diff line number Diff line change
@@ -92,8 +92,8 @@ nav:
- 'String Comparison Specification': 'reference/specifications/custom-operations/string-comparison-operation-spec.md'
- 'OpenFeature Operator':
- 'Installation': 'reference/openfeature-operator/installation.md'
- 'FeatureFlagConfiguration': 'reference/openfeature-operator/crds/featureflagconfiguration.md'
- 'FlagSourceConfiguration': 'reference/openfeature-operator/crds/flagsourceconfiguration.md'
- 'FeatureFlag': 'reference/openfeature-operator/crds/featureflag.md'
- 'FeatureFlagSource': 'reference/openfeature-operator/crds/featureflagsource.md'
- 'Naming': 'reference/naming.md'
- 'FAQ': 'faq.md'
- 'Troubleshooting': 'troubleshooting.md'

0 comments on commit f47ee7e

Please sign in to comment.