<BlogImage
 src="/gitops/flipt-gitops.png"
 alt="Flipt for GitOps"
 width={2400}
 height={1350}
>
 
 Image generated by <a href="https://www.midjourney.com/">MidJourney</a>
 
</BlogImage>

Today we’re excited to announce that we’re exploring a new type of backend for Flipt!

The team has been discussing and exploring ways Flipt could be better positioned to support GitOps-style workflows. For those unfamiliar with GitOps practices, we recommend the WeaveWorks [Guide To GitOps](https://www.weave.works/technologies/gitops/).

Our new [filesystem backends proposal](https://github.com/flipt-io/flipt/discussions/1652) adds two ways to configure Flipt to serve flag state content encoded as yaml stored in files, `local` and `git`.

We’re keen to understand if this idea resonates with you and your use case, this will help us shape the implementation, which is currently underway.

## Problem

We feel that many feature flags offerings (including Flipt today) work at odds with GitOps practices. GitOps prescribes that you store all your configuration in one or more Git repositories. This gives your entire system the benefits of version control. Feature flag configuration is just like any other configuration in that it adjusts the behaviour of your applications at runtime. However, we find that it is rarely stored and tracked within Git itself.

If you’re using GitOps practices for your wider configuration needs, but your feature flag solution is completely isolated, then you’re subverting the benefits and traceability of Git. When the alerts start firing you'll have to correlate your configuration changes in Git with the auditing features of your flagging solution.

Alternatively, some existing feature flag solutions support GitOps by bolting a declarative syntax onto their existing imperative API. For example, some offerings provide a [Terraform](https://www.terraform.io/) provider which is an entirely legitimate way to create a GitOps-style contribution experience. In fact, we’re still considering having one for Flipt and our existing relational backends. However, this approach does have drawbacks, primarily, there are now two sources of truth.

Reconciling from your Git repository into your online feature flag service also has to be performed. This process is often performed during some kind of continuous delivery step (e.g., via a GitHub action), which likely pushes changes into your feature flag system. You may have to manually intervene when this process fails for intermittent reasons. Your environment must also have credentials and access to your application repository and your feature flag solution. Ideally, your feature flag solution provides tooling to ease the extra work required to set up this CI/CD process and make it resilient.

In this scenario, given you’re using a self-hosted solution (such as Flipt), you now have the following set of applications to run and configurations to manage:

- The feature flag service itself (e.g. the `flipt` binary)
- Backing database for storing flag state (e.g. SQLite, PostgreSQL etc)
- Flag state configuration (e.g. in Terraform HCL or via some other process such as `flipt import`)
- CI processes for reconciliation (plus monitoring)
- For solutions such as Terraform, storage of reconciliation state (`tfstate` files)

This is all achievable, but care must be taken when building the reconciliation process to ensure a predictable end state.

Ultimately, feature flag offerings have to build a host of features you’re already getting from your SCM (e.g. GitHub or Gitlab). Version control, peer review, access control and backup to name a few.

## How We Intend to Serve GitOps

We intend to have Flipt pull feature flag state directly from Git at runtime.

We want Flipt to be able to drop its dependency on a database for flag state and go directly to the source. This removes the need for a reconciliation process altogether. By adopting a pull model, we embrace eventual consistency and allow Flipt to recover automatically during transitive errors without intervention.

You'll simply be able to configure Flipt with access to your repository and with some additional configuration, you will be able to control how and where to locate your flag state files. Your repository could be used solely for Flipt, it could be your existing configuration repository, or it could be stored within a monorepo.

<BlogImage
 src="/gitops/gitops-scm.png"
 alt="Flipt for GitOps - SCM"
 width={800}
 height={600}
/>

Flipt’s evaluation and read APIs won't change, meaning your existing interactions with the Flipt SDKs can remain the same. The existing [`flipt export`](https://www.flipt.io/docs/configuration/storage#export) command produces configuration files valid for committing straight to your repositories for ease of transition.

Flipt will be configured to serve a particular branch for a target repository. This branch doesn’t always have to be `main`, meaning you can deploy Flipt in multiple ways to support validating flag state changes in arbitrary Git branches or tags.

You'll also be able to run Flipt over a local directory. In this configuration, Flipt will simply serve your flag configuration without the need to go through Git. Updates to the local directory will update Flipt automatically. There is no need to access an external running instance of Flipt to replicate or alter your production feature flag state in your _local_ environment. Simply check out your repository and run `flipt` to begin experimenting.

<BlogImage
 src="/gitops/gitops-local.png"
 alt="Flipt for GitOps - Local"
 width={800}
 height={600}
/>

## Flipt in CI

Alongside building a new core backend for Flipt, we’re also developing a suite of tools for validating your use of Flipt during your existing continuous integration workflows.

Before Flipt can serve your configuration files, it is important to validate they are fit for consumption. Failure to do so could lead to runtime errors or unexpected behaviour. `flipt validate` is a new subcommand currently being added to Flipt. This will be useful for local validation or running directly in a CI pipeline.

We’re also developing a GitHub action which simplifies running `flipt validate` which will make it trivial to add alongside your existing GitHub workflows.

## Just the Beginning

We’re just getting started turning our proof-of-concept into something ready for production Flipt usage. While we have a good feeling that the experience will resonate with users, there are still a number of interesting technical challenges we expect to have along the way. This is why we wanted to get this plan out early in order to hear your feedback.

Help come shape the future of this solution on [GitHub](https://github.com/flipt-io/flipt/discussions/1652), or in our [Discord](https://www.flipt.io/discord).

Also, check out our new landing page for more of what's possible when combining Flipt + Git: [flipt.io/gitops](https://www.flipt.io/gitops).

How's about Git?

<BlogImage
 src="/audit-events/audit-events.png"
 alt="Events for Flipt"
 width={2400}
 height={1350}
>
 
 Image generated by <a href="https://www.midjourney.com/">MidJourney</a>
 
</BlogImage>

Events and logging are vital for many organizations to either keep track of history within the application/platform or to actually take action on things once they happen. Two brief examples include:

1. An organization keeping track of payment events that have happened on their platform
2. A platform triggering a job to purge data somewhere if an event is of a particular nature

In Flipt's case it may prove essential for some organizations to know when feature flags are mutated in some fashion as they can affect the real-time behavior of the consumer’s application.

It's also important to know who made the change and when it was made, especially when it comes to trying to determine the root cause of an issue in the consuming application. This is where audit events come in.

We're happy to announce that support for these type of audit events are now implemented as of [v1.21](https://github.com/flipt-io/flipt/releases/tag/v1.21.0) of Flipt! 🎉

## Ideal Implementation

Before diving into how the feature was implemented, it is worth discussing what an ideal scenario looks like for Flipt and audit events. Many providers, whether SaaS or open source, leave it strictly up to the consumer to deal with events as they please. In most cases, this is done through a webhook URL that you provide to the platform which sends a request to that URL when an event occurs.

An application that is listening to the endpoint of the webhook URL can then do whatever they want with the event. For instance, they can choose to send the message to a Kafka broker, do some other sort of pub/sub, or send that audit event to Slack in a specialized channel, so this is more of the laissez-faire approach.

What we decided on for an ideal implementation is to have this concept of first-class support for ‘native sinks’. In this case, Flipt will house the logic necessary to interact directly with the sinks that the user provides configuration for. The idea is that messages can go straight to a Kafka broker, pub/sub system, Slack channel, etc, as a direct form of communication. This allows users to avoid having to write their own backend to communicate with these systems and avoid the extra network hop.

The implementations for communicating with these native sinks would ideally have an abstraction point so that users can make easy sense of it to contribute to Flipt and write their own implementations for native sinks. One of the downsides of this native approach, however, is that as more and more sinks become implemented, it can lead to version churn for the Flipt application. To combat this potential for churn and to make contributions more accessible, we are currently looking into a way to make the sink implementations pluggable in their own repositories, potentially using a plugin system like Hashicorp's [go-plugin](https://github.com/hashicorp/go-plugin).

## Implementation

Implementing any event-driven system comes with many considerations and trade-offs. On the producer side of the system, an ‘event’ usually represents things in the system that have already happened to then notify the consumer. The benefit for the consumer(s) is that once the event is received on its end it knows the event is complete, and therefore does not have to poll and waste resources getting the complete event from the source.

While the definition of an event-driven system seems simple enough, there are many considerations to keep in mind. In this case particularly, what happens to the producer or consumer during high-traffic scenarios? Or what if the consumer becomes unavailable for a portion of the time? These represent just a few of many considerations, and we sought to address those in our implementation.

<BlogImage
 src="/audit-events/event-diagram.png"
 alt="OTEL Event Diagram"
 width={300}
 height={261}
 caption="The two basic components of an event system. One has to consider where to implement the functionality to deal with the considerations described above."
/>

Our first stab at an implementation was a basic homegrown publisher which contains abilities to batch events and send batches asynchronously to different sinks that are configured. This is done so the consumer is not burdened with a whole bunch of writes, and it frees up the publisher to do other work without worry of communication failures with the consumer (addressing some of those considerations mentioned above).

In addition to a batch size, there should also be configuration for a flush period to avoid messages laying around in memory for an indefinite amount of time. Considering all of this, it was a pretty straightforward implementation, but halfway through we realized that this problem has been solved several times for a lot of different use cases, leading us to pause the publisher implementation and seek out a more tried and true solution.

### Enter OpenTelemetry

<BlogImage
 src="/audit-events/otel.png"
 alt="OpenTelemetry"
 width={1000}
 height={524}
/>

For the sake of brevity, [OpenTelemetry](https://opentelemetry.io/) will not be discussed in this article, but simply how it was used in the Flipt application to achieve desired functionality for audit events. For trace data, OpenTelemetry (OTEL) not only provides configurable batching, and flushing abilities but also allows users to provide implementations of [`Exporters`](https://opentelemetry.io/docs/concepts/glossary/#exporter) which OTEL uses to send trace data to whatever the implementation specifies. In simpler words... OTEL does everything already implemented in the homegrown publisher implementation, and it already exists as a dependency in the Flipt source code for exporting trace data to [Jaeger](https://www.jaegertracing.io/), [Zipkin](https://zipkin.io/), or [OTLP](https://opentelemetry.io/docs/reference/specification/protocol/).

There might be some lack of context as to what a `Trace` or `Span` here is and how it ties into audit events for Flipt. Essentially, a `Trace` represents a unique transaction of a collection of operations throughout an application. A `Span` represents a single unit within that `Trace` or a single operation. Spans allow for additions of [Events](https://opentelemetry.io/docs/concepts/signals/traces/#span-events) which are viewable through any tracing provider client. The addition of `Event`s is the bit that we leveraged for audit events.

Specifically in the code, we’ve implemented a middleware that will intercept the request, and determine if the event is auditable, if it is, the code will add the details of that audit event to the Span via the `Event` described above. When a batch size or flush period is reached for the `SpanProcessor`, events are pulled off of the `Span`(s) and converted into a data structure housed in our code to then send it off to the native sinks that the user has configured on their Flipt instance. In addition to viewing the audit events in their sink implementation, an added benefit of using OTEL is the span events will show up in the tracing provider client for users to view.

<BlogImage
 src="/audit-events/jaeger-ui.png"
 alt="Jaeger UI with Event"
 width={3024}
 height={1542}
 caption="The audit event added to the flipt.Flipt/CreateConstraint span. The flipt* properties represent the audit event."
 className="shadow-md"
/>

## What's Released

With this initial release, there is only functionality for audit event logging to a file on disk. Users can specify the name of that log file, and Flipt will write the audit events to it in a JSON-encoded format.

If you were to `tail` the logs of your audit event log file for orthodox Flipt usage you might see something like the following:

```json
{"version":"0.1","type":"flag","action":"created","metadata":{"actor":{"authentication":"none","ip":"127.0.0.1"}},"payload":{"description":"your favorite NBA team","enabled":true,"key":"scenter","name":"scenter","namespace_key":"default"},"timestamp":"2023-05-01T14:01:12-05:00"}
{"version":"0.1","type":"variant","action":"created","metadata":{"actor":{"authentication":"none","ip":"127.0.0.1"}},"payload":{"attachment":"","description":"","flag_key":"scenter","id":"41e84846-bfbd-426f-afa9-3358d0d40875","key":"lakers","name":"","namespace_key":"default"},"timestamp":"2023-05-01T14:01:12-05:00"}
{"version":"0.1","type":"segment","action":"created","metadata":{"actor":{"authentication":"none","ip":"127.0.0.1"}},"payload":{"constraints":[],"description":"Segments for evaluation NBA teams","key":"postclavicula","match_type":"ANY_MATCH_TYPE","name":"postclavicula","namespace_key":"default"},"timestamp":"2023-05-01T14:01:12-05:00"}
{"version":"0.1","type":"constraint","action":"created","metadata":{"actor":{"authentication":"none","ip":"127.0.0.1"}},"payload":{"id":"a7ccde21-870e-4e36-953c-4d5849d96a77","namespace_key":"default","operator":"eq","property":"championship","segment_key":"postclavicula","type":"STRING_COMPARISON_TYPE","value":"most"},"timestamp":"2023-05-01T14:01:12-05:00"}
{"version":"0.1","type":"flag","action":"updated","metadata":{"actor":{"authentication":"none","ip":"127.0.0.1"}},"payload":{"description":"your favorite NBA team","enabled":false,"key":"eyepoint","name":"eyepoint","namespace_key":"default"},"timestamp":"2023-05-01T14:01:37-05:00"}
{"version":"0.1","type":"token","action":"created","metadata":{"actor":{"authentication":"none","ip":"127.0.0.1"}},"payload":{"io.flipt.auth.token.description":"hello","io.flipt.auth.token.name":"worldh"},"timestamp":"2023-05-01T14:02:45-05:00"}
```

Currently, the auditable events are all CRUD operations (sans Read) upon the following entities:

- [Flag](https://www.flipt.io/docs/concepts#flags)
- [Variant](https://www.flipt.io/docs/concepts#variants)
- [Distribution](https://www.flipt.io/docs/concepts#distributions)
- [Segment](https://www.flipt.io/docs/concepts#segments)
- [Constraint](https://www.flipt.io/docs/concepts#constraints)
- [Rule](https://www.flipt.io/docs/concepts#rules)
- [Token](https://www.flipt.io/docs/authentication/methods#static-token)
- [Namespace](https://www.flipt.io/docs/concepts#namespaces)

The event payload which is logged has the following fields for each event:

- `type`: the type of entity changing
- `action`: the action taken upon the entity
- `metadata`: extra information about the event such as identity of the subject who initiated the event
- `payload`: the actual payload of the request on Flipt
- `timestamp`: the timestamp of when the event was created

Any combination of actions on those entities will result in an event with the above fields being logged out to the file you specify via configuration:

```yaml
audit:
 sinks:
 log:
 enabled: true
 file: /tmp/flipt/audit.log
```

We also have an example of how you could potentially collect, parse, visualize, and query these events using Grafana's [Promtail](https://grafana.com/docs/loki/latest/clients/promtail/) + [Loki](https://grafana.com/docs/loki/latest/) in our [examples](https://github.com/flipt-io/flipt/tree/main/examples/audit) on GitHub. This would allow you to query the audit events in a similar fashion to how you would query logs in a traditional logging system, even when Flipt is running in a distributed fashion.

<BlogImage
 src="/audit-events/loki.png"
 alt="Grafana Loki Query"
 width={2880}
 height={1800}
 caption="Querying Flipt audit events using Grafana Loki"
 className="shadow-md"
/>

## What's Next

We are excited for this release to see just how users will interact with this feature, and also excited for community discussion on potential event sinks that have not been added yet.

[Contributions](https://github.com/flipt-io/flipt#contributing) are always appreciated! This [document](https://github.com/flipt-io/flipt/tree/643ccc1d541e6a1e79cfeeb548df6b53a09e9914/internal/server/audit) describes how you can implement your own audit event sink.

We hope you found this post useful. As always, you can find us on [GitHub](https://github.com/flipt-io), [Discord](https://www.flipt.io/discord), [Twitter](https://twitter.com/flipt_io), or [Mastodon](https://hachyderm.io/@flipt).

Audit Events for Flipt

<BlogImage
 src="/dagger/embracing-dagger.png"
 alt="Flipt loves Dagger."
 width={2400}
 height={1350}
>
 
 Background by [Paul Volkmer](https://unsplash.com/@laup) on Unsplash
 
</BlogImage>

In a [previous blog post](/blog/generating-the-flipt-go-sdk), I briefly mentioned our adoption of Dagger.
I wanted to take a moment to introduce Dagger and explain how we’re slowly but surely adapting our build, test (and one-day release) pipeline to leverage it.

> Dagger is a programmable CI/CD engine that runs your pipelines in containers.

[Dagger](https://dagger.io) lets you describe your build, test and release pipelines as code, often alongside the application you’re developing it around. They support an expressive set of SDKs in multiple programming languages. At Flipt we’re using Dagger's (you guessed it) [Go SDK](https://github.com/dagger/dagger/tree/main/sdk/go).

Perhaps unsurprisingly, in Dagger, almost everything is a container. I say unsurprisingly since a lot of the team also gave us Docker, the technology which put Linux containers truly on the map. Each of the Dagger SDKs exposes a builder pattern interface with the primary function of describing a graph of instructions. These instructions are remarkably similar to those found in a Dockerfile, which is not a coincidence. These instructions also produce layers in resulting OCI images, which can then be published or exported from your Dagger pipeline.

I don’t know about you, but I do love a DAG and so does Dagger. The DAG (Directed Acyclic Graph) is intrinsic to what makes it such a neat solution. No points for guessing where they got their name.

<BlogImage
 src="/dagger/dag.svg"
 alt="A DAG"
 width={509}
 height={144}
 caption="A DAG"
/>

A DAG is a set of vertices (the boxes) and edges (the arrows). The edges express dependencies from one vertex to the next. Before I can copy my Flipt binary into an appropriate location for execution, I first need to build it from the source. In order to run `go build` I first need to install Go.

DAGs allow us to express the dependent order in which operations must occur. Where this differs from a plain old sequential list, is that each vertex (entry) can have more than one (potentially) independent inputs. When you describe your workflow in this way, an execution engine (such as Dagger) can leverage the fact that fully _independent_ operations can be executed concurrently. If you’re running your workflow on a multicore machine you may even see these operations run in parallel.

In the rough illustration above, our Go and Node components can be built independently from one another. At this stage there are no interdependencies, so they can be run concurrently. Once both operations have been completed, we bring the results together.

### How does it work?

Dagger itself is comprised of a server and client architecture. The server (known as the engine) runs in a container on a target Docker host. Consumers (like Flipt) use one of the Dagger-generated and managed SDKs in one of the supported languages. These SDKs managed to initialize the Dagger engine container for you, as well making all the GraphQL API calls. Dagger has chosen to embrace GraphQL, which is a particularly good fit when you’re talking in directed acyclic graphs.

Having a GraphQL API means consumers are not strictly bound to only the SDKs developed by the Dagger team. Anyone can take the GraphQL docs and bake their own client in the language of their choice. This is similar to how we at Flipt use protobuf and gRPC and generate our managed clients from these definitions.

<StarCTA />

Under the bonnet Dagger leverages [Buildkit](https://github.com/moby/buildkit/). It was originally created by [Tõnis Tiigi](https://github.com/tonistiigi) and now lives under the Moby (Docker) brand. It powers most of `docker buildx`, where Dockerfile’s are actually transpiled into `llb` instructions (A Buildkit structure for describing DAGs) and then _solved_ (evaluated) by a Buildkit daemon.

If you’re familiar with the concept of `git` and its _plumbing_ vs _porcelain_ commands, I would liken the same to Dagger compared with Buildkit. Buildkit is the plumbing and Dagger is the porcelain. Buildkit exposes a fine-grained API for solving DAGs of instructions, which produce OCI images and layers. Dagger is a fast-evolving, developer-friendly layer on top. A layer focussed on solving the higher-level problem of expressing build, test and deployment pipelines in code.

I could talk about these pieces of tech all day, but for now, here is how we’re leveraging them at Flipt to build and ship quickly with confidence.

## Flipt’s Build, Test, Release Pipeline

<BlogImage
 src="/dagger/build-test-deploy.png"
 alt="The classic build, test, and release pipeline"
 width={2570}
 height={694}
 caption="Build, Test, and Release"
/>

Using Dagger we’re developing the classic build, test, and release sequence.

### Build Phase

The Build phase involves sourcing all the raw materials and putting the puzzle together. Effectively we perform the following five-step process:

1. Establish a base image containing all the build and test tools necessary.
2. Fetch all of our source code from GitHub.
3. Download all the Go and Javascript libraries we need.
4. Build the thing(s).
5. Copy the resulting Flipt binary into its own image with only the necessary _runtime_ dependencies.

If you’ve had experience writing a `Dockerfile` in the past, you may be familiar with some tricks folks employ to make better use of the Docker build cache. For example, with Go you might first add just your `go.mod` and `go.sum` files to your container before the rest of your application. Next, you will likely run `go mod download` in order to populate the module cache. Once this is complete then you add the rest of the application source and perform the build. You might also employ Docker's newer `RUN` cache features and mount a cache volume.

```docker
FROM golang:1.20

WORKDIR /src

ADD go.mod .
ADD go.sum .

RUN --mount=type=cache,target=/go/pkg/mod go mod download

ADD . .

RUN --mount=type=cache,target=/go/pkg/mod go build ./...
```

The same can be achieved with Dagger and the experience is familiar. The following is an illustration of using the Go SDK in Dagger to layer our graph to make the best use of caching for Go applications.

```go
func GoApp(ctx context.Context, client *dagger.Client) (*dagger.Container) {
	deps := client.Host().Directory(".", dagger.HostDirectoryOpts{
		Includes: []string{
			"./go.mod",
			"./go.sum",
		},
	})

	return client.Container().
		From("golang:1.20").
		WithWorkDir("/src").
		WithMountedDirectory("/src", deps).
		WithMountedCache("/go/pkg/mod", client.CacheVolume("go-mod-cache")).
		WithExec([]string{"go", "mod", "download"}).
		WithMountedDirectory("/src", client.Host().Directory("."))
		WithExec([]string{"go", "build", "."})
}
```

Our pipeline for building Flipt ultimately leverages this same process, which is to use layers effectively and take advantage of the engine's layer caching, and mounted cache volumes for finer control ensuring fetched or computed assets are preserved between builds. As with Go, the same applies for Node and its dependencies. First add the dependency manifests (`package.json`), install the dependencies and then add the source code.

Beyond this, we have some other details which are a little more specific to how we build Flipt:

1. The Flipt repo is a Go multi-module repository and uses a [Go workspace](https://go.dev/doc/tutorial/workspaces) to tie it all together. We read the contents of the `go.work` file to identify the multiple sets of `go.mod` and `go.sum` file pairs through the repository and ensure they’re all added before downloading dependencies.
2. `client.CacheVolume(...)` in Dagger takes a string to identify the cache volumes key. We build this key based on a hash of the `go.sum` contents. This invalidates our cache each time our sum file changes. The idea is to keep our cache fresh over time and stop it from growing indefinitely.
3. We initially exclude adding the `ui` directory containing our frontend code from the Go base. Instead, we mount this directory into its own container based on a `node` image and produce a static directory containing all of our frontend assets. This resulting static assets directory is copied into the base Go container and we use Go’s embedding to bake this into the binary.

This process is defined in the function we call `Base(...)` and the result is a `*dagger.Container`. Once all the dependencies have been built and added appropriately, we build the `flipt` binary into a well-known path inside the last layer of the container.

There is another function called `Flipt(...)` which takes the resulting container from `Base(...)` and copies the `flipt` binary into a fresh, empty `alpine` Linux image. This image is prepared with just the runtime dependencies needed for Flipt and gives us a thin distributable image for release.

### Test Phase

There are two important artifacts out of the Build phase which become inputs into our Test phase. The first is the base image (the result of steps 1, 2 and 3) with all the build and test tooling and source code. The second is the distributable Flipt OCI image (the thinner distributable image based on `alpine`).

In the testing phase, we first use the base image again to run our suite of Go unit tests. We run our unit test suite against each of the databases Flipt supports (SQLite, Postgres, MySQL and CockroachDB). The unit test suite requires Go to be installed, along with access to all the source code, which is why we use the base image.

The release of Dagger `v0.4.0` came with support for service containers. If you’re familiar with `docker-compose` and how it supports multiple containers being networked together, then this feature will be familiar. It supports the ability to run containers which are used as dependencies for your workflows as network addressable services. For example, a backing database, or your very own service that you want to test over the network. This feature was crucial for connecting the various databases Flipt supports during unit testing. It also allowed us to further build out our integration testing pipeline.

In a [previous blog post](/blog/generating-the-flipt-go-sdk), we discussed building our new Go SDK. In order to gain confidence in Flipt, its API and our SDK, we leverage the full power Dagger gives us with defining our pipelines in Go.

We first defined a suite of test cases using the Go SDK, which exercises a common set of Flipt operations: create a namespace, create a flag, define its variants and segments, evaluate it, etc. The core functional requirements of Flipt as a feature flagging system.

Given how we built our SDK to abstract away details such as the transport used and authentication, we could then easily extract those (non-functional requirement) details as arguments for running our test suite. This means that we could run our suite against the HTTP or gRPC API with or without authentication enabled. With the introduction of namespaces in our [latest release](https://github.com/flipt-io/flipt/releases/tag/v1.20.0), we further enhanced the suite to run across a configurable namespace. Now that our test suite can be run in a number of configurations, we have an n-dimensional matrix of possibilities.

<BlogImage
 src="/dagger/test-matrix.png"
 alt="Our test matrix"
 width={444}
 height={394}
 caption="Our test matrix"
/>

By simply using a set of nested loops in Go, we have a tidy way of expressing the multitude of possible ways Flipt could be run, giving us confidence that we’re not breaking something each time we add or change some functionality. Couple this with the ability to execute each possible configuration combination in a goroutine and we have a fast, concurrent way of executing the many permutations.

```go
func TestAll(base, flipt *dagger.Container) error {
	var g errgroup.Group
	for _, auth := range []bool{true, false} {
		for _, namespace := range []string{"", "some-namespace"} {
			for _, transport := range []string{"http", "grpc"} {
				g.Go(testFlipt(base, flipt, auth, namespace, transport))
			}
		}
	}
	return g.Wait()
}
```

Our pipeline is now fairly large and relatively complex. Lots of layers and concurrent operations in a web of directed edges and vertices are used to describe both build and test functionality. As with all big and complex CI/CD pipelines, they can start to slow down the more you add. This is where the advanced caching capabilities of Buildkit and Dagger come into play.

The beauty of the DAG in the Buildkit world is that each computed vertex (node) in the graph and its outputs are stored in content-addressable storage. Buildkit takes advantage of when vertices whose definitions and their inputs do not change and avoids recomputing any of these outputs. Instead, it retrieves previously computed results and uses those instead.

Locally, we have seen a full 10-minute end-to-end Flipt build pipeline with subsequent integration suite go from 10 minutes with an empty cache to **17 seconds** on a subsequent run. Flipt currently references 3.2GB **(!)** of Go module dependencies. When you compile Flipt with an empty build cache, a fresh run will produce 1GB of build-cache entries. All this takes a considerable amount of time to fetch and compile. Dagger makes a lot of this work trivial to compute once and reuse on subsequent runs.

Buildkit has the functionality to export its cache storage to a number of remote backends so that you can persist all the hard work done computing layers and cache volumes in CI/CD environments and reuse them between separate triggers of your pipeline. Dagger today (`v0.6.0`) does not expose a stable API for this feature. However, the team are hard at work sweating the details so we won't have to. They’re working hard to find a DX that works for many. At Flipt we’re looking forward to when this lands, as we expect the gains in CI will be very noticeable.

### Release Stage

Once Flipt is packaged and tested sufficiently, it is ready for release. Today we still use the excellent [GoReleaser](https://goreleaser.com/) project to package and ship the final Docker images and binaries to their various destinations. We do suspect though, that this will move to be more Dagger driven as time goes on, ultimately publishing the artifacts produced by the pipelines that we have developed using Dagger.

All the code to define our Dagger-based pipeline can be found in the [build](https://github.com/flipt-io/flipt/tree/main/build) directory of the Flipt repository. We use [mage](https://magefile.org/) both in the root of the Flipt repository and in our Dagger pipeline code as the CLI wrapper. We’re big fans of `mage` and so is Dagger. For those wanting a `make`-like interface which is defined in Go, it is a nice intersection of the two. It also marries nicely with all of our pipeline code being defined using the Dagger Go SDK.

### Dagger All The Way

Dagger is shaping up to be the solution I always wanted for CI/CD. Call me strange, but I am actually excited to develop and maintain these pipelines and I am hopeful it is going to be a sharp tool in our belts here at Flipt.

If you’re interested in Dagger then I highly recommend checking out their [site](https://dagger.io/), [GitHub project](https://github.com/dagger/dagger) and in particular [Discord](https://discord.gg/dagger-io).

Equally, we really want to understand your needs in building and shipping software here at [Flipt](/). So please do come and stop by our [Discord](https://www.flipt.io/discord) and say hi too.

Dagger, a ❤️  story

<BlogImage
 src="/go-sdk/flipt-sdk.png"
 alt="Flipt's Go SDK"
 width={2400}
 height={1350}
>
 
 Photo by [Lenny Kuhne](https://unsplash.com/@lennykuhne) on Unsplash
 
</BlogImage>

# Generating the Flipt Go SDK

This blog post describes the journey we took to build our new Go SDK, and how we developed our `protoc` plugin in Go to achieve that. It first explores our motivations and then gets into some of the details of how we built it and the tools that go into the automation around it.

We're releasing the new Go SDK today! You should be able to fetch it using `go get go.flipt.io/flipt/sdk/go`.

## Getting Serious About Clients

Recently, we decided to revise and improve our API client offering, starting with our support for Go.

Go is the core language used to develop Flipt's backend service. It is something the team has a long history with, so this was an obvious place for us to start.

With the [recent addition of different authentication methods](/blog/enhancing-authentication#kubernetes-service-account-authentication) for Flipt, we wondered how we could better support integrating these authentication mechanisms into clients.

Our [documentation](/docs/authentication/using-tokens) explains how to manually wire static client tokens into a gRPC or HTTP client, however, we now support authenticating using Kubernetes service-account tokens. Doing so is a more involved process, with an extra API handshake in the middle, so this is something we ideally want our clients to do for you with minimal configuration.

## Status Quo

Flipt’s core service and APIs are defined using [gRPC](https://grpc.io/) and protobuf. This allows us to define our APIs as a set of RPCs and messages in the [proto](https://protobuf.dev/programming-guides/proto3/) language and then use a set of `protoc` tools and plugins to scaffold domain models, servers and clients in different languages. This is a superpower for us. It allows us to reach other programming ecosystems and languages without prior knowledge or experience in them, opening Flipt up to a wider audience.

However, gRPC alone is not for everyone or every ecosystem. While it has a big reach, not every language is catered to equally. In particular, the browser hasn’t had the best support so we also wanted an equivalent HTTP API. The API should also be understandable by developers, allowing them to write their clients using an HTTP library in their language of choice.

This is where [grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway) comes into the mix. Flipt has used this project since the beginning to present an equivalent REST-like API using JSON as the message serialization format. The grpc-gateway tooling supports server generation (not client) in Go.

This is where we were until very recently. We have a gRPC protobuf generated client for the Go community, with no additional bells or whistles, just a thin shim around the Flipt gRPC endpoints and no support for invoking the HTTP API in Go. While we’re uncertain of the use cases, it seemed a shame to mandate gRPC when the [HTTP API](/docs/reference/overview) is also available.

## Our Goals

- A single consistent SDK API, which abstracts the details of the transport from the caller. While we want our users to have the choice, we don’t think the transport details matter when it comes to consuming the client's functionality in your application code.
- Two implementations of the transport abstraction, one for gRPC and one for HTTP.
- To generate as much of this as possible from the original `proto` definitions. We invested in gRPC and protobuf for the tooling and automation. Having our SDK advance with these definitions will keep us up to date.
- Develop an abstraction around authenticating our SDK, which supports consumers’ needs to access Flipt’s APIs with minimal configuration.

<BlogImage
 src="/go-sdk/Flipt_SDK_Architecture.svg"
 alt="Flipt SDK Architecture"
 width={729}
 height={339}
 caption="Flipt SDK Architecture"
/>

The entry point to our new client is the `SDK` type. This type encapsulates the three sections of the Flipt RPC APIs known as `Flipt` (core API), `Auth` (authentication-related APIs) and `Meta` (server metadata APIs). All of these types are generated from the original `proto` definitions.

These SDK types are (mostly) abstracted away from the transport details. The specifics are hidden behind a set of `Transport` Go interfaces. Each of these interfaces has an equivalent implementation for both `grpc` and `http`.

```go
type Transport interface {
	AuthClient() AuthClient
	FliptClient() flipt.FliptClient
	MetaClient() meta.MetadataServiceClient
}
```

For the most part, the `grpc` transport implementation is identical to that of the `grpc-go` generated client. The packages contain some thin wrapping code to glue our SDK together. The crux of the code has been implemented and the transport interfaces are very close to these concrete `grpc` implementations. This was an intentional decision to minimize effort and generated code.

<StarCTA />

The `http` implementation on the other hand required some more work. For a start, `grpc-gateway` does not ship a generated HTTP Go client, so we had to implement this ourselves. To invoke the API generated by grpc-gateway, we need to produce code that can adapt our RPC messages into the appropriate HTTP requests. We also need to provide a Go implementation that conforms to the Transport interface definitions derived from gRPC.

The grpc-gateway ecosystem has a collection of additional annotations and metadata which describe how the RPC methods should be represented as HTTP requests, for example:

```yaml
http:
 rules:
	# ...
	- selector: flipt.Flipt.CreateVariant
	 post: /api/v1/flags/{flag_key}/variants
	 body: "*"
```

Our custom `protoc` plugin parses this additional metadata and uses it to generate Go code which can produce an equivalent HTTP request.

```go
func (x *FliptClient) CreateVariant(ctx context.Context, v *flipt.CreateVariantRequest, _ ...grpc.CallOption) (*flipt.Variant, error) {
	var body io.Reader
	var values url.Values
	reqData, err := protojson.Marshal(v)
	if err != nil {
		return nil, err
	}
	body = bytes.NewReader(reqData)
	req, err := http.NewRequestWithContext(ctx, http.MethodPost, x.addr+fmt.Sprintf("/api/v1/flags/%v/variants", v.FlagKey), body)
	if err != nil {
		return nil, err
	}
	req.URL.RawQuery = values.Encode()
	resp, err := x.client.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	var output flipt.Variant
	respData, err := io.ReadAll(resp.Body)
	if err != nil {
		return nil, err
	}
	if err := checkResponse(resp, respData); err != nil {
		return nil, err
	}
	if err := protojson.Unmarshal(respData, &output); err != nil {
		return nil, err
	}
	return &output, nil
}
```

I don’t suspect we have managed to support the full breadth of protobuf, grpc and grpc-gateway features. However, we believe we have implemented enough to cover the functionality Flipt takes advantage of.

## How does one write a protobuf Go code generator?

[https://pkg.go.dev/google.golang.org/genproto](https://pkg.go.dev/google.golang.org/genproto) is a Go package designed to aid in the development of `protoc` plugins. It is used by `grpc-gateway` and `grpc-go` in order to parse and generate their respective client and server implementations.

<BlogImage src="/go-sdk/protoc.svg" alt="Protoc" width={561} height={157} />

`protoc` is the entry point to all things protobuf generation. It parses and validates your protobuf files and invokes any configured plugins with a request to generate code on `stdin`.

[https://pkg.go.dev/google.golang.org/protobuf/types/pluginpb#CodeGeneratorRequest](https://pkg.go.dev/google.golang.org/protobuf/types/pluginpb#CodeGeneratorRequest)

The message you are provided is a protobuf serialized structure itself. Specifically, it is a `pluginpb.CodeGeneratorRequest`. This contains the parsed definitions of your protobuf files collected by `protoc`.

It is up to the plugin to interpret this request and produce a response. The response is written to `stdout` as a protobuf encoded `pluginpb.CodeGeneratorResponse`. The response contains all the files you have produced and where they should end up (their file names).

The `protogen` package provides a framework which hides much of the hairy details of writing a `protoc` plugin. Simplifying the wiring and providing useful utilities specifically for generating Go code.

There is an excellent [blog post](https://rotemtam.com/2021/03/22/creating-a-protoc-plugin-to-gen-go-code/) by Rotem Tamir, which laid the foundational knowledge we needed to get started on our custom SDK wrapper and HTTP client. If building something with `protogen` interests you, then I highly recommend reading this first.

### Some `protogen` pointers

I won’t repeat all the wonderful tidbits and details in that blog post, however, I do have a couple of extra pointers that I discovered along the way while developing our SDK generators.

Firstly, we use `proto` version `3` and in particular, we use the `optional` keyword on some message fields. This happens to be a feature of protobuf which was introduced after the initial release of version `3`. If you attempt to use `protogen` on `proto` files using the `optional` keyword without first enabling it as a “supported feature” in your plugin, then you will be confronted with a warning each time your plugin is invoked:

```go
Warning: plugin "go-flipt-sdk" does not support required features.
 Feature "proto3 optional" is required by 1 file(s):
 auth/auth.proto
```

It was a little unclear at first, but the trick is to set the optional feature _bit_ on the `*protogen.Plugin.SupportedFeatures`:

```go
protogen.Options{}.Run(func(gen *protogen.Plugin) error {
		gen.SupportedFeatures |= uint64(pluginpb.CodeGeneratorResponse_FEATURE_PROTO3_OPTIONAL)
		// ....
}
```

`SupportedFeatures` is a bitmask and the nice, human-readable names for the feature bits can be found at [google.golang.org/protobuf/types/pluginpb](http://google.golang.org/protobuf/types/pluginpb).

Secondly, managing imports in your generated Go files can initially be unclear. It turns out that `protogen` has a really nice feature, which does a lot of heavy lifting with regard to managing the naming and qualification of those names in your generated output:

```go
for _, f := range gen.Files {
 if !f.Generate {
 continue
 }

 filename := string(file.GoPackageName) + ".sdk.gen.go"
 g := gen.NewGeneratedFile(filename, myTargetPackageName)

 // QualifiedGoIdent will handle adding the GoImportPath
 // to the target GeneratedFile (g) in the `import` declaration
 // at the top. It even handles when you reference two packages
 // with the same name by adding a numeric suffix to distinguish them.
 httpClient := g.QualifiedGoIdent(protogen.GoIdent{
 GoImportPath: protogen.GoImportPath("net/http"),
 GoName: "Client",
 })

 g.P("type MyClient struct {")
 g.P("client *", httpClient)
 g.P("}")
}
```

`protogen.GeneratedFile.QualifiedGoIdent` ensures that the path you’re referencing is correctly imported into the top of the resulting generated Go file. It also handles any imports with duplicate names by adding a numeric suffix (e.g. importing both `text/template` and `html/template` would resolve to `template "text/template"` and `template1 "html/template"`). Then the resulting import path is correctly prepended onto the type when the `GoIdent` produced by this function is passed into `g.P("...", httpClient)`.

The example generator code above would produce something similar to:

```go
package client

import http "net/http"

type MyClient struct {
	client *http.Client
}
```

### Putting it altogether

So Flipt now has a single `protoc` plugin, which produces three target packages.

The plugin lives [here](https://github.com/flipt-io/flipt/tree/main/internal/cmd/protoc-gen-go-flipt-sdk) and it generates the following three packages into the Flipt repository:

- `sdk/go/http` containing `HTTP` implementations of the `sdk.Transport` interfaces.
- `sdk/go/grpc` contained `gRPC` implementations of the `sdk.Transport` interfaces.
- `sdk/go` the core of our Go SDK.

To bring all of this together, we use a tool called [buf](https://buf.build/) to orchestrate the invocations of the `protoc` toolchain. The protobuf toolchain is a fiddly beast and `buf` greatly simplifies this process for us.

We have a single addition to our `buf.gen.yaml` which drives this tool. It looks like this:

```yaml
plugins:
 # ...
 - name: go-flipt-sdk
 out: sdk/go
 opt:
 - paths=source_relative
 strategy: all
```

Each of the entries under `plugins` is treated as a `protoc` plugin. These will be passed on invocations of the `protoc` tool by `buf`. `protoc` knows when it sees the name `go-flipt-sdk` to prepend `protoc-gen-` onto the front and look that binary in your `PATH`. In our case, it looks for `protoc-gen-go-flipt-sdk`.

## Where next?

We’re hoping this automation keeps us on a good footing with each change to Flipt’s API, allowing us to generate a client in lockstep with the server API, which has support for all the RPC definitions we create.

Beyond just generating the client we plan to add support for the Kubernetes authentication method, reducing that down to some configuration with sensible defaults.

Finally, we have begun the work to build out a new integration test suite to ensure our SDK and Flipt are behaving as we intend. Our next blog post on this topic will explore how we’re building out a new CI pipeline using [Dagger](https://dagger.io). Dagger is enabling us to define a pipeline we can execute anywhere, which is both fast and reproducible. We’re very excited about the future of Dagger and can’t wait to talk about how we plan to leverage it in the Flipt build process.

We hope you’ll find this new SDK useful, and we’re happy to answer any questions that you may have in our [community Discord](https://www.flipt.io/discord) or via GitHub issues/discussions.

We welcome all feedback on how to improve the SDK or Flipt as a whole, so feel free to reach out! You can find us on [GitHub](https://github.com/flipt-io), [Twitter](https://twitter.com/flipt_io), [Mastodon](https://hachyderm.io/@flipt), and [Discord](https://www.flipt.io/discord).

Generating the Flipt Go SDK

<BlogImage
 src="/hi-yoofi/yoofi.png"
 alt="Hello, Yoofi!"
 width={2400}
 height={1350}
>
 
 Photo by [Dejan Zakic](https://unsplash.com/@dejanzakic) on Unsplash
 
</BlogImage>

We are excited to announce a new addition to the Flipt team, [Yoofi Quansah](https://www.linkedin.com/in/redblacktree/) - a Senior Software Engineer with 6+ years of experience and a love of developer tooling. With his impressive background and skills, we are confident that he will play a significant role in advancing our mission of helping engineers everywhere deploy software to production without fear.

Here's what Yoofi had to say about his background and decision to join the Flipt team:

> Hello 👋, my name is Yoofi Quansah. I've had quite the journey to finally find my way here at Flipt, but let me not bore you with details you probably don’t want to know and get to the fun stuff!
>
> Before writing code, I was actually 99% positive I was going to make it to the NFL (as we all were). I am writing this blog post now, so you know that didn't happen 🙂, but I am very happy with how my life has turned out so far.
> I started my career out building simple developer tools over at Honey. After I got over the hump of imposter syndrome and really got into my work, we started to build some really cool tools on the team. These tools included our own feature flagging service (foreshadowing), deployment platforms, and testing platforms to name a few.
> Everything was cool right? Not quite. I realized that even though we were building these cool tools, we were not really getting much recognition for it, and even worse the engineers were relatively slow to adapt. It was quite draining, to say the least.
>
> Enter July 2019... My life changed when I went to Gophercon.
> I found people who were building developer tools and directly interacting with customers with the tools they built. Wow. It was at that point that I knew I wanted to write Go, and work with a company that interacted directly with developers as their customers. After all, it is pretty nice to see the value of the products that you build for others to use directly.
> The result of all this was me leaving my job at Honey, and joining InfluxData in August of 2020, where I met [George](/blog/welcome-george-macrorie)!
>
> InfluxData was an incredible experience. I met tons of smart people, which allowed me to hone my craft as an engineer. It also allowed me to realize exactly what I wanted out of my career, which was to build incredible features for engineers to use. Most of my time there was taken up building the next generation of the query engine, which solved a wealth of problems we were facing with the old one.
> George introduced me to the grand idea of Flipt, all Mark has already done already, and the future outlook/potential roadmap in early 2023. Even though I was quite happy at InfluxData, I fell in love with the challenge, and all that is being hoped to accomplish.
>
> Combined with my previous experience helping out building a feature flagging service at Honey, and a whole lot of issues I ran into with feature flags both at Honey and InfluxData, I believe there is a bright future for this critical piece of software development and delivery.
> I am happy to be here, and hack on!

Welcome Yoofi, we are lucky to have you! 🚀

Meet Yoofi Quansah

<BlogImage
 src="/enhancing-authentication/enhancing-authentication.png"
 alt="Enhancing Flipt Authentication"
 width={2400}
 height={1350}
>
 
 Photo by [Roon van der Meer](https://unsplash.com/@roonz_nl) on Unsplash
 
</BlogImage>

In the previous few posts, we went over the addition of one of our most asked-for features: User Authentication support. Just when you thought that might be the end of our authentication story, we improved it even more by adding three more authentication-related features:

1. API token configuration via the UI
1. Configurable bootstrap token
1. Kubernetes Service Account authentication

In this post we'll briefly go over each feature, discussing its use case, why it's an important addition to our overall auth story, as well as how to get started.

## API Token Configuration

We've had basic token authentication support for authenticating your services with Flipt since v1.15. Admittedly though, it was somewhat incomplete as you could only manage those tokens via the [API](https://www.flipt.io/docs/reference/authentication/create-token).

In this [latest release](https://github.com/flipt-io/flipt/releases/tag/v1.19.0), we added the ability to create and delete static tokens in the UI as well. This allows anyone authenticated with Flipt to see which tokens have been issued and when they expire. It also allows users to create and delete tokens as needed without having to write code to do so.

Enabling and using static token authentication is a good first step when it comes to securing the communication between Flipt and your own services. Making the management of access tokens as user-friendly as possible was one of the major acceptance criteria for this new functionality.

This feature also necessitated a new 'Settings' section of the application which we'll populate with more controls in the future.

<BlogImageGallery
 images={[
 {
 src: "/enhancing-authentication/static-tokens/list.png",
 description: "Settings Screen with Static Tokens View",
 },
 {
 src: "/enhancing-authentication/static-tokens/new.png",
 description: "Creating a New Token",
 },
 {
 src: "/enhancing-authentication/static-tokens/expiry.png",
 description: "Adding an Expiration to a Token",
 },
 {
 src: "/enhancing-authentication/static-tokens/created.png",
 description: "Token Created",
 },
 ]}
/>

After creating a token via the UI, you can easily copy it to your clipboard and store it in a secure location as its value will no longer be accessible from Flipt itself.

## Configurable Bootstrap Token

Another improvement that we added in this release is the ability to provide a configurable bootstrap token when first enabling token authentication. Since v1.15, if an operator enabled token authentication for the first time, we would create what we call an initial bootstrap token on their behalf, logging it to `STDOUT` to be captured and used.

```console
access token created	{"server": "grpc", "client_token": "ks8gyZNdU7jmB92kAIYOp4MEXTcCJbX1TdXJM01VKCs="}
```

This was necessary because all requests to the Flipt API would fail as soon as you enabled and required token authentication.

This meant, however, that there wasn't a great programmatic way to run Flipt with token authentication enabled for the first time, such as in the case of Kubernetes. Flipt operators would have to either:

1. Start Flipt with authentication enabled but not required, create a token via the API, and then restart Flipt with authentication required.
1. Start Flipt with both authentication enabled and required and try to capture the created bootstrap token from our logs.

This also presented a similar challenge when trying to run Flipt in CI, such as we do for our own integration tests, as there was no easy way to set up authentication and then restart Flipt in a test pipeline.

In this release, we added the ability for the user to optionally specify their own known bootstrap token as well as to configure it with an expiration.

<BlogImage
 src="/enhancing-authentication/bootstrap-token-expiration.png"
 alt="Bootstrap token created with expiration"
 width={2442}
 height={490}
 caption="Bootstrap token created with expiration"
 className="shadow-md"
/>

Here's an example of how to configure a bootstrap token with a known value and an expiration of 24 hours:

```yaml
authentication:
 methods:
 token:
 enabled: true
 bootstrap:
 token: "s3cr3t!"
 expiration: 24h
```

In our opinion, this provides the best of both worlds by allowing for the initialization of an authentication token with a potential known value that can expire automatically. This gives operators the ability to enable authentication from the get-go, use a known token to create more tokens, then allow the known token to quietly expire to prevent unwanted access.

More information on how to configure this feature can be found in our [documentation](https://www.flipt.io/docs/configuration/authentication/#token-authentication).

## Kubernetes Service Account Authentication

In most cases, static tokens are a manageable approach for getting services talking with Flipt. For security reasons, you may set an expiry on your tokens and periodically rotate them with new ones. Given you have more than one type or replica of your application(s) communicating with Flipt, you may even choose to create multiple tokens. It may be one per application type or even as many as one per replica.

For those deploying Flipt into Kubernetes environments, we have added the new `kubernetes` authentication method.
This method takes advantage of the [service account](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) mechanisms made available in Kubernetes.

By default Kubernetes periodically writes a service account token (encoded as a JWT) into a well-known path inside each pod's filesystem.
Service account tokens can be used to communicate and identify the caller with the Kubernetes API. With Flipt [v1.19](https://github.com/flipt-io/flipt/releases/tag/v1.19.0) you can exchange this service account token for a Flipt client token via Flipt's API.

A small amount of client-side glue code can keep your applications authenticated without having to manually create, rotate or distribute tokens.

Here's an example using `curl` and `jq` to exchange a Kubernetes service account token for a Flipt client token:

```bash
curl -s -X POST http://flipt:8080/auth/v1/method/kubernetes/serviceaccount \
 --data "{\"service_account_token\":\"$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)\"}" | \
 jq .
{
 "clientToken": "pKkaEik40Nu4lJ7O37l92MNyyD38U8UlaagSmAfJoS0=",
 "authentication": {
 "id": "f191babc-57b8-4856-89b1-f324941403d7",
 "method": "METHOD_KUBERNETES",
 "expiresAt": "2024-02-20T13:39:14Z",
 "createdAt": "2023-02-20T14:11:28.962841Z",
 "updatedAt": "2023-02-20T14:11:28.962841Z",
 "metadata": {
 "io.flipt.auth.k8s.namespace": "default",
 "io.flipt.auth.k8s.pod.name": "someservice-586bfb5b6b-fmh8g",
 "io.flipt.auth.k8s.pod.uid": "b5217947-aeac-4b35-afd3-23f50d63eae9",
 "io.flipt.auth.k8s.serviceaccount.name": "default",
 "io.flipt.auth.k8s.serviceaccount.uid": "8aeb28ad-66f0-4884-bafc-e606e5eda149"
 }
 }
}
```

Enabling this method means Flipt implicitly trusts other services deployed into the same cluster.

While currently leveraging this new method will require some application code on the developers' part, we're actively working on a way to provide out-of-the-box support for our official clients.

As always, our [documentation](https://www.flipt.io/docs/configuration/authentication) has more information on how to configure these features.

Please let us know what you think of these new features and if you have any questions or feedback, feel free to reach out to us on [Discord](https://www.flipt.io/discord), [Twitter](https://twitter.com/flipt_io), or [Mastodon](https://hachyderm.io/@flipt)!

Enhancing Authentication Support

<BlogImage
 src="/new-look-and-oidc/flipt-v1.18.0.png"
 alt="Flipt v1.18.0"
 width={2400}
 height={1350}
>
 Photo by [Jr Korpa](https://unsplash.com/@jrkorpa) on Unsplash
</BlogImage>

I'm happy to announce that there's a [new version of Flipt, v1.18.0](https://github.com/flipt-io/flipt/releases/tag/v1.18.0) which has a few important changes.

- The whole UI has been rewritten in [ReactJS](https://reactjs.org/) and styled with [TailwindCSS](https://tailwindcss.com/). Technically this happened in v1.17, but v1.18 has a few new features that we want to highlight, so we decided to wait and officially announce both at the same time.
- New authentication options — You can now authenticate into Flipt using Google, GitLab, Auth0, Dex, or any [OpenID Connect](https://openid.net/connect/)-compliant service.

## Refreshed User Interface

In the [previous post](/blog/embedding-react-in-go), we went over the technical challenges and decisions we made to integrate our new UI, written in ReactJS, with the existing Flipt backend, written in Go. In this post, we'll quickly cover the why behind this initiative, the result of this effort, and explain how our new UI helps us to improve your experience as an end user of Flipt.

Our previous UI was written in [VueJS](https://vuejs.org/) and it had started showing its age. We had tried to keep it up to date as far as library and dependency versions, however, there was no getting around the fact that it had been written for our needs a few years ago and wasn't as flexible as we needed it to be going forward.

First off, we were using VueJS 2, which was a major version behind the current version of VueJS, 3. While it might not have been too difficult to update our application to the latest version of Vue, we theorized that it would end up requiring a lot more work than if we started fresh by rethinking the user experience and then picking a new framework.

In fact, the component library that we were using in our Vue2 app, [Buefy](https://buefy.org/), has [explicitly stated](https://github.com/buefy/buefy/issues/2505#issuecomment-997000720) that they would not support Vue3 going forward. While this is completely understandable and not a knock on Buefy, it was a concern for us as it meant we were 'stuck' on Vue2.

The second major issue with our front-end application was that it was written in plain JavaScript, so we weren't able to take advantage of all the nice type safety and tooling that you get with TypeScript. This ended up being another supporting reason as to why made the switch from VueJS to React since we knew we wanted to move to TypeScript and would have to effectively re-write the entire application anyways.

The final reason we decided to start from scratch with the UI was that we wanted to create a new, aesthetically pleasing look while enabling our small team to continue to work effectively and be able to ship new features for the front end. Thank goodness libraries such as TailwindCSS exist, allowing even us non-designers to quickly create an attractive UI that we could be proud of.

We were able to accomplish all of these things by switching over from VueJS to React, and the end result was a UI that looked much better and was easier for our team members to develop and maintain. We also decided that React would be a better choice for our application long term because of React's popularity, which makes it easier to find contributors and team members who enjoy working with it.

While we probably could have tackled some of these concerns by better componentizing the existing UI, or upgrading to Vue3 without Buefy, in the end, I think we made the right choice.

The result of our work is a brand-new UI that is responsive, easy to navigate, and looks great on all devices. Here are a few screenshots of the UI in action:

<BlogImageGallery
 images={[
 {
 src: `/new-look-and-oidc/screenshots/flags.png`,
 description: "Flag List",
 },
 {
 src: "/new-look-and-oidc/screenshots/variants.png",
 description: "Add Variant",
 },
 {
 src: "/new-look-and-oidc/screenshots/segments.png",
 description: "Segment List",
 },
 {
 src: "/new-look-and-oidc/screenshots/distributions.png",
 description: "Configure Distributions",
 },
 {
 src: "/new-look-and-oidc/screenshots/evaluation_console.png",
 description: "Evaluation Console",
 },
 ]}
/>

## New Authentication Options

We’re excited to announce that Flipt now supports additional authentication options besides the static token authentication that we added in [v1.15.0](https://www.flipt.io/blog/authenticating-flipt). This new, session-enabled, authentication is powered by the [OIDC (Open ID Connect)](https://openid.net/connect/) protocol, which allows you to use your existing identity providers like Google, GitLab, Auth0, [Dex](https://dexidp.io/), or Okta to log in to Flipt.

In the past we didn't have a great answer for how to secure the Flipt user interface from the outside world, other than to simply:

- Not expose it by putting it behind a VPN
- Put a reverse proxy in front and delegate the authentication to the proxy.

As noted above, in v1.15.0 we added static token support so that you could secure your integrating service-to-service communication with Flipt, but this still did not solve the problem of an end user wanting to authenticate with the UI.

Since OIDC is a popular standard for authentication, enabling it allows Flipt to support a variety of different identity providers using just one login flow, which makes it easier for you to secure your Flipt UI from the outside world.

So what does this mean for end users? If you configure an OIDC provider, Flipt will present it as a login option when you visit your Flipt dashboard. Once the end user authenticates with the provider, they will be returned to the Flipt dashboard. Flipt will establish a client token and set it in a protected cookie. The token has a configurable lifetime and will be rejected once that lifetime expires.

<BlogImage
 src="/new-look-and-oidc/login.png"
 alt="Flipt Login Screen"
 width={441}
 height={444}
 caption="Login Page with OIDC Providers"
 className="shadow-md"
/>

There are several new configuration settings that you can use to set up and customize your OIDC integration, and they are thoroughly documented in our updated docs. You can read more about them here:

- [OIDC Configuration Settings](https://www.flipt.io/docs/configuration/authentication#method-oidc)
- [OIDC Method Overview](https://www.flipt.io/docs/authentication/methods#oidc)

## Wrap Up

In future updates we'll be adding support for other non-OIDC-based authentication such as [GitHub authentication](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps) (via OAuth2) as well as providing UI functionality to manage your static tokens and more.

We hope you’ll find this update useful, and we’re happy to answer any questions that you may have in our [community Discord](https://www.flipt.io/discord) or via GitHub issues/discussions.

We also welcome all feedback on how to improve Flipt as a whole, so feel free to reach out! You can find us on [GitHub](https://github.com/flipt-io), [Twitter](https://twitter.com/flipt_io), [Mastodon](https://hachyderm.io/@flipt), and [Discord](https://www.flipt.io/discord).

New Look + Authentication Options

<BlogImage
 src="/embedding-react-in-go/react-go.png"
 alt="Flipt React + Go"
 width={2416}
 height={1366}
>
 
 Photo by [Jason Leung](https://unsplash.com/@ninjason) on Unsplash
 
</BlogImage>

We’re not far off the 1.17 release of Flipt. It comes with a fresh coat of paint and some foundational changes to the Flipt user interface. We wanted to take a moment and share part of the engineering journey taken to get to this release.

## TL;DR

- We’re moving from Vue to React 🎉
- We experimented with Next.js 🧪
- We struggled with client-side routing 🗺️
- We settled on plain-old React + hash-based routing ⚛️

As we neared the end of 2022, we were settling new authentication features we had been building. The ability to support login in the UI was a primary motivator for the backend changes we were making, so naturally, we were closing in on building login functionality in the frontend. Since we had to tackle some reasonably sized frontend changes anyway, we took a moment to reconsider the state of our frontend architecture.

When Mark first laid the foundations of the current UI back in February 2019, Vue.js presented a quick and easy way to do so. Particularly, in such a way that could be easily embedded into Flipt.
Flipt is a single binary built primarily in Go, and it serves both the HTTP and gRPC protocols.

The UI is served over HTTP directly from the binary using Go’s fantastic [http.FileServer](https://pkg.go.dev/net/http#FileServer) implementation from the standard library. Sometime around February 2021 was the Go 1.16 release, which came with [native embedding](https://github.com/golang/go/issues/41191) of files into Go binaries. Flipt quickly took advantage of this feature for bundling the static UI assets directly into the binary. Go has a handy wrapping function that adapts the `embed.FS` into the required `http.FileSystem` interface to integrate it seamlessly into an `http.Server`.
You can find the current (`v1.16.0`) embed directive in Flipt [here](https://github.com/flipt-io/flipt/blob/9e0ba7d839ef452526815f71ed6e1207d6aa4997/ui/embed.go#L8-L9).

<BlogImage
 src="/embedding-react-in-go/ui-build-process.png"
 alt="UI to Go embedding build process"
 width={1646}
 height={503}
 caption="UI to Go embedding build process"
/>

Fast-forward back to today, and we're reviewing the future of the UI. It appears that React has dominated the world of frontend frameworks since Flipt inception. As such, we have speculated that React could have a broader appeal for Flipt contributors, so we have decided to take the plunge now before we get any more invested in frontend features.

The frontend is not our natural habitat at Flipt. We’re learning by doing. When we decided to take the first steps to transition from Vue to React, we looked around for what is the current hot stuff on the market.
This is where [Next.js](https://nextjs.org/) caught our attention. We had some initial familiarity with it, as this blog and our landing page is built using it.
Next has plenty of batteries included tooling and how-to material to sink our teeth into, so we got to work spiking a prototype.

It didn’t take long for us to get a prototype using Next.js together. Where things started to get tricky was getting Next.js to fit in our Go binary, where the existing UI currently resided.

## Challenges

### Challenge 1: Bundling our Next.js application into a Go binary

Our first goal was to try to replicate what we had already. Easy right? Last time we just:

1. Ran a build process in the UI project to produce a directory of assets.
2. Embedded those assets using Go’s embed tooling.

This first attempt didn’t take too long to replicate. A little digging around Next’s documentation led us to this page: https://nextjs.org/docs/advanced-features/static-html-export. After building the site with `npm run build`, a subsequent `next export` appeared equivalent to how we produced and consumed our Vue.js application. A little more digging to get the export CLI flags right, and it was as simple as `next export -o $FLIPT/ui/dist`.

Now we have all our assets (HTML, JS, CSS etc) in the correct directory. Without changing anything else, we booted Flipt and took a look. At first glance, everything seemed like it might have just worked.

### Challenge 2: Missing Assets

However, things were not quite what they seemed. Interactions weren’t working as expected. A brief look under the hood (via developer tools), and sure enough, there were a bunch of errors.

<BlogImage
 src="/embedding-react-in-go/console-errors.png"
 alt="Errors in the browser console"
 width={2024}
 height={920}
 caption="Errors in the browser console"
/>

The errors were a little misleading at first. What has this got to do with `X-Content-Type-Options: nosniff`? Why is `text/plain` being returned as the content-type for JS assets by our file server? Popping open the network tab was a little more enlightening.

<BlogImage
 src="/embedding-react-in-go/console-network-requests.png"
 alt="Console network tab requests"
 width={2024}
 height={920}
 caption="Console network tab requests"
/>

These failing assets were returning 404 (Not Found) status codes, but not everything was returning a 404.
Looking at the responses a little closer shined a light on our weird `Content-Type` and “blocked” error messages. Our Go static file server was presenting a generic 404 response page (Content-Type: text/plain) for our missing assets. These assets were being requested via `script` tags, and their security mechanisms were kicking in when they got back a content-type they weren’t expecting.

Long-story short, our Go file server was not serving some subset of our assets.
A quick check of the asset folder we created earlier, and the assets were actually where they should be.

```
➜ tree ui/dist
.
├── 404.html
├── _next
│ ├── E5aRj9aVYvtSy47LN7sYl
│ └── static
│ ├── E5aRj9aVYvtSy47LN7sYl
│ │ ├── _buildManifest.js
│ │ └── _ssgManifest.js
// trimmed output for brevity
```

So, what was it that these particular assets had in common, separate from the assets which were being served successfully?

<BlogImage
 src="/embedding-react-in-go/console-network-requests-ordered.png"
 alt="Console network tab requests ordered"
 width={2056}
 height={950}
 caption="Console network tab requests ordered"
/>

Could it be that they start with an underscore? A bit of digging into Go’s [embed](https://pkg.go.dev/embed#hdr-Directives) standard library turned up just what we were looking for.

```
If a pattern names a directory, all files in the subtree rooted at that directory are embedded (recursively), except that files with names beginning with ‘.’ or ‘_’ are excluded.
…

If a pattern begins with the prefix ‘all:’, then the rule for walking directories is changed to include those files beginning with ‘.’ or ‘_’. For example, ‘all:image’ embeds both ‘image/.tempfile’ and ‘image/dir/.tempfile’.
```

It appears that all we needed was to update our call to the embed directive to the following:

```diff
-// go:embed dist/*
+// go:embed all:dist/*
var UI embed.FS
```

This did the trick. At-least, the errors in the console were gone. All assets were returning status code 200.

### Challenge 3: Right-Click, Open New Tab

It didn’t take long to stumble onto the next set of issues and subsequent can of worms.
When attempting to open a link in a new tab, or visiting it in a new window, we were encountering errors.

Some actions returned 404s, and some listed links to other pages with unexpected content.

<BlogImage
 src="/embedding-react-in-go/segments-page-listing-contents.png"
 alt="Segments page returning directory contents"
 width={2378}
 height={1774}
 caption="Segments page returning directory contents"
/>

What is `[pid].html`? Why are we seeing 404s attempting to create a new flag? I thought this was simply another single-page app? Are we actually navigating to non-existent pages?

Comparing old and new side-by-side, we spotted something we had not considered during the transition. The routing appeared to be different.

<BlogImage
 src="/embedding-react-in-go/current-flipt-ui.png"
 alt="Current Flipt UI Routing Contains Hash"
 width={2040}
 height={1602}
 caption="Current Flipt UI Routing Contains Hash"
/>

We spotted the `#` before the path in our existing Vue.js application. The hash in the URL path (known as a URI fragment) is never sent as part of a server-side request. It is purely there to serve the frontend. When added to a URL, most browsers will attempt to locate an equivalent HTML ID attribute in the page and scroll to that location in the view. However, it has since become popular to leverage the hash value to drive single-page application paths.

In reality, only the root `index.html` (the file server for `/` path) file is being served.

In hindsight, that makes sense. It is a single-page application.
However, in our new application, we have real paths in the URL. These appear to work as expected when you stay within the same window, but the moment you navigate from a new context, we see attempts to serve these paths from the Go file server.

This is where the differences in the transition really started to become clear.
We put on our thinking caps to explore a path forward.

_Unsurprisingly, as the dust settled, some of these problems and solutions started to present themselves in other documentation and blog posts. That was after some failed attempts to Google the problem and come up with our own hacks solutions. Fortunately, we were on the right path._

We explored and prototyped three different paths forward.

1. Update our Go file server to only serve `index.html` for all (HTML asset) paths.
2. Teach our Go file server how to handle Next.js [File-System Routing](https://nextjs.org/docs/routing/introduction).
3. Change back to hash-based routing in our frontend application.

#### Serving `index.html` for all HTML requests

One quick trick (which we later found outlined in [Vue’s documentation](https://v3.router.vuejs.org/guide/essentials/history-mode.html#example-server-configurations) on a similar subject) is to serve the `index.html` page generated by Next, whenever any request for HTML is made.

| path requested | currently rendered | desired page |
| -------------- | ------------------ | ------------ |
| /flags | /flags.html | index.html |
| /segments/one | /segments/one.html | index.html |
| /console | /console.html | index.html |

You get the idea.

Though this isn’t the full picture as one small additional change is required.
By default, it appears that the Next.js router doesn’t attempt to reconcile the actual browser path (window.location.path) with the routers' initialization value for the path.
When we render `index.html` for say the `/segments` page, the router initializes with the path `/`.
I suspect our particular use case is something Next.js isn’t trying to cater for.

In order to get around this problem, we employed a quick hack.
On page load, we forcibly update the router's path if it was not as expected via a [`useEffect`](https://reactjs.org/docs/hooks-effect.html).
This causes a little visual hop from the root page to the desired destination... but it works.
If you know of a better way of doing it, come nerd-snipe us in our [Discord](http://discord.flipt.io)!

#### Implementing Next.js File-System Routing in Go

This approach was a little heavier on the Go side. The crux of the solution is to support Next.js ability to serve dynamic pages via an on-disk naming convention using square brackets in the filename (This is our friend `[pid].html`).

Firstly, there is one-quick trick we did with `next export` functionality, that saved us some further complexity in our implementation. Set the `trailingSlash` property in the Next configuration to true.
https://nextjs.org/docs/api-reference/next.config.js/trailing-slash

This changes the exported output structure of the static HTML slightly.

- `segments.html` becomes `segments/index.html`
- `[pid].html` becomes `[pid]/index.html`.

This happens to be more congruent with how the Go file server handles particular request paths.
When a path happens to refer to a directory, like `/segments` is in Flipt, Go will render an HTML snippet containing a list of links to the directories contents.
This is what led to the screenshot earlier. Containing the following files:

- [pid].html
- new.html

When that directory happens to contain an `index.html`, it serves that instead.

This gets us a lot of the way there, however, the final challenge is dynamic routes in Next. For example, when requesting the path `/flags/my_flag_key`, the standard Go file server will attempt to open the following two files:

- /flags/my_flag_key
- /flags/my_flag_key/index.html

Neither of these files exists, as the `my_flag_key` refers to a flag key stored within the Flipt backend system. With next.js, what we really want to serve is `/flags/[pid]/index.html`. This page knows how to handle extracting the key from the path and requesting it from the backend.

We need a way to map all dynamically routed paths to their respective dynamic files “on-disk”.
I say “on-disk” in inverted quotes because remember, we embed these files into our Go binary earlier. The assets are not really on-disk. They are exposed via a filesystem abstraction (an interface) in Go.

Go’s [embed.FS](https://pkg.go.dev/embed#FS) is a structure that implements the [fs.FS](https://pkg.go.dev/io/fs#FS) interface.
This interface requires a single `Open(name string) (fs.File, error)` method.

Given that we know and can explore the contents of this directory on initialization of Flipt; we do so to derive the expected dynamic paths. Then we implemented a decorator of the `fs.FS` interface, which decides whether an incoming file path needs to be re-directed and open one of the dynamic paths.

```go
type nextFS struct {
 // we will slot our embed.FS instance in here
 fs.FS

 // prefix tree of potential paths
 tree *node
}

func newNextFS(embedded fs.FS) fs.FS {
 var root *node
 // walk provided filesystem "embedded" to derive
 // potential dynamic paths and build a tree.

 return &nextFS{
 FS: embedded,
 tree: root,
 }
}

func (*nextFS) Open(name string) (fs.FS, error) {
 var adjustedPath string

 // walk tree in order to replace any dynamic path
 // parametes with the name of the dynamic paths on disk
 // building and adjusted path to the desired file.

 return n.FS.Open(adjustedPath)
}
```

Our first pass implementation of this can be found [here](https://github.com/flipt-io/flipt/blob/88ce30f342075fa216c1b64b76a05b86ae0009cb/internal/cmd/ui.go#L59).
The TL;DR is we built a crude prefix tree based on the paths in the embedded filesystem, with the dynamic files annotated within the tree.

When a requested file matches a dynamic path in the prefix tree, we re-write the path name before handing it on to the embedded `fs.FS` implementation.

Now `/flags/my_flag` serves the contents of `/flags/[pid]`.

#### Embracing Hash Routing

Finally, hash-based routing. This is what our current UI does with Vue.js.
Re-instating this routing capability as the primary approach to client-side routing brings us back in line with how Flipt works today.
It fully encapsulates Flipt as a single-page application, meaning, we can easily embed it into a simple, vanilla file server implementation in Go.
Furthermore, this approach is backward compatible with existing Flipt URLs (without additional changes).

As this potential strategy dawned on us, we also decided to review our decision to use Next.js.
We still feel that adopting React is a worthwhile bet for the future of Flipt, however, we don’t have to use Next.js to do so. In fact, we suspect vanilla React will be more broadly understood than Next.js right now.
Next.js brings plenty of extra opinions, which in hindsight are not necessarily congruent with where Flipt is going.

Finally, React Router has an out-of-the-box implementation of [hash routing](https://reactrouter.com/en/main/routers/create-hash-router) right there for the taking.

#### The Decision

After exploring all of the above, we settled on approach (3), vanilla React and hash-based routing.

_Sorry, perhaps next time Next.js. You’re very cool and shiny. But React is all we require right now._

The product of this choice is no change to the Go side of the equation.
The frontend application involves a simple npm-driven build process, which outputs a “dist” folder containing all the necessary assets.
This folder contains a single HTML file (`index.html`), along with several Javascript and CSS files.
We embed the folder exactly as we had before, using the Go standard library to both embed and serve it.

## Final Words

We hope that moving from Vue to React will attract more contributions from a wider pool of developers.
Flipt is an open-source solution, and we want to build an active community around it.

The new UI will be part of the `v1.17.0` release of Flipt.
We hope you will take a moment to give it a test drive.
Hot on this release's heels will be login functionality in the UI.

We intend to publish another blog post around `v1.18.0` talking more about the journey to this new UI, the new authentication related features and where we’re going next.

Embedding Our New React UI in Go

<BlogImage
 src="/grafana/announcing-dashboards.png"
 alt="Grafana Dashboards"
 width={2400}
 height={1350}
>
 Photo by [Jay R](https://unsplash.com/@justjthings) on Unsplash
</BlogImage>

We recently started developing a collection of Grafana Dashboards to provide visibility
into both the health of your Flipt deployment and the state of the evaluation system.

In [Flipt v1.16.0](https://github.com/flipt-io/flipt/releases/tag/v1.16.0) we have made some alterations to the metrics that we expose. This includes some measurement naming changes, along with the addition of some new ones, specifically around the evaluation engine.

These new dashboards depend on the names and new metrics added in [v1.16.0](https://github.com/flipt-io/flipt/releases/tag/v1.16.0). Upgrading to this version is a requirement before attempting to use these new dashboards.
Metrics are exposed as Prometheus-style metrics. Our dashboards have been developed against a target Prometheus instance. See [configuring metrics](https://www.flipt.io/docs/configuration#metrics) for documentation on configuring metrics in Flipt.

Currently, there are two separate dashboards—one for system overview and the other for flag evaluation state.

Flipt System is the name of the system dashboard. It includes operational details of Flipt, including RPC request throughput, response codes, and latency, as well as details relating to interactions with the backing SQL database.

<BlogImage
 src="/grafana/flipt-system-dash.png"
 alt="Grafana Flipt System Dashboard"
 width={3336}
 height={1416}
 caption="System Dashboard"
/>

Flipt Flag Evaluations dashboard includes details specific to each flag. Selecting a specific flag will present historical details on the resulting matches, match reasons, segments, and values produced.

<BlogImage
 src="/grafana/flipt-flag-dash.png"
 alt="Grafana Flipt Flag Evaluation Dashboard"
 width={3354}
 height={1926}
 caption="Flag Evaluation Dashboard"
/>

The system dashboard is more focused on operators trying to understand the health of a Flipt deployment, whereas the evaluations dashboard is focused on Flipt users who want to understand what Flipt is returning and why. It is critical as an end user of a feature flag system to understand how your flags are being evaluated in a production context so that you can answer questions like "Is my flag being referenced?", "Is it safe to delete this flag yet?" or "How often is variant A returned compared with variant B?".

This is our first pass at building reusable dashboards for Flipt. Our dashboards are open-source and we invite anyone who would like to contribute and improve them. We intend to keep them maintained and preserve a level of compatibility going forward with respect to measurement naming.

Head to our [Grafana dashboards repository](https://github.com/flipt-io/grafana-dashboards) to try them out or contribute.

As always, if you have any questions or feedback, please reach out to us on [Discord](https://www.flipt.io/discord) or [Twitter](https://twitter.com/flipt_io).

Cheers and happy graphing 📈!

Grafana Dashboards

<BlogImage
 src="/auth-v1/auth.png"
 alt="Flipt Authentication"
 width={2400}
 height={1350}
>
 Photo by [FLY:D](https://unsplash.com/@flyd2069) on Unsplash
</BlogImage>

Last week we cut the [v1.15.0 release](https://github.com/flipt-io/flipt/releases/tag/v1.15.0) of Flipt. The primary feature of this release was authentication.
As of v1.15.0, Flipt has support for static client token-based authentication.
This is our first step to bringing authentication and authorization features to Flipt.

Currently, the way to obtain a client token is to enable the “token” authentication method in Flipt’s configuration.
Once enabled, a section of the API ([/auth/v1/method/token](/docs/reference/authentication/create-token)) is mounted and available to create new access tokens.

Note that this endpoint is also protected when authentication is set to required, meaning prior authentication is needed to create tokens.

```yaml
authentication:
 methods:
 token:
 enabled: true
```

Check out our [token authentication configuration](/docs/configuration#token) documentation for more specific details.

If no tokens exist in the backing store then one will be created the first time you enable the token authentication method.
This way, an initial token can be bootstrapped so that you don’t lock yourself out of Flipt (authentication can also be set to not required in this situation).
The bootstrapped token will be output in the logs:

```
…
2022-11-22T12:02:10Z INFO access token created {"server": "grpc", "client_token": "nCq9QO-FeEAS91LV1LFD2qOpUASXl8eljlXokeorbyY="}
…
```

By default Flipt remains open, however, with a slight adjustment to your instance configuration, Flipt’s API can be secured.

```yaml
authentication:
 required: true
```

Attempts to perform API operations will require a client token to be presented via the Authorization header:

```sh
curl localhost:8080/api/v1/flags \
 -H 'Authorization: Bearer nCq9QO-FeEAS91LV1LFD2qOpUASXl8eljlXokeorbyY=' \
 -H 'Content-Type: application/json'
```

Putting this altogether we get a secured API with the ability for prior authenticated clients to create additional credentials:

```yaml
authentication:
 required: true
 methods:
 token:
 enabled: true
```

Head over to the new [Authentication](/docs/authentication) section of our documentation to learn more about interacting with Flipt when authentication is required.

As mentioned, this is our first step to securing Flipt. Once authentication is enabled, the UI becomes unusable since we have not yet implemented the features required to authenticate browser sessions.

In the next release, we expect to add Google as the first OAuth login provider, followed by other authentication providers in subsequent releases.

Equally, we’re working on automated processes for managing expired client tokens.
With v1.15.0 it is currently on the operator to use Flipt’s APIs to delete outdated tokens, however, we plan for this mechanism to be built-in, automated, and configurable in the future.

On top of all this, we’re actively designing authorization features for Flipt, so that you can decide who can do what when interacting with the API and UI.

Join us in our [Discord](https://flipt.io/discord) to chat about your needs and to help influence the future of authentication and authorization with Flipt.

Authenticating Flipt

<BlogImage
 src="/openfeature-go/openfeature.png"
 alt="Flipt + OpenFeature"
 width={2400}
 height={1350}
/>

## What is OpenFeature?

[OpenFeature](https://openfeature.dev/) is a [CNCF Sandbox project](https://www.cncf.io/projects/openfeature/) that is developing an open standard for feature flag management.

> OpenFeature provides a unified API and SDK, and a developer-first, cloud-native implementation, with extensibility for open source and commercial offerings.

In short, OpenFeature provides a specification and implementation of a unified API to query and evaluate feature flags which abstract away the specific details of the backend responsible for storing and managing the flags themselves.

This allows the developers who are adding feature flags in their applications to use the OpenFeature SDK in their code and then register their feature flag management solution of choice as the 'provider', abstracting it away. The benefits of this are twofold:

1. It guards against 'vendor lock-in' which would require a large code refactor if a team were to decide to switch from one feature flag solution to another down the road.
1. It allows for common functionality to be shared and maintained by the community, which reduces the amount of duplication required as well as generally increases the quality and velocity of development. More on this later.

## SDKs and Providers

Before we get into more details of how OpenFeature works, it's important to define the key terminology and develop a shared model.

As mentioned above, OpenFeature has defined a [specification](https://docs.openfeature.dev/docs/specification/) that serves as a guide for how to think about OpenFeature from an end user perspective as well as how to implement a vendor specific library that OpenFeature can integrate with.

The specification defines '[providers](https://docs.openfeature.dev/docs/reference/concepts/provider)' as the adaptive layer that translates to and from feature flag solutions, such as Flipt and other open source and commercial solutions. It's up to the community or the feature flag vendors/projects themselves to build these providers that conform to the [OpenFeature Provider specification](https://docs.openfeature.dev/docs/specification/sections/providers).

<BlogImage
 src="/openfeature-go/openfeature-provider.png"
 alt="OpenFeature Provider"
 width={1654}
 height={340}
/>

An OpenFeature SDK is available for many popular programming languages such as **Go, JavaScript, .NET and Java**. The OpenFeature team just recently announced that these SDKs [have all reached a 1.0 version](https://docs.openfeature.dev/blog/hardening-and-1-0-sdks/), representing a certain maturity and resistance to breaking changes. They've also announced that more SDKs will be made available in the future for languages such as **PHP, Python, and Ruby**.

## Evaluation API

The [Evaluation API](https://docs.openfeature.dev/docs/specification/sections/flag-evaluation/) is the primary interface to access and interact with feature flags in the OpenFeature ecosystem. The OpenFeature Evaluation API allows you to query feature flags given a `flagKey`, default value, as well as an optional [evaluation context](https://docs.openfeature.dev/docs/specification/sections/evaluation-context). The evaluation context allows for the feature flag solution (provider) to make decisions based on configured rules, for example end-user targeting or percentage-based rollouts.

This maps nicely to how we think about [evaluation at Flipt](/docs/concepts#evaluation), where the integrator can provide as much or as little information as they need to make a decision for the purpose of flag evaluation.

## Announcing The Flipt OpenFeature Provider for Go

Today we are happy to announce that we've **open sourced** the initial version of the [OpenFeature Go Provider for Flipt](https://github.com/flipt-io/flipt-openfeature-provider-go)! It supports both HTTP(s) and GRPC transports to connect to your Flipt instance and is highly configurable allowing you to bring your own HTTP or GRPC clients.

To ensure that we conform to the OpenFeature Provider specification, we even decided to pull in OpenFeature's own [integration test suite](https://github.com/open-feature/test-harness/tree/5153eac71dc47413da4326bdb49a94e573b99578) into the repository. This move actually helped us find several bugs in our implementation, while exercising it as an end-user would.

To see our provider in action, checkout the [example in our main repository](https://github.com/flipt-io/flipt/tree/main/examples/openfeature) which shows how to integrate OpenFeature + our provider into an example REST API project. Stay tuned for updated documentation, more examples, and future providers written in other languages. Also, if you are itching to write your own provider for Flipt in your language of choice, feel free to reach out in our [Discord](https://discord.com/invite/kRhEqG2TEZ), we'd love to help!

## Hooks and the Power of a Common API

Before wrapping up, I'd like to quickly go over one of what we think is the most powerful features of OpenFeature, the [Hooks API](https://docs.openfeature.dev/docs/specification/sections/hooks). Hooks allow you to use a common API for performing actions at different stages of the evaluation lifecycle. By implementing Hooks that use the OpenFeature data model, the community can take advantage of shared implementations, preventing the need for duplicating effort for each provider. Some of the use cases for hooks include things like adding metrics and telemetry, request retries and circuit breaking, performing validation on data, and performing client side caching.

The OpenFeature team has released their own [OpenTelemetry Hook for Go](https://github.com/open-feature/go-sdk-contrib/tree/main/hooks/open-telemetry), allowing any integrator of the Go SDK to get [OpenTelemetry](https://opentelemetry.io/) traces with the evaluated feature flag data for free. In our [example application](https://github.com/flipt-io/flipt/tree/main/examples/openfeature) for integrating the Flipt OpenFeature provider we wired up the OpenTelemetry hook with a few lines of code, resulting in some cool visualizations of our feature flag data:

<BlogImage
 src="/openfeature-go/jaeger-openfeature-otel-trace.jpg"
 alt="OpenFeature OpenTelemetry Trace"
 width={1582}
 height={399}
/>

<BlogImage
 src="/openfeature-go/jaeger-openfeature-otel.jpg"
 alt="OpenFeature OpenTelemetry Trace"
 width={1305}
 height={390}
/>

We are looking forward to seeing what the community comes up with by leveraging hooks to provide common functionality for all implementers of the OpenFeature SDKs!

## Committed to Helping Organizations Unlock the Power of Feature Flags

We love feature flags here at Flipt and think that we have just started to scratch the surface of what can be accomplished with their use in the software development lifecycle. With the introduction of the OpenFeature project, we hope that teams can begin to realize the full potential of feature flags in a way that is easy to implement and use. We're also very excited to see how the OpenFeature project evolves in regards to the CloudNative space, something we're also particularly interested in here at Flipt.

If you have any feedback on our provider, want us to prioritize specific language support, or just to learn more about how Flipt can help your organization get started with feature flags, please reach out either by joining our [Discord](https://discord.com/invite/kRhEqG2TEZ) or send us an email at [hello@flipt.io](mailto://hello@flipt.io).

Announcing the Flipt OpenFeature Provider for Go

<BlogImage
 src="/hi-george/geo.png"
 alt="Hello, George!"
 width={2400}
 height={1350}
>
 
 Photo by [Lampos Aritonang](https://unsplash.com/@lamposaritonang) on
 Unsplash
 
</BlogImage>

I'm excited to announce that [George MacRorie](https://www.linkedin.com/in/geokeaton/) has joined Flipt as our first Founding Software Engineer! George is a seasoned engineer with over 10 years of experience building and scaling software products. George and I first met at CodeShip, where we worked together for 3 years. George is based in the UK 🇬🇧 and will be key to developing and scaling Flipt as well as helping to build out our engineering team and remote first culture. George is an amazing engineer and a great person and friend, and I'm excited to have him on the team!

I asked George to write a bit about himself and his background, and here's what he had to say:

> My name is George. I’ve been bashing the internet pipes in exchange for money for over a decade. I cut my teeth as a junior engineer in the world of Java (and a lot of XML) in 2012. Before abandoning it all for my new love, the Go programming language, in 2014. Somewhere along the way I discovered the root of all my frustrations didn’t come from within, it was with my tools. Yeah, that's right, the tools were the problem. Thus, a developer tooling engineer was born.
>
> For me, It all started with CI/CD. I don’t think it is a coincidence that I embraced baldness around that time. Hair pulling was a known side effect of the available solutions back then. I joined CodeShip to build the alternative of our dreams. The CI/CD SaaS market was heating up at the time and CircleCI was already out in front, a position they’ve held well. In the end, our little ship didn’t quite cut the mustard. We didn’t get to fulfil our dreams of a CI/CD revolution.
>
> Yet, the best part about my time there was the people. We met many times in person (we were remote) all over Europe and North America. We shared ideas, laughs, and one hair-raising e-bike ride around the city of Lisbon. An experience which went down like Marmite. It was during this time that I met Mark. It was also during this time that Flipt came to be.
>
> When it all came to an end, Mark went off to continue the good developer tooling fight at GitHub. I and a few other ex-shippers figured we had solved CI/CD, so we should do databases next (InfluxDB). At Influx, I soon fell into my old habits of trying to solve developer tooling problems. They let me attempt to lead the Deployments team. A team which tackles many things’ platform engineering, despite the name.
>
> Feature flags at Influx are critical to how engineers develop in production. I wasn’t personally involved in the implementation of feature flags for Influx Cloud; it was another member of the old CodeShip crew who unlocked this capability. Unquestionably, they delivered on enabling the team to safely ship changes.
>
> Over time, our flagging libraries and frameworks accrued a little kludge. Some flags became entrenched and forgotten in code. Complexities in targeting logic grew. Local development and remote environments diverged in flag state configuration. Developers became suspicious if their flags were working as expected. One uncompleted large-scale refactor left the system fractured.
>
> Along the way, I got to see how the frustration played out, and I experienced it first-hand. I can’t say that has left me with all the answers. But, I would like to think it has left me with empathy. Something I intend to bring to Flipt.
>
> When Mark reached out to me and said, “want to come and build the future of feature flags?” I felt very ready for the challenge.

Welcome to the team, George! 🎉 🎉 🎉

Meet George MacRorie

<BlogImage
 src="/all-in/hello-world.png"
 alt="Hello World"
 width={1792}
 height={1024}
>
 
 Art by [Alejandro Ortiz](https://unsplash.com/@alejandroortiz) on Unsplash
 
</BlogImage>

## The Origins of Flipt

When I started [Flipt](https://github.com/flipt-io/flipt) almost 4 years ago, I started it to scratch my own itch. Throughout the previous 10 years of my career as a software engineer, I noticed that every company I'd worked at that used feature flags seemed to run into similar issues.

From the outside, the idea of feature flags seems simple enough. At their most basic, they are boolean values used to make decisions in your code that can change 'remotely' at runtime. Because of this perceived simplicity, most engineering organizations that I'd been a part of had decided to roll their own solution. This usually took the form of either an internal library developed in-house or an open-source library that was integrated into the main application and added to haphazardly over the years.

This approach works fine when feature flags are used sparingly and the team and application architecture are small enough. Once the organization and architecture grow, however, the simple, in-house solutions start to show their cracks. In most cases, the solution that works when there is a monolithic application no longer scales with the move to multiple services and programming languages. As the team begins to build out more complex features that require many different moving parts and dependencies, it becomes necessary for access to feature flags to be shared between these different services and teams.

At the time, I was aware of existing solutions that aimed to solve this same problem of distributed feature flags, however, they were all mostly SaaS-based. To me, this was not an ideal solution as I believed that most teams would want to avoid the lock-in, cost, security, and latency concerns associated with these solutions. Back in 2018, [gRPC](https://grpc.io/) was still a relatively new technology but it seemed like a promising solution for creating a reliable remote access layer that could be used to solve the above-mentioned problem of distributed access to feature flags in a multitude of programming languages.

Thus, Flipt was born, a stand-alone, self-hosted, feature flag service that allows developers to make use of feature flags in any programming language or framework while being focused on low latency and data residency from the start.

## Going All In

Over these past several years, myself and an amazing group of [contributors](https://github.com/flipt-io/flipt/graphs/contributors) have continued to make improvements to Flipt, adding features and support for new technologies and use cases. Over this same time, I've also talked with engineers, managers, and engineering leaders that use Flipt in production at their companies, helping provide real value to their end-users.

While this has been incredibly motivating and gratifying, it's also presented a bit of a challenge to keep up with all the new things I want to support and features to add while only being able to work on Flipt in my spare time. Thankfully, I've recently been given the opportunity to be able to work on Flipt full-time and also build out a small team to help make shipping software easier and less error-prone for developers everywhere.

The software industry has also come a long way over these past several years. More and more companies have fully embraced the CloudNative software development model, which has allowed us to build systems that are more resilient and performant than ever before. There's also been an explosion of new open source projects for developers to use as building blocks for their applications, which has made it much easier to get started with many common tasks such as testing, logging and monitoring. All of this has helped to make software development a more enjoyable, productive experience. However, there's still one major area where things haven't changed as much: shipping code safely. Despite all the advances we've seen in other areas, it remains just as difficult for developers to push their code changes into production while being assured that their changes will not cause errors.

This is the area where we want to focus our efforts with Flipt. We want to make it as easy and stress-free for developers to ship software as confidently as possible, regardless of their development environment, language, or platform.

We also want to continue to stay true to the project's core principles so that Flipt:

- Remains open-source and self-service.
- Stays flexible enough to support various modes of experimentation.
- Is seamless to configure and secure in modern cloud environments.
- Fits into your existing stack.
- Continues to be fast and consistent.

## Looking Forward

We're working on some really exciting features right now that we'll be releasing over the next few months, so keep an eye out for those!

I'm incredibly excited to take on this new challenge, embrace this opportunity, and build a team of like-minded individuals who are passionate about shipping code safely and securely.

**Takeaway**: We want to build the future of modern software deployment mechanisms, and we'd love to have you along for the ride. Flipt is not going anywhere and will remain open-source and community-driven. We are committed to making Flipt even better and would love your help! Please join us on our [GitHub](https://github.com/flipt-io/flipt) and in our [Discord](https://discord.com/invite/kRhEqG2TEZ) to learn more and help build the future of Flipt.

Thank you for your support, and we can't wait to see what you build with Flipt!