docs: complete overhaul and switch to `mkdocs` #321

hiddeco · 2020-03-01T17:41:03Z

This PR (or rather mega-PR) catches up with all changes made to the Helm Operator that were still undocumented.

It introduces new get started guides including a quickstart guide, a refined HelmRelease guide including explanations and guides on more advanced topics, updated FAQ questions, embedded Helm chart documentation generated from the chart's README.md, auto-generated API / CRD reference, and much more.

It also switches from sphinx to mkdocs due to various issues we had with the Markdown support of sphinx.

Rendered documentation preview: https://test-helm-op.readthedocs.io
Addresses: #222, #293, #316, #327, #94

docs/get-started/using-helm.md

docs/get-started/using-kustomize.md

docs/get-started/using-yamls.md

sa-spag · 2020-03-24T10:57:40Z

docs/helmrelease-guide/rollbacks.md

+  delete/recreate if needed. Defaults to `false` when omitted.
+* `recreate` _(Optional)_: When set to `true`, performs pods restart for the
+  resource if applicable. Defaults to `false` when omitted.
+* `timeout` _(Optional)_: Time to wait for any individual Kubernetes operation


If not mistaken, this is the timeout for the rollback operation, not the duration after which the operator triggers a rollback. Can you please make it clear people should use .spec.timeout for that purpose?

I was under the impression that this would be clear by it being a nested key under rollback.

Would

Time to wait for any individual Kubernetes operation that is part of the rollback

be more clear to you?

Yes, clearer. My point is that it should not be mistaken for .spec.timeout, which is mostly what users care about I believe.

Another thing that comes to mind now is that people will likely want to increase the terminationGracePeriod on the Helm Operator pod when they set the timeout to a high value to prevent releases from getting stuck in a faulty state.

Thanks for the suggestion!

sa-spag · 2020-03-24T11:00:31Z

docs/helmrelease-guide/reconciliation-and-upgrades.md

+the value of the annotation equals to `<namespace>:helmrelease/<name>`.
+
+The purpose of this annotation is to indicate that the cause of that resource
+is a `HelmRelease`. It is also functions as a safe guard during reconciliation


Suggested change

is a `HelmRelease`. It is also functions as a safe guard during reconciliation

is a `HelmRelease`. It also functions as a safe guard during reconciliation

sa-spag · 2020-03-24T11:06:45Z

docs/helmrelease-guide/values.md

