Add OTel Collector Security Best Practices to OTel Docs Site

[mjingle]

Desired feature or idea:

The OTel Collector repo contains a Security Best Practices document. This information is very useful and should be included in the OTel Docs site rather than hidden in a repo file.

Including this information is helpful in that it sets expectations, gives an opinion, and provides important security information to OTel Collector users.

Additional context:

I know the file itself is written with a repository lens, for example with mentions of specific issues, so depending on preference, some editorial work may be required before publishing.

Suggestion: to reduce maintenance, the repository file could be linked into the OTel docs site, so whenever the repository file is updated, the website version is also updated.

[cartermp]

Great idea - we should definitely have this documented on the site.

[chalin]

I'd rather not bring in another submodule if we can, especially for a single page. Would it be conceivable to have the page reside in this repo?

[cartermp]

I'd much prefer that, yes. @open-telemetry/collector-approvers any thoughts?

[mx-psi]

We discussed this previously, I think my comment on #3227 (comment) still stands, IMO we should split the doc in two and have the user-focused part on the opentelemetry.io page

[mjingle]

To be clear, my suggestion to wire repos together is very much optional and intended to address potential concerns with maintainers keeping documentation up to date. I've encountered different preferences and solutions, but I totally understand the preference for less submodules.

I'm excited to see positive reception for this information to be in the public docs! Please let me know if there's anything I can do to keep moving this forward.

[svrnm]

@mjingle following @mx-psi's comment I think a good starting point would be taking a look at the current security documentation and extract what is user-facing and bringing it into a PR for the website.

[jpkrohling]

I agree that the end user part of the linked documentation should be placed exclusively under opentelemetry.io. The current file in the repository could link to the website while keeping the advice targeted to component developers.

[theletterf]

@mjingle Could you advance with the draft?

[mx-psi]

It would be nice to have this completed for the Collector v1 distro. I see this as a basic part of how to setup your Collector and think this should be documented when this happens, so I have added it to the Collector v1 project board

[svrnm]

@mjingle do you have time/bandwidth to work on this?

[tiffany76]

I've messaged @mjingle about this issue and to let her know I'm going to take over so we can get security documentation in place for v1.0. Hope to put up a fresh PR this week. Thanks!

[mx-psi]

Coming back to this: what is left to do here? One thing to do is to remove the info that now lives on the website from the github doc, is there anything else left?

[tiffany76]

@mx-psi, yes, that's exactly it. All that remains is to update the core repo README. I started work on that but got pulled into other things. I'll try to finish it up this week or next.