open-telemetry
wip: Establish Security section for OTel documentation
OpenTelemetry (OTel) currently does not have public documentation on security recommendations. A markdown file in the OpenTelemetry Collector repository (linked below) does address some concerns, but is not easily findable by end users.
The goal of this PR is to establish hosting and configuration security recommendations for OTel Collector end users within the OpenTelemetry public documentation site. While the inspiration document contains both end-user and Component Developer security recommendations, this public documentation adapts the existing content focused on end users and links back to the inspiration document for Component Developers.
NOTE: The inspiration document also does not cover topics in detail and I need help filling in those blanks. Refer to any <!-- TODO: --> within the files that indicates knowledge gaps. From there, the page content can be re-organized, given the available information.
This PR adds:
- a Security Overview page
- an OpenTelemetry Collector hosting best practices page
- an OpenTelemetry Collector configuration best practices page
This proposed structure tries to be flexible for future Security content pages to be added. (Additional content doesn't have to focus on OTel Collector. Other Security-related areas in OTel can be addressed also, but that's not within the scope of this PR.)
Identified Areas of Potential Help
I already know this PR needs some extra help and this is my first time contributing a PR to this project. These include:
- Filling in content gaps. (Refer to NOTE: above.)
- Correct wiring for the menu. My goal is to have Security as a top level menu option.
- Links to related content within the OTel community documentation, if applicable.
- Amending the inspiration document in the OTel Collector repo to focus on Component Developers only.
Source Materials
https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/security-best-practices.md
Associated Issues
Initial issue: https://github.com/open-telemetry/opentelemetry.io/issues/3479 Related issue: https://github.com/open-telemetry/opentelemetry.io/issues/3227
Preview: https://deploy-preview-3652--opentelemetry.netlify.app/docs/security/
Thinking about the "where to put this" once again: We now have established /docs/security/ and have the CVE there and will also have more content like https://github.com/open-telemetry/opentelemetry.io/pull/3675 as well. This PR contains security guidelines for the collector, so we have technically 2 places to house this:
/docs/security/collector/docs/collector/security
I think we should go for option (2) but at the same time add a "Practices" page under /docs/security/practices that will list collector (and later other components as well) and link back to the component specific security, wdyt?
Thinking out "loud", there are two moments I'm concerned about security for my collector:
- when evaluating the collector
- when hardening it right before going into production
For the first situation, I'd prefer the security documentation to be close to the getting started, so that I can have an idea whether the collector satisfies my security needs. During the second situation, I think I'd prefer it close to the collector documentation again, as I probably don't care about the security aspects of the SDK or other parts.
In summary: I'm with you that placing it closer to the collector makes sense, as long as there's a reference to it from within the /security pages.
@svrnm My question is why not have the content in both locations? (This may not be possible with the functionality/architecture of the OTel docs site, but I still ask the question.)
I agree that when setting up the OTel Collector, information on securing your OTel Collector is very relevant and should exist within the OTel Collector documentation.
In the original vision by establishing this Security section, we're also:
- trying to highlight to potential OTel adopters that you can be secure and open source.
- encouraging security best practices related to OpenTelemetry...beyond the OTel Collector.
@svrnm My question is why not have the content in both locations? (This may not be possible with the functionality/architecture of the OTel docs site, but I still ask the question.)
We can certainly do this (somehow), but this often comes with some additional questions: is this a redirect (so people go from /security to /collector), is it just the same content presented at 2 places, what is the point where this list outgrows that (I assume that we eventually will have security best practices across the docs).
To make it short: yes, we can do that, but we might reconsider it eventually.
I agree that when setting up the OTel Collector, information on securing your OTel Collector is very relevant and should exist within the OTel Collector documentation.
In the original vision by establishing this Security section, we're also:
1. trying to highlight to potential OTel adopters that you can be secure and open source. 2. encouraging security best practices related to OpenTelemetry...beyond the OTel Collector.
This seems to be untouched by the decision where this content lives. Even if we have it only in the collector section I would want to have a /security/practices page that gives a general overview and then links out to relevant pages like the collector security pages.
@mjingle Thanks SO much for starting this. This is necessary. Hope you'll find my suggestions useful.
All: I've rebased & resolved conflicts so that we can get a fresher view of this addition in the context of the updated website -- a lot has changed since this was submitted! :)
@mjingle LMK if you need to discuss the draft or need more direct support — my comments are not meant to be blockers. Would be happy to commit to your fork if you want.