diff --git a/authentication/methods.mdx b/authentication/methods.mdx index e625cd4..b508801 100644 --- a/authentication/methods.mdx +++ b/authentication/methods.mdx @@ -58,6 +58,26 @@ The bootstrap token can also be configured to have an expiration date by setting See the [Configuration: Method Token](/configuration/overview#authentication-methods-token) documentation for more details. +### Token Expiration + +Tokens can be created with an optional expiration date. This can be used to ensure that a token is only valid for a short period of time before automatically expiring. Expired tokens will be automatically be deleted by Flipt. The interval and grace period for this cleanup process can be configured via the `token.cleanup.interval` and `token.cleanup.grace_period` values in the configuration. + +### Namespaced Tokens + +Tokens can be created with an optional namespace to allow for more granular control over access to resources. Namespaces allow for grouping resources such as flags, segments, etc. To learn more about namespaces, see the [Concepts: Namespaces](/concepts#namespaces) documentation. + +Namespaced tokens are useful for the scenario when you want to limit the privileges of an integration such as a CI/CD pipeline or internal service. + + + It's important to note that namespaced tokens offer limited access to the + Flipt API, as only API requests that can be scoped to a namespace are + supported. + + +For example, the `/api/v1/namespaces/{namespace}/flags` endpoint supports a `namespace` parameter, therefore a namespaced token can be used to access this endpoint. However, the `/auth/v1/tokens` endpoint is not associated with a single `namespace`, so a namespaced token cannot be used to access this endpoint. + +This also means that namespaced tokens themselves cannot be used to create additional tokens. Tokens must be created using a non-namespaced (default) token. + ## OpenID Connect [OpenID Connect](https://openid.net/connect/) (OIDC) is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner. diff --git a/authentication/using-tokens.mdx b/authentication/using-tokens.mdx index 5172120..e5cdb7c 100644 --- a/authentication/using-tokens.mdx +++ b/authentication/using-tokens.mdx @@ -57,9 +57,9 @@ def doRequest(): ### 2. `Cookie` Header - Please enable [CSRF](/configuration/authentication#session) prevention in your - Flipt configuration when using a "session compatible" authentication method - and `Cookie` based authentication in the browser. + It's important to enable [CSRF](/configuration/authentication#session) + prevention in your Flipt configuration when using a "session compatible" + authentication method and `Cookie` based authentication in the browser. For browser-based applications (e.g. Flipt's own user interface) we support supplying a client token via a particular `Cookie` called `flipt_client_token`. diff --git a/configuration/overview.mdx b/configuration/overview.mdx index 76e838d..0c503be 100644 --- 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__ +``` + +Environment variables **MUST** have `FLIPT_` prefix and be in `UPPER_SNAKE_CASE` format. + + + Using environment variables to override defaults is especially helpful when + running with Docker as described in the [Installation](/installation) + documentation. + + +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__ -``` - -Environment variables **MUST** have `FLIPT_` prefix and be in `UPPER_SNAKE_CASE` format. - - - Using environment variables to override defaults is especially helpful when - running with Docker as described in the [Installation](/installation) - documentation. - - -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 index 3358a3d..678506f 100644 --- 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. 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). + + + + + ```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="/flipt/bundles" + ``` + + + + + ```yaml + storage: + type: "oci" + oci: + repository: "some.oci.registry/repository/image:tag" + poll_interval: "30s" + authentication: + username: "username" + password: "password" + bundles_directory: "/flipt/bundles" + ``` + + + + ### 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 index dde4cda..45f4629 100644 --- 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. - 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. @@ -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/images/authentication/create-token.png b/images/authentication/create-token.png index 0195898..3eeef68 100644 Binary files a/images/authentication/create-token.png and b/images/authentication/create-token.png differ diff --git a/images/concepts/constraints.png b/images/concepts/constraints.png index fb39eab..27ae431 100644 Binary files a/images/concepts/constraints.png and b/images/concepts/constraints.png differ diff --git a/images/concepts/constraints_types.png b/images/concepts/constraints_types.png index 4c79309..7fc160e 100644 Binary files a/images/concepts/constraints_types.png and b/images/concepts/constraints_types.png differ diff --git a/images/concepts/distributions.png b/images/concepts/distributions.png index c52195f..9b0244c 100644 Binary files a/images/concepts/distributions.png and b/images/concepts/distributions.png differ diff --git a/images/concepts/evaluation.png b/images/concepts/evaluation.png index 001f7df..96a6afa 100644 Binary files a/images/concepts/evaluation.png and b/images/concepts/evaluation.png differ diff --git a/images/concepts/flags.png b/images/concepts/flags.png index e158457..4832639 100644 Binary files a/images/concepts/flags.png and b/images/concepts/flags.png differ diff --git a/images/concepts/flags_boolean.png b/images/concepts/flags_boolean.png index b91c085..b79a048 100644 Binary files a/images/concepts/flags_boolean.png and b/images/concepts/flags_boolean.png differ diff --git a/images/concepts/flags_variants.png b/images/concepts/flags_variants.png index 5f26305..da66d49 100644 Binary files a/images/concepts/flags_variants.png and b/images/concepts/flags_variants.png differ diff --git a/images/concepts/namespaces_default.png b/images/concepts/namespaces_default.png index eac5fd2..fd6b17f 100644 Binary files a/images/concepts/namespaces_default.png and b/images/concepts/namespaces_default.png differ diff --git a/images/concepts/namespaces_production.png b/images/concepts/namespaces_production.png index 2903328..0176880 100644 Binary files a/images/concepts/namespaces_production.png and b/images/concepts/namespaces_production.png differ diff --git a/images/concepts/rollouts.png b/images/concepts/rollouts.png index 52a5ef1..a67f5f6 100644 Binary files a/images/concepts/rollouts.png and b/images/concepts/rollouts.png differ diff --git a/images/concepts/rules.png b/images/concepts/rules.png index 8d9fa01..4c53f93 100644 Binary files a/images/concepts/rules.png and b/images/concepts/rules.png differ diff --git a/images/concepts/segments.png b/images/concepts/segments.png index 6b15b5a..0a1774b 100644 Binary files a/images/concepts/segments.png and b/images/concepts/segments.png differ diff --git a/images/concepts/settings_namespaces.png b/images/concepts/settings_namespaces.png index 491c121..a69abf3 100644 Binary files a/images/concepts/settings_namespaces.png and b/images/concepts/settings_namespaces.png differ diff --git a/images/configuration/readonly.png b/images/configuration/readonly.png index 378f176..8157c69 100644 Binary files a/images/configuration/readonly.png and b/images/configuration/readonly.png differ diff --git a/images/getting_started/create_constraint.png b/images/getting_started/create_constraint.png index 289a35d..54713d5 100644 Binary files a/images/getting_started/create_constraint.png and b/images/getting_started/create_constraint.png differ diff --git a/images/getting_started/create_flag.png b/images/getting_started/create_flag.png index 2e141da..b0ddfca 100644 Binary files a/images/getting_started/create_flag.png and b/images/getting_started/create_flag.png differ diff --git a/images/getting_started/create_rule.png b/images/getting_started/create_rule.png index 2aa5dab..9299b42 100644 Binary files a/images/getting_started/create_rule.png and b/images/getting_started/create_rule.png differ diff --git a/images/getting_started/create_segment.png b/images/getting_started/create_segment.png index e4c4a34..1c6cc75 100644 Binary files a/images/getting_started/create_segment.png and b/images/getting_started/create_segment.png differ diff --git a/images/getting_started/create_variant.png b/images/getting_started/create_variant.png index e3738ac..7029506 100644 Binary files a/images/getting_started/create_variant.png and b/images/getting_started/create_variant.png differ diff --git a/images/getting_started/evaluation_console.png b/images/getting_started/evaluation_console.png index 8e9caaa..dd9d478 100644 Binary files a/images/getting_started/evaluation_console.png and b/images/getting_started/evaluation_console.png differ diff --git a/reference/overview.mdx b/reference/overview.mdx index 5ed6562..8274d4a 100644 --- a/reference/overview.mdx +++ b/reference/overview.mdx @@ -10,6 +10,10 @@ The Flipt REST API can also be used with any language that can make HTTP request The latest version of the REST API is fully documented using the [OpenAPI v3 specification](https://github.com/flipt-io/flipt-openapi). +## SDKs + +We're adding new SDKs all the time. To see the current list of official REST SDKs, head to the [REST SDKs](/integration/rest) documentation. + ## Backward Compatibility We take great care to ensure that the Flipt REST API is backward compatible. This means that you can safely upgrade to a newer version of Flipt without having to change your API calls. @@ -34,24 +38,6 @@ All previous endpoints without the `/namespaces` prefix still work as before (i. See the [Concepts: Namespaces](/concepts#namespaces) section for more information. -## SDKs - -Official REST client SDKs exist for the following languages: - -- [Go](https://pkg.go.dev/go.flipt.io/flipt/sdk/go) -- [Node.js/TypeScript](https://github.com/flipt-io/flipt-node) -- [Java](https://github.com/flipt-io/flipt-java) -- [Rust](https://github.com/flipt-io/flipt-rust) -- [Python](https://github.com/flipt-io/flipt-python) - - -We're working on more REST API SDKs and would love to hear from you if you're -interested in helping out or have a request for an SDK in a specific language. - -Please reach out to us in our [Discord server](https://www.flipt.io/discord). - - - ## Authentication diff --git a/tooling/github-actions.mdx b/tooling/github-actions.mdx index 5c5d3bb..3a38268 100644 --- 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.