Fleet persona quickstart #254

kakabisht · 2025-05-20T14:39:15Z

No description provided.

…t/fleet-docs into feat-persona-quickstart

0xavi0

I'm normally not too picky in code reviews (sorry), but this one is about the quickstart and that's normally the entry point of anybody that tries to use Fleet (or any other software) for the first time, so IMHO it should be one the best pages in the docs.

I find the example (or the guidance) a bit confusing (specially because of the suggestion to include the gitrepo.yaml in the git repository that you're later going to deploy via a GitRepo resource).
I would not suggest new users to have any GitRepo yaml in the same git repository as it might deploy nested GitRepos or more complex behaviours that are not intended to be used by new users.

We can maybe discuss with the team what should be a good example that shows how Fleet works for newbies in the quickstart.

For example, I don't know if it should be better to start adding the targets just in the GitRepo itself.

Anyway, I found a few nitpicks you can fix meanwhile.

docs/quickstart.md

0xavi0 · 2025-05-23T08:55:27Z

docs/persona.md

+| Persona | Responsibilities | Key Benefits |
+| --- | ----- | ----- |
+| Platform Engineers | Set up and manage Fleet installation across clusters <br/> Define and enforce multi-cluster application and policy deployments <br/> Manage GitRepo and fleet.yaml configurations <br/> Perform cluster-wide updates and rollbacks | Centralized control across clusters <br/> Improved standardization and compliance |
+| Application Developers | Structure application Helm charts or manifests in Git <br/> Define deployment targets and environments in `fleet.yaml` <br/> Monitor deployment status via UI or CLI | GitOps-based workflows <br/> Faster, automated, and consistent deployments across environments |
+| Security Administrators | Define and enforce security policies as code- <br/> Deploy security tools and configurations <br/> Audit and manage security posture across clusters | Reduced risk and centralized compliance management <br/> Automated, consistent security configuration |


What do you think about adding a dot at the end of each sentence in the items that are in the same column?

I see we have fleet.yaml and fleet.yaml in the document. I guess we should use the same form, but I'm not sure which one is better (looks like fleet.yaml). We maybe should define a style guide.

Could we use bullet points to make points easier to distinguish from each other?

docs/quickstart.md

0xavi0 · 2025-05-23T09:00:14Z

docs/quickstart.md

+Fleet follows a GitOps mode, allowing you to track who made changes and when using your Git history. When you push changes to your Git repository:
+
+1. Fleet detects the change and evaluates `fleet.yaml` to determine which clusters to target.  
+1. It deploys the updated resources automatically.


Suggested change

1. It deploys the updated resources automatically.

2. It deploys the updated resources automatically.

Numbering shouldn't matter much here, as indexes of numbered lists are computed when rendering Markdown into HTML.

0xavi0 · 2025-05-23T09:19:27Z

docs/quickstart.md

+Structure your repository like this:
+
+![Screenshot displaying the file directory](../static/img/file-structure-sample-ss.png)


I would not suggest to have the gitrepo.yaml in the repository being deployed.

The reason why is because the GitRepo can be considered as just another resource by Fleet and can add confusion.

For example... lets say you have a git repository with some YAML fields and that one of them is a GitRepo.

Fleet will deploy that GitRepo, which means it will create another GitRepo (you are nesting GitRepos).
You might want to do that, but I don't think that's the case in this example.

I would take the GitRepo out of the git repository here to avoid confusions and unexpected behaviour.

+1

It was confusing to me as well the first time I deploy an application using Fleet
I think I would also add a warning about this bad approach

Co-authored-by: Xavi Garcia <[email protected]>

Copilot

Pull Request Overview

This PR introduces a quickstart update that incorporates persona documentation and updates several documentation pages to better guide users through Fleet deployments.

Adds a new "persona" sidebar entry in sidebars.js
Updates the quickstart guide with refined installation instructions, examples, and image references
Introduces a new docs/persona.md file documenting key personas and their roles

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

File	Description
sidebars.js	Added a new sidebar entry for the persona page
docs/quickstart.md	Updated installation steps, examples, and image references for clarity
docs/persona.md	New documentation file with a personas table

Copilot · 2025-05-23T10:27:18Z

docs/persona.md

+| --- | ----- | ----- |
+| Platform Engineers | Set up and manage Fleet installation across clusters <br/> Define and enforce multi-cluster application and policy deployments <br/> Manage GitRepo and fleet.yaml configurations <br/> Perform cluster-wide updates and rollbacks | Centralized control across clusters <br/> Improved standardization and compliance |
+| Application Developers | Structure application Helm charts or manifests in Git <br/> Define deployment targets and environments in `fleet.yaml` <br/> Monitor deployment status via UI or CLI | GitOps-based workflows <br/> Faster, automated, and consistent deployments across environments |
+| Security Administrators | Define and enforce security policies as code- <br/> Deploy security tools and configurations <br/> Audit and manage security posture across clusters | Reduced risk and centralized compliance management <br/> Automated, consistent security configuration |


Consider revising 'as code-' to 'as code:' or another appropriate phrasing to fix the punctuation typo.

Suggested change

| Security Administrators | Define and enforce security policies as code- Deploy security tools and configurations Audit and manage security posture across clusters | Reduced risk and centralized compliance management Automated, consistent security configuration |

| Security Administrators | Define and enforce security policies as code: Deploy security tools and configurations Audit and manage security posture across clusters | Reduced risk and centralized compliance management Automated, consistent security configuration |

Copilot · 2025-05-23T10:27:18Z

docs/quickstart.md


-Change `spec.repo` to your git repo of choice.  Kubernetes manifest files that should
-be deployed should be in `/manifests` in your repo.
+Specify the Git repositories containing your deployment manifests or Helm charts. For hello world, example you need:


[nitpick] Consider rephrasing 'For hello world, example you need:' to 'For example, for a hello world deployment, include:' for improved clarity.

weyfonk · 2025-05-26T07:51:37Z

docs/quickstart.md


-Change `spec.repo` to your git repo of choice.  Kubernetes manifest files that should
-be deployed should be in `/manifests` in your repo.
+Specify the Git repositories containing your deployment manifests or Helm charts. For hello world, example you need:


I think it would make more sense to use a singular here, to prevent confusion among users: a given GitRepo resources watches one git repository.

Suggested change

Specify the Git repositories containing your deployment manifests or Helm charts. For hello world, example you need:

Specify the Git repository containing your deployment manifests or Helm charts. For hello world, example you need:

weyfonk · 2025-05-26T07:55:20Z

docs/quickstart.md

+* deployment.yaml for defining workload
+* fleet.yaml for how should Fleet control the deployment
+* Gitrepo.yaml for where to find your git repo, which branch and sub-path to monitor.
+  * (optionally) You can also add credentials


Suggested change

* deployment.yaml for defining workload

* fleet.yaml for how should Fleet control the deployment

* Gitrepo.yaml for where to find your git repo, which branch and sub-path to monitor.

* (optionally) You can also add credentials

* deployment.yaml for defining your workload

* fleet.yaml providing configuration instructing Fleet on how to control the deployment

* Gitrepo.yaml referencing your git repo, which branch and sub-path to monitor.

* (optionally) You can also add credentials

weyfonk · 2025-05-26T07:57:22Z

docs/quickstart.md


+![Screenshot displaying the Rancher Desktop ](../static/img/rancher-gitrepos-ss.png)
+
+Or you can run the following command:


Two commands are listed here ;)

