Skip to content

Commit ccc0471

Browse files
odubajDTStackScribetoddbaert
authored
docs: use v1beta1 API version (#553)
Signed-off-by: odubajDT <ondrej.dubaj@dynatrace.com> Signed-off-by: odubajDT <93584209+odubajDT@users.noreply.github.com> Co-authored-by: Meg McRoberts <meg.mcroberts@dynatrace.com> Co-authored-by: Todd Baert <toddbaert@gmail.com> Co-authored-by: Todd Baert <todd.baert@dynatrace.com>
1 parent 233be79 commit ccc0471

11 files changed

+91
-113
lines changed

CONTRIBUTING.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,16 @@ There are a few things to consider before contributing to open-feature-operator.
77
Firstly, there's [a code of conduct](https://github.com/open-feature/.github/blob/main/CODE_OF_CONDUCT.md).
88
TLDR: be respectful.
99

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

1212
The go version in the `go.mod` is the currently supported version of go.
1313

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

1616
## Development
1717

18-
### FeatureFlagConfiguration custom resource definition versioning
19-
Custom resource definitions support multiple versions. The kubebuilder framework exposes a system to seamlessly convert between versions (using a "hub and spoke" model) maintaining backwards compatibility. It does this by injecting conversion webhooks that call our defined convert functions. The hub version of the `FeatureFlagConfiguration` custom resource definition (the version to which all other versions are converted) is `v1alpha1`.
18+
### FeatureFlag custom resource definition versioning
19+
Custom resource definitions support multiple versions. The kubebuilder framework exposes a system to seamlessly convert between versions (using a "hub and spoke" model) maintaining backwards compatibility. It does this by injecting conversion webhooks that call our defined convert functions. The hub version of the `FeatureFlag` custom resource definition (the version to which all other versions are converted) is `v1beta1`.
2020
Follow [this tutorial](https://book.kubebuilder.io/multiversion-tutorial/conversion-concepts.html) to implement a new version of the custom resource definition.
2121

2222
### Local build

docs/README.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -12,14 +12,14 @@ Follow the detailed installation guide to deploy open feature operator to your l
1212

1313
## Configuration
1414

15-
Configuration of the deployed sidecars is handled through the `FlagSourceConfiguration` custom resources defined at`openfeature.dev/flagsourceconfiguration` annotation of the deployed `PodSpec`.
15+
Configuration of the deployed sidecars is handled through the `FeatureFlagSource` custom resources referenced via `openfeature.dev/featureflagsource` annotations of the deployed `PodSpec`.
1616

1717
The relationship between the deployment and custom resources is highlighted in the diagram below,
1818

1919
```mermaid
2020
flowchart TD
21-
A[Pod]-->|Annotation: openfeature.dev/flagsourceconfiguration| B[FlagSourceConfiguration CR]
22-
B--> |Flag source| C[FeatureFlagConfiguration CR]
21+
A[Pod]-->|Annotation: openfeature.dev/featureflagsource| B[FeatureFlagSource CR]
22+
B--> |Flag source| C[FeatureFlag CR]
2323
B--> |Flag source| D[HTTP sync]
2424
B--> |Flag source| E[Filepath sync]
2525
B--> |Flag source| F[GRPC sync]
@@ -29,8 +29,8 @@ flowchart TD
2929
To configure and understand more,
3030

3131
- Deployment configurations: [Annotations](./annotations.md)
32-
- Define flag sources for the deployment: [FlagSourceConfiguration](./flag_source_configuration.md)
33-
- Define feature flags as custom resource: [FeatureFlagConfigurations](./feature_flag_configuration.md)
32+
- Define flag sources for the deployment: [FeatureFlagSource](./feature_flag_source.md)
33+
- Define feature flags as custom resource: [FeatureFlags](./feature_flag.md)
3434

3535
## Other Resources
3636
- [Permissions](./permissions.md)

docs/annotations.md

+3-28
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,9 @@ Example:
1313
openfeature.dev/enabled: "true"
1414
```
1515
16-
### `openfeature.dev/flagsourceconfiguration`
16+
### `openfeature.dev/featureflagsource`
1717

18-
This annotation specifies the names of the `FlagSourceConfigurations` used to configure the injected flagd sidecar.
18+
This annotation specifies the names of the `FeatureFlagSources` used to configure the injected flagd sidecar.
1919
The annotation value is a comma separated list of values following one of 2 patterns: {NAME} or {NAMESPACE}/{NAME}.
2020

2121
If no namespace is provided, it is assumed that the custom resource is within the **same namespace** as the annotated pod.
@@ -28,7 +28,7 @@ Example:
2828
metadata:
2929
annotations:
3030
openfeature.dev/enabled: "true"
31-
openfeature.dev/flagsourceconfiguration: "config-A, config-B"
31+
openfeature.dev/featureflagsource: "config-A, config-B"
3232
```
3333

3434
### `openfeature.dev/allowkubernetessync`
@@ -40,28 +40,3 @@ When the OFO manager pod is started, all `Service Accounts` of any `Pods` with t
4040
## Deprecated annotations
4141

4242
Given below are references to **deprecated** annotations used by previous versions of the operator.
43-
44-
### `openfeature.dev/featureflagconfiguration`
45-
*This annotation is DEPRECATED in favour of the `openfeature.dev/flagsourceconfiguration` annotation and should no longer be used.*
46-
47-
This annotation specifies the names of the FeatureFlagConfigurations used to configure the injected flagd sidecar.
48-
The annotation value is a comma separated list of values following one of 2 patterns: {NAME} or {NAMESPACE}/{NAME}.
49-
If no namespace is provided it is assumed that the CR is within the same namespace as the deployed pod.
50-
Example:
51-
```yaml
52-
metadata:
53-
annotations:
54-
openfeature.dev/enabled: "true"
55-
openfeature.dev/featureflagconfiguration: "demo, test/demo-2"
56-
```
57-
58-
### `openfeature.dev`
59-
*This annotation is DEPRECATED in favour of the `openfeature.dev/enabled` annotation and should no longer be used.*
60-
61-
When a value of `"enabled"` is provided, the operator will inject a flagd sidecar into the annotated pods.
62-
Example:
63-
```yaml
64-
metadata:
65-
annotations:
66-
openfeature.dev: "enabled"
67-
```

docs/concepts.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,11 @@ The high level architecture of the operator is as follows:
1313

1414
## Modes of flag syncs
1515

16-
- Kubernetes: sync configuration which configures injected flagd sidecar instances to monitor the Kubernetes API
17-
for changes in flag configuration custom resources (`FeatureFlagConfiguration`).
18-
- filepath: sync configuration which creates and mounts ConfigMap files from flag configuration custom resources
19-
(`FeatureFlagConfiguration`) and configures injected flagd sidecar instances to monitor them.
20-
- grpc: sync configuration which listen for flagd compatible grpc stream
16+
- Kubernetes: sync configuration that configures injected flagd sidecar instances to monitor the Kubernetes API
17+
for changes in flag definition custom resources (`FeatureFlag`).
18+
- filepath: sync configuration that creates and mounts ConfigMap files from flag configuration custom resources
19+
(`FeatureFlag`) and configures injected flagd sidecar instances to monitor them.
20+
- grpc: sync configuration that listens for flagd compatible grpc stream
2121
- http: sync configuration which watch and periodically poll flagd compatible http endpoint
2222
- [flagd-proxy](./flagd_proxy.md)
2323

Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
1-
# Feature Flag Configuration
1+
# Feature Flag
22

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

55
```yaml
6-
apiVersion: core.openfeature.dev/v1alpha2
7-
kind: FeatureFlagConfiguration
6+
apiVersion: core.openfeature.dev/v1beta1
7+
kind: FeatureFlag
88
metadata:
9-
name: featureflagconfiguration-sample
9+
name: featureflag-sample
1010
spec:
11-
featureFlagSpec:
11+
flagSpec:
1212
flags:
1313
foo:
1414
state: "ENABLED"
@@ -22,7 +22,7 @@ In the example above, we have defined a `String` type feature flag named `foo` a
2222
It has variants of `bar` and `baz`, referring to respected values of `BAR` and `BAZ`.
2323
The default variant is set to`bar`.
2424

25-
## featureFlagSpec
25+
## flagSpec
2626

27-
The `featureFlagSpec` is an object representing the flag configurations themselves.
27+
The `flagSpec` is an object representing the flag definitions themselves.
2828
The documentation for this object can be found [here](https://github.com/open-feature/flagd/blob/main/docs/configuration/flag_configuration.md).

docs/flag_source_configuration.md docs/feature_flag_source.md

+33-30
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,45 @@
11
# Flag Source configuration
22

3-
The injected sidecar is configured using the `FlagSourceConfiguration` custom resource definition.
4-
The `openfeature.dev/flagsourceconfiguration` annotation is used to assign Pods with their respective`FlagSourceConfiguration` custom resources.
3+
The injected sidecar is configured using the `FeatureFlagSource` custom resource definition.
4+
The `openfeature.dev/featureflagsource` annotation is used to assign Pods with their respective `FeatureFlagSource` custom resources.
55

6-
A minimal example of a `FlagSourceConfiguration` is given below,
6+
A minimal example of a `FeatureFlagSource` is given below,
77

88
```yaml
9-
apiVersion: core.openfeature.dev/v1alpha3
10-
kind: FlagSourceConfiguration
9+
apiVersion: core.openfeature.dev/v1beta1
10+
kind: FeatureFlagSource
1111
metadata:
12-
name: flag-source-configuration
12+
name: feature-flag-source
1313
spec:
1414
sources: # flag sources for the injected flagd
15-
- source: flags/sample-flags # FlagSourceConfiguration - namespace/name
16-
provider: kubernetes # kubernetes flag source backed by FlagSourceConfiguration custom resource
15+
- source: flags/sample-flags # FeatureFlag - namespace/name
16+
provider: kubernetes # kubernetes flag source backed by FeatureFlag custom resource
1717
port: 8080 # port of the flagd sidecar
1818
```
1919
2020
## Feature flag sources
2121
2222
This section explains how to configure feature flag sources to injected flag sidecar.
2323
24-
`FlagSourceConfiguration` support multiple flag sources. Sources are configured as a list and given below are supported sources and their configurations,
24+
`FeatureFlagSource` support multiple flag sources. Sources are configured as a list.
25+
Supported sources and their configurations are listed below.
2526

26-
### kubernetes aka `FeatureFlagConfiguration`
27+
### kubernetes aka `FeatureFlag`
2728

28-
This is `FeatureFlagConfiguration` custom resource backed flagd feature flag definition.
29-
Read more on the custom resource at the dedicated documentation of [FeatureFlagConfiguration](./feature_flag_configuration.md)
29+
This is `FeatureFlag` custom resource backed flagd feature flag definition.
30+
Read more about the custom resource at the dedicated documentation of [FeatureFlag](./feature_flag.md)
3031

31-
To refer this custom resource in `FlagSourceConfiguration`, provider type `kubernetes` is used as below example,
32+
The following example of a `FeatureFlagSource` uses `kubernetes` as the `provider` type:
3233

3334
```yaml
3435
sources:
35-
- source: flags/sample-flags # FeatureFlagConfiguration - namespace/custom_resource_name
36-
provider: kubernetes # kubernetes flag source backed by FeatureFlagConfiguration custom resource
36+
- source: flags/sample-flags # FeatureFlag - namespace/custom_resource_name
37+
provider: kubernetes # kubernetes flag source backed by FeatureFlag custom resource
3738
```
3839

3940
### flagd-proxy
4041

41-
`flagd-proxy` is an alternative to direct resource access on `FeatureFlagConfiguration` custom resources.
42+
`flagd-proxy` is an alternative to direct resource access on `FeatureFlag` custom resources.
4243
This source type is useful when there is a need for restricting workload permissions and/or to reduce k8s API load.
4344

4445
Read more about proxy approach to access kubernetes resources: [flagd-proxy](./flagd_proxy.md)
@@ -81,7 +82,7 @@ sources:
8182

8283
## Sidecar configurations
8384

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

8788
| Configuration | Explanation | Default |
@@ -105,18 +106,20 @@ If no namespace is provided, it is assumed that the CR is within the same namesp
105106
namespace: test-ns
106107
annotations:
107108
openfeature.dev/enabled: "true"
108-
openfeature.dev/flagsourceconfiguration: "config-A, test-ns-2/config-B"
109+
openfeature.dev/featureflagsource: "config-A, test-ns-2/config-B"
109110
```
110111

111112
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.
112113

113-
The `FlagSourceConfiguration` version `v1alpha3` CRD defines a CR with the following example structure, the documentation for this CRD can be found [here](crds.md#flagsourceconfiguration):
114+
The `FeatureFlagSource` version `v1beta1` CRD defines a CR with the following example structure.
115+
The documentation for this CRD can be found
116+
[here](crds.md#featureflagsource):
114117

115118
```yaml
116-
apiVersion: core.openfeature.dev/v1alpha3
117-
kind: FlagSourceConfiguration
119+
apiVersion: core.openfeature.dev/v1beta1
120+
kind: FeatureFlagSource
118121
metadata:
119-
name: flag-source-sample
122+
name: feature-flag-source-sample
120123
spec:
121124
metricsPort: 8080
122125
port: 80
@@ -145,16 +148,16 @@ spec:
145148
memory: 256Mi
146149
```
147150

148-
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.
151+
The relevant `FeatureFlagSources` are passed to the operator by setting the `openfeature.dev/featureflagsource` annotation, which provides the full configuration of the injected sidecar.
149152

150153
## Configuration Merging
151154

152-
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.
155+
When multiple `FeatureFlagSources` are provided, the configurations are merged. The last `CR` takes precedence over the first.
153156

154157

155158
```mermaid
156159
flowchart LR
157-
FlagSourceConfiguration-values -->|highest priority| environment-variables -->|lowest priority| defaults
160+
FeatureFlagSource-values -->|highest priority| environment-variables -->|lowest priority| defaults
158161
```
159162

160163

@@ -163,12 +166,12 @@ An example of this behavior:
163166
metadata:
164167
annotations:
165168
openfeature.dev/enabled: "true"
166-
openfeature.dev/flagsourceconfiguration:"config-A, config-B"
169+
openfeature.dev/featureflagsource:"config-A, config-B"
167170
```
168171
Config-A:
169172
```
170-
apiVersion: core.openfeature.dev/v1alpha2
171-
kind: FlagSourceConfiguration
173+
apiVersion: core.openfeature.dev/v1beta1
174+
kind: FeatureFlagSource
172175
metadata:
173176
name: config-A
174177
spec:
@@ -177,8 +180,8 @@ spec:
177180
```
178181
Config-B:
179182
```
180-
apiVersion: core.openfeature.dev/v1alpha2
181-
kind: FlagSourceConfiguration
183+
apiVersion: core.openfeature.dev/v1beta1
184+
kind: FeatureFlagSource
182185
metadata:
183186
name: config-B
184187
spec:

docs/flagd_proxy.md

+6-6
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,13 @@
22

33
> The flagd kube proxy is currently in an experimental state
44
5-
The `flagd-proxy` is a pub/sub for mechanism watching configuration changes in `FeatureFlagConfiguration` CRs.
5+
The `flagd-proxy` is a pub/sub for mechanism watching configuration changes in `FeatureFlag` CRs.
66
This source type avoids the need for additional cluster wide permissions in the workload pod, and reduces load on the k8s API.
7-
In order for a pod to have the required permissions to watch a `FeatureFlagConfiguration` CR in the default implementation, it must have its service account appended to the `flagd-kubernetes-sync` role binding, the details for this role can be found [here](./permissions.md).
7+
In order for a pod to have the required permissions to watch a `FeatureFlag` CR in the default implementation, it must have its service account appended to the `flagd-kubernetes-sync` role binding, the details for this role can be found [here](./permissions.md).
88
In some use cases this may not be favorable, in these scenarios the alternative `flagd-proxy` implementation may be used.
99

1010
The `flagd-proxy` bypasses the widespread permissions issue by acting as the single source of truth for subscribed flagd instances, broadcasting configuration changes to all subscribed pods via gRPC streams.
11-
For each requested `FeatureFlagConfiguration` a new ISync implementation is started, and closed once there are no longer any listeners.
11+
For each requested `FeatureFlag` a new ISync implementation is started, and closed once there are no longer any listeners.
1212
This results in only one set of resources requiring the `flagd-kubernetes-sync` permissions, tightening the restrictions on all other pods.
1313

1414
## Architecture
@@ -19,15 +19,15 @@ The diagram below describes the high level architecture and implementation of th
1919
<img src="../images/flagd-proxy-arch.png" width="95%">
2020
</p>
2121

22-
The `flagd-proxy` is only deployed once the reconcile loop for a `FlagSourceConfiguration` is run with a CR containing the provider `"flagd-proxy"` in its source array.
22+
The `flagd-proxy` is only deployed once the reconcile loop for a `FeatureFlagSource` is run with a CR containing the provider `"flagd-proxy"` in its source array.
2323

2424
## Implementation
2525

2626
Update the end-to-end test in `/config/samples/end-to-end.yaml` to use the `"flagd-proxy"` provider, the source should be a `namespace/name`.
2727

2828
```diff
29-
apiVersion: core.openfeature.dev/v1alpha2
30-
kind: FlagSourceConfiguration
29+
apiVersion: core.openfeature.dev/v1beta1
30+
kind: FeatureFlagSource
3131
metadata:
3232
name: end-to-end
3333
namespace: open-feature-demo

docs/installation.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -37,16 +37,16 @@ OpenFeature Operator's CRDs are templated, and can be updated apart from the ope
3737
helm template openfeature/open-feature-operator -s templates/{CRD} | kubectl apply -f -
3838
```
3939

40-
For the `featureflagconfigurations.core.openfeature.dev` CRD:
40+
For the `featureflags.core.openfeature.dev` CRD:
4141

4242
```sh
43-
helm template openfeature/open-feature-operator -s templates/apiextensions.k8s.io_v1_customresourcedefinition_featureflagconfigurations.core.openfeature.dev.yaml | kubectl apply -f -
43+
helm template openfeature/open-feature-operator -s templates/apiextensions.k8s.io_v1_customresourcedefinition_featureflags.core.openfeature.dev.yaml | kubectl apply -f -
4444
```
4545

46-
For the `flagsourceconfigurations.core.openfeature.dev` CRD:
46+
For the `featureflagsources.core.openfeature.dev` CRD:
4747

4848
```sh
49-
helm template openfeature/open-feature-operator -s templates/apiextensions.k8s.io_v1_customresourcedefinition_flagsourceconfigurations.core.openfeature.dev.yaml | kubectl apply -f -
49+
helm template openfeature/open-feature-operator -s templates/apiextensions.k8s.io_v1_customresourcedefinition_featureflagsources.core.openfeature.dev.yaml | kubectl apply -f -
5050
```
5151

5252
Keep in mind, you can set values as usual during this process:
@@ -77,7 +77,7 @@ kubectl delete namespace open-feature-operator-system
7777
<!-- x-release-please-end -->
7878

7979
## Release contents
80-
- `FeatureFlagConfiguration` `CustomResourceDefinition` (custom type that holds the configured state of feature flags).
80+
- `FeatureFlag` `CustomResourceDefinition` (custom type that holds the configured state of feature flags).
8181
- Standard kubernetes primitives (e.g. namespace, accounts, roles, bindings, configmaps).
8282
- Operator controller manager service.
8383
- Operator webhook service.

0 commit comments

Comments
 (0)