kibana/packages/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 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.

To run, go to the Kibana root and run `node scripts/es --help` to get the latest command line options.

The script attempts to preserve the existing interfaces used by Elasticsearch CLI. This includes passing through options with the `-E` argument and the `ES_JAVA_OPTS` environment variable for Java options.

### Examples

Run a snapshot install with a trial license
```
node scripts/es snapshot --license=trial
```

Run from source with a configured data directory
```
node scripts/es source --Epath.data=/home/me/es_data
```

## API

### run
Start a cluster
```
var es = require('@kbn/es');
es.run({
  license: 'basic',
  version: 7.0,
})
.catch(function (e) {
  console.error(e);
  process.exitCode = 1;
});
```

#### Options

##### options.license

Type: `String`

License type, one of: trial, basic, gold, platinum

##### options.version

Type: `String`

Desired elasticsearch version

##### options['source-path']

Type: `String`

Cloned location of elasticsearch repository, used when running from source

##### options['base-path']

Type: `String`

Location where snapshots are cached

## Snapshot Pinning

Sometimes we need to pin snapshots for a specific version. We'd really like to get this automated, but until that is completed here are the steps to take to build, upload, and switch to pinned snapshots for a branch.

To use these steps you'll need to setup the google-cloud-sdk, which can be installed on macOS with `brew cask install google-cloud-sdk`. Login with the CLI and you'll have access to the `gsutil` to do efficient/parallel uploads to GCS from the command line.

 1. Clone the elasticsearch repo somewhere
 2. Checkout the branch you want to build
 3. Build the new artifacts

    ```
    node scripts/es build_snapshots --output=~/Downloads/tmp-artifacts --source-path=/path/to/es/repo
    ```

 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/
    ```

 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
    if (!process.env.KBN_ES_SNAPSHOT_URL && !process.argv.some(isVersionFlag)) {
      // return undefined;
      return 'https://storage.googleapis.com/kibana-ci-tmp-artifacts/{name}-{version}-{os}-x86_64.{ext}';
    }
    ```

    For 6.8, the format of the url should look like:

    ```
    'https://storage.googleapis.com/kibana-ci-tmp-artifacts/{name}-{version}.{ext}';
    ```