From e6a9eaa4f899438ded4f8028984694131aace3f5 Mon Sep 17 00:00:00 2001
From: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
Date: Fri, 22 Sep 2023 11:37:59 -0400
Subject: [PATCH] [8.6] [DOCS] Adds shards object to Create pack and Update
 pack API (#166363) (#166627)

# Backport

This will backport the following commits from `main` to `8.6`:
- [[DOCS] Adds shards object to Create pack and Update pack API
(#166363)](https://github.com/elastic/kibana/pull/166363)

<!--- Backport version: 8.9.7 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT
[{"author":{"name":"natasha-moore-elastic","email":"137783811+natasha-moore-elastic@users.noreply.github.com"},"sourceCommit":{"committedDate":"2023-09-18T13:55:57Z","message":"[DOCS]
Adds shards object to Create pack and Update pack API (#166363)\n\n##
Summary\r\n\r\n- Resolves
https://github.com/elastic/security-docs/issues/3822 \r\n\r\nAdds the
`shards` object schema definition to Create pack and Update\r\npack API,
and to the Create pack request example.\r\n\r\n- Related dev PR:
https://github.com/elastic/kibana/pull/166178","sha":"0215ed3a0f54823b816fc24d5efa931cd1d55b10","branchLabelMapping":{"^v8.11.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Docs","release_note:skip","v8.6.0","v8.7.0","v8.8.0","v8.9.0","v8.10.0","v8.11.0"],"number":166363,"url":"https://github.com/elastic/kibana/pull/166363","mergeCommit":{"message":"[DOCS]
Adds shards object to Create pack and Update pack API (#166363)\n\n##
Summary\r\n\r\n- Resolves
https://github.com/elastic/security-docs/issues/3822 \r\n\r\nAdds the
`shards` object schema definition to Create pack and Update\r\npack API,
and to the Create pack request example.\r\n\r\n- Related dev PR:
https://github.com/elastic/kibana/pull/166178","sha":"0215ed3a0f54823b816fc24d5efa931cd1d55b10"}},"sourceBranch":"main","suggestedTargetBranches":["8.6","8.7","8.8","8.9","8.10"],"targetPullRequestStates":[{"branch":"8.6","label":"v8.6.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.7","label":"v8.7.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.8","label":"v8.8.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.9","label":"v8.9.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.10","label":"v8.10.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v8.11.0","labelRegex":"^v8.11.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/166363","number":166363,"mergeCommit":{"message":"[DOCS]
Adds shards object to Create pack and Update pack API (#166363)\n\n##
Summary\r\n\r\n- Resolves
https://github.com/elastic/security-docs/issues/3822 \r\n\r\nAdds the
`shards` object schema definition to Create pack and Update\r\npack API,
and to the Create pack request example.\r\n\r\n- Related dev PR:
https://github.com/elastic/kibana/pull/166178","sha":"0215ed3a0f54823b816fc24d5efa931cd1d55b10"}}]}]
BACKPORT-->

Co-authored-by: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com>
---
 docs/api/osquery-manager/packs/create.asciidoc | 14 ++++++++++++--
 docs/api/osquery-manager/packs/update.asciidoc |  2 ++
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/docs/api/osquery-manager/packs/create.asciidoc b/docs/api/osquery-manager/packs/create.asciidoc
index 5f9829164b245..2fcfc58d43dba 100644
--- a/docs/api/osquery-manager/packs/create.asciidoc
+++ b/docs/api/osquery-manager/packs/create.asciidoc
@@ -33,6 +33,8 @@ experimental[] Create packs.
 
 `policy_ids`:: (Optional, array) A list of agents policy IDs.
 
+`shards`:: (Required, object) An object with shard configuration for policies included in the pack. For each policy, set the shard configuration to a percentage (1–100) of target hosts.
+
 `queries`:: (Required, object) An object of queries.
 
 
@@ -56,8 +58,13 @@ $ curl -X POST api/osquery/packs \
   "description": "My pack",
   "enabled": true,
   "policy_ids": [
-    "my_policy_id"
+    "my_policy_id",
+    "fleet-server-policy"
   ],
+  "shards": {
+    "my_policy_id": 35,
+    "fleet-server-policy": 58
+  },
   "queries": {
     "my_query": {
       "query": "SELECT * FROM listening_ports;",
@@ -67,7 +74,10 @@ $ curl -X POST api/osquery/packs \
           "field": "port"
         },
         "tags": {
-          "value": ["tag1", "tag2"]
+          "value": [
+            "tag1",
+            "tag2"
+          ]
         }
       }
     }
diff --git a/docs/api/osquery-manager/packs/update.asciidoc b/docs/api/osquery-manager/packs/update.asciidoc
index 0fc2e2684e0e9..d098d2567f1ac 100644
--- a/docs/api/osquery-manager/packs/update.asciidoc
+++ b/docs/api/osquery-manager/packs/update.asciidoc
@@ -38,6 +38,8 @@ WARNING: You are unable to update a prebuilt pack (`read_only = true`).
 
 `policy_ids`:: (Optional, array) A list of agent policy IDs.
 
+`shards`:: (Optional, object) An object with shard configuration for policies included in the pack. For each policy, set the shard configuration to a percentage (1–100) of target hosts.
+
 `queries`:: (Required, object) An object of queries.