From 5b5aa70df7438a22dcfe2cb6bbb0ee9772365fd1 Mon Sep 17 00:00:00 2001
From: Brandon Morelli <brandon.morelli@elastic.co>
Date: Mon, 6 Jul 2020 10:36:44 -0700
Subject: [PATCH] docs: add annotation user docs (#70265)

---
 docs/apm/api.asciidoc           |  1 +
 docs/apm/apm-app-users.asciidoc | 50 ++++++++++++++++++++++++++++++++-
 2 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/docs/apm/api.asciidoc b/docs/apm/api.asciidoc
index 54159b642dd1..2fbeea0534fc 100644
--- a/docs/apm/api.asciidoc
+++ b/docs/apm/api.asciidoc
@@ -355,6 +355,7 @@ allowing you to easily see how these events are impacting the performance of you
 
 By default, annotations are stored in a newly created `observability-annotations` index.
 The name of this index can be changed in your `config.yml` by editing `xpack.observability.annotations.index`.
+If you change the default index name, you'll also need to <<apm-app-annotation-user-create,update your user privileges>> accordingly.
 
 The following APIs are available:
 
diff --git a/docs/apm/apm-app-users.asciidoc b/docs/apm/apm-app-users.asciidoc
index 442a07d27972..d766c866f87e 100644
--- a/docs/apm/apm-app-users.asciidoc
+++ b/docs/apm/apm-app-users.asciidoc
@@ -4,7 +4,7 @@
 
 :beat_default_index_prefix: apm
 :beat_kib_app: APM app
-:annotation_index: `observability-annotations`
+:annotation_index: observability-annotations
 
 ++++
 <titleabbrev>Users and privileges</titleabbrev>
@@ -102,6 +102,54 @@ Here are two examples:
 ***********************************  ***********************************
 ////
 
+[role="xpack"]
+[[apm-app-annotation-user-create]]
+=== APM app annotation user
+
+++++
+<titleabbrev>Create an annotation user</titleabbrev>
+++++
+
+NOTE: By default, the `apm_user` built-in role provides access to Observability annotations.
+You only need to create an annotation user if the default annotation index
+defined in <<apm-settings-kb,`xpack.observability.annotations.index`>> has been customized.
+
+[[apm-app-annotation-user]]
+==== Annotation user
+
+View deployment annotations in the APM app.
+
+. Create a new role, named something like `annotation_user`,
+and assign the following privileges:
++
+[options="header"]
+|====
+|Type | Privilege | Purpose
+
+|Index
+|`read` on +\{ANNOTATION_INDEX\}+^1^
+|Read-only access to the observability annotation index
+
+|Index
+|`view_index_metadata` on +\{ANNOTATION_INDEX\}+^1^
+|Read-only access to observability annotation index metadata
+|====
++
+^1^ +\{ANNOTATION_INDEX\}+ should be the index name you've defined in
+<<apm-settings-kb,`xpack.observability.annotations.index`>>.
+
+. Assign the `annotation_user` created previously, and the built-in roles necessary to create
+a <<apm-app-reader-full,full>> or <<apm-app-reader-partial,partial>> APM reader to any users that need to view annotations in the APM app
+
+[[apm-app-annotation-api]]
+==== Annotation API
+
+See <<apm-app-api-user>>.
+
+////
+***********************************  ***********************************
+////
+
 [role="xpack"]
 [[apm-app-central-config-user]]
 === APM app central config user