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

Quickstart k8s otel doc added #4488

Open
wants to merge 8 commits into
base: main
Choose a base branch
from

Conversation

eedugon
Copy link
Contributor

@eedugon eedugon commented Nov 6, 2024

Description

Adding a quickstart document for Unified Kubernetes Observability with EDOT.

Preview: https://observability-docs_bk_4488.docs-preview.app.elstc.co/guide/en/observability/master/monitor-k8s-otel-edot.html

The objective of this doc is to be a good entry point for this use case, considering that we have all details and detailed documents in elastic/opentelemetry repo: https://github.com/elastic/opentelemetry/tree/main/docs/kubernetes/operator

If possible I'd like to get a review by @mdbirnstiehl or @bmorelli25 before requesting the review by @mlunadia and @akhileshpok .

Initial concerns:

  • The pre-requisites section looks a bit ugly and not very homogeneous.
  • The title is a bit long, but I think this is what Miguel or Akhilesh wanted (we can check with them at a later stage).
  • Should we add a similar doc to Serverless?

Documentation sets edited in this PR

Check all that apply.

  • Stateful (docs/en/observability/*)
  • Serverless (docs/en/serverless/*)
  • Integrations Developer Guide (docs/en/integrations/*)
  • None of the above

Related issue

Closes #4428

Checklist

  • Product/Engineering Review
  • Writer Review

Follow-up tasks

Select one.

  • This PR does not need to be ported to another doc set because:
    • The concepts in this PR only apply to one doc set (serverless or stateful)
    • The PR contains edits to both doc sets (serverless and stateful)
  • This PR needs to be ported to another doc set:
    • Port to stateful docs: <link to PR or tracking issue>
    • Port to serverless docs: <link to PR or tracking issue>

@eedugon eedugon requested a review from a team as a code owner November 6, 2024 17:05
Copy link
Contributor

github-actions bot commented Nov 6, 2024

A documentation preview will be available soon.

Request a new doc build by commenting
  • Rebuild this PR: run docs-build
  • Rebuild this PR and all Elastic docs: run docs-build rebuild

run docs-build is much faster than run docs-build rebuild. A rebuild should only be needed in rare situations.

If your PR continues to fail for an unknown reason, the doc build pipeline may be broken. Elastic employees can check the pipeline status here.

Copy link
Contributor

mergify bot commented Nov 6, 2024

This pull request does not have a backport label. Could you fix it @eedugon? 🙏
To fixup this pull request, you need to add the backport labels for the needed
branches, such as:

  • backport-/d./d is the label to automatically backport to the /d./d branch. /d is the digit
    NOTE: backport-skip has been added to this pull request.

@mergify mergify bot added the backport-skip Skip notification from the automated backport with mergify label Nov 6, 2024
Copy link
Member

@bmorelli25 bmorelli25 left a comment

Choose a reason for hiding this comment

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

Looking good! A few grammar things

@bmorelli25 bmorelli25 added backport-8.x Automated backport to the 8.x branch with mergify backport-8.16 Automated backport with mergify and removed backport-skip Skip notification from the automated backport with mergify labels Nov 6, 2024
@eedugon
Copy link
Contributor Author

eedugon commented Nov 8, 2024

@akhileshpok , @mlunadia : would you please review this PR? It will be the official quickstart / onboarding doc for k8s + OTel we have talked about for 8.16.

Note that this doc aims to not be too long, neither to provide / duplicate the same information we already have in our elastic/opentelemetry repository in markdown docs.

For example about instrumenting applications I've just referenced the GH repo

@mdbirnstiehl : feel free to review also if you like!

Copy link
Contributor

mergify bot commented Nov 12, 2024

This pull request is now in conflict. Could you fix it @eedugon? 🙏
To fixup this pull request, you can check out it locally. See documentation: https://help.github.com/articles/checking-out-pull-requests-locally/

git fetch upstream
git checkout -b otel_k8s_onboarding upstream/otel_k8s_onboarding
git merge upstream/main
git push upstream otel_k8s_onboarding

@eedugon
Copy link
Contributor Author

eedugon commented Nov 12, 2024

conflict solved (hopefully) :-D

@eedugon
Copy link
Contributor Author

eedugon commented Nov 13, 2024

@akhileshpok : I've talked with @bmorelli25 and we are going to add the information about being able to use on-premises clusters for this quickstart. We will add it in a different PR as we will update all quickstarts where this is applicable.

For serverless we will port this new doc to the serverless documentation as soon as it's approved.

Copy link
Contributor

@mdbirnstiehl mdbirnstiehl left a comment

Choose a reason for hiding this comment

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

Looks great! Just had a couple of suggestions.

[role="screenshot"]
image::images/quickstart-k8s-otel-entry-point.png[Kubernetes-OTel entry point]

. Follow the on-screen instructions to perform the installation of all needed components.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
. Follow the on-screen instructions to perform the installation of all needed components.
. Follow the on-screen instructions to install all needed components.

* Create a namespace.
* Create a secret with an API Key and the {es} endpoint to be used by the collectors.
* Install the `opentelemetry-kube-stack` helm chart with the provided `values.yaml`.
* Optionally, for instrumenting applications, apply the corresponding `annotations` as showed in {kib}.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
* Optionally, for instrumenting applications, apply the corresponding `annotations` as showed in {kib}.
* Optionally, for instrumenting applications, apply the corresponding `annotations` as shown in {kib}.

* `Deployment` EDOT Collector configured for cluster level metrics.
* `Instrumentation` object for applications https://opentelemetry.io/docs/kubernetes/operator/automatic/[auto-instrumentation].

For a more detailed description of the components and advanced configuration refer to the https://github.com/elastic/opentelemetry/blob/main/docs/kubernetes/operator/README.md[elastic/opentelemetry] GitHub repository.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
For a more detailed description of the components and advanced configuration refer to the https://github.com/elastic/opentelemetry/blob/main/docs/kubernetes/operator/README.md[elastic/opentelemetry] GitHub repository.
For a more detailed description of the components and advanced configuration, refer to the https://github.com/elastic/opentelemetry/blob/main/docs/kubernetes/operator/README.md[elastic/opentelemetry] GitHub repository.


. In {kib}, go to **Observability** and click **Add Data**.

. Under the question *`What do you want to monitor?`* select **Kubernetes**, and then select the **OpenTelemetry: Full Observability** option.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
. Under the question *`What do you want to monitor?`* select **Kubernetes**, and then select the **OpenTelemetry: Full Observability** option.
. Under *`What do you want to monitor?`*, select **Kubernetes**, and then select the **OpenTelemetry: Full Observability** option.

== Troubleshooting and more

* For troubleshooting deployment and installation, refer to https://github.com/elastic/opentelemetry/tree/main/docs/kubernetes/operator#installation-verification[installation verification].
* For applications instrumentation details, refer to https://github.com/elastic/opentelemetry/blob/main/docs/kubernetes/operator/instrumenting-applications.md[Instrumenting applications with EDOT SDKs on Kubernetes].
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
* For applications instrumentation details, refer to https://github.com/elastic/opentelemetry/blob/main/docs/kubernetes/operator/instrumenting-applications.md[Instrumenting applications with EDOT SDKs on Kubernetes].
* For application instrumentation details, refer to https://github.com/elastic/opentelemetry/blob/main/docs/kubernetes/operator/instrumenting-applications.md[Instrumenting applications with EDOT SDKs on Kubernetes].

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
backport-8.x Automated backport to the 8.x branch with mergify backport-8.16 Automated backport with mergify needs-product-review
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add OTel/K8s onboarding workflow to Observability Guide
3 participants