[docs] Add and improve SSL/TLS documentation

[bmorelli25]

Closes #1579.
A preview of the changes made in this PR is available here.

I'm beginning to remember why this issue has been open for almost a year. We are at the mercy of Beats formatting of the Securing {beatname_uc} section. I'm not sure these changes would've been possible before Asciidoctor.

This PR adds quite a bit of complexity to the shared Beats files. It's unfortunate, but we've needed this documentation for a long time, so it's probably necessary.

The proposed layout is:

• Configuring APM Server
  • ...
  • SSL/TLS settings
    • SSL output settings
    • SSL input settings
  • ...
• Securing APM Server
  • Secure communication with APM Agents
  • Secure communication with Elasticsearch
  • Secure communication with Logstash by using SSL
  • Use X-Pack security
  • Use Linux Secure Computing Mode (seccomp)

Changes in this PR also need to be persisted in the Beats repo.

[bmorelli25]

Alrighty, here's a rough draft. It'd be great to get a review from @simitt when you have some time. @axw, I've tagged you as well since you opened the issue. If you have time, feel free to leave your thoughts too!

[axw]

Thank you @bmorelli25!

A few preliminary thoughts:

• we have "SSL output settings" at the same level as "Secure communication with Elasticsearch" and "Secure communication with Logstash by using SSL", so it's not really clear where I should get my info
• likewise "SSL input settings" and "Secure communication with APM Agents"
• The "by using SSL" in "Secure communication with Logstash by using SSL" is a bit incongruous with Elasticsearch/APM Agents

Are those fixable, or are they the things for which we're at the mercy of Beats?

I'm not 100% on this, but would it be better if "SSL output settings" and "SSL input settings" were under "Configuring APM Server", since they're fairly low-level descriptions of the config attributes? That would leave "Securing APM Server" for higher level guides. We could then cross-reference them.

[bmorelli25]

The "by using SSL" in "Secure communication with Logstash by using SSL" is a bit incongruous with Elasticsearch/APM Agents

I'm not sure why Beats chose this naming convention. You're right that it doesn't fit with the other two. I'll propose the change in Beats!

• we have "SSL output settings" at the same level as "Secure communication with Elasticsearch" and "Secure communication with Logstash by using SSL", so it's not really clear where I should get my info
• likewise "SSL input settings" and "Secure communication with APM Agents"

would it be better if "SSL output settings" and "SSL input settings" were under "Configuring APM Server"

This is a good point. My thought process was that having everything under the securing section would make the most sense -- one stop shopping if you will. But you're right, with the heading levels it is a bit confusing to figure out where to start. Let me try moving these two files to the "Configuring APM Server" section and we can see how that looks.

[bmorelli25]

Actually, that was a pretty easy move since I already understood the complexities. I've updated the description of this PR to include the new layout. I even got to use :leveloffset: 🎉 for the first time: 0d0ca91#diff-8030d30c800b13aa90b7f19b29e67665R38

[simitt]

Not directly part of this PR but in Securing Communication With Elasticsearch there is this sentence:

You can also configure it to use client authentication by specifying the certificate and key to use when the server requires the Beat to authenticate.

It is hard to understand for APM Server as the mentioned server is the one APM Server talks to. I suggest to change Beat to APM Server:

You can also configure it to use client authentication by specifying the certificate and key to use when the server requires the APM Server to authenticate.

[axw]

I find this structure much easier to navigate - thank you.

[bmorelli25]

Thanks for the feedback @axw and @simitt!

Silvia, sorry, a lot of those were dumb mistakes. Thanks for catching them 😇. I have one clarifying question above.

It is hard to understand for APM Server as the mentioned server is the one APM Server talks to. I suggest to change Beat to APM Server:

Good spot -- updated to {beatname_uc}.

[simitt]

Looks great! Once again - really like the new docs structure you build here.

[axw]

Thank you, this is a great improvement :)

[bmorelli25]

jenkins, run tests again please

[bmorelli25]

@elasticmachine, run elasticsearch-ci/docs rebuild

[bmorelli25]

jenkins, run tests again please

[bmorelli25]

Added to elastic/beats#13596 to persist the shared changes in the Beats repo.