Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reorganise and improve the installation docs #1573

Merged
merged 7 commits into from
Aug 24, 2023
Merged

Reorganise and improve the installation docs #1573

merged 7 commits into from
Aug 24, 2023

Conversation

stefanprodan
Copy link
Member

@stefanprodan stefanprodan commented Jul 20, 2023

This PR reorganises and improves the installation documentation as specified in #1560.

Co-authored-by: @mehak151 and @kingdonb

Preview

https://deploy-preview-1573--fluxcd.netlify.app/flux/installation/

Completion status

  • Installation
    • Bootstrap
      • Generic Git server
      • GitHub
      • GitLab
      • Bitbucket
      • AWS CodeCommit
      • Azure DevOps
      • Google Cloud Source
    • Configuration
      • Optional components
      • Bootstrap customization
      • Vertical scaling
      • Horizontal scaling
      • Multi-tenancy lockdown
      • Workload Identity
      • Air-Gapped installation
      • OpenShift installation
      • Proxy settings
      • Deploy key rotation
      • Helm drift detection
      • Helm OOM detection
      • Helm DNS lookups
    • Upgrade
    • Uninstall

Refs

Closes: #1560
Supersedes: #1568

@hiddeco
Copy link
Member

hiddeco commented Jul 20, 2023

Outline of the rewritten GitHub bootstrap documentation looks pretty good to me, and should be sufficient to proceed with the other ones. I will do more in-depth proof reading when I have the proper time, as I have some thoughts but nothing that would require rigorous changes.

@stefanprodan stefanprodan force-pushed the install-v2 branch 4 times, most recently from 9e1d077 to 099a4c2 Compare July 20, 2023 16:17
@stefanprodan stefanprodan changed the title Reorganise the installation docs Reorganise and improve the installation docs Jul 20, 2023
@stefanprodan stefanprodan force-pushed the install-v2 branch 2 times, most recently from 5aacf17 to a7b6319 Compare July 21, 2023 15:48
@stefanprodan stefanprodan added area/docs Documentation related issues and pull requests enhancement New feature or request area/ux In pursuit of a delightful user experience area/flux Flux related issues and pull requests labels Jul 21, 2023
static/_redirects Outdated Show resolved Hide resolved
stefanprodan pushed a commit that referenced this pull request Aug 17, 2023
Made updates in accordance to the GitHub, GitLab, etc docs as done in #1573

Signed-off-by: mehak151 <[email protected]>
stefanprodan and others added 5 commits August 17, 2023 12:32
Co-authored-by: Kingdon Barrett <[email protected]>
Co-authored-by: mehak151 <[email protected]>
Signed-off-by: Stefan Prodan <[email protected]>
Signed-off-by: Stefan Prodan <[email protected]>
@stefanprodan stefanprodan requested a review from a team August 17, 2023 09:43
@stefanprodan stefanprodan marked this pull request as ready for review August 17, 2023 09:44
@kingdonb
Copy link
Member

kingdonb commented Aug 17, 2023

I see some bad link regressions after the rebase:

https://gist.github.com/kingdonb/b725109eb070dc33ac9337e8609d7446

They are all in the blog, I think you probably don't care about that too much. But we can still fix them.

