diff --git a/_install-and-configure/configuring-opensearch/availability-recovery.md b/_install-and-configure/configuring-opensearch/availability-recovery.md index d25396a63fa..69a53545e08 100644 --- a/_install-and-configure/configuring-opensearch/availability-recovery.md +++ b/_install-and-configure/configuring-opensearch/availability-recovery.md @@ -29,9 +29,9 @@ OpenSearch supports the following snapshot settings: For security-related snapshot settings, see [Security settings]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/security-settings/). -### File system settings +### Shared file system -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). +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). ### Amazon S3 settings diff --git a/_install-and-configure/configuring-opensearch/index.md b/_install-and-configure/configuring-opensearch/index.md index bb99a57bac2..de8ca692203 100755 --- a/_install-and-configure/configuring-opensearch/index.md +++ b/_install-and-configure/configuring-opensearch/index.md @@ -23,13 +23,13 @@ Whenever possible, use the Cluster Settings API; `opensearch.yml` is local to ea 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/). -## Specifying settings as environment variables +## Specifying configuration settings at startup -You can specify environment variables in the following ways. +You can specify configuration settings in the following ways. -### Arguments at startup +### Flags at startup -You can specify environment variables as arguments using `-E` when launching OpenSearch: +You can pass the configuration directly to the JVM process at startup using the `-E` flag when launching OpenSearch: ```bash ./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]({ ### (Optional) CORS header configuration -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). +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: + ```yml -- http.host:0.0.0.0 -- http.port:9200 -- http.cors.allow-origin:"http://localhost" -- http.cors.enabled:true -- http.cors.allow-headers:X-Requested-With,X-Auth-Token,Content-Type,Content-Length,Authorization -- http.cors.allow-credentials:true +http.host: 0.0.0.0 +http.port: 9200 +http.cors.allow-origin: "http://localhost" +http.cors.enabled: true +http.cors.allow-headers: X-Requested-With,X-Auth-Token,Content-Type,Content-Length,Authorization +http.cors.allow-credentials: true ``` diff --git a/_install-and-configure/install-dashboards/docker.md b/_install-and-configure/install-dashboards/docker.md index 7f18fd7a662..a601326b3ff 100644 --- a/_install-and-configure/install-dashboards/docker.md +++ b/_install-and-configure/install-dashboards/docker.md @@ -8,17 +8,89 @@ redirect_from: - /opensearch/install/docker-security/ --- -# Run OpenSearch Dashboards using Docker +# Run OpenSearch Dashboards using Docker and Docker Compose -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. +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. -1. Run `docker pull opensearchproject/opensearch-dashboards:2`. +## Run OpenSearch Dashboards using Docker + +If you have defined your network using `docker network create os-net` and started OpenSearch using the following command: + +```bash +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=" opensearchproject/opensearch:latest +``` +{% include copy.html %} + +Then you can start OpenSearch Dashboards using the following steps: + +1. Create an `opensearch_dashboards.yml` configuration file: + + ```bash + server.name: opensearch_dashboards + server.host: "0.0.0.0" + server.customResponseHeaders : { "Access-Control-Allow-Credentials" : "true" } + + # Disabling HTTPS on OpenSearch Dashboards + server.ssl.enabled: false + + opensearch.hosts: ["https://opensearch-node:9200"] # Using the opensearch container name + + opensearch.ssl.verificationMode: none + opensearch.username: kibanaserver + opensearch.password: kibanaserver + opensearch.requestHeadersWhitelist: ["securitytenant","Authorization"] + + # Multitenancy + opensearch_security.multitenancy.enabled: true + opensearch_security.multitenancy.tenants.preferred: ["Private", "Global"] + opensearch_security.readonly_mode.roles: ["kibana_read_only"] + ``` + {% include copy.html %} + +2. Execute the following command to start OpenSearch Dashboards: + + ```bash + docker run -d --name osd \ + --network os-net \ + -p 5601:5601 \ + -v ./opensearch_dashboards.yml:/usr/share/opensearch-dashboards/config/opensearch_dashboards.yml \ + opensearchproject/opensearch-dashboards:latest + ``` + {% include copy.html %} + +## Run OpenSearch Dashboards using Docker Compose + +Use the following steps to run OpenSearch Dashboards using Docker Compose: 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). - Just like `opensearch.yml`, you can pass a custom `opensearch_dashboards.yml` to the container in the Docker Compose file. + 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). {: .tip } +1. Create an `opensearch_dashboards.yml` file: + + ```yaml + server.name: opensearch_dashboards + server.host: "0.0.0.0" + server.customResponseHeaders : { "Access-Control-Allow-Credentials" : "true" } + + # Disabling HTTPS on OpenSearch Dashboards + server.ssl.enabled: false + + opensearch.ssl.verificationMode: none + opensearch.username: kibanaserver + opensearch.password: kibanaserver + opensearch.requestHeadersWhitelist: ["securitytenant","Authorization"] + + # Multitenancy + opensearch_security.multitenancy.enabled: true + opensearch_security.multitenancy.tenants.preferred: ["Private", "Global"] + opensearch_security.readonly_mode.roles: ["kibana_read_only"] + ``` + + 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). + {: .note} + 1. Run `docker compose up`. Wait for the containers to start. Then see the [OpenSearch Dashboards documentation]({{site.url}}{{site.baseurl}}/dashboards/index/). diff --git a/_install-and-configure/install-dashboards/helm.md b/_install-and-configure/install-dashboards/helm.md index 58ca995c3e6..1cc439a9447 100644 --- a/_install-and-configure/install-dashboards/helm.md +++ b/_install-and-configure/install-dashboards/helm.md @@ -11,7 +11,7 @@ redirect_from: 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. -The Helm chart contains the resources described in the following table. +The [Helm chart](https://github.com/opensearch-project/helm-charts) contains the resources described in the following table. Resource | Description :--- | :--- diff --git a/_install-and-configure/install-opensearch/docker.md b/_install-and-configure/install-opensearch/docker.md index 817b45e57b5..d6e40556c90 100644 --- a/_install-and-configure/install-opensearch/docker.md +++ b/_install-and-configure/install-opensearch/docker.md @@ -497,12 +497,167 @@ For a full list of settings, see [Security]({{site.url}}{{site.baseurl}}/securit 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/). -After replacing the certificates and creating your own internal users, roles, mappings, action groups, and tenants, use Docker Compose to start the cluster: +#### Complete Docker Compose example with custom configuration + +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: + +```yaml +version: '3' +services: + opensearch-node1: + image: opensearchproject/opensearch:${OS_VER} + container_name: opensearch-node1_${OS_VER} + environment: + - cluster.name=opensearch-cluster + - node.name=opensearch-node1 + - discovery.seed_hosts=opensearch-node1,opensearch-node2,opensearch-node3 + - cluster.initial_master_nodes=opensearch-node1,opensearch-node2,opensearch-node3 + - bootstrap.memory_lock=true + - "ES_JAVA_OPTS=-Xms2g -Xmx2g" + ulimits: + memlock: + soft: -1 + hard: -1 + nofile: + soft: 65536 + hard: 65536 + volumes: + - ./opensearch.yml:/usr/share/opensearch/config/opensearch.yml + - ./esnode.pem:/usr/share/opensearch/config/esnode.pem + - ./esnode-key.pem:/usr/share/opensearch/config/esnode-key.pem + - ./root-ca.pem:/usr/share/opensearch/config/root-ca.pem + - ./kirk-key.pem:/usr/share/opensearch/config/kirk-key.pem + - ./kirk.pem:/usr/share/opensearch/config/kirk.pem + - ./config.yml:/usr/share/opensearch/config/opensearch-security/config.yml + - ./roles_mapping.yml:/usr/share/opensearch/config/opensearch-security/roles_mapping.yml + - ./roles.yml:/usr/share/opensearch/config/opensearch-security/roles.yml + - ./action_groups.yml:/usr/share/opensearch/config/opensearch-security/action_groups.yml + - ./allowlist.yml:/usr/share/opensearch/config/opensearch-security/allowlist.yml + - ./audit.yml:/usr/share/opensearch/config/opensearch-security/audit.yml + - ./internal_users.yml:/usr/share/opensearch/config/opensearch-security/internal_users.yml + - ./nodes_dn.yml:/usr/share/opensearch/config/opensearch-security/nodes_dn.yml + - ./tenants.yml:/usr/share/opensearch/config/opensearch-security/tenants.yml + - ./whitelist.yml:/usr/share/opensearch/config/opensearch-security/whitelist.yml + ports: + - 9201:9200 + - 9600:9600 + networks: + - opensearch-net + + opensearch-node2: + image: opensearchproject/opensearch:${OS_VER} + container_name: opensearch-node2_${OS_VER} + environment: + - cluster.name=opensearch-cluster + - node.name=opensearch-node2 + - discovery.seed_hosts=opensearch-node1,opensearch-node2,opensearch-node3 + - cluster.initial_master_nodes=opensearch-node1,opensearch-node2,opensearch-node3 + - bootstrap.memory_lock=true + - "ES_JAVA_OPTS=-Xms2g -Xmx2g" + ulimits: + memlock: + soft: -1 + hard: -1 + nofile: + soft: 65536 + hard: 65536 + volumes: + - ./opensearch.yml:/usr/share/opensearch/config/opensearch.yml + - ./esnode.pem:/usr/share/opensearch/config/esnode.pem + - ./esnode-key.pem:/usr/share/opensearch/config/esnode-key.pem + - ./root-ca.pem:/usr/share/opensearch/config/root-ca.pem + - ./kirk-key.pem:/usr/share/opensearch/config/kirk-key.pem + - ./kirk.pem:/usr/share/opensearch/config/kirk.pem + - ./config.yml:/usr/share/opensearch/config/opensearch-security/config.yml + - ./roles_mapping.yml:/usr/share/opensearch/config/opensearch-security/roles_mapping.yml + - ./roles.yml:/usr/share/opensearch/config/opensearch-security/roles.yml + - ./action_groups.yml:/usr/share/opensearch/config/opensearch-security/action_groups.yml + - ./allowlist.yml:/usr/share/opensearch/config/opensearch-security/allowlist.yml + - ./audit.yml:/usr/share/opensearch/config/opensearch-security/audit.yml + - ./internal_users.yml:/usr/share/opensearch/config/opensearch-security/internal_users.yml + - ./nodes_dn.yml:/usr/share/opensearch/config/opensearch-security/nodes_dn.yml + - ./tenants.yml:/usr/share/opensearch/config/opensearch-security/tenants.yml + - ./whitelist.yml:/usr/share/opensearch/config/opensearch-security/whitelist.yml + ports: + - 9200:9200 + networks: + - opensearch-net + + opensearch-node3: + image: opensearchproject/opensearch:${OS_VER} + container_name: opensearch-node3_${OS_VER} + environment: + - cluster.name=opensearch-cluster + - node.name=opensearch-node3 + - discovery.seed_hosts=opensearch-node1,opensearch-node2,opensearch-node3 + - cluster.initial_master_nodes=opensearch-node1,opensearch-node2,opensearch-node3 + - bootstrap.memory_lock=true + - "ES_JAVA_OPTS=-Xms2g -Xmx2g" + - OPENSEARCH_INITIAL_ADMIN_PASSWORD=admin3 + ulimits: + memlock: + soft: -1 + hard: -1 + nofile: + soft: 65536 + hard: 65536 + volumes: + - ./opensearch.yml:/usr/share/opensearch/config/opensearch.yml + - ./esnode.pem:/usr/share/opensearch/config/esnode.pem + - ./esnode-key.pem:/usr/share/opensearch/config/esnode-key.pem + - ./root-ca.pem:/usr/share/opensearch/config/root-ca.pem + - ./kirk-key.pem:/usr/share/opensearch/config/kirk-key.pem + - ./kirk.pem:/usr/share/opensearch/config/kirk.pem + - ./config.yml:/usr/share/opensearch/config/opensearch-security/config.yml + - ./roles_mapping.yml:/usr/share/opensearch/config/opensearch-security/roles_mapping.yml + - ./roles.yml:/usr/share/opensearch/config/opensearch-security/roles.yml + - ./action_groups.yml:/usr/share/opensearch/config/opensearch-security/action_groups.yml + - ./allowlist.yml:/usr/share/opensearch/config/opensearch-security/allowlist.yml + - ./audit.yml:/usr/share/opensearch/config/opensearch-security/audit.yml + - ./internal_users.yml:/usr/share/opensearch/config/opensearch-security/internal_users.yml + - ./nodes_dn.yml:/usr/share/opensearch/config/opensearch-security/nodes_dn.yml + - ./tenants.yml:/usr/share/opensearch/config/opensearch-security/tenants.yml + - ./whitelist.yml:/usr/share/opensearch/config/opensearch-security/whitelist.yml + ports: + - 9202:9200 + networks: + - opensearch-net + + opensearch-dashboards: + image: opensearchproject/opensearch-dashboards:${OSD_VER} + container_name: opensearch-dashboards_${OSD_VER} + volumes: + - ./opensearch_dashboards.yml:/usr/share/opensearch-dashboards/config/opensearch_dashboards.yml + - ./opensearch_dashboards.crt:/usr/share/opensearch-dashboards/config/opensearch_dashboards.crt + - ./opensearch_dashboards.key:/usr/share/opensearch-dashboards/config/opensearch_dashboards.key + ports: + - 5601:5601 + expose: + - "5601" + environment: + OPENSEARCH_HOSTS: '["https://opensearch-node1:9200", "https://opensearch-node2:9200", "https://opensearch-node3:9200" ]' + networks: + - opensearch-net + depends_on: + - opensearch-node1 + - opensearch-node2 + - opensearch-node3 + +networks: + opensearch-net: + +``` +{% include copy.html %} + +Use Docker Compose to start the cluster: ```bash docker compose up -d ``` {% include copy.html %} +The password for the `admin` user provided in the `.env` file is overridden by the password provided in the `internal_users.yml` file. +{: .note} + ### Working with plugins 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. diff --git a/_install-and-configure/install-opensearch/helm.md b/_install-and-configure/install-opensearch/helm.md index ed2aa628e39..c41e8c9a811 100644 --- a/_install-and-configure/install-opensearch/helm.md +++ b/_install-and-configure/install-opensearch/helm.md @@ -11,7 +11,7 @@ redirect_from: 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. -The Helm chart contains the resources described in the following table. +The [Helm chart](https://github.com/opensearch-project/helm-charts) contains the resources described in the following table. Resource | Description :--- | :---