chore: migration docs (#571)

Signed-off-by: Kavindu Dodanduwa <[email protected]>

Author: Kavindu-Dodan

README.md

@@ -12,7 +12,13 @@
 
 ## Get started
 
-The OpenFeature Operator allows you to expose feature flags to your applications. It injects a [flagD](https://github.com/open-feature/flagd) sidecar into relevant pods exposes gRPC and HTTP interfaces for flag evaluation. To get started, follow the installation instructions in the [docs](./docs).
+The OpenFeature Operator allows you to expose feature flags to your applications. 
+It injects a [flagd](https://github.com/open-feature/flagd) sidecar into relevant pods and exposes gRPC and HTTP interfaces for flag evaluation.
+To get started, follow the installation instructions in the [docs](./docs).
+
+> [!NOTE]
+> With version [v0.5.0](https://github.com/open-feature/open-feature-operator/releases/tag/v0.5.0), we have migrated 
+> to API version `v1beta1`. Please check the [migration guide](./docs/v1beta_migration.md) to migrate from old configurations.
 
 <h2 align="center"><a href="https://killercoda.com/open-feature/scenario/openfeature-operator-demo" target="_blank">Try the OpenFeature Operator in the Killercoda Playground (in browser)</a></h2>
 

config/samples/pod.yaml

@@ -3,11 +3,13 @@ kind: Pod
 metadata:
   name: nginx
   annotations:
+    # enable flagd injection for this workload
     openfeature.dev/enabled: "true"
-    openfeature.dev/featureflagconfiguration: "featureflagconfiguration-sample"
+    # flag source configuration(FeatureFlagSource) crd reference. See end-to-end.yaml for example
+    openfeature.dev/featureflagsource: "FeatureFlagSource"
 spec:
   containers:
-  - name: nginx
-    image: nginx:1.14.2
-    ports:
-    - containerPort: 80
+    - name: nginx
+      image: nginx:1.14.2
+      ports:
+        - containerPort: 80

docs/README.md

@@ -1,5 +1,9 @@
 # Documentation
 
+> [!NOTE]
+> With version [v0.5.0](https://github.com/open-feature/open-feature-operator/releases/tag/v0.5.0), we have migrated
+> to API version `v1beta1`. Please check the [migration guide](./v1beta_migration.md) to migrate from old configurations.
+
 This directory contains OpenFeature Operator documentation.
 
 Interested in having OpenFeature Operator up and running within 5 minutes? Follow the quick start guide found below.

docs/installation.md

@@ -7,7 +7,7 @@ The installation docs for cert manager can be found [here](https://cert-manager.
 Alternatively, running the commands below will install cert manager into the `cert-manager` namespace.
 
 ```sh
-kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.12.0/cert-manager.yaml &&
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.2/cert-manager.yaml &&
 kubectl wait --for=condition=Available=True deploy --all -n 'cert-manager'
 ```
 

docs/quick_start.md

@@ -18,7 +18,7 @@ kind create cluster -n kind
 #### 2. Install cert-manager
 
 ```sh
-kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.12.0/cert-manager.yaml &&
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.2/cert-manager.yaml &&
 kubectl wait --for=condition=Available=True deploy --all -n 'cert-manager'
 ```
 
@@ -66,7 +66,7 @@ kind: FeatureFlag
 metadata:
   name: sample-flags
 spec:
-  featureFlagSpec:
+  flagSpec:
     flags:
       foo:
         state: "ENABLED"

docs/v1beta_migration.md

@@ -0,0 +1,62 @@
+# Migrate to v1beta1
+
+OpenFeature Operator version [v0.5.0](https://github.com/open-feature/open-feature-operator/releases/tag/v0.5.0) contain improved, stable CRDs which were upgraded to `v1beta1` api version.
+This document shows what was changed and how you can upgrade your existing CRDs to be compatible with this new release.
+
+## Renaming FeatureFlagConfiguration to FeatureFlag
+
+Along with the API version upgrade to `v1beta1`, we have renamed `FeatureFlagConfiguration` to `FeatureFlag`, making the naming clearer for the custom resource maintainers. 
+In this CRD, spec section naming has changed. The older CRD used `featureFlagSpec` to define flag configurations.
+In the new version, flags are configured under `flagSpec` element.
+
+Consider below example with diff from old version to new version, 
+
+```diff
+- apiVersion: core.openfeature.dev/v1alpha3
++ apiVersion: core.openfeature.dev/v1beta1
+kind: FeatureFlagConfiguration
+metadata:
+  name: end-to-end
+  labels:
+    app: open-feature-demo
+spec:
+-  featureFlagSpec:
++  flagSpec 
+    flags:
+      new-welcome-message:
+        state: ENABLED
+        variants:
+          'on': true
+          'off': false
+        defaultVariant: 'off'
+```
+
+## openfeature.dev annotations
+
+There are several [annotations](./annotations.md) to control how OFO works on your workload.
+
+With the upgrade to `v1beta1`, we no longer support deprecated `openfeature.dev/featureflagconfiguration` annotation.
+Workloads which require feature flagging now need to use `openfeature.dev/featureflagsource` annotation, referring a [FeatureFlagSource](./feature_flag_source.md) CRD.
+
+```diff
+  annotations:
+    openfeature.dev/enabled: "true"
+-    openfeature.dev/featureflagconfiguration: "end-to-end"
++    openfeature.dev/featureflagsource: "end-to-end"
+```
+
+`FeatureFlagSource` provide more flexibility by allowing users to configure the injected flag with many options.
+Consider below example for a `FeatureFlagSource` where flagd is instructed to use `FeatureFlag` custom resource named `end-to-end` as its flag source
+
+```yaml
+apiVersion: core.openfeature.dev/v1beta1
+kind: FeatureFlagSource
+metadata:
+  name: end-to-end
+  labels:
+    app: open-feature-demo
+spec:
+  sources:
+    - source: end-to-end
+      provider: kubernetes
+```