(Feedback welcome about the log output format, I have added a logger and can now set up custom log formatting for the report... I'm making the enhancements needed so we can put this into our CI pipeline)

I excluded everything that isn't high-level status (INFO) and tried to use a couple of the other log statuses, any messages that aren't needed for the work go to DEBUG level now.

I'll push a commit updating these, the other errors are all about "components" which are just depending on the changes in other repos linked above. Those other components issues should all be resolved once those above PRs get merged.

@kingdonb
Copy link
Member

Note this is gone from the updated docs:

https://fluxcd.io/flux/cheatsheets/bootstrap/#enable-notifications-for-third-party-controllers

We can fix the blog so it points at the v2.0 docs once this transition to versioned docs is over, (right now it's not clear to me where that link is going to wind up.)

@stefanprodan
Copy link
Member Author

Uh please push a commit to this branch for the blog, not sure how I messed up the rebase.

@stefanprodan
Copy link
Member Author

Note this is gone from the updated docs:
https://fluxcd.io/flux/cheatsheets/bootstrap/#enable-notifications-for-third-party-controllers

Can you please add this to tf-controller docs.

Co-authored-by: Kingdon Barrett <[email protected]>
Co-authored-by: mehak151 <[email protected]>
Signed-off-by: Stefan Prodan <[email protected]>
The bootstrap cheatsheet doc is going away

Signed-off-by: Kingdon Barrett <[email protected]>
@kingdonb
Copy link
Member

kingdonb commented Aug 18, 2023

That doc link is updated in the branch now, I pulled it in so we could check over this PR with the v1-beta check in #1630 one last time.

kingdonb pushed a commit that referenced this pull request Aug 21, 2023
This PR implements:

* https://github.com/kingdonb/link-checker-gpt/tree/v1-beta#integration-as-a-ci-check

I'm testing the new Dockerized version of the link-checker-gpt, that
helped us fix all the broken links in #1573

It should be possible to merge this if we are happy with it, independent
of the release for Flux v2.1 (it can certainly wait until after 👍)

I'm going to push a broken link as a test. The currently only major
issue that I'm aware of is that, if Netlify build takes longer than a
few seconds (60s or so) then subsequent checks may not be running
against the latest version. I would like to fix this before releasing it
by adding a reader that checks the GitHub Actions Checks statuses.

It is already checking to see if the preview site is really online, and
waiting up to 60s for that condition to become ready (with a sizeable
delay front-loaded as we have to gather a baseline report from fluxcd.io
before we can begin to check a PR, there has been some thought put into
making a good workflow in a way such that we don't want to 86 it right
away... minor annoyances should all be squashed prior to their annoying
anyone, 🤞 bet)

Signed-off-by: Kingdon Barrett <[email protected]>
kingdonb pushed a commit that referenced this pull request Aug 21, 2023
This PR implements:

* https://github.com/kingdonb/link-checker-gpt/tree/v1-beta#integration-as-a-ci-check

I'm testing the new Dockerized version of the link-checker-gpt, that
helped us fix all the broken links in #1573

It should be possible to merge this if we are happy with it, independent
of the release for Flux v2.1 (it can certainly wait until after 👍)

I'm going to push a broken link as a test.

There has been some thought put into making a good workflow in a way
such that we don't want to 86 it right away... minor annoyances should
all be squashed prior to their annoying anyone

* add the workflow to .github/workflows

* fix the bug (upstream)

* provide GH_TOKEN to link checker
* (fix github token)

Signed-off-by: Kingdon Barrett <[email protected]>
@kingdonb
Copy link
Member

The link checker report still reads some errors, but we can deal with it after it merges if any are still present:

I  Summary:
I  --------
I  Total issues in main site: 72
I  Total issues in preview site: 8
I  Resolved issues: 71
I  New issues: 7

I added b73421b in the install-v2 branch, that fixes one more.

Copy link
Member

@hiddeco hiddeco left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks excellent! 🙇🏼‍♂️❤️

@stefanprodan stefanprodan merged commit 4b2c379 into main Aug 24, 2023
@stefanprodan stefanprodan deleted the install-v2 branch August 24, 2023 08:17
kingdonb pushed a commit that referenced this pull request Sep 7, 2023
This PR implements:

* https://github.com/kingdonb/link-checker-gpt/tree/v1-beta#integration-as-a-ci-check

I'm testing the new Dockerized version of the link-checker-gpt, that
helped us fix all the broken links in #1573

It should be possible to merge this if we are happy with it, independent
of the release for Flux v2.1 (it can certainly wait until after 👍)

I'm going to push a broken link as a test.

There has been some thought put into making a good workflow in a way
such that we don't want to 86 it right away... minor annoyances should
all be squashed prior to their annoying anyone

* add the workflow to .github/workflows

* fix the bug (upstream)

* provide GH_TOKEN to link checker
* (fix github token)

Signed-off-by: Kingdon Barrett <[email protected]>
makkes pushed a commit that referenced this pull request Sep 14, 2023
The re-organization that happened as part of #1573 removed this page.

closes #1658

Signed-off-by: Max Jonas Werner <[email protected]>
makkes pushed a commit that referenced this pull request Sep 14, 2023
The re-organization that happened as part of #1573 removed this page.

PR #1573 added a redirect for /flux/cheatsheets/bootstrap but in this
case it's better to specifically link directly to the customization
guide instead of the general configuration page.

closes #1658

Signed-off-by: Max Jonas Werner <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area/docs Documentation related issues and pull requests area/flux Flux related issues and pull requests area/ux In pursuit of a delightful user experience enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[GSoD] Reorganise the installation docs
4 participants