Skip to content

Commit aebf5b1

Browse files
AntonEliatrakolchfa-awsnatebower
authored
adding docker examples for custom configuration (#10684)
* adding docker examples for custom configuration Signed-off-by: Anton Rubin <anton.rubin@eliatra.com> * updating description for link for Shared file system Signed-off-by: Anton Rubin <anton.rubin@eliatra.com> * adding helm chart repo links Signed-off-by: Anton Rubin <anton.rubin@eliatra.com> * elaboring on providing configuration at start up using -E flag Signed-off-by: Anton Rubin <anton.rubin@eliatra.com> * fixing the CORS configuration Signed-off-by: Anton Rubin <anton.rubin@eliatra.com> * Update docker.md Signed-off-by: AntonEliatra <anton.rubin@eliatra.com> * Apply suggestions from code review Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: AntonEliatra <anton.rubin@eliatra.com> * Apply suggestions from code review Signed-off-by: Nathan Bower <nbower@amazon.com> --------- Signed-off-by: Anton Rubin <anton.rubin@eliatra.com> Signed-off-by: AntonEliatra <anton.rubin@eliatra.com> Signed-off-by: Nathan Bower <nbower@amazon.com> Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Co-authored-by: Nathan Bower <nbower@amazon.com>
1 parent 159aa43 commit aebf5b1

File tree

6 files changed

+248
-20
lines changed

6 files changed

+248
-20
lines changed

‎_install-and-configure/configuring-opensearch/availability-recovery.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,9 @@ OpenSearch supports the following snapshot settings:
2929

3030
For security-related snapshot settings, see [Security settings]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/security-settings/).
3131

32-
### File system settings
32+
### Shared file system
3333

