From 71652fb45c7b45c1d1a5bb6863bfbf067c7faa1b Mon Sep 17 00:00:00 2001
From: Tiago Costa <tiago.costa@elastic.co>
Date: Fri, 3 Jun 2022 02:44:56 +0100
Subject: [PATCH] docs(NA): adds @kbn/es into ops devdocs (#133353)

---
 dev_docs/operations/operations_landing.mdx    |  3 +-
 nav-kibana-dev.docnav.json                    |  3 +-
 packages/kbn-es/BUILD.bazel                   |  1 -
 packages/kbn-es/{README.md => README.mdx}     | 42 +++++++------------
 .../src/cli_commands/build_snapshots.js       | 12 +++++-
 5 files changed, 29 insertions(+), 32 deletions(-)
 rename packages/kbn-es/{README.md => README.mdx} (70%)

diff --git a/dev_docs/operations/operations_landing.mdx b/dev_docs/operations/operations_landing.mdx
index 165421deb8430..b9e68beb9637e 100644
--- a/dev_docs/operations/operations_landing.mdx
+++ b/dev_docs/operations/operations_landing.mdx
@@ -50,6 +50,7 @@ layout: landing
     { pageId: "kibDevDocsOpsAmbientUiTypes" },
     { pageId: "kibDevDocsOpsTestSubjSelector" },
     { pageId: "kibDevDocsOpsBazelRunner" },
-    { pageId: "kibDevDocsOpsCliDevMode" }
+    { pageId: "kibDevDocsOpsCliDevMode" },
+    { pageId: "kibDevDocsOpsEs" },
   ]}
 />
\ No newline at end of file
diff --git a/nav-kibana-dev.docnav.json b/nav-kibana-dev.docnav.json
index 0a2f2c4e3b6f1..1473bf4d59a0e 100644
--- a/nav-kibana-dev.docnav.json
+++ b/nav-kibana-dev.docnav.json
@@ -206,7 +206,8 @@
             { "id": "kibDevDocsOpsAmbientUiTypes" },
             { "id": "kibDevDocsOpsTestSubjSelector" },
             { "id": "kibDevDocsOpsBazelRunner" },
-            { "id": "kibDevDocsOpsCliDevMode" }
+            { "id": "kibDevDocsOpsCliDevMode" },
+            { "id": "kibDevDocsOpsEs" }
           ]
         }
       ]
diff --git a/packages/kbn-es/BUILD.bazel b/packages/kbn-es/BUILD.bazel
index 2ea9c32858dd3..892cd43244de7 100644
--- a/packages/kbn-es/BUILD.bazel
+++ b/packages/kbn-es/BUILD.bazel
@@ -24,7 +24,6 @@ filegroup(
 
 NPM_MODULE_EXTRA_FILES = [
   "package.json",
-  "README.md",
 ]
 
 RUNTIME_DEPS = [
diff --git a/packages/kbn-es/README.md b/packages/kbn-es/README.mdx
similarity index 70%
rename from packages/kbn-es/README.md
rename to packages/kbn-es/README.mdx
index 80850c9e6a09c..a5392504490fe 100644
--- a/packages/kbn-es/README.md
+++ b/packages/kbn-es/README.mdx
@@ -1,6 +1,13 @@
-# @kbn/es
+---
+id: kibDevDocsOpsEs
+slug: /kibana-dev-docs/ops/es
+title: "@kbn/es"
+description: A cli package for running elasticsearch or building snapshot artifacts
+date: 2022-05-24
+tags: ['kibana', 'dev', 'contributor', 'operations', 'es']
+---
 
-> A command line utility for running elasticsearch from source or archive.
+> A command line utility for running elasticsearch from snapshot, source, archive or even building snapshot artifacts. 
 
 ## Getting started
 If running elasticsearch from source, elasticsearch needs to be cloned to a sibling directory of Kibana.
@@ -71,41 +78,20 @@ To use these steps you'll need to setup the google-cloud-sdk, which can be insta
 
  1. Clone the elasticsearch repo somewhere
  2. Checkout the branch you want to build
- 3. Run the following to delete old distributables
+ 3. Build the new artifacts
 
     ```
-    find distribution/archives -type f \( -name 'elasticsearch-*-*.tar.gz' -o -name 'elasticsearch-*-*.zip' \) -not -path *no-jdk* -exec rm {} \;
+    node scripts/es build_snapshots --output=~/Downloads/tmp-artifacts --source-path=/path/to/es/repo
     ```
 
- 4. Build the new artifacts
-
-    ```
-    ./gradlew -p distribution/archives assemble --parallel
-    ```
-
- 4. Copy new artifacts to your `~/Downloads/tmp-artifacts`
-
-    ```
-    rm -rf ~/Downloads/tmp-artifacts
-    mkdir ~/Downloads/tmp-artifacts
-    find distribution/archives -type f \( -name 'elasticsearch-*-*.tar.gz' -o -name 'elasticsearch-*-*.zip' \) -not -path *no-jdk* -exec cp {} ~/Downloads/tmp-artifacts \;
-    ```
-
- 5. Calculate shasums of the uploads
-
-    ```
-    cd ~/Downloads/tmp-artifacts
-    find * -exec bash -c "shasum -a 512 {} > {}.sha512" \;
-    ```
-
- 6. Check that the files in `~/Downloads/tmp-artifacts` look reasonable
- 7. Upload the files to GCS
+ 4. Check that the files in `~/Downloads/tmp-artifacts` look reasonable
+ 5. Upload the files to GCS
 
     ```
     gsutil -m rsync . gs://kibana-ci-tmp-artifacts/
     ```
 
- 8. Once the artifacts are uploaded, modify `packages/kbn-es/src/custom_snapshots.js` in a PR to use a URL formatted like:
+ 6. Once the artifacts are uploaded, modify `packages/kbn-es/src/custom_snapshots.js` in a PR to use a URL formatted like:
 
     ```
     // force use of manually created snapshots until ReindexPutMappings fix
diff --git a/packages/kbn-es/src/cli_commands/build_snapshots.js b/packages/kbn-es/src/cli_commands/build_snapshots.js
index 070f11b8b5f84..b4a15a0645cce 100644
--- a/packages/kbn-es/src/cli_commands/build_snapshots.js
+++ b/packages/kbn-es/src/cli_commands/build_snapshots.js
@@ -6,6 +6,7 @@
  * Side Public License, v 1.
  */
 
+const dedent = require('dedent');
 const { resolve, basename } = require('path');
 const { createHash } = require('crypto');
 const { promisify } = require('util');
@@ -21,7 +22,16 @@ const pipelineAsync = promisify(pipeline);
 
 exports.description = 'Build and collect ES snapshots';
 
-exports.help = () => ``;
+exports.help = () => dedent`
+    Options:
+
+      --output          Path to create the built elasticsearch snapshots
+      --source-path     Path where the elasticsearch repository is checked out
+
+    Example:
+
+      es build_snapshots --source-path=/path/to/es/checked/repo --output=/tmp/es-built-snapshots
+  `;
 
 exports.run = async (defaults = {}) => {
   const argv = process.argv.slice(2);