Dogfooding and documenting GitOps best practice

[noahtalerman]

Goal

User story
As a Fleet user looking to use Fleet's best practice GitOps,
I want the Fleet team to dogfood and document the GitOps best practice
so that I can use best practice GitOps in my production Fleet.

Context

Fleet's best practice GitOps was released as beta in Fleet 4.45.

After completing this dogfooding and documenting story, the plan is to bring the feature out of beta and announce it publically.

Changes

Product

• [x] Dogfood:
  • Add a dogfood-gitops.yml workflow
  • These workflows will need to be updated/removed:
    • https://github.com/fleetdm/fleet/actions/workflows/example-workflow.yaml
    • https://github.com/fleetdm/fleet/actions/workflows/fleetctl-workstations.yml
    • https://github.com/fleetdm/fleet/actions/workflows/fleetctl-workstations-canary.yml
  • Add a new it-and-security/ top level folder.
  • Update YAML files to reflect dogfood:
    • Add profiles. They currently live in mdm_profiles/. All these go to workstations and workstations (canary)
    • Add scripts. We don’t have scripts in a folder so we can download scripts from Fleet and get them into the lib/
    • Add queries, policies, settings. We don't have these files so we can export them from Fleet
• [x] Outdated documentation changes:
  • New "GitOps" page replace the "Configuration files" page. This page includes a reference of all top-level keys and their options.
  • On the "GitOps" page, add a link to the legacy YAML format used w/ fleetctl apply. Clarify that fleetctl apply is used for imports and supported for backwards compatibility GitOps.
  • Doc PR is here: https://github.com/fleetdm/fleet/pull/19740

Engineering

• [ ] Database schema migrations: TODO
• [ ] Load testing: TODO

ℹ️  Please read this issue carefully and understand it. Pay special attention to UI wireframes, especially "dev notes".

QA

Risk assessment

• Requires load testing: TODO
• Risk level: Low / High TODO
• Risk description: TODO

Manual testing steps

1. Step 1
2. Step 2
3. Step 3

Testing notes

Confirmation

1. [ ] Engineer (@____): Added comment to user story confirming successful completion of QA.
2. [ ] QA (@____): Added comment to user story confirming successful completion of QA.

[getvictor]

@noahtalerman Do you want me to update/refactor the configuration page, or will the product team do it?

[noahtalerman]

@getvictor the product team can take the documentation.

Please feel free to mark this as ready for release w/o the docs.

We'll catch this TODO as part of the "confirm and celebrate ritual."

[noahtalerman]

Open docs PR is here: https://github.com/fleetdm/fleet/pull/17890

[noahtalerman]

C&C: Docs are still TODO

[noahtalerman]

Hey @marko-lisica just a reminder that docs are still TODO. Rachael and I are going over open stories during confirm and celebrate ritual.

[lukeheath]

@noahtalerman @marko-lisica It's crucial to merge feature documentation promptly when the feature is released. This story was completed two months ago, and until now, there have been no docs online describing best practices. Was there anything blocking this that we can avoid in the future? Maybe a new weekly ritual to review all outstanding documentation PRs would help?

[noahtalerman]

Decided that @spokanemac will take on docs: https://fleetdm.slack.com/archives/C071NNMSP2R/p1715890274157719

cc @marko-lisica @lukeheath

[spokanemac]

Decided that @spokanemac will take on docs: https://fleetdm.slack.com/archives/C071NNMSP2R/p1715890274157719

For this particular case, and not all docs.

[lukeheath]

For this particular case, and not all docs.

@spokanemac Yes! This is a one-off because you've familiarized yourself with it, albeit painfully.

@noahtalerman, Heads up that JD is at capacity right now, so we won't be able to take further doc updates. The best place to offload docs is to Engineers during the planning process, although I recognize this situation is unique.

[spokanemac]

@noahtalerman I corrected some grammar and added a section to reference Organization settings. This is ready to pull out of draft and publish.

I will note that this is not what I would want for documentation of this feature if I'm a MacAdmin unfamiliar with Fleet and/or GitOps. I will do my best to bridge the gap in my dogfooding gitops article.

[noahtalerman]

Thanks @spokanemac! I'm going to pick up this documentation task (assigned) to get it unstuck and merged.

[noahtalerman]

Docs are merged!

Here's the new GitOps reference page: https://fleetdm.com/docs/using-fleet/gitops

cc @spokanemac @lukeheath @zayhanlon @dherder

[fleet-release]

GitOps best practice, In Fleet's cloud city it blooms, Guide for your journey.