Add mutual TLS docs

[kilfoyle]

Thanks for the nice draft @nimarezainia! I made only very, very small changes.

@AndersonQ and @michel-laterman Let me know if you're not the right folks to review this. I'm not sure who worked on the feature.

Please see Docs Preview

There are also some mTLS docs changes in #1099

Closes: #1131

[github-actions]

A documentation preview will be available soon.

• 🔨 Buildkite builds
• 📚 HTML diff
• 📙 Preview page

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.}

[nimarezainia]

@michel-laterman @AndersonQ would you mind reviewing these to ensure accuracy with what we have in code. TIA

[AndersonQ]

Folks, here are my 2 (or 22) cents.

There are a few disparities between what is written and how things actually happen or are. Those I marked with [Blocker], they need to be addressed or [Blocker-ish] I'd rather see them addressed, but if you understand my point and still believe the current version is good, I won't make a stand.

The ones marked with [Suggestion] are exactly that, suggestions, feel free to ignore, no need to explain to me why.

Also I've put some suggested changes, those are just suggestion, feel free to use whatever wording you find more appropriated. I just used it as a tool to make my point clear rather than asking it to b taken as I put.

[kilfoyle]

Thanks for the excellent review @AndersonQ! 🙏
I've addressed all of your comments, most of them exactly as suggested.

[AndersonQ]

@kilfoyle my bad here, I should have explained better about the configuration name/key/flag.

Actually I've just realised the design doc was wrong as well, it's fixed now.

When it's a cli parameter or flag, it's in the form --+name-of-the-flag (--name-of-the-flag).

For the policy, it's a YAML path like some.yaml.path.to.my_config_name.

Below are the correct forms

tl;dt

• in the policy (the one for the advanced YAML box):

ssl.certificate_authorities:
  - /path/to/ca
ssl.certificate: /path/to/cert
ssl.key: /path/to/cert_key

# OR

  ssl:
    certificate_authorities:
      - /path/to/ca
    certificate: /path/to/cert
    key: /path/to/cert_key

• for the cli (install/enroll cmd)

--certificate-authorities
--elastic-agent-cert
--elastic-agent-cert-key

--certificate-authorities # this is the same cli flag as the one above
--fleet-server-cert
--fleet-server-cert-key

--fleet-server-es-ca
--fleet-server-es-cert
--fleet-server-es-cert-key

I suggested a fix for the 1st set of cli flags and there are 2 other minor comments

[kilfoyle]

@AndersonQ this is great. I've fixed up all of the settings as you suggested.

For the policy settings that go in the "advanced YAML" box, I updated the screen capture so the example uses the correct format, and I also added the following in that section of the page, so that people will be sure to know what format to use:

[kilfoyle]

@AndersonQ When you have some time can you please give this one a final check?

[nimarezainia]

@AndersonQ in context of this issue - could you please provide the updated cli flag description that you envisage so that the docs can reference the ideal description text and whoever takes over the issue can update the helper text according to what we place in the docs.

cc: @pierrehilbert

[pierrehilbert]

@AndersonQ is on SDH rotation this week, unless the week is really noisy from that perspective, he should have time to do the final check soon.

[AndersonQ]

sorry for the delay, the SDHs were keeping me quite busy, it's approved now.

[pierrehilbert]

Thanks @AndersonQ
@kilfoyle we are now good to go.

[AndersonQ]

@AndersonQ in context of this issue - could you please provide the updated cli flag description that you envisage so that the docs can reference the ideal description text and whoever takes over the issue can update the helper text according to what we place in the docs.

cc: @pierrehilbert

I updated elastic/elastic-agent#5037 with a proposed changes and opened elastic/elastic-agent#5048

[kilfoyle]

Brilliant! Thanks a lot @AndersonQ!