+    - item2
+```
+
+## Values from sources


Can you please mention the downside of this feature is that changes made on these values take more time to be propagated (as per #151)? Or perhaps mention it under "Reconciliation".

sa-spag · 2020-03-24T11:09:50Z

docs/faq.md

+1. Increase the [various polling intervals](references/operator.md) based on
+   what your environment really needs:
+
+       - **`--status-update-interval`:** The interval at which Helm is polled for


Suggested change

- **`--status-update-interval`:** The interval at which Helm is polled for

- `--status-update-interval`: The interval at which Helm is polled for

sa-spag · 2020-03-24T11:20:27Z

docs/helmrelease-guide/chart-sources.md

+is detected the Helm Operator will collect all `HelmRelease` resources making
+use of the mirror and inspect if the change updates the chart at the `path`
+given, when this is true it will schedule a new release and an upgrade will
+follow.


We could add a note to suggest users to use Git tags to version their charts.

sa-spag · 2020-03-24T11:27:15Z

Prometheus metrics are no longer documented. Is that intended?

hiddeco · 2020-03-24T11:29:27Z

@sa-spag I removed them during the initial rewrite / clean up as I was working in parallel on #334 which will extend those metrics. I will re-add a placeholder page under references.

sa-spag · 2020-03-24T11:30:31Z

What about /api/v1/sync-git endpoint? Do we want to document it?

hiddeco · 2020-03-24T11:31:24Z

@sa-spag see https://test-helm-op.readthedocs.io/en/latest/helmrelease-guide/chart-sources/#notifying-the-helm-operator-about-git-changes

squaremo

Thoughtful and thorough documentation is a pleasure to read, so reviewing this was ❤️

90% of my comments are tidying up punctuation and could go in one batched commit. There's just a handful that might need typing rather than a button click -- pretty good for 4000-odd lines!

squaremo · 2020-03-24T10:16:40Z

README.md


-The FluxCD projects adheres to the [CNCF Code of
+Flux and its umbrella projects adhere to the [CNCF Code of


"its umbrella projects" is tricky to interpret. Does it refer to other projects under fluxcd/? If so, I think it might be better to say "Flux and other projects in the FluxCD umbrella" or name them explicitly (or just name this project explicitly).

Reading this now I agree, I have opted for The Helm Operator and other projects in [...].

squaremo · 2020-03-24T10:24:38Z

chart/helm-operator/README.md

+| `git.ssh.configMapKey`                            | `config`                                             | The name of the key in the kubernetes config map specified above
+| `chartsSyncInterval`                              | `3m`                                                 | Period on which to reconcile the Helm releases with `HelmRelease` resources
+| `statusUpdateInterval`                            | `None`                                               | Period on which to update the Helm release status in `HelmRelease` resources
+| `workers`                                         | `None`                                               | Amount of workers processing releases


"Number" rather than "Amount" (number is for things that can be counted e.g., workers, amount is for stuff that cannot be counted, e.g., water)

squaremo · 2020-03-24T10:26:19Z

chart/helm-operator/README.md

+| `logReleaseDiffs`                                 | `false`                                              | Helm Operator should log the diff when a chart release diverges (possibly insecure)
+| `allowNamespace`                                  | `None`                                               | If set, this limits the scope to a single namespace. If not specified, all namespaces will be watched
+| `helm.versions`                                   | `v2,v3`                                              | Helm versions supported by this operator instance, if v2 is specified then Tiller is required
+| `tillerNamespace`                                 | `kube-system`                                        | Namespace in which the Tiller server can be found


Might be worth noting that this and many following only matter for v2

squaremo · 2020-03-24T10:33:09Z

docs/faq.md

+[`--status-update-interval`](references/operator.md#reconciliation-configuration)).
+
+The message is the error reported during the latest release failure. When this
+failure was for example due to a validation error, the upgrade has never been


Suggested change

failure was for example due to a validation error, the upgrade has never been

failure was for example due to a validation error, the upgrade has not been

completed, and the status of the release will thus still be `deployed`.

(can't be applied as is, since it changes the next line too)

squaremo · 2020-03-24T10:34:50Z

docs/faq.md

+### It takes a long time before the operator processes an update to a resource. How can I speed up the processing of releases?
+
+The operator watches for changes of Custom Resources of kind `HelmRelease`. It
+receives Kubernetes Events and queues these to be processed, all resources will


Suggested change

receives Kubernetes Events and queues these to be processed, all resources will

receives Kubernetes Events and queues these to be processed. All resources will

squaremo · 2020-03-24T12:28:28Z

docs/helmrelease-guide/rollbacks.md

+  release until `maxRetries` is reached. Defaults to `false` when omitted.
+* `maxRetries` _(Optional)_: The maximum amount of retries that should be
+  attempted for a rolled back release. Defaults to `5` when omitted, use `0`
+  for an unlimited amount of retries.


Suggested change

for an unlimited amount of retries.

for an unlimited number of retries.

squaremo · 2020-03-24T12:29:04Z

docs/helmrelease-guide/values.md

+It is possible to define a list of config maps, secrets (in the same namespace
+as the `HelmRelease` by default, or in a configured namespace) or external
+sources (URLs) from which to take values. For charts from a Git
+repository, there is an additional option available to refer to a file in


a file in ...?

squaremo · 2020-03-24T13:28:21Z

docs/index.md

+
+The Helm Operator is a [Kubernetes operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/),
+allowing one to declaratively manage Helm chart releases. Combined with
+[Flux](https://github.com/fluxcd/flux) this can be utilized to automate


Suggested change

[Flux](https://github.com/fluxcd/flux) this can be utilized to automate

[Flux](https://github.com/fluxcd/flux) it can automate

squaremo · 2020-03-24T13:28:38Z

docs/index.md

+The Helm Operator is a [Kubernetes operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/),
+allowing one to declaratively manage Helm chart releases. Combined with
+[Flux](https://github.com/fluxcd/flux) this can be utilized to automate
+releases in a GitOps manner, but the usage of Flux is not a strict


Suggested change

releases in a GitOps manner, but the usage of Flux is not a strict

releases in a GitOps manner, but the use of Flux is not a strict

squaremo · 2020-03-24T13:29:43Z

docs/index.md

+releases in a GitOps manner, but the usage of Flux is not a strict
+requirement.
+
+The desired state of a Helm release is described through a Kubernetes


This is a concise and lucid explanation of the operator 💯

squaremo

Thoughtful and thorough documentation is a pleasure to read, so reviewing this was ❤️

90% of my comments are tidying up punctuation and could go in one batched commit. There's just a handful that might need typing rather than a button click -- pretty good for 4000-odd lines!

hiddeco added the docs Issue or PR related to documentation label Mar 1, 2020

hiddeco force-pushed the docs/revamp branch 9 times, most recently from 5a7f1ce to 1d08578 Compare March 5, 2020 11:21

hiddeco force-pushed the docs/revamp branch 4 times, most recently from 7f4cbf0 to 90031fb Compare March 23, 2020 22:47

dholbach reviewed Mar 24, 2020

View reviewed changes

docs/get-started/using-helm.md Outdated Show resolved Hide resolved

dholbach reviewed Mar 24, 2020

View reviewed changes

docs/get-started/using-kustomize.md Outdated Show resolved Hide resolved

dholbach reviewed Mar 24, 2020

View reviewed changes

docs/get-started/using-yamls.md Outdated Show resolved Hide resolved

hiddeco force-pushed the docs/revamp branch 2 times, most recently from 7d9284d to 898aef4 Compare March 24, 2020 10:24

sa-spag reviewed Mar 24, 2020

View reviewed changes

squaremo approved these changes Mar 24, 2020

View reviewed changes

Daniel Holbach and others added 27 commits March 25, 2020 14:32

HelmRelease

ba71ceb

apply suggestions by Hidde - thanks!

f28008c

adjust links to /latest/ - they will change once flux#2919 is merged

e37947d

change links to stable docs where applicable

8f4086a

fix indentation in list

a27df4c

docs: structure and indentation fixes

91019ad

docs: 'Helm operator' -> 'Helm Operator'

db5d1e2

docs: update CRD reference tmpl to match new style

db29835

docs: provide get-started guides

a92eb75

docs: embed Helm chart reference in documentation

5123d60

docs: add introduction to index and restructure

3aa1d5e

docs: small tweaks

770e65f

docs: enable favicon, github link and toc anchors

6f4000d

build: 'flux-helm-operator' -> 'helm-operator'

2608efd

docs: document upgrade failures

b16365d

docs: enhance debugging documentation

50b44ef

docs: rewrite FAQ

8f24bb7

hack: do not follow symlinks during verify diff

5b1ed6d

docs: small corrections

0a8bbf7

docs: honour our contributors

b980ae5

docs: restyle installation instructions chart

8ae886b

docs: small fixes

494eb7d

docs: review suggestions, lots

9bc24d1

docs: rollback timeout suggestions

97990d3

docs: add minimal monitoring reference

a92343e

docs: more versioned links and small FAQ rephrase

f59601c

docs: troubleshooting

40db060

hiddeco force-pushed the docs/revamp branch from 5173356 to 40db060 Compare March 25, 2020 13:33

hiddeco merged commit cc1fbe2 into master Mar 25, 2020

hiddeco deleted the docs/revamp branch March 25, 2020 14:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: complete overhaul and switch to `mkdocs` #321

docs: complete overhaul and switch to `mkdocs` #321

hiddeco commented Mar 1, 2020 •

edited

Loading

sa-spag Mar 24, 2020

hiddeco Mar 24, 2020

sa-spag Mar 24, 2020

hiddeco Mar 24, 2020 •

edited

Loading

sa-spag Mar 24, 2020

sa-spag Mar 24, 2020 •

edited

Loading

sa-spag Mar 24, 2020

sa-spag Mar 24, 2020

sa-spag commented Mar 24, 2020

hiddeco commented Mar 24, 2020

sa-spag commented Mar 24, 2020

hiddeco commented Mar 24, 2020

squaremo left a comment

squaremo Mar 24, 2020

hiddeco Mar 24, 2020

squaremo Mar 24, 2020

hiddeco Mar 24, 2020

squaremo Mar 24, 2020

squaremo Mar 24, 2020

squaremo Mar 24, 2020

squaremo Mar 24, 2020

squaremo Mar 24, 2020

squaremo Mar 24, 2020

squaremo Mar 24, 2020

squaremo Mar 24, 2020

squaremo Mar 24, 2020

squaremo left a comment

	is a `HelmRelease`. It is also functions as a safe guard during reconciliation
	is a `HelmRelease`. It also functions as a safe guard during reconciliation

	- `--status-update-interval`: The interval at which Helm is polled for
	- `--status-update-interval`: The interval at which Helm is polled for


		The FluxCD projects adheres to the [CNCF Code of
		Flux and its umbrella projects adhere to the [CNCF Code of

	failure was for example due to a validation error, the upgrade has never been
	failure was for example due to a validation error, the upgrade has not been
	completed, and the status of the release will thus still be `deployed`.

	receives Kubernetes Events and queues these to be processed, all resources will
	receives Kubernetes Events and queues these to be processed. All resources will

	for an unlimited amount of retries.
	for an unlimited number of retries.

	[Flux](https://github.com/fluxcd/flux) this can be utilized to automate
	[Flux](https://github.com/fluxcd/flux) it can automate

	releases in a GitOps manner, but the usage of Flux is not a strict
	releases in a GitOps manner, but the use of Flux is not a strict

docs: complete overhaul and switch to mkdocs #321

docs: complete overhaul and switch to mkdocs #321

Conversation

hiddeco commented Mar 1, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hiddeco Mar 24, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sa-spag Mar 24, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sa-spag commented Mar 24, 2020

hiddeco commented Mar 24, 2020

sa-spag commented Mar 24, 2020

hiddeco commented Mar 24, 2020

squaremo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

squaremo left a comment

Choose a reason for hiding this comment

docs: complete overhaul and switch to `mkdocs` #321

docs: complete overhaul and switch to `mkdocs` #321

hiddeco commented Mar 1, 2020 •

edited

Loading

hiddeco Mar 24, 2020 •

edited

Loading

sa-spag Mar 24, 2020 •

edited

Loading