feat(config): add details around OCI (#143)

* feat(config): add details around OCI * chore(config): move env var details to top of overview * chore: format code * chore: empty commit * chore: remove backend suffix * chore(config): correct copy paste error in oci config * chore: format code --------- Co-authored-by: GeorgeMac <[email protected]> Co-authored-by: Mark Phelps <[email protected]>
flipt-io · Nov 15, 2023 · 0e07425 · 0e07425
1 parent 193923a
commit 0e07425
Show file tree

Hide file tree

Showing 4 changed files with 108 additions and 62 deletions.
diff --git a/configuration/overview.mdx b/configuration/overview.mdx
@@ -40,9 +40,52 @@ The server will check in a few different locations for server configuration (in
 You can edit any of these properties to your liking, and on restart Flipt will
 pick up the new changes.
 
-These properties are as follows:
+## Environment Variables
+
+All options in the configuration file can be overridden using environment
+variables using the syntax:
+
+```yaml
+FLIPT_<SectionName>_<KeyName>
+```
+
+Environment variables **MUST** have `FLIPT_` prefix and be in `UPPER_SNAKE_CASE` format.
+
+<Note>
+  Using environment variables to override defaults is especially helpful when
+  running with Docker as described in the [Installation](/installation)
+  documentation.
+</Note>
+
+Keys should be uppercase and `.` should be replaced by `_`. For example,
+given these configuration settings:
+
+```yaml
+server:
+  grpc_port: 9000
 
-### General
+db:
+  url: file:/var/opt/flipt/flipt.db
+```
+
+You can override them using:
+
+```console
+export FLIPT_SERVER_GRPC_PORT=9001
+export FLIPT_DB_URL="postgres://postgres@localhost:5432/flipt?sslmode=disable"
+```
+
+### Multiple Values
+
+Some configuration options can have a list of values. For example, the `cors.allowed_origins` option can have multiple origins.
+
+In this case, you can use a space separated list of values for the environment variable override:
+
+```console
+export FLIPT_CORS_ALLOWED_ORIGINS="http://localhost:3000 http://localhost:3001"
+```
+
+## Configuration Parameters
 
 | Property                      | Description                                                   | Default             | Since   |
 | ----------------------------- | ------------------------------------------------------------- | ------------------- | ------- |
@@ -199,6 +242,16 @@ These properties are as follows:
 | storage.object.s3.endpoint      | The S3 endpoint to use for object storage   |         | v1.25.0 |
 | storage.object.s3.poll_interval | The interval to poll S3 for changes         | 30s     | v1.25.0 |
 
+#### Storage OCI
+
+| Property                            | Description                                           | Default               | Since   |
+| ----------------------------------- | ----------------------------------------------------- | --------------------- | ------- |
+| storage.oci.repository              | The target bundle repository (with optional registry) |                       | v1.31.0 |
+| storage.oci.authentication.username | The username to use for authentication                |                       | v1.31.0 |
+| storage.oci.authentication.password | The password to use for authentication                |                       | v1.31.0 |
+| storage.oci.bundles_directory       | The directory in which to store local bundles         | $config/flipt/bundles | v1.31.0 |
+| storage.oci.poll_interval           | The interval to poll the registry for changes         | 30s                   | v1.31.0 |
+
 ### Cache
 
 | Property      | Description                                             | Default | Since   |
@@ -291,48 +344,3 @@ be logged in the Flipt logs when a deprecated configuration option is used.
 
 All deprecated options are listed in the [DEPRECATIONS](https://github.com/flipt-io/flipt/blob/main/DEPRECATIONS.md) file
 in the Flipt repository as well as the [CHANGELOG](https://github.com/flipt-io/flipt/blob/main/CHANGELOG.md).
-
-## Environment Variables
-
-All options in the configuration file can be overridden using environment
-variables using the syntax:
-
-```yaml
-FLIPT_<SectionName>_<KeyName>
-```
-
-Environment variables **MUST** have `FLIPT_` prefix and be in `UPPER_SNAKE_CASE` format.
-
-<Note>
-  Using environment variables to override defaults is especially helpful when
-  running with Docker as described in the [Installation](/installation)
-  documentation.
-</Note>
-
-Keys should be uppercase and `.` should be replaced by `_`. For example,
-given these configuration settings:
-
-```yaml
-server:
-  grpc_port: 9000
-
-db:
-  url: file:/var/opt/flipt/flipt.db
-```
-
-You can override them using:
-
-```console
-export FLIPT_SERVER_GRPC_PORT=9001
-export FLIPT_DB_URL="postgres://postgres@localhost:5432/flipt?sslmode=disable"
-```
-
-### Multiple Values
-
-Some configuration options can have a list of values. For example, the `cors.allowed_origins` option can have multiple origins.
-
-In this case, you can use a space separated list of values for the environment variable override:
-
-```console
-export FLIPT_CORS_ALLOWED_ORIGINS="http://localhost:3000 http://localhost:3001"
-```
diff --git a/configuration/storage.mdx b/configuration/storage.mdx
@@ -3,9 +3,9 @@ title: Storage
 description: This document describes how to configure Flipt's storage backend mechanisms.
 ---
 
-## Databases
+## Relational Database
 
-Flipt supports [SQLite](https://www.sqlite.org/index.html), [PostgreSQL](https://www.postgresql.org/), [CockroachDB](https://www.cockroachlabs.com/) and [MySQL](https://dev.mysql.com/) databases.
+Flipt supports [SQLite](https://www.sqlite.org/index.html), [PostgreSQL](https://www.postgresql.org/), [CockroachDB](https://www.cockroachlabs.com/) and [MySQL](https://dev.mysql.com/) relational databases.
 
 <Note>
   As of [v1.29.0](https://github.com/flipt-io/flipt/releases/tag/v1.29.0), Flipt
@@ -114,14 +114,14 @@ docker run -it -v $HOME/flipt:/var/opt/flipt flipt/flipt:latest /bin/sh -c './fl
 If you don't use mounted volumes to persist your data, your data will be lost
 when the migration container exits, having no effect on your Flipt instance!
 
-## Filesystem
+## Declarative
 
-The following backend types are designed to support declarative management of feature flag state.
+The following backend types are designed to support declarative management of feature flag state via a well-known file format.
 In particular, they're designed to support GitOps practices with minimal external dependencies.
 
-Currently, we classify `local`, `git`, and `object` as the three filesystem backends.
+Currently, we classify `local`, `git`, `object` and `oci` as the four declarative backends.
 The `local` backend has been primarily developed to support a local development experience,
-whereas, the `git` and `object` backends are intended for production and serve flag state directly from a configurable repository and Git reference (e.g. branch) or object storage bucket.
+whereas, the `git`, `object` and `oci` backends are intended for production use.
 
 ### Read Only Mode
 
@@ -321,6 +321,43 @@ AWS_ACCESS_KEY_ID=...
 AWS_SECRET_ACCESS_KEY=...
 ```
 
+### OCI
+
+Since `v1.31.0`, Flipt supports using any [OCI](https://opencontainers.org/) compatible registry as a declarative backend source.
+Flipt has its own custom OCI manifest format (we call them `bundles`), which can be built and managed using the [Flipt CLI](/cli/commands/bundle).
+
+<Tabs>
+  <Tab title="Environment Variable">
+
+    ```bash
+    FLIPT_STORAGE_TYPE="oci"
+    FLIPT_STORAGE_OCI_REPOSITORY="some.oci.registry/repository/image:tag"
+    FLIPT_STORAGE_OCI_POLL_INTERVAL="30s"
+    # authentication credentials
+    FLIPT_STORAGE_OCI_AUTHENTICATION_USERNAME="username"
+    FLIPT_STORAGE_OCI_AUTHENTICATION_PASSWORD="password"
+    # location used for storing local bundles
+    FLIPT_STORAGE_OCI_BUNDLES_DIRECTORY="<user_config_dir>/flipt/bundles"
+    ```
+
+  </Tab>
+  <Tab title="Configuration Yaml">
+
+    ```yaml
+    storage:
+      type: "oci"
+      oci:
+        repository: "some.oci.registry/repository/image:tag"
+        poll_interval: "30s"
+        authentication:
+          username: "username"
+          password: "password"
+        bundles_directory: "<user_config_dir>/flipt/bundles"
+    ```
+
+  </Tab>
+</Tabs>
+
 ### Flag State Configuration
 
 Each of Flipt's filesystem backends expects you to represent your feature flag configuration via a set of YAML files.

diff --git a/guides/get-going-with-gitops.mdx b/guides/get-going-with-gitops.mdx
@@ -114,17 +114,18 @@ The entity ID used here is going to be an identifier for the requests authentica
 Our context map is going to contain a single key `organization`, which is populated by a call to `getOrganization(r.Context())`.
 This will also return an identifier, only this time for the requesting user's organization.
 
-## Flipt's Filesystem Backends
+## Flipt's Declarative Backends
 
-The focus of this guide is to leverage Flipt's new "filesystem backends" to enable a GitOps workflow.
+The focus of this guide is to leverage Flipt's new "declarative backends" to enable a GitOps workflow.
 The name comes from the fact that the backend for Flipt is modeled around configuration files in a directory structure.
 These configuration files can coexist in a directory alongside other content (application code or other configuration code).
 
-There currently exist three top-level filesystem backend types:
+There currently exist three top-level declarative backend types:
 
 - `local` (local directory)
 - `git` (remote Git repository and branch)
 - `object` (object storage, currently only AWS S3)
+- `oci` (OCI registry storage)
 
 In this guide we will explore both the `local` and `git` backend types.
 
@@ -209,8 +210,8 @@ Flipt will track the HEAD of this repository's `main` branch.
 Changes will eventually propagate into our running instance of Flipt.
 
 <Info>
-  Head to [Configuration: Storage: Filesystem
-  Backends](/configuration/storage#filesystem) to learn more about configuring
+  Head to [Configuration: Storage: Declarative
+  Backends](/configuration/storage#declarative) to learn more about configuring
   these backend types for Flipt.
 </Info>
 
@@ -466,7 +467,7 @@ func (s *Server) ListWords(w http.ResponseWriter, r *http.Request) {
 
 ## Recap
 
-We've successfully rolled a feature out to production using GitOps practices via Flipt's declarative feature flag configuration files and filesystem backends.
+We've successfully rolled a feature out to production using GitOps practices via Flipt's declarative feature flag configuration files and declarative backends.
 Along the way, we had the opportunity to use Git to understand the current state of the world.
 At each commit, we could've fully recreated the configuration of our entire application, including the state of Flipt itself.
 
@@ -477,9 +478,9 @@ Now you have all the tools necessary to practice GitOps with your feature flags.
 However, in production, your mileage may vary with the different backed types.
 You might want to consider the `object` (and AWS S3 type) backend if your source Git repositories are large (we're working on a guide for that now).
 
-The filesystem storage backends currently mandate that the UI is **read-only**.
+The declarative storage backends currently mandate that the UI is **read-only**.
 We've thoughts on how this could change in the future, but for now, this is a limitation.
 You always have your editor, Git and the SCMs (GitHub, Gitlab etc) for state management in the meantime.
 
 Each of these backends work by polling their sources (git, local directory or object store) and the interval can be configured.
-Checkout the [Configuration: Storage: Filesystem](/configuration/storage#filesystem) for details on adjusting these intervals.
+Checkout the [Configuration: Storage: Declarative](/configuration/storage#declarative) for details on adjusting these intervals.
diff --git a/tooling/github-actions.mdx b/tooling/github-actions.mdx
@@ -7,7 +7,7 @@ description: How to use our GitHub Actions to automate your workflows.
 
 ![Flipt Validate Action](/images/tooling/validate-action.png)
 
-The [flipt-validate action](https://github.com/flipt-io/validate-action) is used to validate your [features.yml](/configuration/storage#flag-state-configuration) files in a GitHub workflow. We recommend to use this action in your workflow to ensure that your Flipt data is syntactically and semantically valid before deploying when using [Git](https://www.flipt.io/docs/configuration/storage#git) or other [file-based backends](https://www.flipt.io/docs/configuration/storage#filesystem).
+The [flipt-validate action](https://github.com/flipt-io/validate-action) is used to validate your [features.yml](/configuration/storage#flag-state-configuration) files in a GitHub workflow. We recommend to use this action in your workflow to ensure that your Flipt data is syntactically and semantically valid before deploying when using [Git](https://www.flipt.io/docs/configuration/storage#git) or other [declarative backends](https://www.flipt.io/docs/configuration/storage#declarative).
 
 It uses the [`flipt validate`](/cli/commands/validate) command under the hood to validate your data. If the data is invalid, the action will fail and provide a detailed error annotation at the source of the error.