Update Observability and CLI documentation for Kyma 2.0 docs

[NHingerl]

Description

Instead of being split based on components, Kyma 2.0 docs will be split up into practical guides which should take Kyma personas into account. We need to reflect this in our documentation. CLI docs will be integrated in the main Kyma documentation.

More info:

• Personas
• Kyma 2.0 docs issue
• Kyma 2.0 docs Slack channel
• Preview of the current Kyma 2.0 documents.

Overview "What Kyma is capable of? Will it solve my problems?"

• [x] Is the current short paragraph in the Main areas document good? => @JeremyHarisch
• [x] Review the Observability overview document. => @skhalash https://github.com/kyma-project/kyma/pull/11291
• [x] Discuss if/where the existing explanatory documents about Loki, Kiali, Alertmanager, Istio, Jaeger… will be integrated in Kyma 2.0 docu as well. => @suleymanakbas91 https://github.com/kyma-project/kyma/pull/11278 review/confirm: we can probably remove the separate files and put a paragraph for each into the the Observability overview document. Please align with @skhalash
• [X] Should we have similarly explanatory docs about Fluent Bit / OpenTelemetry at this point? => Agreement: also just a paragraph in the overview doc and link to official docu. @suleymanakbas91 @skhalash I'll follow up with you => postponed till https://github.com/kyma-project/kyma/issues/11105 is finished => Update Aug 9th (@chrkl): depends on default config etc, still TBD. Check with @JeremyHarisch and/or @skhalash if @chrkl is unavailable. => update Sept 14: Postponed, after K2.0

Getting Started Nothing to discuss here, this section will only contain one tutorial/sample procedure, which PB provides outlined, and Maja provides. => https://github.com/kyma-project/kyma/issues/11470

Deep Dive/Tutorials "What specific tasks can I accomplish with Kyma/Observability?"

This main tab is currently alphabetical; it's going to have sub-tabs based on the main areas that were introduced in the Overview section; that means: one subtab for Telemetry/Observability. (=> done)

We've got the existing Monitoring flow tutorial, which Icke confirmed is up to date.

• [x] Which other existing instructions are relevant? => @a-thaler Review (see outcomes), for example Access Kiali and extend to describe purpose etc

• [x] Does it make sense to have a separate subtab for the main area UI/CLI? I feel the CLI-related instructions might fit better near the corresponding non-CLI instructions. => Agreement: no separate subtab for CLI, include it in other main area instructions wherever it applies.

• [x] Do we need any new instructions for kyma 2.0? => yes we do.

• [X] #11888 and how to set up end-to-end tracing, looking at what comes with Kubernetes and what needs to be done to propagate HTTP headers etc. => update Sept 14: Postponed, after K2.0

Operation Guides "How do I keep my cluster healthy and safe?" Anything related to security and maintenance - I assume several CLI/Observability documents go here.

This section currently has three subtabs Configuration (set up non-default Kyma installation etc) Operations (typical maintainence stuff) Troubleshooting (the "old" components troubleshooting guides etc)

• [x] Does this division make sense to you? => division not intuitive, @NHingerl merge Config and Ops and check whether it's a too long list; we can put all backup-related bits into one document.
• [x] Review the existing documents. => postponed to next sprint. Update: done May 26.
• [x] Should security-related instructions go here or into the Deep Dive section? => Suggestion: Put information how to keep the cluster secure under Operations, and instructions to keep the applications secure in the respective Tutorials sections. => in progress with https://github.com/kyma-project/kyma/pull/11357

New guides:

• [x] How to access Kiali and Grafana (review outcomes relevant too) => @skhalash, done with #11359, doc belongs to Operations though
• [x] How to expose Kiali and Grafana securely @chrkl https://github.com/kyma-project/kyma/pull/11403 => also into Operations

To Dos after review:

Configuration

• [x] Make sure the profiles (default, eval, prod) are documented. => see preview.
• [x] Add note to use eval for local installation.
• [x] Remove alpha from the code examples - with K2.0, the commands won't be alpha anymore.
• [x] Update components yaml example with K2.0 components. => https://github.com/kyma-project/kyma/pull/11485
• [x] Add documentation how to remove components after installation (=> use Helm client, not CLI, to remove the component chart). => see preview
• [x] Docs describing how to keep the applications secure go into Tutorials.
• [x] Clarify whether Enable the Runtime Agent is still relevant. => Reply: "yup, probably yes. @majakurcius will probably include it in the Application Connectivity scope."

Operations

• [x] #11892
• [x] Entire "Operations" subsection consists only of Backup docs => Distinction between Config and Ops is obsolete.

Troubleshooting

• [x] Prometheus-Istio: Update overrides file, must be values YAML file now. => https://github.com/kyma-project/kyma/pull/11713 and https://github.com/kyma-project/kyma/pull/11793
• [x] Tracing: Rewrite thoroughly; value 60 (percent!) is just an example... 100 % needs caution though because might destabilize Istio. => https://github.com/kyma-project/kyma/pull/11880
• [x] Troubleshoot port forwarding @skhalash

