Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add the Kubernetes Operator install instructions #1017

Merged
merged 4 commits into from
Sep 21, 2022
Merged

Add the Kubernetes Operator install instructions #1017

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d6eefb5
Add the Kubernetes Operator install instructions
Naarcha-AWS Aug 29, 2022
bc00ad1
Copy edits
Naarcha-AWS Aug 29, 2022
03e03f8
Add doc review
Naarcha-AWS Sep 15, 2022
975c25b
Add editorial
Naarcha-AWS Sep 21, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 145 additions & 0 deletions _clients/k8s-operator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
---
layout: default
title: OpenSearch Kubernetes Operator
nav_order: 210
---

The OpenSearch Kubernetes (K8s) Operator is an open-source K8s operator that helps automate the deployment, provisioning, of OpenSearch and OpenSearch Dashboards in a containerized environment. The operator can manage multiple OpenSearch clusters which can be scaled up and down depending on your needs.
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

## Installation

There are two ways to get started with the Operator:
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

- [Use a Helm chart](#use-a-helm-chartuse-a-helm)
- [Use a local installation](#use-a-local-installation)
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

### Use a Helm chart

If you use Helm to manage your K8s cluster, you can use the OpenSearch Kubernetes Operator's CNCF project stored in Artifact Hub, a web-based application for finding, installing, and publishing CNCF packages.
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

To begin, log into your K8s cluster and add the Helm repo from [Artifact Hub](https://opster.github.io/opensearch-k8s-operator/).
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

```
helm repo add opensearch-operator https://opster.github.io/opensearch-k8s-operator/
```

Make sure that the repo is included in your K8s cluster.

```
helm repo list | grep opensearch
```

Both the `opensearch` and `opensearch-operator` repos appear on the list of repos.
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved


Install the manager that operates all of the OpenSearch Kubernetes Opeartor's actions.
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

```
helm install opensearch-operator opensearch-operator/opensearch-operator
```

After the install completes, the operator returns information on the deployment with the `STATUS: deployed`. Then you can configure and start your [OpenSearch cluster](#deploy-a-new-opensearch-cluster).
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

### Use a local installation
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why can't you use the helm chart just because you're running a local minikube cluster? i think these are separate topics:

  • how you run your k8s cluster (real cluster vs. minikube)
  • how you deploy the operator (helm vs. self-built)


If you want to create a new K8s cluster on your existing machine, use a local installation.

If this your first time running K8s and you intend on running through these instructions on your laptop, make sure that you have the following installed:
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

- [K8s](https://kubernetes.io/docs/tasks/tools/)
- [Docker](https://docs.docker.com/engine/install/)
- [minikube](https://minikube.sigs.k8s.io/docs/start/)

Before running through the installation steps, make sure that you have a K8s environment running locally. When using minikube, open a new terminal window and enter `minikube start`. K8s will now use a containerized minikube cluster with a namespace called `default`.

Then install the OpenSearch Kubernetes operating using the following steps:
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

1. In your preferred directory, clone the [OpenSearch Kubernetes Operator repo](https://github.com/Opster/opensearch-k8s-operator). `cd` into the repo directory.
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved
2. Go to the `opensearch-operator` folder.
3. Enter `make build manifests`.
4. Start a Kubernetes cluster. When using minikube, open a new terminal window and enter `minikube start`. K8s will now use a containerized minikube cluster with a namespace called `default`. Make sure that `~/.kube/config` points to the cluster.
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

```yml
apiVersion: v1
clusters:
- cluster:
certificate-authority: /Users/naarcha/.minikube/ca.crt
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you shouldn't include real paths / usernames in the documentation, it provides no added value and just causes confusion. (same applies to the other 2 places where you have your username in the example file)

extensions:
- extension:
last-update: Mon, 29 Aug 2022 10:11:47 CDT
provider: minikube.sigs.k8s.io
version: v1.26.1
name: cluster_info
server: https://127.0.0.1:61661
name: minikube
contexts:
- context:
cluster: minikube
extensions:
- extension:
last-update: Mon, 29 Aug 2022 10:11:47 CDT
provider: minikube.sigs.k8s.io
version: v1.26.1
name: context_info
namespace: default
user: minikube
name: minikube
current-context: minikube
kind: Config
preferences: {}
users:
- name: minikube
user:
client-certificate: /Users/naarcha/.minikube/profiles/minikube/client.crt
client-key: /Users/naarcha/.minikube/profiles/minikube/client.key
```

5. Enter `make install` to create the CRD that runs in your K8s cluster.
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved
6. Start the OpenSearch Kubernetes Operator. Enter `make run`.

## Verify K8s deployment

To ensure that K8s recognizes the OpenSearch Kubernetes Operator as a namespace, enter `k get ns | grep opensearch`. Both `opensearch` and `opensearch-operator-system` should appear as `Active`.

With the operator active, use `k get pod -n opensearch-operator-system` to make that the operator's pods are running.
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

```
NAME READY STATUS RESTARTS AGE
opensearch-operator-controller-manager-<pod-id> 2/2 Running 0 25m
```

With our K8s cluster running, we can now run OpenSearch inside the cluster.
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

## Deploy a new OpenSearch cluster
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it should be clearly noted that these are purely examples and are not production ready (using demo TLS certificates, etc.)


From your cloned OpenSearch Kubernetes Operator repo, navigate to the `opensearch-operator/examples` directory. There you'll find the `opensearch-cluster.yaml` file which can be customized to the needs of your cluster, including the `clusterName` that acts as the namespace your new OpenSearch cluster will reside.
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

With your cluster configured, run the `kubectl apply` command.

```
kubectl apply -f opensearch-cluster.yaml
```

The operator creates several pods, including a bootstrap pod, three OpenSearch cluster pods, and one Dashboards pod. To connect to your cluster, use the `port-forward` command.

```
kubectl port-forward svc/my-cluster-dashboards 5601
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

while i hope that people using k8s are aware of this, it might be worth noting that this is only done for demo purposes; in a real setup an Ingress resource (or Route on OpenShift) must be set up to have a proper route available and not rely on port-forwarding

```

Open http://localhost:5601 in your preferred browser and login with the default demo credentials `admin / admin`. You can also run curl commands against the OpenSearch REST API by forwarding to port 9200.
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

```
kubectl port-forward svc/my-cluster 9200
```

In order to delete the OpenSearch cluster, delete the cluster resources. The following command deletes the cluster namespace and all its resources.

```
kubectl delete -f opensearch-cluster.yaml
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if this also deletes the PVCs (= the data) then you should add a big fat warning as this will be a non-reversible option with data loss (which may or may not be intentional)!

```

## Next steps

To learn more about how to customize your K8s OpenSearch cluster, including Data Persistence, auth methods, and scaling, see the [OpenSearch Operator User Guide](https://github.com/Opster/opensearch-k8s-operator/blob/main/docs/userguide/main.md).
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

If you want to contribute to the development of the OpenSearch Kubernetes Operator, see the repo [design documents](https://github.com/Opster/opensearch-k8s-operator/blob/main/docs/designs/high-level.md).