Merge pull request #278 from james-milligan/docs

docs: OFO doc updates

Author: james-milligan

README.md

@@ -12,168 +12,21 @@
 [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/6615/badge)](https://bestpractices.coreinfrastructure.org/projects/6615)
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fopen-feature%2Fopen-feature-operator.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fopen-feature%2Fopen-feature-operator?ref=badge_shield)
 
-The OpenFeature Operator is a Kubernetes native operator that allows you to expose feature flags to your applications. It injects a [flagD](https://github.com/open-feature/flagd) sidecar into your pod and allows you to poll the flagD server for feature flags in a variety of ways.
 
-## Deploy the latest release
+## Get started
 
-_Requires [cert manager](https://cert-manager.io/docs/installation/kubernetes/) installed (see why [here](#cert-manager))_
+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).
 
-## Helm
+## Contributing
 
-Install cert manager (if not already installed):
-```
-kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.9.1/cert-manager.yaml
-```
-Install helm charts:
-```
-helm repo add openfeature https://open-feature.github.io/open-feature-operator/
-```
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to the OpenFeature project.
 
-```
-helm install ofo openfeature/ofo
-```
+Our community meetings are held regularly and open to everyone. Check the [OpenFeature community calendar](https://calendar.google.com/calendar/u/0?cid=MHVhN2kxaGl2NWRoMThiMjd0b2FoNjM2NDRAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ) for specific dates and for the Zoom meeting links.
 
+Thanks so much to our contributors.
 
-## Kubectl
+<a href="https://github.com/open-feature/flagd/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=open-feature/open-feature-operator" />
+</a>
 
-<!---x-release-please-start-version-->
-
-```
-kubectl create namespace open-feature-operator-system
-kubectl apply -f https://github.com/open-feature/open-feature-operator/releases/download/v0.2.20/release.yaml
-```
-
-<!---x-release-please-end-->
-
-
-### Release contents
-
-- `release.yaml` contains the configuration of:
-  - `FeatureFlagConfiguration` `CustomResourceDefinition` (custom type that holds the configured state of feature flags).
-  - Standard kubernetes primitives (e.g. namespace, accounts, roles, bindings, configmaps).
-  - Operator controller manager service.
-  - Operator webhook service.
-  - Deployment with containers kube-rbac-proxy & manager.
-  - `MutatingWebhookConfiguration` (configures webhooks to call the webhook service).
-
-### How to deploy a flag consuming application
-
-_Prerequisite: the release and certificates have been deployed as outlined above._
-
-Deploying a flag consuming application requires (at minimum) the creation of the following 2 resources (an example can be found [here](./config/samples/end-to-end.yaml)):
-
-#### FeatureFlagConfiguration
-
-This is a `CustomResourceDefinition` which contains the feature flags specification and a name of the spec.
-
-#### Deployment (or Statefulset/Daemonset)
-
-This is a kubernetes primitive for deploying an application. The metadata annotations must include `openfeature.dev/featureflagconfiguration`
-with the value set as the name of the `FeatureFlagConfiguration` created in the step prior.
-
-e.g.
-```
-metadata:
-  annotations:
-    openfeature.dev/featureflagconfiguration: "demo"
-```
-
-## Architecture
-
-As per the issue [here](https://github.com/open-feature/ofep/issues/1)
-
-As per v0.1.1, the default sync provider has been optimized as per this OpenFeature Enhancement Proposal [issue](https://github.com/open-feature/ofep/blob/main/004-OFEP-kubernetes-sync-service.md).
-
-High level architecture is as follows:
-
-<img src="images/arch-0.png" width="700">
-
-### Requirements
-
-#### Namespace
-
-The Kubernetes resources created by OpenFeature Operator are under the `open-feature-operator-system` namespace. This means
-any resources that want to communicate with the OFO system (e.g. an application calling flag evaluations) must fall under
-this namespace.
-
-#### Cert Manager
-
-OpenFeature Operator is a server that communicates with Kubernetes components within the cluster, as such it requires a means of
-authorizing requests between peers. [Cert manager](https://cert-manager.io/) handles the authorization by
-adding certificates and certificate issuers as resource types in Kubernetes clusters, and simplifies the process of
-obtaining, renewing and using those certificates.
-
-## Example
-
-When wishing to leverage feature flagging within the local pod, the following steps are required:
-
-1. Create a new feature flag custom resource.
-
-_See [here](config/samples/crds/custom_provider.yaml) for additional custom resource parameters_
-
-```
-apiVersion: core.openfeature.dev/v1alpha2
-kind: FeatureFlagConfiguration
-metadata:
-  name: featureflagconfiguration-sample
-spec:
-  featureFlagSpec:
-    flags:
-      foo:
-        state: "ENABLED"
-        variants:
-          "bar": "BAR"
-          "baz": "BAZ"
-        defaultVariant: "bar",
-        targeting: {}
-```
-
-1. Reference the CR within the pod spec annotations
-The `openfeature.dev/featureflagconfiguration` annotation is a comma separated list of CR references, listed as `{namespace}/{name}`. e.g. `"default/featureflagconfiguration-sample, test/featureflagconfiguration-sample-2"`. If no namespace is defined, it is assumed that the flag configuration is in the same namespace as the deployed pod.
-
-```
-apiVersion: v1
-kind: Pod
-metadata:
-  name: nginx
-  annotations:
-    openfeature.dev/enabled: "true"
-    openfeature.dev/featureflagconfiguration: "default/featureflagconfiguration-sample"
-spec:
-  containers:
-  - name: nginx
-    image: nginx:1.14.2
-    ports:
-    - containerPort: 80
-```
-
-3. Example usage from host container
-
-```
-root@nginx:/# curl -X POST "localhost:8013/schema.v1.Service/ResolveString" -d '{"flagKey":"foo","context":{}}' -H "Content-Type: application/json"
-{"value":"BAR","reason":"DEFAULT","variant":"bar"}
-```
-
-### Running the operator locally
-
-#### Create a local cluster with cert manager and our operator
-
-1.  Create a local cluster with MicroK8s or Kind (forward requests from your localhost:30000 to your cluster, see MicroK8s/Kind doc)
-1.  `IMG=ghcr.io/open-feature/open-feature-operator:main make deploy-operator`
-
-#### Run the example
-
-1. Apply the end-to-end example: `kubectl apply -f config/samples/end-to-end.yaml`
-1. Visit `http://localhost:30000/`
-1. Update the value of the `defaultVariant` field in the custom resource instance in `config/samples/end-to-end.yaml` and re-apply to update the flag value!
-1. Visit `http://localhost:30000/` and see the change!
-
-## Testing
-
-Run `make test` to run the test suite. The controller integration tests use [envtest](https://book.kubebuilder.io/reference/envtest.html), this sets up and starts an instance of etcd and the Kubernetes API server, without kubelet, controller-manager or other components.
-This provides means of asserting that the Kubernetes components reach the desired state without the overhead of using an actual cluster, keeping
-test runtime and resource consumption down.
-
-## Releases
-
-This repo uses _Release Please_ to release packages. Release Please sets up a running PR that tracks all changes for the library components, and maintains the versions according to [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/), generated when [PRs are merged](https://github.com/amannn/action-semantic-pull-request). When Release Please's running PR is merged, any changed artifacts are published.
+Made with [contrib.rocks](https://contrib.rocks).

docs/README.md

@@ -0,0 +1,23 @@
+# Docs
+
+This directory contains all OpenFeature Operator documentation, see table of contents below:
+
+## Usage
+
+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.
+
+- [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)
+
+- [Annotations](./annotations.md)
+- [FeatureFlagConfigurations](./feature_flag_configuration.md)
+
+## Other Resources
+- [Architecture](./architecture.md)
+- [Permissions](./permissions.md)
+- [Development Notes](./development_notes.md)

docs/annotations.md

@@ -5,7 +5,7 @@ The following annotations are used by the operator to control the injection and
 ### `openfeature.dev/enabled`
 When a value of `"true"` is provided, the operator will inject a flagd sidecar into the annotated pods.  
 Example: 
-```
+```yaml
     metadata:
     annotations:
         openfeature.dev/enabled: "true"
@@ -16,7 +16,7 @@ This annotation specifies the names of the FeatureFlagConfigurations used to con
 The annotation value a comma separated list of values following one of 2 patterns: {NAME} or {NAMESPACE}/{NAME}. 
 If no namespace is provided it is assumed that the CR is within the same namespace as the deployed pod.
 Example:
-```
+```yaml
     metadata:
     annotations:
         openfeature.dev/enabled: "true"
@@ -28,7 +28,7 @@ Example:
 
 When a value of `"enabled"` is provided, the operator will inject a flagd sidecar into the annotated pods.  
 Example: 
-```
+```yaml
     metadata:
     annotations:
         openfeature.dev: "enabled"

docs/architecture.md

@@ -0,0 +1,6 @@
+# Architecture
+
+The high level architecture of the operator is as follows:  
+<p align="center">
+    <img src="../images/arch-0.png" width="650">
+</p>

docs/development_notes.md

@@ -0,0 +1,20 @@
+# Development Notes
+
+## Running the operator locally
+
+The project `Makefile` defines a useful method for locally deploying the operator, allowing for the operator image to be defined:
+```sh
+IMG=ghcr.io/open-feature/open-feature-operator:main make deploy-operator
+```
+
+## Testing
+
+Run `make test` to run the test suite. The controller integration tests use [envtest](https://book.kubebuilder.io/reference/envtest.html), this sets up and starts an instance of etcd and the Kubernetes API server, without kubelet, controller-manager or other components.
+This provides means of asserting that the Kubernetes components reach the desired state without the overhead of using an actual cluster, keeping
+test runtime and resource consumption down.
+
+An e2e test suite can also be found in the [`/test/e2e`](../test/e2e/DEVELOPER.md) directory. These tests are run as part of the `pr-lint` github action, they work by deploying an nginx reverse proxy and asserting that curls to the proxy elicit expected behaviour from the flagd sidecar created by open-feature-operator.
+
+## Releases
+
+This repo uses _Release Please_ to release packages. Release Please sets up a running PR that tracks all changes for the library components, and maintains the versions according to [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/), generated when [PRs are merged](https://github.com/amannn/action-semantic-pull-request). When Release Please's running PR is merged, any changed artifacts are published.

docs/feature_flag_configuration.md

@@ -0,0 +1,29 @@
+# Feature Flag Configuration
+
+The `FeatureFlagConfiguration` version `v1alpha2` CRD defines the a CR with the following example structure:
+
+```yaml
+apiVersion: core.openfeature.dev/v1alpha2
+kind: FeatureFlagConfiguration
+metadata:
+    name: featureflagconfiguration-sample
+spec:
+    flagDSpec:
+        envs:
+        - name: FLAGD_PORT
+          value: "8080"
+    featureFlagSpec: 
+        flags: 
+            foo: 
+                state: "ENABLED"
+                variants: 
+                    bar: "BAR"
+                    baz: "BAZ"
+                defaultVariant: "bar"
+```
+
+Within the CRD there are 2 main objects, namely the `flagDSpec` and the `featureFlagSpec`, both offering a different set of configuration for the injected `flagd` sidecars.
+
+The `featureFlagSpec` is an object representing the flag configurations themselves, the documentation for this object can be found [here](https://github.com/open-feature/flagd/blob/main/docs/configuration/flag_configuration.md).
+
+The `flagDSpec` has one property called `envs` which contains a list of environment variables used to override the default start command values in `flagd`, the documentation for this configuration can be found [here](https://github.com/open-feature/flagd/blob/main/docs/configuration/configuration.md). These environment variables are also made available in the workload `Pod` for simplified configuration.

docs/getting_started.md

@@ -0,0 +1,97 @@
+# Getting Started
+
+Once you have [installed the operator](./installation.md) you can follow this guide to deploy an example application demonstrating the operator.
+
+### Deploy a `FeatureFlagConfiguration`
+
+This `FeatureFlagConfiguration` is watched by the injected `flagd` container and used to construct its internal flag definitions state. If multiple configurations are supplied to `flagd` these states will be merged.
+
+```yaml
+apiVersion: core.openfeature.dev/v1alpha2
+kind: FeatureFlagConfiguration
+metadata:
+  name: featureflagconfiguration-sample
+spec:
+  featureFlagSpec:
+    flags:
+      foo:
+        state: "ENABLED"
+        variants:
+          "bar": "BAR"
+          "baz": "BAZ"
+        defaultVariant: "bar",
+        targeting: {}
+```
+
+### Reference the deployed FeatureFlagConfiguration within a Deployment spec annotation.
+
+In this example, a`Deployment` containing a `busybox-curl` container is created. In the example below, the `metadata.annotations` object contains the required annotations for the operator to correctly configure and inject the `flagd` sidecar into each deployed `Pod`. The documentation for these annotations can be found [here](./annotations.md).
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: busybox-curl
+  annotations:
+    openfeature.dev/enabled: "true"
+    openfeature.dev/featureflagconfiguration: "default/featureflagconfiguration-sample"
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: my-busybox-curl-app
+  template:
+      metadata:
+        labels:
+          app: my-busybox-cur-app
+      spec:
+        containers:
+        - name: busybox
+          image: yauritux/busybox-curl:latest
+          ports:
+          - containerPort: 80
+          args:
+            - sleep
+            - "30000"
+```
+
+### Confirm that operator has injected the `flagd` sidecar
+
+Once the `deployment.yaml` has been applied, our `Pod` should be created grouping 2 containers.
+```sh
+kubectl get pods -n default
+```
+Should give a similar output to the following
+```sh
+NAME                                                READY   STATUS              RESTARTS   AGE
+busybox-curl-7bd5767999-spf7v                              0/2     ContainerCreating   0          2s
+```
+When the `Pod` is described, the injected sidecar has the following configuration:
+```sh
+kubectl describe pod busybox-curl-7bd5767999-spf7v
+```
+```yaml
+  flagd:
+    Image:         ghcr.io/open-feature/flagd:v0.2.5
+    Port:          8014/TCP
+    Host Port:     0/TCP
+    Args:
+      start
+      --uri/
+      core.openfeature.dev/default/featureflagconfiguration-sample
+    Environment:
+      FLAGD_METRICS_PORT:  8014
+```
+
+Now that we have confirmed that the `flagd` sidecar has been injected and the configuration is correct, we can test the flag evaluation using `curl`.
+
+> This is not the usual suggested best practice for evaluating flags in applications, typically a language specific `flagd` provider would be used in conjunction with the OpenFeature SDK, documentation can be found [here](https://github.com/open-feature/flagd/blob/main/docs/usage/flagd_providers.md).
+
+```sh
+kubectl exec -it busybox-curl-7bd5767999-spf7v sh
+curl -X POST "localhost:8013/schema.v1.Service/ResolveString" -d '{"flagKey":"foo","context":{}}' -H "Content-Type: application/json"
+```
+output:
+```sh
+{"value":"BAR","reason":"DEFAULT","variant":"bar"}
+```