Move files:

• [x] Into Operations: Customizing Kiali+Grafana (port-forward, secure, expose)
• [x] Into Tutorials: Use CLI as kubectl plugin goes into Tutorials, not Operations. Explain context "If you want to use kubectl, you can..."
• [x] Into Tutorials: Configure Authorization (OAuth2, JWT), Security guidelines for MicroFrontend and ClusterMicroFrontend CRs, Publish events without Kyma Application

Remove docs:

• [x] Discard most of the existing Installation docs, for example: no more differentiation between local/cluster installation no more Advanced Configuration no more info about ConfigMaps/Helm Overrides no more conflicting entries.
• [x] Console PW
• [x] Can't log in after hibernation
• [x] Errors after restarting
• [x] Can't deprovision

Technical References "Sometimes I need more detail"

This contains the config charts, component architecture, custom resources, and other references the users might want to look up. Most of them are in subfolders now, which netlify preview doesn't display. Review whether the existing docs make sense. => postponed to next sprint

• [x] Review and update the observability diagrams => https://github.com/kyma-project/kyma/pull/11582 and https://github.com/kyma-project/kyma/pull/11679
• [x] #11889 and other Tech Reference docs

Glossary

• [x] Discuss whether we need to add more terms. => @NHingerl keep an eye open, add terms as they come up.

Area

• Observability docs
• CLI docs

Reasons

We should change the docs so that Kyma target groups can easily navigate and find answers to their questions in our documentation.

11029

#10857

Assignees

@kyma-project/technical-writers

Attachments

[lanphan]

Hi @NHingerl ,

Currently, I'm interested in auth aspect of kyma (how to use dex, ory to add new account; how to setup SSO on multiple sites; how to setup auth for new component ...), do you have any tutorial relating to auth currently? I think auth is deserved as a dedicated tutorial for end-user like monitoring, what do you think?

[NHingerl]

Hi @NHingerl ,

Currently, I'm interested in auth aspect of kyma (how to use dex, ory to add new account; how to setup SSO on multiple sites; how to setup auth for new component ...), do you have any tutorial relating to auth currently? I think auth is deserved as a dedicated tutorial for end-user like monitoring, what do you think?

Hi @lanphan, maybe the following tutorials of the existing documentation are helpful for you:

• Expose and secure a service
• Manage static users in Dex
• Add an Identity Provider to Dex

If not, we might be able to support you better via Slack. For Kyma 2.0 docs, we'll keep your suggestion in mind. Thank you for your support!

[NHingerl]

Update after review of the tutorials with @a-thaler

PR https://github.com/kyma-project/kyma/pull/11315:

• [x] We'll get rid of the Compare Traces file. The info should be covered in Jaeger docu.
• [x] Search for Traces to be removed; we can add it again if it's sorely missing.
• [x] Update TLS Certificate goes to the Operations guides. Need to align content with Goats @strekm.
• [x] The Monitoring Flow and its four sub-tasks must be updated to reflect K2.0 - @tobiscr might be able to provide input. => in agreement with @tobiscr and @clebs, the instructions for Slack notifications will be updated.
• [x] Two files, Develop Service w/o Docker and Publish a Docker image don't belong to one Main Area => need to sort out where to put them. =>. They'll be directly under the main tab, not within any Main Area subtab (https://github.com/kyma-project/kyma/pull/11315/commits/d7c8e5ae632b51416594e73c2cf0008edf16c09b)

PR https://github.com/kyma-project/kyma/pull/11359:

• [x] For Kiali and Grafana, we need a tutorial how it's going to work w/o Dex - port forwarding, securing, exposing? Update May 26h: This goes into Operations; it's a one-time configuration task, not everyday use of Kyma. => port forwarding in https://github.com/kyma-project/kyma/pull/11359

[NHingerl]

In our Telemetry+Observability overview topic, we announce a tutorial that explains Configuring In-Cluster Observability. I don't think we have that yet, right? => discarded We've got the Monitoring Flow, which covers Prometheus, Grafana, and the Alertmanager. But what about Jaeger, Loki, and Kiali? => new checkbox in issue

[NHingerl]

As agreed with @skhalash: Let's add a troubleshooting guide for port forwarding in case the port is already occupied. => https://github.com/kyma-project/kyma/pull/11359

[NHingerl]

Removed some ToDos from the list (were not really related to Observability) and created a separate issues for them:

• Explain concept: We just need a values yaml with a "global" Kyma chart and sub-charts for the components. Document the syntax and semantic of the prerequisites attribute in the yaml file. => https://github.com/kyma-project/kyma/issues/11715
• Clarify with SREs: Tutorial how to keep the cluster secure.=> https://github.com/kyma-project/kyma/issues/11716