# Deploy an ELK Stack

For reference on the ELK stack, see [the docs](https://www.elastic.co/what-is/elk-stack).

## Prerequisites

1. An existing Grey Matter deployment running on Kubernetes ([tutorial](https://greymatter.gitbook.io/grey-matter-documentation/1.3/installation/installation-kubernetes))
2. `kubectl` or `oc` setup with access to the cluster
3. `greymatter` cli [setup](https://greymatter.gitbook.io/grey-matter-documentation/1.3/installation/commands-cli) with access to the deployment

## Steps

### 1. Clone and configure

If you have not already, clone the [Grey Matter helm-charts repository](https://github.com/greymatter-io/helm-charts) and cd into it:

```bash
git clone --single-branch --branch release-2.3 https://github.com/greymatter-io/helm-charts.git && cd ./helm-charts
```

If you installed Grey Matter using the [installation guide](https://greymatter.gitbook.io/grey-matter-documentation/1.3/installation/installation-kubernetes), and your core Grey Matter services are running in the `default` namespace, move on to [install](#2-install).

> If your core Grey Matter services are running in a Kubernetes namespace other than `default`, edit the file [`custom-values-files/kibana-proxy-values.yaml`](https://github.com/greymatter-io/helm-charts/blob/16f8c712f95e6b922a4c133edd8348c49269f231/observables/custom-values-files/kibana-proxy-values.yaml#L10) in your cloned repo, and change the `sidecar.envvars.xds_host` value to `control.<your-gm-namespace>.svc`.

### 2. Install

Run the following from the root directory of the helm-charts to install the ELK stack into a namespace `observables`:

```bash
make observables EKS=true
```

> If you want to install the ELK stack into a different namespace, or your Grey Matter deployment is not running in EKS, modify the command to `make observables EKS=<true or false> OBSERVABLES_NAMESPACE=<desired-namespace>`

The ELK stack may take up to 15 minutes to stabilize. You can check the status with:

```bash
kubectl get pods -n observables
```

While it starts up, move on to [step 3](#3-upgrade-grey-matter-for-the-observables-namespace).

### 3. Upgrade Grey Matter for the observables namespace

To allow Grey Matter Fabric to discover the observables namespace, open the `global.yaml` file you originally used when [installing Grey Matter](https://greymatter.gitbook.io/grey-matter-documentation/1.3/installation/installation-kubernetes). Edit the `global.control.additional_namespaces` value and add `observables`:

```yaml
global:
  control:
    ...
    additional_namespaces: observables
```

Then, upgrade your Grey Matter fabric and sense installations for the new namespace:

```bash
helm upgrade fabric greymatter/fabric -f global.yaml --set=global.environment=eks
helm upgrade sense greymatter/sense -f global.yaml --set=global.environment=eks --set=global.waiter.service_account.create=false
```

### 4. Configure the Kibana proxy in the mesh

Now, to configure the Kibana proxy with the mesh, run the following to generate the mesh configurations:

```bash
pathogen generate 'git@github.com:greymatter-io/pathogen-greymatter//all?ref=release-2.3'  kibana-observables-proxy/
```

Answer the prompts as follows:

1. serviceName = `kibana-observables-proxy`
2. serviceHost = `kibana-kibana.observables.svc.cluster.local` - if you changed the namespace, replace `.observables.` with `.<your-namespace>.`
3. servicePort = `5601`
4. sidecarIngressPort = `10808`
5. sidecarEgressPort = `10909`
6. trustDomain = `quickstart.greymatter.io`
7. zone = `zone-default-zone`
8. displayName = `Kibana Observables Proxy`
9. version = `7.1.0`
10. owner = `kibana`
11. capability = `observables`
12. documentation = `/services/kibana-observables-proxy/7.1.0`
13. minInstances = `1`
14. maxInstances = `1`

The configurations will be saved into a directory `kibana-observables-proxy`, make sure that your [cli is configured](https://greymatter.gitbook.io/grey-matter-documentation/1.3/installation/commands-cli) and control-api is accessible on port `5555`. When ready, run the following to apply them:

```bash
cd kibana-observables-proxy
./apply.sh
cd ..
```

You should then be able to see the card `Kibana Observables Proxy` on your Grey Matter application, and access it via the documentation link.

### 5. Verify

Once all of the pods are running in the `observables` namespace, and you can access the Kibana proxy at the documentation link from the Grey Matter application, you have successfully installed the ELK stack! Move on to [configure audits](https://greymatter.gitbook.io/grey-matter-documentation/1.3/guides/security-guides/audits/configure-audits).

```bash
$ kubectl get pods -n observables
NAME                                       READY   STATUS    RESTARTS   AGE
elasticsearch-master-0                     1/1     Running   0          11m
kafka-observables-0                        1/1     Running   2          11m
kafka-observables-1                        1/1     Running   2          11m
kafka-observables-2                        1/1     Running   1          11m
kafka-observables-zookeeper-0              1/1     Running   0          11m
kafka-observables-zookeeper-1              1/1     Running   0          11m
kafka-observables-zookeeper-2              1/1     Running   0          11m
kibana-kibana-56b5c6f578-4rwx6             1/1     Running   0          11m
kibana-observables-proxy-9df87ff86-cd7r8   1/1     Running   0          11m
logstash-logstash-0                        1/1     Running   0          11m
```

## Questions

{% hint style="success" %}
Create an account at [Grey Matter Support](https://support.greymatter.io/support/home) to reach our team.
{% endhint %}