Docs information architecture refactor pass 1 #1259
Conversation
grafsean
requested review from
grcevski,
mariomac,
marctc and
rafaelroquetto
as code owners
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #1259 +/- ##
==========================================
- Coverage 80.77% 80.69% -0.08%
==========================================
Files 131 131
Lines 13465 13465
==========================================
- Hits 10876 10866 -10
- Misses 2079 2086 +7
- Partials 510 513 +3
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
grafsean
changed the title
grafsean
added
documentation
| @@ -266,14 +267,14 @@ Because of the AppArmour restriction, to run Beyla as unprivileged container, yo | |||
| - Set `container.apparmor.security.beta.kubernetes.io/beyla: "unconfined"` in your Kubernetes deployment files. | |||
| - Set a modified AppArmour policy which allows Beyla to perform `mount`. | |||
|
|
|||
| **Note** Since the `beyla` container does not have the privileges required to mount or un-mount the BPF filesystem, this sample leaves the BPF filesystem mounted on the host, even after the sample is deleted. This samples uses a unique path for each namespace to ensure re-use the same mount if Beyla is re-deployed, but to avoid collisions if multiple instances of Beyla is run in different namespaces. | |||
| **Note** Since the `beyla` container does not have the privileges required to mount or un-mount the BPF filesystem, this sample leaves the BPF filesystem mounted on the host, even after the sample is deleted. This samples uses a unique path for each namespace to ensure re-use the same mount if Beyla is re-deployed, but to avoid collisions if multiple instances of Beyla is run in different namespaces. | |||
There was a problem hiding this comment.
Let's leave it for now, we can follow up with a PR to remove all references to the BPF file system in docs, examples etc.
|
|
||
| **Note** Loading BPF programs requires that Beyla is able to read the Linux performance events, or at least be able to execute the Linux Kernel API `perf_event_open()`. | ||
| **Note** Loading BPF programs requires that Beyla is able to read the Linux performance events, or at least be able to execute the Linux Kernel API `perf_event_open()`. |
There was a problem hiding this comment.
In addition to this, it may be worth at least mentioning https://docs.kernel.org/admin-guide/sysctl/kernel.html#unprivileged-bpf-disabled
There was a problem hiding this comment.
Thank you @rafaelroquetto I'll do another pass to update further content. This pass focused on improving the information architecture and deprecated articles. See Next steps in the description.
| ## Requirements | ||
|
|
||
| - Linux with Kernel 5.8 or higher with BPF Type Format [(BTF)](https://www.kernel.org/doc/html/latest/bpf/btf.html) | ||
| enabled. BTF became enabled by default on most Linux distributions with kernel 5.14 or higher. | ||
| You can check if your kernel has BTF enabled by verifying if `/sys/kernel/btf/vmlinux` exists on your system. | ||
| If you need to recompile your kernel to enable BTF, the configuration option `CONFIG_DEBUG_INFO_BTF=y` must be | ||
| set. | ||
| - Alternatively, RHEL 4.18 Linux kernels (at least build 348) are also supported, due to their heavily backported nature. | ||
| - Beyla also supports RedHat-based distributions: RHEL8, Centos 8, Rocky8, AlmaLinux8, and others, which ship a Kernel 4.18 that backports eBPF-related patches. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Grafana.Spelling] Did you really mean 'Centos'? The Grafana dictionary might not know of this word yet. To add a new word, refer to Add words to the Grafana Labs dictionary. Alternatively, raise an issue and a maintainer will add it for you. For UI elements, use bold formatting. The spell checker doesn't check words with bold formatting. For paths; configuration; user input; code; class, method, and variable names; statuscodes; and console output, use code formatting. The spell checker doesn't check words with code formatting.
If the rule is incorrect or needs improving, report an issue.
If you have reason to diverge from the style guidance, to skip a rule, refer to Skip rules.
| ## Requirements | ||
|
|
||
| - Linux with Kernel 5.8 or higher with BPF Type Format [(BTF)](https://www.kernel.org/doc/html/latest/bpf/btf.html) | ||
| enabled. BTF became enabled by default on most Linux distributions with kernel 5.14 or higher. | ||
| You can check if your kernel has BTF enabled by verifying if `/sys/kernel/btf/vmlinux` exists on your system. | ||
| If you need to recompile your kernel to enable BTF, the configuration option `CONFIG_DEBUG_INFO_BTF=y` must be | ||
| set. | ||
| - Alternatively, RHEL 4.18 Linux kernels (at least build 348) are also supported, due to their heavily backported nature. | ||
| - Beyla also supports RedHat-based distributions: RHEL8, Centos 8, Rocky8, AlmaLinux8, and others, which ship a Kernel 4.18 that backports eBPF-related patches. |
There was a problem hiding this comment.
[Grafana.WordList] Use 'CentOS' instead of 'Centos'.
For more information, refer to https://grafana.com/docs/writers-toolkit/write/style-guide/word-list/.
If the rule is incorrect or needs improving, report an issue.
If you have reason to diverge from the style guidance, to skip a rule, refer to Skip rules.
|
|
||
| Because of the AppArmour restriction, to run Beyla as unprivileged container, you need to either: | ||
|
|
||
| - Set `container.apparmor.security.beta.kubernetes.io/beyla: "unconfined"` in your Kubernetes deployment files. |
There was a problem hiding this comment.
[Grafana.Kubernetes] Use 'Kubernetes Deployment' instead of 'Kubernetes deployment'.
For more information, refer to https://grafana.com/docs/writers-toolkit/write/style-guide/capitalization-punctuation/#kubernetes-objects.
If the rule is incorrect or needs improving, report an issue.
If you have reason to diverge from the style guidance, to skip a rule, refer to Skip rules.
|
Thank you all for your feedback ❤️ I'll keep the enhancement PRs coming 🙂 |
* Move content and remove tutorial * Move helm alloy * Remove tutorial section * Add k8s walkthrough to quickstart * Add notes about standalone
Hi all, I've put together a first pass at refactoring and improving the information architecture of our documentation with a focus on the getting started experience. Please let me know if you'd like to discuss anything.
Changes
For the stability guarantees page, is that something we typically add to products or documentation? If we want to keep it, is it up to date?
Navigation before
Navigation after
Next steps
None of the content has been edited in this PR other than updating for link changes. I'd like to do a editing pass over everything to address Vale errors and edit for consistency.
I'd also like to update the language quickstarts to use Docker and code tabs. By using code tabs we can condense many articles into one and present a single language quickstart article.
When this refactor series is complete I'd like to get onto further content enhancement and additions.
Background
Last quarter in Slack, I discussed a few areas of the documentation (setup, tutorials, and quickstarts) that covered similar ground. Last week I checked with Mario about content similarities and areas we could make improvements.