Add new topic about agent policies

[dedemorton]

Add a topic to the Fleet docs that describes:

What a policy is
How it's used
How to create a policy
Etc

[EricDavisX]

I'm working on some policy info in other tickets and as it relates, I can start writing some thoughts for this. And we can make @ph review / chime in to make it awesome as possible. My goal is to get this started, then #394 confirmed and then #395 all in succession. :)

[EricDavisX]

What is a Policy?
An Agent Policy is a collection of inputs and relating settings that comprise what data will be sent by the processes being run by Agent. An Agent can only be enrolled to a single Policy at one time. In more details, an Agent Policy typically consists of a set of individual Integration Policies (the inputs), which is where the actual settings reside. The available settings in an Integration relate to the version of the Integration in use, newer functionality can be exposed in this manner over time. A Policy can be represented in plain-text yaml format and is sent down to the Agent as such. A Policy can be viewed in Kibana in the Fleet 'Policies' section in the Policies list. When viewing an individual Agent Policy details will show as to what Integrations are configured and more.

How is a Policy used?
An Agent Policy is used in 2 main ways in the Fleet app. 1) It allows a user to see a visual representation of the configuration to be sent to one or more Agents, in the Fleet UI. And 2) It is stored in a text format and sent to the Agent to configure the Filebeat and Metricbeat inputs.

But that doesn't inform on how one should logically think about Policies and why. They allow to indicate an intended logical grouping of inputs aimed for a particular set of hosts. For example, it may benefit users to set up an Agent Policy per OS type (Windows, macOS, and Linux hosts) or by functional groupings of how the hosts are used (IT Email servers, Linux servers, user work-stations), or by user categories (Engineering department, Marketing Department, and more). The value in having multiple Agent Policies is that you maintain the flexibility in large scale deployments to do both of testing changes before rolling them out to hosts, and to manage larger swaths of the infrastructure landscape at the same time.

---

How / Where to create a policy (or edit or delete)? This is covered in #394 - we could condense them into one issue, if easier? Anyhow, this is a small initial brain dump and between the 3 relating issues gives users better understanding of the what, where, how, why of Agent policies.

[EricDavisX]

to achieve this, when we say we want a new 'topic' does that translate to a new top level docs url/route we will use like here?
https://www.elastic.co/guide/en/fleet/current/elastic-agent-installation-configuration.html
...which seems to map to this file:
https://github.com/elastic/observability-docs/blob/master/docs/en/ingest-management/elastic-agent/elastic-agent.asciidoc

I can do up the new files in a new folder in git, if that is desired or the same folder? I don't know how or from where that macro is defined to link to the docs page above, but I can do some leg work if you want @dedemorton . I don't mind so long as it isn't going down the wrong path. :)

[EricDavisX]

@dedemorton when you get a chance, let me know if I'm on the right track. If you want to hold off in general that is ok, but if it is easy enough to help guide me and we want to do it with the current structure of files I am happy to help now, or later on.

[dedemorton]

@EricDavisX This is a simple question with a complex answer.

tl;dr: Let's create the topic about agent policies at the top level (same level as "Manage Your Elastic Agents").

Here's why....

In the new doc system, the navigation structure (on the left) will be quite flat, so we'll need to start moving towards longer topics. The high-level navigation is still being discussed, but I expect the topics to live under a Management category somewhere (perhaps users will select Manage then expand Fleet to see all the relevant topics...still TBD). Users will also be able to filter by tags.

In this new system, most of the topics currently nested under "Manage Your Elastic Agents" (except the topics about policy settings and input configuration) will exist in a single, long scrolling topic with a robust right-hand nav that scrolls as you move through the page. Think of it as a one-stop shop for everything you need to know about installing, upgrading, and running Elastic Agent.

I want to do the same with other things that users need to manage, like agent policies and enrollment tokens. My thought is that there are two types of user goals: end-user goals around monitoring stuff (how do I get data in? how do I see it in Kibana? how do I set up alerts? etc) plus all the goals around managing stuff (how do I enroll an agent in fleet? how do I add a new policy? how do I modify an existing policy? how do I upgrade an agent? etc). For that second type of user, I want to organize the docs around the actual components that users need to manage. Does that make sense? I'm trying to focus on structuring the content around the questions that users will ask.

The two types of users I describe here might be one person, but IMO we should optimize the docs for the more common scenario. (Currently we tend to optimize for the simple use case where one person does everything.)

TBH, I've never created a system like this with very long scrolling pages because I feel it impacts SEO negatively. On the other hand, short, choppy topics with loads of links are also unhelpful. So I have an open mind!

[EricDavisX]

Sounds good to me, perfect answer. :) And I totally follow the reasoning, I'm sure it will be great.

• I'll try to take a stab at it, sometime soon!

[EricDavisX]

I may run out of time, but I'm going to try t put something up, even if ugly for us to talk about, for Agent Policies.

[EricDavisX]

hopefully we'll be able to resolve this from this pr:
#469

[bmorelli25]

Closed in #469.