Skip to content

Commit d9bc8d6

Browse files
siegfriedwebersiegfriedweber
authored
docs: Extend the documentation for OpenSearch Dashboards (#77)
1 parent 5d25107 commit d9bc8d6

File tree

10 files changed

+373
-37
lines changed

10 files changed

+373
-37
lines changed

‎docs/modules/opensearch/examples/getting_started/getting_started.sh‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -76,9 +76,9 @@ kubectl rollout status --watch statefulset/simple-opensearch-nodes-default --tim
7676
sleep 10
7777

7878
echo "Starting port-forwarding of port 9200"
79-
# tag::port-forwarding[]
79+
# tag::opensearch-port-forwarding[]
8080
kubectl port-forward services/simple-opensearch 9200 > /dev/null 2>&1 &
81-
# end::port-forwarding[]
81+
# end::opensearch-port-forwarding[]
8282
PORT_FORWARD_PID=$!
8383
# shellcheck disable=2064 # we want the PID evaluated now, not at the time the trap is
8484
trap "kill $PORT_FORWARD_PID" EXIT
@@ -107,3 +107,25 @@ curl \
107107
# Output:
108108
# {"_index":"sample_index","_id":"1","_version":1,"_seq_no":0,"_primary_term":1,"found":true,"_source":{"name": "Stackable"}}
109109
# end::rest-api[]
110+
111+
echo
112+
echo "Using OpenSearch Dashboards"
113+
# tag::opensearch-dashboards[]
114+
kubectl create secret generic opensearch-credentials \
115+
--from-literal kibanaserver=E4kENuEmkqH3jyHC
116+
117+
helm install opensearch-dashboards opensearch-dashboards \
118+
--repo https://opensearch-project.github.io/helm-charts \
119+
--version 3.1.0 \
120+
--values opensearch-dashboards-values.yaml \
121+
--wait
122+
# end::opensearch-dashboards[]
123+
124+
echo "Starting port-forwarding of port 5601"
125+
# tag::opensearch-dashboards-port-forwarding[]
126+
kubectl port-forward services/opensearch-dashboards 5601 > /dev/null 2>&1 &
127+
# end::opensearch-dashboards-port-forwarding[]
128+
PORT_FORWARD_PID=$!
129+
# shellcheck disable=2064 # we want the PID evaluated now, not at the time the trap is
130+
trap "kill $PORT_FORWARD_PID" EXIT
131+
sleep 600

‎docs/modules/opensearch/examples/getting_started/getting_started.sh.j2‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -76,9 +76,9 @@ kubectl rollout status --watch statefulset/simple-opensearch-nodes-default --tim
7676
sleep 10
7777

7878
echo "Starting port-forwarding of port 9200"
79-
# tag::port-forwarding[]
79+
# tag::opensearch-port-forwarding[]
8080
kubectl port-forward services/simple-opensearch 9200 > /dev/null 2>&1 &
81-
# end::port-forwarding[]
81+
# end::opensearch-port-forwarding[]
8282
PORT_FORWARD_PID=$!
8383
# shellcheck disable=2064 # we want the PID evaluated now, not at the time the trap is
8484
trap "kill $PORT_FORWARD_PID" EXIT
@@ -107,3 +107,25 @@ curl \
107107
# Output:
108108
# {"_index":"sample_index","_id":"1","_version":1,"_seq_no":0,"_primary_term":1,"found":true,"_source":{"name": "Stackable"}}
109109
# end::rest-api[]
110+
111+
echo
112+
echo "Using OpenSearch Dashboards"
113+
# tag::opensearch-dashboards[]
114+
kubectl create secret generic opensearch-credentials \
115+
--from-literal kibanaserver=E4kENuEmkqH3jyHC
116+
117+
helm install opensearch-dashboards opensearch-dashboards \
118+
--repo https://opensearch-project.github.io/helm-charts \
119+
--version 3.1.0 \
120+
--values opensearch-dashboards-values.yaml \
121+
--wait
122+
# end::opensearch-dashboards[]
123+
124+
echo "Starting port-forwarding of port 5601"
125+
# tag::opensearch-dashboards-port-forwarding[]
126+
kubectl port-forward services/opensearch-dashboards 5601 > /dev/null 2>&1 &
127+
# end::opensearch-dashboards-port-forwarding[]
128+
PORT_FORWARD_PID=$!
129+
# shellcheck disable=2064 # we want the PID evaluated now, not at the time the trap is
130+
trap "kill $PORT_FORWARD_PID" EXIT
131+
sleep 600

‎docs/modules/opensearch/examples/getting_started/opensearch-dashboards-values.yaml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
opensearchHosts: https://simple-opensearch-nodes-default.default.svc.cluster.local:9200
3+
image:
4+
repository: oci.stackable.tech/sdp/opensearch-dashboards
5+
tag: 3.1.0-stackable0.0.0-dev
6+
serviceAccount:
7+
create: false
8+
name: simple-opensearch-serviceaccount
9+
config:
10+
opensearch_dashboards.yml:
11+
server:
12+
ssl:
13+
enabled: true
14+
certificate: /stackable/opensearch-dashboards/config/tls/tls.crt
15+
key: /stackable/opensearch-dashboards/config/tls/tls.key
16+
opensearch:
17+
username: kibanaserver
18+
ssl:
19+
verificationMode: full
20+
certificateAuthorities:
21+
- /stackable/opensearch-dashboards/config/tls/ca.crt
22+
opensearch_security:
23+
cookie:
24+
secure: true
25+
extraEnvs:
26+
- name: OPENSEARCH_PASSWORD
27+
valueFrom:
28+
secretKeyRef:
29+
name: opensearch-credentials
30+
key: kibanaserver
31+
extraVolumes:
32+
- name: tls
33+
ephemeral:
34+
volumeClaimTemplate:
35+
metadata:
36+
annotations:
37+
secrets.stackable.tech/class: tls
38+
secrets.stackable.tech/scope: service=opensearch-dashboards
39+
spec:
40+
storageClassName: secrets.stackable.tech
41+
accessModes:
42+
- ReadWriteOnce
43+
resources:
44+
requests:
45+
storage: "1"
46+
extraVolumeMounts:
47+
- mountPath: /stackable/opensearch-dashboards/config/tls
48+
name: tls
49+
- mountPath: /stackable/opensearch-dashboards/config/opensearch_dashboards.yml
50+
name: config
51+
subPath: opensearch_dashboards.yml
52+
podSecurityContext:
53+
fsGroup: 1000

‎docs/modules/opensearch/examples/getting_started/opensearch-dashboards-values.yaml.j2‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
opensearchHosts: https://simple-opensearch-nodes-default.default.svc.cluster.local:9200
3+
image:
4+
repository: oci.stackable.tech/sdp/opensearch-dashboards
5+
tag: 3.1.0-stackable{{ versions.opensearch }}
6+
serviceAccount:
7+
create: false
8+
name: simple-opensearch-serviceaccount
9+
config:
10+
opensearch_dashboards.yml:
11+
server:
12+
ssl:
13+
enabled: true
14+
certificate: /stackable/opensearch-dashboards/config/tls/tls.crt
15+
key: /stackable/opensearch-dashboards/config/tls/tls.key
16+
opensearch:
17+
username: kibanaserver
18+
ssl:
19+
verificationMode: full
20+
certificateAuthorities:
21+
- /stackable/opensearch-dashboards/config/tls/ca.crt
22+
opensearch_security:
23+
cookie:
24+
secure: true
25+
extraEnvs:
26+
- name: OPENSEARCH_PASSWORD
27+
valueFrom:
28+
secretKeyRef:
29+
name: opensearch-credentials
30+
key: kibanaserver
31+
extraVolumes:
32+
- name: tls
33+
ephemeral:
34+
volumeClaimTemplate:
35+
metadata:
36+
annotations:
37+
secrets.stackable.tech/class: tls
38+
secrets.stackable.tech/scope: service=opensearch-dashboards
39+
spec:
40+
storageClassName: secrets.stackable.tech
41+
accessModes:
42+
- ReadWriteOnce
43+
resources:
44+
requests:
45+
storage: "1"
46+
extraVolumeMounts:
47+
- mountPath: /stackable/opensearch-dashboards/config/tls
48+
name: tls
49+
- mountPath: /stackable/opensearch-dashboards/config/opensearch_dashboards.yml
50+
name: config
51+
subPath: opensearch_dashboards.yml
52+
podSecurityContext:
53+
fsGroup: 1000

‎docs/modules/opensearch/images/getting_started/opensearch-dashboards.png‎

213 KB
Loading

‎docs/modules/opensearch/pages/getting_started/first_steps.adoc‎

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,11 @@ Such a hash can be e.g. generated with `htpasswd`:
2323

2424
[source,bash]
2525
----
26-
$ htpasswd -nbBC 10 admin AJVFsGJBbpT6mChnq
26+
$ htpasswd -nbBC 10 admin AJVFsGJBbpT6mChn
2727
admin:$2y$10$xRtHZFJ9QhG9GcYhRpAGpufCZYsk//nxsuel5URh0GWEBgmiI4Q/e
28+
29+
$ htpasswd -nbBC 10 kibanaserver E4kENuEmkqH3jyHC
30+
kibanaserver:$2y$10$vPgQ/6ilKDM5utawBqxoR.7euhVQ0qeGl8mPTeKhmFT475WUDrfQS
2831
----
2932

3033
== Creation of OpenSearch nodes
@@ -63,7 +66,7 @@ To forward the HTTP port (`9200`) to localhost, run:
6366

6467
[source,bash]
6568
----
66-
include::example$getting_started/getting_started.sh[tag=port-forwarding]
69+
include::example$getting_started/getting_started.sh[tag=opensearch-port-forwarding]
6770
----
6871

6972
== Using the REST API
@@ -78,6 +81,32 @@ include::example$getting_started/getting_started.sh[tag=rest-api]
7881
Great!
7982
Now you can create your own indexes, populate them with data and search for it.
8083

84+
== Using OpenSearch Dashboards
85+
86+
OpenSearch Dashboards is currently not managed by the operator, but the Stackable Data Platform provides a supported OCI image.
87+
First, create the Helm values file `opensearch-dashboards-values.yaml`:
88+
89+
[source,yaml]
90+
----
91+
include::example$getting_started/opensearch-dashboards-values.yaml[]
92+
----
93+
94+
Then, create the Secret with the credentials for the `kibanaserver` user and deploy the OpenSearch Dashboards Helm chart:
95+
96+
[source,bash]
97+
----
98+
include::example$getting_started/getting_started.sh[tag=opensearch-dashboards]
99+
----
100+
101+
Forward the OpenSearch Dashboards port 5601 to localhost, open `https://localhost:5601` in your browser and log in with username `admin` and password `AJVFsGJBbpT6mChn`:
102+
103+
[source,bash]
104+
----
105+
include::example$getting_started/getting_started.sh[tag=opensearch-dashboards-port-forwarding]
106+
----
107+
108+
image::getting_started/opensearch-dashboards.png[Browser showing OpenSearch Dashboards after logging in]
109+
81110
== What's next
82111

83112
Check the xref:usage-guide/index.adoc[] to find out more about configuring your OpenSearch instance or have a look at the OpenSearch documentation to https://docs.opensearch.org/docs/latest/getting-started/[ingest, search or visualize your data with OpenSearch Dashboards{external-link-icon}^].

‎docs/modules/opensearch/pages/usage-guide/opensearch-dashboards.adoc‎

Lines changed: 75 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,14 +10,83 @@ A basic `values.yaml` file to deploy OpenSearch Dashboards with this chart might
1010

1111
[source,yaml]
1212
----
13-
opensearchHosts: https://opensearch.<opensearch-namespace>.svc.cluster.local:9200 # <1>
14-
image:
15-
repository: oci.stackable.tech/sdp/opensearch-dashboards # <2>
13+
opensearchHosts: https://opensearch-nodes-default.<opensearch-namespace>.svc.cluster.local:9200 # <1>
14+
image: # <2>
15+
repository: oci.stackable.tech/sdp/opensearch-dashboards
1616
tag: 3.1.0-stackable0.0.0-dev
17-
serviceAccount: # <3>
17+
serviceAccount:
1818
create: false
19-
name: opensearch-serviceaccount
19+
name: opensearch-serviceaccount # <3>
20+
config:
21+
opensearch_dashboards.yml:
22+
server:
23+
ssl:
24+
enabled: true # <4>
25+
certificate: /stackable/opensearch-dashboards/config/tls/tls.crt # <5>
26+
key: /stackable/opensearch-dashboards/config/tls/tls.key # <6>
27+
opensearch:
28+
username: kibanaserver # <7>
29+
ssl:
30+
verificationMode: full # <8>
31+
certificateAuthorities:
32+
- /stackable/opensearch-dashboards/config/tls/ca.crt # <9>
33+
opensearch_security:
34+
cookie:
35+
secure: true # <10>
36+
extraEnvs:
37+
- name: OPENSEARCH_PASSWORD
38+
valueFrom:
39+
secretKeyRef:
40+
name: opensearch-credentials
41+
key: kibanaserver # <11>
42+
extraVolumes:
43+
- name: tls # <12>
44+
ephemeral:
45+
volumeClaimTemplate:
46+
metadata:
47+
annotations:
48+
secrets.stackable.tech/class: tls
49+
secrets.stackable.tech/scope: service=opensearch-dashboards
50+
spec:
51+
storageClassName: secrets.stackable.tech
52+
accessModes:
53+
- ReadWriteOnce
54+
resources:
55+
requests:
56+
storage: "1"
57+
extraVolumeMounts:
58+
- mountPath: /stackable/opensearch-dashboards/config/tls
59+
name: tls
60+
- mountPath: /stackable/opensearch-dashboards/config/opensearch_dashboards.yml
61+
name: config # <13>
62+
subPath: opensearch_dashboards.yml
63+
podSecurityContext:
64+
fsGroup: 1000 # <14>
2065
----
21-
<1> Address of the OpenSearch Service deployed by the operator
66+
<1> Address of the OpenSearch Service deployed by the operator;
67+
This address must be adapted according to your deployment.
2268
<2> Use the OCI image provided by the Stackable Data Platform
2369
<3> If running on OpenShift, use the ServiceAccount of OpenSearch because its permissions are already configured to work on OpenShift.
70+
This ServiceAccount name must probably adapted according to your deployment.
71+
<4> Enable TLS, so that OpenSearch Dashboards is served over HTTPS.
72+
<5> The TLS server certificate
73+
<6> The key for the TLS server certificate
74+
<7> OpenSearch Dashboards uses the user `kibanaserver` to communicate with OpenSearch.
75+
<8> OpenSearch Dashboards verifies the certificate of OpenSearch. This is disabled by default.
76+
<9> The CA certificate which is used to verify the OpenSearch certificate
77+
<10> Ensure that cookies are not sent via an insecure connection.
78+
<11> The password for the `kibanaserver` user
79+
<12> This example uses the secret operator to provide a TLS certificate.
80+
<13> The Helm chart only adds a volume mount at `/usr/share/opensearch-dashboards/config`, but in the image provided by Stackable, OpenSearch Dashboards is located in `/stackable/opensearch-dashboards`.
81+
<14> Mount the volumes with the `stackable` group so that the files are accessible by OpenSearch Dashboards.
82+
83+
After the values are adjusted according to your deployment, especially `opensearchHosts` and `serviceAccount.name`, you can deploy the Helm chart as follows:
84+
85+
[shell,yaml]
86+
----
87+
helm install opensearch-dashboards opensearch-dashboards \
88+
--repo https://opensearch-project.github.io/helm-charts \
89+
--version 3.1.0 \
90+
--values opensearch-dashboards-values.yaml \
91+
--wait
92+
----

0 commit comments

Comments
 (0)