Revise Flux project description

[scottrigby]

Current proposed project description

Flux is continuous and progressive delivery from Git to Kubernetes.

There's a lot more we could write. The goal of this discussion is to update our current short description. Ideally one sentence, or possibly two short ones.

Please reply on #620 (comment).

Context

I first started thinking about this as part of the CNCF due diligence for review of Flux Incubation status. Due diligence asks about scope of the project, and I realized I couldn't find a documented scope for Flux. Our description was the closest I could find, and it seemed that it may not fully capture the current vision of Flux.

Original issue description

The current description of Flux feels like it needs an update. We should broaden it to include what it can do already, and ideally – in a more aspirational way – reflect the current vision of Flux as a CNCF project.

Specifically, Flux GitOps doesn't always have to keep a Kubernetes cluster in sync, or update only configuration. Flux is built on Kubernetes because it's currently the best choice for reconciliation. But Flux doesn't restrict what the operations are that should be reconciled, or where they should be located (whether workloads in the same or another k8s cluster, one or more full clusters via CAPI, or something apart from k8s altogether). For example, the community could build and maintain a Flux operator that keeps HTML in an s3 bucket in sync from a static site generator source code in git (or the other way around). Or a Terraform controller (as Stefan mentioned, this a widely requested feature).

• Current description (on fluxcd.io and the first line in the docs):

  Flux is a tool for keeping Kubernetes clusters in sync with sources of configuration (like Git repositories), and automating updates to configuration when there is new code to deploy.

• Possible broader description:

  Flux is a tool that watches the desired state of your operations defined in source code (like Git repositories, cloud storage, or OCI images), and uses Kubernetes to automatically reconcile your operations – wherever they live – when source code definitions change.

I'm also not sure if we should describe Flux as "a tool" or something like "an ecosystem of tools". The Flux project currently contains a "toolkit" for building controllers described above, a set of controllers for base functionality and some project interoperability (straight k8s manifests, other kustomize features, and helm), and other related tooling (soon to include Flagger).

I sketched up the "possible broader description" above as a conversation starter, brought this up at today's Flux dev meeting and am looking for other maintainer and community input. If people feel there's a need to update the description, I will follow this up with PRs to the website and docs.

[scottrigby]

@hiddeco pointed me to this branch from @squaremo as probably the newest and closest description out there now: https://github.com/squaremo/toc/blob/flux-annual-review/reviews/2020-flux-annual.md#preface

The Flux project aims to provide a complete Continuous Delivery platform on top of Kubernetes, supporting all the common practices and tooling in the field, e.g. Helm, kustomize, metrics with Prometheus and so on.

Flux was the first project to clearly define GitOps practices, which can be summarised as:

1. Describing your system declaratively;
2. Keeping configuration under source control; and
3. Using software agents to reconcile along with alerts, etc., to and ensure correctness.

[scottrigby]

Discussed with @cdavisafc on Wednesday, who raised some more good points in the language connotations. Here is an updated proposal:

Flux is a tool that watches both the actual state of your operations and the desired state declared in versioned source control (like Git repositories, cloud storage buckets or Helm repos), and automatically reconciles your delivery and operations – wherever they live – when the actual and desired states diverge.

There's a lot more we could write. The goal of this discussion is to update our current short description. Ideally one sentence, or possibly two short ones.

[scottrigby]

From today's Flux dev meeting. See notes:

Had good discussion on this. The proposed description fits with the Flux scope as defined in the Flux Due Diligence doc. However @squaremo noted that “automatically reconciles your operations – wherever they live” part may be too aspirational for what Flux can currently do (image update automation can reconcile writing back to git itself, but all other current Flux controllers only reconcile things in k8s - this is only 2 places so far, not "wherever"). But all agree the current description is not very inspiring. So hopefully we can find a middle path

[dholbach]

Was this approved some time? Shall we review in one of the next Flux team meetings?

[dholbach]

@scottrigby WDYT

[dholbach]

Discussion on 2021-09-01 (meeting recording)

• Last proposed statement in discussion is twice as long as the original.
• “Flux makes Git your single source of truth for your Kubernetes system” (not sure if that is what was actually proposed).
• Does this capture everything we do with GOTK and Flagger?
• Should we talk about Progressive Delivery and reconciliation?
• “Flux is a Continuous Delivery solution for Kubernetes.” is the bare-bones approach. But what’s specific about Flux?
• Should mention ‘delivery’ and ‘deployments’.
• New proposal “Flux is Continuous Delivery from Git to Kubernetes”

Comments?

[squaremo]

• “Flux is Continuous Delivery from Git to Kubernetes”

This works as a slogan; I think it can expand a little (as in, by a few words) and still be a concise description. Having said that, I don't know what I would add that makes it more precise without diluting it.

[squaremo]

It would be nice to include Flagger in the description. Though it has a little less punch:

Flux is continuous and progressive delivery from Git to Kubernetes.

EDIT: oh but the SEOs ...

[scottrigby]

I love this @squaremo. IMO this is much better than the earlier brainstorm. Short, memorable, accurate, delivers the message. Adding "and progressive" sounds good to me too! 💯 I updated the discussion description above ☝️

[scottrigby]

One more thought…

I ❤️ these parts of what we have and what's proposed above (IMO, in order of importance):

1. "from Git to Kubernetes"
2. "continuous and progressive delivery"
3. "open and extensible" from this website metadata description

Can we have all three in one sentence? Or is this too much of a mouthful:

- description = "Open and extensible continuous delivery solution for Kubernetes."
+ description = "Open and extensible continuous and progressive delivery solution from Git to Kubernetes."

I do like the simplicity of "Continuous delivery from Git to Kubernetes." What do you all think are the most important thing(s) to highlight first in the initial description sentence?

[scottrigby]

We addressed this and more. See #620 (comment)

[scottrigby]

Update

We discussed this pretty thoroughly during today's flux meeting. Flux maintainers feel a style guide would help define how and in which contexts different Flux descriptions may be used. I have an action item to sketch that up.

Here's the sketch in a HackMD doc for feedback as part of this ongoing discussion: Flux style guide (draft), which anyone can view, logged in users can comment, and owners can edit. Feedback is welcome from the Flux community, contributors, and maintainers. The community maintainers should work on this, but I believe the spirit of our governance makes the final decision fall under the scope of the Flux oversight committee, so I have invited both groups as owners.

Next steps

When we feel the HackMD draft is in a good direction in general, I'll open a PR in the fluxcd/community repo and we can continue the normal review process there. Once that style guide PR is reviewed and merged, we can then update any descriptions needed on the website, in docs, etc to follow the new style guide.

[dholbach]

Thanks a lot for typing this up. This looks great to me already - I left just a small comment.

[scottrigby]

OK updated to address comment, and added section about specifying versions. Opened as a PR fluxcd/community#122