34-
For information about file system settings, see [Shared file system]({{site.url}}{{site.baseurl}}/tuning-your-cluster/availability-and-recovery/snapshots/snapshot-restore/#shared-file-system).
34+
For information about using a shared file system, see [Shared file system]({{site.url}}{{site.baseurl}}/tuning-your-cluster/availability-and-recovery/snapshots/snapshot-restore/#shared-file-system).
3535

3636
### Amazon S3 settings
3737

‎_install-and-configure/configuring-opensearch/index.md‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,13 @@ Whenever possible, use the Cluster Settings API; `opensearch.yml` is local to ea
2323

2424
Certain operations are static and require you to modify the `opensearch.yml` [configuration file](#configuration-file) and restart the cluster. In general, these settings relate to networking, cluster formation, and the local file system. To learn more, see [Cluster formation]({{site.url}}{{site.baseurl}}/opensearch/cluster/).
2525

26-
## Specifying settings as environment variables
26+
## Specifying configuration settings at startup
2727

28-
You can specify environment variables in the following ways.
28+
You can specify configuration settings in the following ways.
2929

30-
### Arguments at startup
30+
### Flags at startup
3131

32-
You can specify environment variables as arguments using `-E` when launching OpenSearch:
32+
You can pass the configuration directly to the JVM process at startup using the `-E` flag when launching OpenSearch:
3333

3434
```bash
3535
./opensearch -Ecluster.name=opensearch-cluster -Enode.name=opensearch-node1 -Ehttp.host=0.0.0.0 -Ediscovery.type=single-node
@@ -148,12 +148,13 @@ The demo configuration includes a number of [settings for the Security plugin]({
148148
149149
### (Optional) CORS header configuration
150150
151-
If you are working on a client application running against an OpenSearch cluster on a different domain, you can configure headers in `opensearch.yml` to allow for developing a local application on the same machine. Use [Cross Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) so that your application can make calls to the OpenSearch API running locally. Add the following lines in your `custom-opensearch.yml` file (note that the "-" must be the first character in each line).
151+
If you are working on a client application running against an OpenSearch cluster on a different domain, you can configure headers in `opensearch.yml` to allow for developing a local application on the same machine. Use [Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) so that your application can make calls to the OpenSearch API running locally. Add the following lines in your `custom-opensearch.yml` file:
152+
152153
```yml
153-
- http.host:0.0.0.0
154-
- http.port:9200
155-
- http.cors.allow-origin:"http://localhost"
156-
- http.cors.enabled:true
157-
- http.cors.allow-headers:X-Requested-With,X-Auth-Token,Content-Type,Content-Length,Authorization
158-
- http.cors.allow-credentials:true
154+
http.host: 0.0.0.0
155+
http.port: 9200
156+
http.cors.allow-origin: "http://localhost"
157+
http.cors.enabled: true
158+
http.cors.allow-headers: X-Requested-With,X-Auth-Token,Content-Type,Content-Length,Authorization
159+
http.cors.allow-credentials: true
159160
```

‎_install-and-configure/install-dashboards/docker.md‎

Lines changed: 76 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,17 +8,89 @@ redirect_from:
88
- /opensearch/install/docker-security/
99
---
1010

11-
# Run OpenSearch Dashboards using Docker
11+
# Run OpenSearch Dashboards using Docker and Docker Compose
1212

13-
You *can* start OpenSearch Dashboards using `docker run` after [creating a Docker network](https://docs.docker.com/engine/reference/commandline/network_create/) and starting OpenSearch, but the process of connecting OpenSearch Dashboards to OpenSearch is significantly easier with a Docker Compose file.
13+
You can use either Docker or Docker Compose to run OpenSearch Dashboards. The Docker Compose method is easier because you can define the entire configuration in a single file.
1414

15-
1. Run `docker pull opensearchproject/opensearch-dashboards:2`.
15+
## Run OpenSearch Dashboards using Docker
16+
17+
If you have defined your network using `docker network create os-net` and started OpenSearch using the following command:
18+
19+
```bash
20+
docker run -d --name opensearch-node -p 9200:9200 -p 9600:9600 --network os-net -e "discovery.type=single-node" -e "OPENSEARCH_INITIAL_ADMIN_PASSWORD=<admin_password>" opensearchproject/opensearch:latest
21+
```
22+
{% include copy.html %}
23+
24+
Then you can start OpenSearch Dashboards using the following steps:
25+
26+
1. Create an `opensearch_dashboards.yml` configuration file:
27+
28+
```bash
29+
server.name: opensearch_dashboards
30+
server.host: "0.0.0.0"
31+
server.customResponseHeaders : { "Access-Control-Allow-Credentials" : "true" }
32+
33+
# Disabling HTTPS on OpenSearch Dashboards
34+
server.ssl.enabled: false
35+
36+
opensearch.hosts: ["https://opensearch-node:9200"] # Using the opensearch container name
37+
38+
opensearch.ssl.verificationMode: none
39+
opensearch.username: kibanaserver
40+
opensearch.password: kibanaserver
41+
opensearch.requestHeadersWhitelist: ["securitytenant","Authorization"]
42+
43+
# Multitenancy
44+
opensearch_security.multitenancy.enabled: true
45+
opensearch_security.multitenancy.tenants.preferred: ["Private", "Global"]
46+
opensearch_security.readonly_mode.roles: ["kibana_read_only"]
47+
```
48+
{% include copy.html %}
49+
50+
2. Execute the following command to start OpenSearch Dashboards:
51+
52+
```bash
53+
docker run -d --name osd \
54+
--network os-net \
55+
-p 5601:5601 \
56+
-v ./opensearch_dashboards.yml:/usr/share/opensearch-dashboards/config/opensearch_dashboards.yml \
57+
opensearchproject/opensearch-dashboards:latest
58+
```
59+
{% include copy.html %}
60+
61+
## Run OpenSearch Dashboards using Docker Compose
62+
63+
Use the following steps to run OpenSearch Dashboards using Docker Compose:
1664
1765
1. Create a [`docker-compose.yml`](https://docs.docker.com/compose/compose-file/) file appropriate for your environment. A sample file that includes OpenSearch Dashboards is available on the OpenSearch [Docker installation page]({{site.url}}{{site.baseurl}}/opensearch/install/docker#sample-docker-composeyml).
1866
19-
Just like `opensearch.yml`, you can pass a custom `opensearch_dashboards.yml` to the container in the Docker Compose file.
67+
You can pass a custom `opensearch_dashboards.yml` file to the container in the Docker Compose file. For more information, see [Complete Docker Compose example with custom configuration]({{site.url}}{{site.baseurl}}/install-and-configure/install-opensearch/docker/#complete-docker-compose-example-with-custom-configuration).
2068
{: .tip }
2169
70+
1. Create an `opensearch_dashboards.yml` file:
71+
72+
```yaml
73+
server.name: opensearch_dashboards
74+
server.host: "0.0.0.0"
75+
server.customResponseHeaders : { "Access-Control-Allow-Credentials" : "true" }
76+
77+
# Disabling HTTPS on OpenSearch Dashboards
78+
server.ssl.enabled: false
79+
80+
opensearch.ssl.verificationMode: none
81+
opensearch.username: kibanaserver
82+
opensearch.password: kibanaserver
83+
opensearch.requestHeadersWhitelist: ["securitytenant","Authorization"]
84+
85+
# Multitenancy
86+
opensearch_security.multitenancy.enabled: true
87+
opensearch_security.multitenancy.tenants.preferred: ["Private", "Global"]
88+
opensearch_security.readonly_mode.roles: ["kibana_read_only"]
89+
```
90+
91+
The `opensearch.hosts` setting must be configured if you are not passing it as an environment variable. For an example of how to configure this setting, see [Complete Docker Compose example with custom configuration]({{site.url}}{{site.baseurl}}/install-and-configure/install-opensearch/docker/#complete-docker-compose-example-with-custom-configuration).
92+
{: .note}
93+
2294
1. Run `docker compose up`.
2395
2496
Wait for the containers to start. Then see the [OpenSearch Dashboards documentation]({{site.url}}{{site.baseurl}}/dashboards/index/).

‎_install-and-configure/install-dashboards/helm.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ redirect_from:
1111

1212
Helm is a package manager that allows you to easily install and manage OpenSearch Dashboards in a Kubernetes cluster. You can define your OpenSearch configurations in a YAML file and use Helm to deploy your applications in a version-controlled and reproducible way.
1313

14-
The Helm chart contains the resources described in the following table.
14+
The [Helm chart](https://github.com/opensearch-project/helm-charts) contains the resources described in the following table.
1515

1616
Resource | Description
1717
:--- | :---

‎_install-and-configure/install-opensearch/docker.md‎

Lines changed: 156 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -497,12 +497,167 @@ For a full list of settings, see [Security]({{site.url}}{{site.baseurl}}/securit
497497

498498
Use the same process to specify a [Backend configuration]({{site.url}}{{site.baseurl}}/security/configuration/configuration/) in `/usr/share/opensearch/config/opensearch-security/config.yml` as well as new internal users, roles, mappings, action groups, and tenants in their respective [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/).
499499

500-
After replacing the certificates and creating your own internal users, roles, mappings, action groups, and tenants, use Docker Compose to start the cluster:
500+
#### Complete Docker Compose example with custom configuration
501+
502+
After creating your own certificates, `internal_users.yml`, `roles.yml`, `roles_mapping.yml`, and the rest of the security configuration files, your `docker-compose.yaml` file should appear similar to the following:
503+
504+
```yaml
505+
version: '3'
506+
services:
507+
opensearch-node1:
508+
image: opensearchproject/opensearch:${OS_VER}
509+
container_name: opensearch-node1_${OS_VER}
510+
environment:
511+
- cluster.name=opensearch-cluster
512+
- node.name=opensearch-node1
513+
- discovery.seed_hosts=opensearch-node1,opensearch-node2,opensearch-node3
514+
- cluster.initial_master_nodes=opensearch-node1,opensearch-node2,opensearch-node3
515+
- bootstrap.memory_lock=true
516+
- "ES_JAVA_OPTS=-Xms2g -Xmx2g"
517+
ulimits:
518+
memlock:
519+
soft: -1
520+
hard: -1
521+
nofile:
522+
soft: 65536
523+
hard: 65536
524+
volumes:
525+
- ./opensearch.yml:/usr/share/opensearch/config/opensearch.yml
526+
- ./esnode.pem:/usr/share/opensearch/config/esnode.pem
527+
- ./esnode-key.pem:/usr/share/opensearch/config/esnode-key.pem
528+
- ./root-ca.pem:/usr/share/opensearch/config/root-ca.pem
529+
- ./kirk-key.pem:/usr/share/opensearch/config/kirk-key.pem
530+
- ./kirk.pem:/usr/share/opensearch/config/kirk.pem
531+
- ./config.yml:/usr/share/opensearch/config/opensearch-security/config.yml
532+
- ./roles_mapping.yml:/usr/share/opensearch/config/opensearch-security/roles_mapping.yml
533+
- ./roles.yml:/usr/share/opensearch/config/opensearch-security/roles.yml
534+
- ./action_groups.yml:/usr/share/opensearch/config/opensearch-security/action_groups.yml
535+
- ./allowlist.yml:/usr/share/opensearch/config/opensearch-security/allowlist.yml
536+
- ./audit.yml:/usr/share/opensearch/config/opensearch-security/audit.yml
537+
- ./internal_users.yml:/usr/share/opensearch/config/opensearch-security/internal_users.yml
538+
- ./nodes_dn.yml:/usr/share/opensearch/config/opensearch-security/nodes_dn.yml
539+
- ./tenants.yml:/usr/share/opensearch/config/opensearch-security/tenants.yml
540+
- ./whitelist.yml:/usr/share/opensearch/config/opensearch-security/whitelist.yml
541+
ports:
542+
- 9201:9200
543+
- 9600:9600
544+
networks:
545+
- opensearch-net
546+
547+
opensearch-node2:
548+
image: opensearchproject/opensearch:${OS_VER}
549+
container_name: opensearch-node2_${OS_VER}
550+
environment:
551+
- cluster.name=opensearch-cluster
552+
- node.name=opensearch-node2
553+
- discovery.seed_hosts=opensearch-node1,opensearch-node2,opensearch-node3
554+
- cluster.initial_master_nodes=opensearch-node1,opensearch-node2,opensearch-node3
555+
- bootstrap.memory_lock=true
556+
- "ES_JAVA_OPTS=-Xms2g -Xmx2g"
557+
ulimits:
558+
memlock:
559+
soft: -1
560+
hard: -1
561+
nofile:
562+
soft: 65536
563+
hard: 65536
564+
volumes:
565+
- ./opensearch.yml:/usr/share/opensearch/config/opensearch.yml
566+
- ./esnode.pem:/usr/share/opensearch/config/esnode.pem
567+
- ./esnode-key.pem:/usr/share/opensearch/config/esnode-key.pem
568+
- ./root-ca.pem:/usr/share/opensearch/config/root-ca.pem
569+
- ./kirk-key.pem:/usr/share/opensearch/config/kirk-key.pem
570+
- ./kirk.pem:/usr/share/opensearch/config/kirk.pem
571+
- ./config.yml:/usr/share/opensearch/config/opensearch-security/config.yml
572+
- ./roles_mapping.yml:/usr/share/opensearch/config/opensearch-security/roles_mapping.yml
573+
- ./roles.yml:/usr/share/opensearch/config/opensearch-security/roles.yml
574+
- ./action_groups.yml:/usr/share/opensearch/config/opensearch-security/action_groups.yml
575+
- ./allowlist.yml:/usr/share/opensearch/config/opensearch-security/allowlist.yml
576+
- ./audit.yml:/usr/share/opensearch/config/opensearch-security/audit.yml
577+
- ./internal_users.yml:/usr/share/opensearch/config/opensearch-security/internal_users.yml
578+
- ./nodes_dn.yml:/usr/share/opensearch/config/opensearch-security/nodes_dn.yml
579+
- ./tenants.yml:/usr/share/opensearch/config/opensearch-security/tenants.yml
580+
- ./whitelist.yml:/usr/share/opensearch/config/opensearch-security/whitelist.yml
581+
ports:
582+
- 9200:9200
583+
networks:
584+
- opensearch-net
585+
586+
opensearch-node3:
587+
image: opensearchproject/opensearch:${OS_VER}
588+
container_name: opensearch-node3_${OS_VER}
589+
environment:
590+
- cluster.name=opensearch-cluster
591+
- node.name=opensearch-node3
592+
- discovery.seed_hosts=opensearch-node1,opensearch-node2,opensearch-node3
593+
- cluster.initial_master_nodes=opensearch-node1,opensearch-node2,opensearch-node3
594+
- bootstrap.memory_lock=true
595+
- "ES_JAVA_OPTS=-Xms2g -Xmx2g"
596+
- OPENSEARCH_INITIAL_ADMIN_PASSWORD=admin3
597+
ulimits:
598+
memlock:
599+
soft: -1
600+
hard: -1
601+
nofile:
602+
soft: 65536
603+
hard: 65536
604+
volumes:
605+
- ./opensearch.yml:/usr/share/opensearch/config/opensearch.yml
606+
- ./esnode.pem:/usr/share/opensearch/config/esnode.pem
607+
- ./esnode-key.pem:/usr/share/opensearch/config/esnode-key.pem
608+
- ./root-ca.pem:/usr/share/opensearch/config/root-ca.pem
609+
- ./kirk-key.pem:/usr/share/opensearch/config/kirk-key.pem
610+
- ./kirk.pem:/usr/share/opensearch/config/kirk.pem
611+
- ./config.yml:/usr/share/opensearch/config/opensearch-security/config.yml
612+
- ./roles_mapping.yml:/usr/share/opensearch/config/opensearch-security/roles_mapping.yml
613+
- ./roles.yml:/usr/share/opensearch/config/opensearch-security/roles.yml
614+
- ./action_groups.yml:/usr/share/opensearch/config/opensearch-security/action_groups.yml
615+
- ./allowlist.yml:/usr/share/opensearch/config/opensearch-security/allowlist.yml
616+
- ./audit.yml:/usr/share/opensearch/config/opensearch-security/audit.yml
617+
- ./internal_users.yml:/usr/share/opensearch/config/opensearch-security/internal_users.yml
618+
- ./nodes_dn.yml:/usr/share/opensearch/config/opensearch-security/nodes_dn.yml
619+
- ./tenants.yml:/usr/share/opensearch/config/opensearch-security/tenants.yml
620+
- ./whitelist.yml:/usr/share/opensearch/config/opensearch-security/whitelist.yml
621+
ports:
622+
- 9202:9200
623+
networks:
624+
- opensearch-net
625+
626+
opensearch-dashboards:
627+
image: opensearchproject/opensearch-dashboards:${OSD_VER}
628+
container_name: opensearch-dashboards_${OSD_VER}
629+
volumes:
630+
- ./opensearch_dashboards.yml:/usr/share/opensearch-dashboards/config/opensearch_dashboards.yml
631+
- ./opensearch_dashboards.crt:/usr/share/opensearch-dashboards/config/opensearch_dashboards.crt
632+
- ./opensearch_dashboards.key:/usr/share/opensearch-dashboards/config/opensearch_dashboards.key
633+
ports:
634+
- 5601:5601
635+
expose:
636+
- "5601"
637+
environment:
638+
OPENSEARCH_HOSTS: '["https://opensearch-node1:9200", "https://opensearch-node2:9200", "https://opensearch-node3:9200" ]'
639+
networks:
640+
- opensearch-net
641+
depends_on:
642+
- opensearch-node1
643+
- opensearch-node2
644+
- opensearch-node3
645+
646+
networks:
647+
opensearch-net:
648+
649+
```
650+
{% include copy.html %}
651+
652+
Use Docker Compose to start the cluster:
501653
```bash
502654
docker compose up -d
503655
```
504656
{% include copy.html %}
505657

658+
The password for the `admin` user provided in the `.env` file is overridden by the password provided in the `internal_users.yml` file.
659+
{: .note}
660+
506661
### Working with plugins
507662

508663
To use the OpenSearch image with a custom plugin, you must first create a [`Dockerfile`](https://docs.docker.com/engine/reference/builder/). Review the official Docker documentation for information about creating a Dockerfile.

‎_install-and-configure/install-opensearch/helm.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ redirect_from:
1111

1212
Helm is a package manager that allows you to easily install and manage OpenSearch in a Kubernetes cluster. You can define your OpenSearch configurations in a YAML file and use Helm to deploy your applications in a version-controlled and reproducible way.
1313

14-
The Helm chart contains the resources described in the following table.
14+
The [Helm chart](https://github.com/opensearch-project/helm-charts) contains the resources described in the following table.
1515

1616
Resource | Description
1717
:--- | :---

0 commit comments

Comments
 (0)