need Fleet docs for creating new & modifying existing Agent and Integration Policies

[EricDavisX]

we have an example of adding nginx to the default policy here:
https://www.elastic.co/guide/en/fleet/current/fleet-quick-start.html

• but it isn't very explicit and it isn't called out as clearly in the docs (it is in only in the quick-start) so I think a separate section is likely warranted. or we can expand or just link back to the quick start for a quick win if we want.

I got asked in an SDH how to create a new policy, was the impetus for this, not sure if they had read the docs or not, but I wanted a better answer if I was going to tell someone to 'read the docs'.

we have a section called Policy Settings which sounds exaxctly what I was looking for but it just says 'it is in the UI' while it focused on stand-alone agent. So, this below may be where we want to add it I suppose? or where we need to make sure we are linking to wherever we end up creating it: https://www.elastic.co/guide/en/fleet/current/elastic-agent-configuration.html'

[EricDavisX]

Here is some text I basically wrote up for the SDH I was working where they asked about this functionality, if we can use it? It is accurate as of 7.11.x UI (tho it hasn't changed in 8.0 that I know of and should apply to 7.10, too):

The below steps outline how a user can navigate in the Fleet application and create a new Agent policy [1] and then apply the new policy to a set of Agents [2] and then add (for example) the Elastic Security integration to the new Agent policy [3]

1. If you wish to create a new Policy, browse to the Fleet App in Kibana. This is recommended, as leaving Default Agent policy alone reserves it as a useful comparison tool if problems should arise later on. So, click on 'Policies'. Then click the button on the right 'Create agent policy'. A flyout then appears. Only a policy name is required, and usually leaving the defaults as set is ok at this state (they can be modified later). After adding a name, then press 'Create agent policy' button on bottom right of the flyout. The flyout will close and Fleet will update to show the new policy in the list.

2. The new policy as created above has only the 'System' integration in it. So we can apply it to the desired Agents and confirm it is healthy before moving forward. To do this, click on the 'Agents' tab in Fleet. Then use the check-boxes on the left to select the Agent or Agents you want to use the new policy. When one or more is selected the 'bulk action' menu drop down will appear with '1 agent selected' (or however many are selected) and the down arrow indicating it can be clicked. Click the down arrow and select 'Assign to new policy'. This opens the policy selector flyout. Select the newly created policy and press the 'Assign policy' button on the bottom right of the flyout. This assigns the policy and the flyout closes. At this point it may take a few minutes for this to complete. You should see a status in the Agent Details or Agent logs indicating the policy is applying, and it will be 'healthy' when all is completed, if there are no problems.

3. Presuming the Agent is healthy, new Integration can be added to the policy, one at a time. Do this by going to the Policies page and click on the name of the new policy. On this page you should see the System integration listed. Click on the button on the right hand side that says 'Add integration'. The 'add integration' dialog shows now. Type in 'Elastic Security' or scroll to browse until you see it, then click on it to begin adding this Integration and it's relating Integration Policy to the new Agent policy. You must give it a name, type in something descriptive and you can press 'Save integration'. This will save the Integration Policy as part of the larger Agent Policy, and since it is updated (now) Fleet will send the new Agent policy to all Agents that are enrolled with it. This includes the hosts we just selected in step 2. They should update again. When the policy is finished applying the Elastic Security process will be running on the host and will be communicating with the Elastic Agent to protect the host!

4. To change the name or other settings of an Integration, or to delete it from the Policy entirely, the same basic steps are followed as in step 3 above. A user can click on the policy and then click the 'Actions' menu option on the right and select either 'Edit integration' or 'Delete integration' as desired. Editing or deleting an integration cannot be 'undone' but of course you can always re-add the Integration or change the settings back as you desire them. In either case, the new policy changes are immediately applied to all Agents enrolled with the given policy. For this example, let us click 'Edit integration' option on the line for the 'System' Integration listing. This opens the Integration policy editing page. Here, for the System integration a user can edit the name, and data namespace used, and the options to collect system instance metrics (and which ones) or collect various system instance logs. If you cancel, nothing is changed. But, if you press 'Save integration' the Integration policy is updated and the overall Agent policy is applied again to all Agent that are enrolled to that policy.

5. Separately, there are Agent policy settings that are exposed on the 'settings' tab when viewing the given policy. The settings here are basic Agent components and apply along with any added Integrations setup. The Agent policy name can be modified here, along with a given namespace, the ability to collect Metrics on the Agent process itself, and the desire for Agent's logs to be sent into Elasticssearch, for monitoring, of course.

6. Finally, when on the Agent policy view in Fleet, a user can make a copy of or view the yaml text that makes up the policy definition as it is sent to the Agents. To view the yaml details or copy a policy, click the 'Actions' drop down on the top right of the UI and select your choice. When viewing the policy yaml, you can see the current version of each Integration used. Each Policy can have different versions of the Integration in use, but they generally should be kept in sync (and up-to-date) except when first trying a new Integration version. The version information is listed under the 'inputs' section in the yaml, then under 'meta', 'package', and 'version'. Find the version that is direction below the relating package 'name' you are interested in. This is useful when evaluating if you wish to update and evaluate using a newly released Integration version, discussed in separate documentation.

[EricDavisX]

I added some relating additional content to the above 271...should we combine the 2 together?

[EricDavisX]

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

[bmorelli25]

Closed in #469.