Suggested change

Or you can run the following command:

Or you can run the following commands:

weyfonk · 2025-05-26T07:57:40Z

docs/quickstart.md

-```
-NAME       READY   UP-TO-DATE   AVAILABLE   AGE
-frontend   3/3     3            3           116m
+## Automating Deployments and Scaling


Suggested change

## Automating Deployments and Scaling

## Automating Deployments and Scaling

weyfonk · 2025-05-26T07:59:17Z

docs/quickstart.md

+
+To target specific clusters, apply labels such as `env=qa` or `region=eu` to your clusters. Use the `clusterSelector` and `targetCustomizations` fields in your `fleet.yaml` file to define which clusters receive which configurations.
+
+![Diagram displaying flow of target specific clusters](../static/img/Flow-clusterSelector-targetCustomizations.png)


I like the idea of having a diagram here, but in my web browser at least, it reads pretty small compared to the rest of the page contents. We may need to increase the font size and/or change its style to make it comfortable to read to as many readers as possible.

weyfonk · 2025-05-26T08:00:36Z

docs/quickstart.md

+Fleet follows a GitOps mode, allowing you to track who made changes and when using your Git history. When you push changes to your Git repository:
+
+1. Fleet detects the change and evaluates `fleet.yaml` to determine which clusters to target.  
+1. It deploys the updated resources automatically.


Numbering shouldn't matter much here, as indexes of numbered lists are computed when rendering Markdown into HTML.

weyfonk · 2025-05-26T08:01:24Z

static/img/file-structure-sample-ss.png

This could perhaps be replaced with a text block, which would be easier to edit.

weyfonk · 2025-05-26T08:03:18Z

docs/persona.md

+| Persona | Responsibilities | Key Benefits |
+| --- | ----- | ----- |
+| Platform Engineers | Set up and manage Fleet installation across clusters <br/> Define and enforce multi-cluster application and policy deployments <br/> Manage GitRepo and fleet.yaml configurations <br/> Perform cluster-wide updates and rollbacks | Centralized control across clusters <br/> Improved standardization and compliance |
+| Application Developers | Structure application Helm charts or manifests in Git <br/> Define deployment targets and environments in `fleet.yaml` <br/> Monitor deployment status via UI or CLI | GitOps-based workflows <br/> Faster, automated, and consistent deployments across environments |
+| Security Administrators | Define and enforce security policies as code- <br/> Deploy security tools and configurations <br/> Audit and manage security posture across clusters | Reduced risk and centralized compliance management <br/> Automated, consistent security configuration |


Could we use bullet points to make points easier to distinguish from each other?

olblak · 2025-05-28T09:10:01Z

docs/quickstart.md


- Fleet is distributed as a Helm chart. Helm 3 is a CLI, has no server side component, and its use is
-  fairly straightforward. To install the Helm 3 CLI follow the <a href="https://helm.sh/docs/intro/install">official install instructions</a>.
+Fleet is distributed as a Helm chart. Helm 3 is a CLI, has no server side component, and its use is


Suggested change

Fleet is distributed as a Helm chart. Helm 3 is a CLI, has no server side component, and its use is

Fleet is distributed as a Helm chart. Helm is a CLI, has no server side component, and its use is

Do we need to specify version 3?
My understanding is that the Helm project is planning on a version 4 and this page will look outdated very soon.
Plus the version "3" provides no valuable information

kakabisht and others added 5 commits May 20, 2025 12:50

Adding information about quick start and persona

6930d60

upading sidebar.js

2397229

Merge branch 'main' into feat-persona-quickstart

516b920

Fix build error

287721a

Merge branch 'feat-persona-quickstart' of https://github.com/kakabish…

4587f4e

…t/fleet-docs into feat-persona-quickstart

kakabisht marked this pull request as ready for review May 22, 2025 07:42

kakabisht requested a review from a team as a code owner May 22, 2025 07:42

fix visual assets

98383d1

0xavi0 reviewed May 23, 2025

View reviewed changes

kakabisht and others added 4 commits May 23, 2025 15:36

Update docs/quickstart.md

cb39727

Co-authored-by: Xavi Garcia <[email protected]>

Update docs/quickstart.md

48ae1ac

Co-authored-by: Xavi Garcia <[email protected]>

Update docs/quickstart.md

12c942f

Co-authored-by: Xavi Garcia <[email protected]>

Update docs/quickstart.md

54af92c

Co-authored-by: Xavi Garcia <[email protected]>

thardeck requested a review from Copilot May 23, 2025 10:26

Copilot AI reviewed May 23, 2025

View reviewed changes

weyfonk reviewed May 26, 2025

View reviewed changes

olblak reviewed May 28, 2025

View reviewed changes

manno changed the title ~~Feat persona quickstart~~ Fleet persona quickstart Jul 14, 2025

	1. It deploys the updated resources automatically.
	2. It deploys the updated resources automatically.

		Structure your repository like this:

		![Screenshot displaying the file directory](../static/img/file-structure-sample-ss.png)

	\| Security Administrators \| Define and enforce security policies as code- <br/> Deploy security tools and configurations <br/> Audit and manage security posture across clusters \| Reduced risk and centralized compliance management <br/> Automated, consistent security configuration \|
	\| Security Administrators \| Define and enforce security policies as code: <br/> Deploy security tools and configurations <br/> Audit and manage security posture across clusters \| Reduced risk and centralized compliance management <br/> Automated, consistent security configuration \|

	Specify the Git repositories containing your deployment manifests or Helm charts. For hello world, example you need:
	Specify the Git repository containing your deployment manifests or Helm charts. For hello world, example you need:


		![Screenshot displaying the Rancher Desktop ](../static/img/rancher-gitrepos-ss.png)

		Or you can run the following command:

	Or you can run the following command:
	Or you can run the following commands:

	## Automating Deployments and Scaling

	## Automating Deployments and Scaling


		To target specific clusters, apply labels such as `env=qa` or `region=eu` to your clusters. Use the `clusterSelector` and `targetCustomizations` fields in your `fleet.yaml` file to define which clusters receive which configurations.

		![Diagram displaying flow of target specific clusters](../static/img/Flow-clusterSelector-targetCustomizations.png)

	Fleet is distributed as a Helm chart. Helm 3 is a CLI, has no server side component, and its use is
	Fleet is distributed as a Helm chart. Helm is a CLI, has no server side component, and its use is

Fleet persona quickstart #254

Are you sure you want to change the base?

Fleet persona quickstart #254

Uh oh!

Conversation

kakabisht commented May 20, 2025

Uh oh!

0xavi0 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI May 23, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 23, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

olblak May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

olblak May 28, 2025 •

edited

Loading