From 3aa7595e1540d1e7e4ddf1b3efe50baa9f6b754e Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Mon, 2 Oct 2023 12:00:50 -0400 Subject: [PATCH 1/2] chore: update otlp config section (#128) --- configuration/observability.mdx | 18 +++++++++++++++++- configuration/overview.mdx | 7 ++++--- 2 files changed, 21 insertions(+), 4 deletions(-) diff --git a/configuration/observability.mdx b/configuration/observability.mdx index 8dd0db5..56ee053 100644 --- a/configuration/observability.mdx +++ b/configuration/observability.mdx @@ -30,7 +30,7 @@ showing how to set up Flipt with Prometheus can be found in the GitHub repositor ![Grafana Dashboard](/images/configuration/grafana_flag_dashboard.png) -We provide created a set of [Grafana](https://grafana.com/) dashboards that you can use to visualize the metrics collected by Flipt, including both server health and flag evaluation metrics. +We provide a set of [Grafana](https://grafana.com/) dashboards that you can use to visualize the metrics collected by Flipt, including both server health and flag evaluation metrics. You can find the dashboards in our [grafana-dashboards](https://github.com/flipt-io/grafana-dashboards) repository. @@ -48,6 +48,22 @@ Enable tracing via the values described in the [Tracing configuration](/configur [Examples](https://github.com/flipt-io/flipt/tree/main/examples/tracing) showing how to set up Flipt with each of the supported tracing backends can be found in the main GitHub repository . +### OTLP + +OTLP supports additional configuration such as specifying the protocol to use (gRPC or HTTP) as well as providing custom headers to send with the request. + +Custom headers can be used to provide authentication information to the collector which may be required if you are using a hosted collector such as [NewRelic](https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/get-started/opentelemetry-set-up-your-app/), [DataDog](https://docs.datadoghq.com/opentelemetry/otlp_ingest_in_the_agent/?tab=host), or [Honeycomb](https://docs.honeycomb.io/getting-data-in/opentelemetry-overview/#instrumenting-with-opentelemetry). + +These can be configured via the `tracing.otlp` configuration section. + +```yaml +tracing: + otlp: + endpoint: "https://{your-collector-url}" + headers: + "X-Some-Header": "some-value" +``` + ## Audit Events Flipt supports sending audit events to configured sinks. Audit events have the following structure: diff --git a/configuration/overview.mdx b/configuration/overview.mdx index 1dd7cea..3cb81ac 100644 --- a/configuration/overview.mdx +++ b/configuration/overview.mdx @@ -271,9 +271,10 @@ These properties are as follows: #### Tracing: OTLP -| Property | Description | Default | Since | -| --------------------- | ------------------------------ | -------------- | ------- | -| tracing.otlp.endpoint | The OTLP GRPC receiver address | localhost:4317 | v1.18.2 | +| Property | Description | Default | Since | +| --------------------- | ----------------------------------------------------------------- | --------------------- | ------- | +| tracing.otlp.endpoint | The OTLP receiver address (supports: grpc, http, https) | grpc://localhost:4317 | v1.18.2 | +| tracing.otlp.headers | Additional headers to send with OTLP requests (map[string]string) | | v1.28.0 | ## Deprecations From 9813bc78f4576bb573bc5f0aa2e65c03010f52c6 Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Mon, 2 Oct 2023 12:02:08 -0400 Subject: [PATCH 2/2] feat: add CLI docs (#126) * feat: add CLI docs * chore: update cli overview * chore: more info --- .vale/styles/Flipt/spelling-exceptions.txt | 13 ++++--- cli/commands/config/edit.mdx | 24 ++++++++++++ cli/commands/config/init.mdx | 25 ++++++++++++ cli/commands/export.mdx | 24 ++++++++++++ cli/commands/import.mdx | 23 +++++++++++ cli/commands/migrate.mdx | 19 ++++++++++ cli/commands/validate.mdx | 20 ++++++++++ cli/overview.mdx | 44 ++++++++++++++++++++++ configuration/overview.mdx | 18 ++++----- mint.json | 22 +++++++++++ 10 files changed, 216 insertions(+), 16 deletions(-) create mode 100644 cli/commands/config/edit.mdx create mode 100644 cli/commands/config/init.mdx create mode 100644 cli/commands/export.mdx create mode 100644 cli/commands/import.mdx create mode 100644 cli/commands/migrate.mdx create mode 100644 cli/commands/validate.mdx create mode 100644 cli/overview.mdx diff --git a/.vale/styles/Flipt/spelling-exceptions.txt b/.vale/styles/Flipt/spelling-exceptions.txt index e976ee4..72c709d 100644 --- a/.vale/styles/Flipt/spelling-exceptions.txt +++ b/.vale/styles/Flipt/spelling-exceptions.txt @@ -5,6 +5,7 @@ boolean caddy codeowners codespaces +darwin datetime declaratively deletable @@ -14,7 +15,9 @@ dev dex flipt flipt's +Gitlab grafana +hostname http httplug https @@ -28,6 +31,7 @@ mintlify namespace namespaces nginx +ngrok oauth oidc okta @@ -37,11 +41,13 @@ PGBouncer postgres protobuf protoc +Quicksort redis regexes rflipt rollout rollouts +SCMs sdk sdks sqlite @@ -49,9 +55,4 @@ unary uncomment URIs yaml -zipkin -Quicksort -SCMs -Gitlab -ngrok -hostname \ No newline at end of file +zipkin \ No newline at end of file diff --git a/cli/commands/config/edit.mdx b/cli/commands/config/edit.mdx new file mode 100644 index 0000000..b4c5cb2 --- /dev/null +++ b/cli/commands/config/edit.mdx @@ -0,0 +1,24 @@ +--- +title: "config edit" +description: "Edit Flipt configuration" +--- + +``` +flipt config edit [flags] +``` + +### Options + +``` + -h, --help help for edit +``` + +### Inherited Options + +``` + --config string path to config file +``` + +### More Info + +See the [configuration](/configuration) section of the documentation for more information. diff --git a/cli/commands/config/init.mdx b/cli/commands/config/init.mdx new file mode 100644 index 0000000..837f272 --- /dev/null +++ b/cli/commands/config/init.mdx @@ -0,0 +1,25 @@ +--- +title: "config init" +description: "Initialize Flipt configuration" +--- + +``` +flipt config init [flags] +``` + +### Options + +``` + -y, --force Overwrite existing configuration file + -h, --help help for init +``` + +### Inherited Options + +``` + --config string path to config file +``` + +### More Info + +See the [configuration](/configuration) section of the documentation for more information. diff --git a/cli/commands/export.mdx b/cli/commands/export.mdx new file mode 100644 index 0000000..4b3579f --- /dev/null +++ b/cli/commands/export.mdx @@ -0,0 +1,24 @@ +--- +title: "export" +description: "Export Flipt data to file/stdout" +--- + +``` +flipt export [flags] +``` + +### Options + +``` + -a, --address string address of remote Flipt instance to export from (defaults to direct DB export if not supplied) + --all-namespaces export all namespaces. (mutually exclusive with --namespaces) + --config string path to config file + -h, --help help for export + --namespaces string comma-delimited list of namespaces to export from. (mutually exclusive with --all-namespaces) (default "default") + -o, --output string export to filename (default STDOUT) + -t, --token string client token used to authenticate access to remote Flipt instance when exporting. +``` + +### More Info + +See the [import/export](/operations/import-export) section of the documentation for more information. diff --git a/cli/commands/import.mdx b/cli/commands/import.mdx new file mode 100644 index 0000000..6c4fa09 --- /dev/null +++ b/cli/commands/import.mdx @@ -0,0 +1,23 @@ +--- +title: "import" +description: "Import Flipt data from file/stdin" +--- + +``` +flipt import [flags] +``` + +### Options + +``` + -a, --address string address of remote Flipt instance to import into (defaults to direct DB import if not supplied) + --config string path to config file + --drop drop database before import + -h, --help help for import + --stdin import from STDIN + -t, --token string client token used to authenticate access to remote Flipt instance when importing. +``` + +### More Info + +See the [import/export](/operations/import-export) section of the documentation for more information. diff --git a/cli/commands/migrate.mdx b/cli/commands/migrate.mdx new file mode 100644 index 0000000..355a639 --- /dev/null +++ b/cli/commands/migrate.mdx @@ -0,0 +1,19 @@ +--- +title: "migrate" +description: "Run pending database migrations" +--- + +``` +flipt migrate [flags] +``` + +### Options + +``` + --config string path to config file + -h, --help help for migrate +``` + +### More Info + +See the [migrations](/configuration/storage#migrations) section of the documentation for more information. diff --git a/cli/commands/validate.mdx b/cli/commands/validate.mdx new file mode 100644 index 0000000..7f7d86c --- /dev/null +++ b/cli/commands/validate.mdx @@ -0,0 +1,20 @@ +--- +title: "validate" +description: "Validate Flipt flag state (.yaml, .yml) files" +--- + +``` +flipt validate [flags] +``` + +### Options + +``` + -F, --format string output format: json, text (default "text") + -h, --help help for validate + --issue-exit-code int Exit code to use when issues are found (default 1) +``` + +### More Info + +See the [flag state](/configuration/storage#flag-state-configuration) section of the documentation for more information. diff --git a/cli/overview.mdx b/cli/overview.mdx new file mode 100644 index 0000000..0103678 --- /dev/null +++ b/cli/overview.mdx @@ -0,0 +1,44 @@ +--- +title: "Overview" +description: "Overview of the flipt CLI" +--- + +The `flipt` CLI is a command line interface for managing Flipt. It's useful for configuring your Flipt instance, running migrations, validating `.features.yml` files, and more. + +You can use it in various environments, including your local machine, CI/CD, and more. + +### Installation + + +```console Homebrew +brew install flipt-io/brew/flipt +``` + +```console Binary +curl -fsSL https://github.com/flipt-io/flipt/raw/main/install.sh | bash +``` + + + +### Usage + +``` +flipt [flags] +``` + +`flipt` with no arguments will run the Flipt server. It will look for a configuration file as described in the [configuration](/configuration/overview#configuration-file) documentation. You can specify a different configuration file with the `--config` flag. + +### Examples + +``` +$ flipt +$ flipt config init +$ flipt --config /path/to/config.yml migrate +``` + +### Options + +``` + --config string path to config file + -h, --help help for flipt +``` diff --git a/configuration/overview.mdx b/configuration/overview.mdx index 3cb81ac..6463d05 100644 --- a/configuration/overview.mdx +++ b/configuration/overview.mdx @@ -3,7 +3,7 @@ title: Overview description: This document describes how to configure the Flipt server. --- -`Flipt` server can be configured in two ways. +Flipt server can be configured in two ways. Configuration precedence is as follows: @@ -18,30 +18,28 @@ The default way that Flipt is configured is with the use of a configuration file This file is read when Flipt starts up and configures several important properties for the server. + + You can generate a default configuration file by running `flipt config init` + as of v1.28.0. See the [CLI](/cli) documentation for more information. + + The server will check in a few different locations for server configuration (in order): 1. `--config` flag as an override 2. `{{ USER_CONFIG_DIR }}/flipt/config.yml` (the `USER_CONFIG_DIR` value is based on your architecture and specified in the [Go documentation](https://pkg.go.dev/os#UserConfigDir)) 3. `/etc/flipt/config/default.yml` - + We provide both a [JSON schema](https://raw.githubusercontent.com/flipt-io/flipt/main/config/flipt.schema.json) and a [Cue schema](https://raw.githubusercontent.com/flipt-io/flipt/main/config/flipt.schema.cue) that you can use to validate your configuration file and it's properties. - + You can edit any of these properties to your liking, and on restart Flipt will pick up the new changes. - - These defaults are commented out in - [default.yml](https://github.com/flipt-io/flipt/blob/main/config/default.yml) - to give you an idea of what they are. To change them you'll first need to - uncomment them. - - These properties are as follows: ### General diff --git a/mint.json b/mint.json index d2da9fd..78e44fb 100644 --- a/mint.json +++ b/mint.json @@ -103,6 +103,28 @@ "configuration/telemetry" ] }, + { + "group": "CLI", + "pages": [ + "cli/overview", + { + "group": "Commands", + "pages":[ + { + "group": "config", + "pages":[ + "cli/commands/config/init", + "cli/commands/config/edit" + ] + }, + "cli/commands/export", + "cli/commands/import", + "cli/commands/migrate", + "cli/commands/validate" + ] + } + ] + }, { "group": "Authentication", "pages": [