{"_id":"5a8fae0368264c001f20cc0b","category":{"_id":"5a8fae0268264c001f20cc02","version":"5a8fae0268264c001f20cc00","project":"5633ebff7e9e880d00af1a53","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-12-23T20:06:16.013Z","from_sync":false,"order":3,"slug":"quickstart-guides-1","title":"Quickstart Guides"},"parentDoc":null,"user":"5633eb67737ea01700ea328b","project":"5633ebff7e9e880d00af1a53","version":{"_id":"5a8fae0268264c001f20cc00","project":"5633ebff7e9e880d00af1a53","__v":2,"createdAt":"2018-02-23T06:00:34.961Z","releaseDate":"2018-02-23T06:00:34.961Z","categories":["5a8fae0268264c001f20cc01","5a8fae0268264c001f20cc02","5a8fae0368264c001f20cc03","5a8fae0368264c001f20cc04","5a8fae0368264c001f20cc05","5a8fae0368264c001f20cc06","5a8fae0368264c001f20cc07","5a8fae0368264c001f20cc08","5a8fae0368264c001f20cc09","5abaa7eb72d6dc0028a07bf3"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"__v":0,"updates":["5a716ce6a0827200245d3703"],"next":{"pages":[],"description":""},"createdAt":"2015-10-30T23:30:56.237Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"status\" : 200,\n  \"name\" : \"Jackpot\",\n  \"cluster_name\" : \"elasticsearch\",\n  \"version\" : {\n    \"number\" : \"1.5.2\",\n    \"build_hash\" : \"8682ee02d32bf1942b7207aa5d6c15658775c650\",\n    \"build_timestamp\" : \"2015-10-12T18:54:33Z\",\n    \"build_snapshot\" : false,\n    \"lucene_version\" : \"4.10.4\"\n  },\n  \"tagline\" : \"You Know, for Search\"\n}","name":""}]},"settings":"","auth":"required","params":[],"url":"/"},"isReference":false,"order":0,"body":"Every Bonsai cluster is created with a unique URL designed for secure, authenticated access to an Elasticsearch cluster. This URL allows a wide array of platforms and application clients to communicate with Elasticsearch. This URL looks something like this:\n\n```\nhttps://a1b2c3d4e:5f6g7h8i9:::at:::somehost-1234567.region-x-y.bonsaisearch.net\n```\n\nThis URL has the following parts:\n\n* **Protocol (ex: https).** The protocol to use for communicating with Elasticsearch. This can be either HTTP or HTTPS. The primary difference between the two is that HTTPS is encrypted, whereas HTTP is not. Bonsai defaults to HTTPS to ensure that your data can not be read in transit.\n* **Authentication Credentials (ex: a1b2c3d4e:5f6g7h8i9).** This is a randomly-generated username/password pair. By default, you will need to include these credentials _with every request_ to your cluster, otherwise Bonsai will return an `HTTP 401: Authorization required` message.\n* **Hostname (ex: something-1234567).** The hostname will be a concatenated string generated by your cluster's name, and a random number. This provides some security through obscurity by making guesses and enumeration extraordinarily difficult, as well as avoiding name collisions.\n* **Region (ex: us-east-1).** This is the region in which the cluster is provisioned. There are a number of possible regions for this, and we use the [AWS naming conventions](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html) to indicate where the cluster is located.\n* **Domain (ex: bonsaisearch.net).** Bonsai clusters can be accessed via one of two domains: bonsai.io and bonsaisearch.net. This is to avoid the rare case of a TLD outage; if the .io or .net TLD is down for some reason, the cluster can still be accessed.\n\nLet's examine these in greater detail.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Protocols and Ports\"\n}\n[/block]\nAll Bonsai clusters default to secure HTTPS using recent versions of TLS for encrypted communication. These connections should use port 443, the standard for SSL/TLS. \n\nWe also support unencrypted HTTP access over ports 80 and 9200.\n\nYou can see a table describing the protocols and ports available here:\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"80\",\n    \"0-1\": \"HTTP\",\n    \"0-2\": \"Unencrypted.\",\n    \"1-0\": \"**443**\",\n    \"1-1\": \"**HTTPS**\",\n    \"1-2\": \"**Default; recommended.**\",\n    \"2-0\": \"9200\",\n    \"2-1\": \"HTTP\",\n    \"2-2\": \"Unencrypted.\",\n    \"2-3\": \"Deprecated\",\n    \"3-0\": \"9300\",\n    \"3-2\": \"Not supported.\",\n    \"3-3\": \"Not supported\",\n    \"3-1\": \"Elasticsearch Native Binary Protocol\",\n    \"h-0\": \"Port\",\n    \"h-1\": \"Protocol\",\n    \"h-2\": \"Notes\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\nUnfortunately we do not support the native binary protocol on 9300 at this time. If your application strongly depends on the binary protocol, please contact our sales team at [info@bonsai.io](mailto:info@bonsai.io) to design a custom cluster deployment.\n[block:api-header]\n{\n  \"title\": \"Authentication Credentials\"\n}\n[/block]\nWhen your cluster is created, it is provided with a randomly generated set of credentials. In the example URL above, the API Key is `a1b2c3d4e` and the API Secret is `5f6g7h8i9`. These are often supplied to various HTTP or Elasticsearch clients as the HTTP username and password, and encoded according to the Basic Authorization scheme. (Cf. [RFC 2617 Section 2](https://www.ietf.org/rfc/rfc2617.txt).)\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Credentials are Random\",\n  \"body\": \"The cluster credentials are not the same as what you would use to log into your Bonsai/Heroku/Manifold account. These are randomly generated when the cluster is created.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"If you're seeing this message, then you're not including the correct authentication credentials in your request. Double check that the request includes the credentials shown in your dashboard and try again.\",\n  \"title\": \"HTTP 401: Authentication required\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"Because the URL includes authentication information, anyone with the fully-qualified URL can access your cluster. Treat the URL like a password: don't hard-code it into applications, don't check it into source control, and for Pete's sake, never ever paste it into a StackOverflow question. If you need to share your cluster URL with us for support purposes, the auth-less host name is all you need:\\n\\nBad: \\\"My cluster is https://username:password@somehost-1234567.us-east-1.bonsaisearch.net\\\"\\n\\nGood: \\\"My cluster is somehost-1234567\\\"\\n\\nIf your URL is leaked somehow, you can regenerate the credentials. See [The Dashboard](doc:bonsai-elasticsearch-dashboard) for more information.\",\n  \"title\": \"Keep Your URL Secret\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Hostname\"\n}\n[/block]\nEach Bonsai cluster has a unique hostname. In the example above, this is `somehost-1234567`. The hostname is a blend of your cluster's name along with a unique identifier. The hostname is immutable: once the cluster has been created, the hostname can not be changed. Keep this in mind when creating your cluster.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"When asking questions via our support channels, you may provide the unique identifier portion of your hostname (e.g., `somehost-1234567`) to help us cross-reference with your account and your cluster's logs.\",\n  \"title\": \"Hostnames and Support\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Region\"\n}\n[/block]\nAll Bonsai clusters have a region slug included in the URL. Some example slugs might be:\n\n* us-east-1\n* us-west-2\n* eu-west-1\n* ... and so on.\n\nThese slugs are based on the [AWS Regions and AZs](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html), and indicate where on the planet your cluster is running. Ideally, this will be as close as possible to your application servers, to minimize latency.\n[block:api-header]\n{\n  \"title\": \"Domain\"\n}\n[/block]\nAll Bonsai clusters can be accessed via either of two domains: bonsai.io or bonsaisearch.net. In other words, both of these URLs will work:\n\n```\nhttps://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net\nhttps://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsai.io\n```\n\nThis is a failover option to accommodate for the rare, but not unheard of, TLD outage. If there is an outage impacting .net or .io domains, users can point their application to whichever TLD is operational.\n[block:api-header]\n{\n  \"title\": \"Connecting to Elasticsearch via Curl\"\n}\n[/block]\nOne way to connect to Elasticsearch is with a command line tool called `curl`. Curl is easy to use and comes preinstalled on many operating systems (and is widely available for download and installation). Curl can send and receive data from your Bonsai Elasticsearch cluster like so:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net\\n{\\n  \\\"name\\\" : \\\"PvRcoFq\\\",\\n  \\\"cluster_name\\\" : \\\"elasticsearch\\\",\\n  \\\"cluster_uuid\\\" : \\\"DNlbVYS0TIGYwbQ6CUNwTw\\\",\\n  \\\"version\\\" : {\\n    \\\"number\\\" : \\\"5.4.3\\\",\\n    \\\"build_hash\\\" : \\\"eed30a8\\\",\\n    \\\"build_date\\\" : \\\"2017-06-22T00:34:03.743Z\\\",\\n    \\\"build_snapshot\\\" : false,\\n    \\\"lucene_version\\\" : \\\"6.5.1\\\"\\n  },\\n  \\\"tagline\\\" : \\\"You Know, for Search\\\"\\n}\\n\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nCurl can be used to create and remove indices, add data, check on cluster state and more:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Create an index called 'test'\\ncurl -s -XPUT https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net/test\\n{\\\"acknowledged\\\":true,\\\"shards_acknowledged\\\":true}\\n\\n# Add a document to the 'test' index\\ncurl -s -XPUT https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net/test/doc/1 -d '{\\\"title\\\":\\\"test doc\\\"}'\\n{\\\"_index\\\":\\\"test\\\",\\\"_type\\\":\\\"doc\\\",\\\"_id\\\":\\\"1\\\",\\\"_version\\\":1,\\\"result\\\":\\\"created\\\",\\\"_shards\\\":{\\\"total\\\":2,\\\"successful\\\":2,\\\"failed\\\":0},\\\"created\\\":true}\\n\\n# Delete the 'test' index\\ncurl -s -XDELETE https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net/test\\n{\\\"acknowledged\\\":true}\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Connecting to Elasticsearch via Browser\"\n}\n[/block]\nAnother way to connect to Elasticsearch is via your browser of choice. Simply copy the full URL from the Bonsai dashboard, and paste it into the browser's address bar. It should look something like this:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/5fa2414-getting-started-7.png\",\n        \"getting-started-7.png\",\n        604,\n        328,\n        \"#0b74e4\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Some browsers, as a security feature, will strip the authentication credentials from the URL to prevent them from being displayed in the address bar. The credentials are stored in a local session. However, if you subsequently copy/paste the URL from the address bar, it will drop the credentials. There are some other conditions that can cause the credentials to be lost from the active window.\\n\\nIf you're using a browser to interact with Elasticsearch and you are seeing HTTP 401 errors, try to copy/paste the credentials back into the address bar.\",\n  \"title\": \"HTTP 401: Authorization required When Using a Browser\"\n}\n[/block]\nThis method is good for reading the cluster state, but not so great for creating indices, updating data, etc.\n[block:api-header]\n{\n  \"title\": \"Connecting to Elasticsearch via Interactive Console\"\n}\n[/block]\nThe Bonsai dashboard offers an interactive console which allows users to engage with their cluster. This console simplifies the process of communicating with the cluster, and it obviates the need for dealing with credentials altogether.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/c16b6f5-console.gif\",\n        \"console.gif\",\n        952,\n        586,\n        \"#06353c\"\n      ],\n      \"caption\": \"The interactive console in action.\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"connecting-to-elasticsearch","type":"basic","title":"Connecting to Bonsai"}

Connecting to Bonsai


Every Bonsai cluster is created with a unique URL designed for secure, authenticated access to an Elasticsearch cluster. This URL allows a wide array of platforms and application clients to communicate with Elasticsearch. This URL looks something like this: ``` https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net ``` This URL has the following parts: * **Protocol (ex: https).** The protocol to use for communicating with Elasticsearch. This can be either HTTP or HTTPS. The primary difference between the two is that HTTPS is encrypted, whereas HTTP is not. Bonsai defaults to HTTPS to ensure that your data can not be read in transit. * **Authentication Credentials (ex: a1b2c3d4e:5f6g7h8i9).** This is a randomly-generated username/password pair. By default, you will need to include these credentials _with every request_ to your cluster, otherwise Bonsai will return an `HTTP 401: Authorization required` message. * **Hostname (ex: something-1234567).** The hostname will be a concatenated string generated by your cluster's name, and a random number. This provides some security through obscurity by making guesses and enumeration extraordinarily difficult, as well as avoiding name collisions. * **Region (ex: us-east-1).** This is the region in which the cluster is provisioned. There are a number of possible regions for this, and we use the [AWS naming conventions](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html) to indicate where the cluster is located. * **Domain (ex: bonsaisearch.net).** Bonsai clusters can be accessed via one of two domains: bonsai.io and bonsaisearch.net. This is to avoid the rare case of a TLD outage; if the .io or .net TLD is down for some reason, the cluster can still be accessed. Let's examine these in greater detail. [block:api-header] { "type": "basic", "title": "Protocols and Ports" } [/block] All Bonsai clusters default to secure HTTPS using recent versions of TLS for encrypted communication. These connections should use port 443, the standard for SSL/TLS. We also support unencrypted HTTP access over ports 80 and 9200. You can see a table describing the protocols and ports available here: [block:parameters] { "data": { "0-0": "80", "0-1": "HTTP", "0-2": "Unencrypted.", "1-0": "**443**", "1-1": "**HTTPS**", "1-2": "**Default; recommended.**", "2-0": "9200", "2-1": "HTTP", "2-2": "Unencrypted.", "2-3": "Deprecated", "3-0": "9300", "3-2": "Not supported.", "3-3": "Not supported", "3-1": "Elasticsearch Native Binary Protocol", "h-0": "Port", "h-1": "Protocol", "h-2": "Notes" }, "cols": 3, "rows": 4 } [/block] Unfortunately we do not support the native binary protocol on 9300 at this time. If your application strongly depends on the binary protocol, please contact our sales team at [info@bonsai.io](mailto:info@bonsai.io) to design a custom cluster deployment. [block:api-header] { "title": "Authentication Credentials" } [/block] When your cluster is created, it is provided with a randomly generated set of credentials. In the example URL above, the API Key is `a1b2c3d4e` and the API Secret is `5f6g7h8i9`. These are often supplied to various HTTP or Elasticsearch clients as the HTTP username and password, and encoded according to the Basic Authorization scheme. (Cf. [RFC 2617 Section 2](https://www.ietf.org/rfc/rfc2617.txt).) [block:callout] { "type": "info", "title": "Credentials are Random", "body": "The cluster credentials are not the same as what you would use to log into your Bonsai/Heroku/Manifold account. These are randomly generated when the cluster is created." } [/block] [block:callout] { "type": "warning", "body": "If you're seeing this message, then you're not including the correct authentication credentials in your request. Double check that the request includes the credentials shown in your dashboard and try again.", "title": "HTTP 401: Authentication required" } [/block] [block:callout] { "type": "danger", "body": "Because the URL includes authentication information, anyone with the fully-qualified URL can access your cluster. Treat the URL like a password: don't hard-code it into applications, don't check it into source control, and for Pete's sake, never ever paste it into a StackOverflow question. If you need to share your cluster URL with us for support purposes, the auth-less host name is all you need:\n\nBad: \"My cluster is https://username:password@somehost-1234567.us-east-1.bonsaisearch.net\"\n\nGood: \"My cluster is somehost-1234567\"\n\nIf your URL is leaked somehow, you can regenerate the credentials. See [The Dashboard](doc:bonsai-elasticsearch-dashboard) for more information.", "title": "Keep Your URL Secret" } [/block] [block:api-header] { "title": "Hostname" } [/block] Each Bonsai cluster has a unique hostname. In the example above, this is `somehost-1234567`. The hostname is a blend of your cluster's name along with a unique identifier. The hostname is immutable: once the cluster has been created, the hostname can not be changed. Keep this in mind when creating your cluster. [block:callout] { "type": "info", "body": "When asking questions via our support channels, you may provide the unique identifier portion of your hostname (e.g., `somehost-1234567`) to help us cross-reference with your account and your cluster's logs.", "title": "Hostnames and Support" } [/block] [block:api-header] { "title": "Region" } [/block] All Bonsai clusters have a region slug included in the URL. Some example slugs might be: * us-east-1 * us-west-2 * eu-west-1 * ... and so on. These slugs are based on the [AWS Regions and AZs](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html), and indicate where on the planet your cluster is running. Ideally, this will be as close as possible to your application servers, to minimize latency. [block:api-header] { "title": "Domain" } [/block] All Bonsai clusters can be accessed via either of two domains: bonsai.io or bonsaisearch.net. In other words, both of these URLs will work: ``` https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsai.io ``` This is a failover option to accommodate for the rare, but not unheard of, TLD outage. If there is an outage impacting .net or .io domains, users can point their application to whichever TLD is operational. [block:api-header] { "title": "Connecting to Elasticsearch via Curl" } [/block] One way to connect to Elasticsearch is with a command line tool called `curl`. Curl is easy to use and comes preinstalled on many operating systems (and is widely available for download and installation). Curl can send and receive data from your Bonsai Elasticsearch cluster like so: [block:code] { "codes": [ { "code": "curl https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net\n{\n \"name\" : \"PvRcoFq\",\n \"cluster_name\" : \"elasticsearch\",\n \"cluster_uuid\" : \"DNlbVYS0TIGYwbQ6CUNwTw\",\n \"version\" : {\n \"number\" : \"5.4.3\",\n \"build_hash\" : \"eed30a8\",\n \"build_date\" : \"2017-06-22T00:34:03.743Z\",\n \"build_snapshot\" : false,\n \"lucene_version\" : \"6.5.1\"\n },\n \"tagline\" : \"You Know, for Search\"\n}\n", "language": "curl" } ] } [/block] Curl can be used to create and remove indices, add data, check on cluster state and more: [block:code] { "codes": [ { "code": "# Create an index called 'test'\ncurl -s -XPUT https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net/test\n{\"acknowledged\":true,\"shards_acknowledged\":true}\n\n# Add a document to the 'test' index\ncurl -s -XPUT https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net/test/doc/1 -d '{\"title\":\"test doc\"}'\n{\"_index\":\"test\",\"_type\":\"doc\",\"_id\":\"1\",\"_version\":1,\"result\":\"created\",\"_shards\":{\"total\":2,\"successful\":2,\"failed\":0},\"created\":true}\n\n# Delete the 'test' index\ncurl -s -XDELETE https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net/test\n{\"acknowledged\":true}", "language": "curl" } ] } [/block] [block:api-header] { "title": "Connecting to Elasticsearch via Browser" } [/block] Another way to connect to Elasticsearch is via your browser of choice. Simply copy the full URL from the Bonsai dashboard, and paste it into the browser's address bar. It should look something like this: [block:image] { "images": [ { "image": [ "https://files.readme.io/5fa2414-getting-started-7.png", "getting-started-7.png", 604, 328, "#0b74e4" ] } ] } [/block] [block:callout] { "type": "info", "body": "Some browsers, as a security feature, will strip the authentication credentials from the URL to prevent them from being displayed in the address bar. The credentials are stored in a local session. However, if you subsequently copy/paste the URL from the address bar, it will drop the credentials. There are some other conditions that can cause the credentials to be lost from the active window.\n\nIf you're using a browser to interact with Elasticsearch and you are seeing HTTP 401 errors, try to copy/paste the credentials back into the address bar.", "title": "HTTP 401: Authorization required When Using a Browser" } [/block] This method is good for reading the cluster state, but not so great for creating indices, updating data, etc. [block:api-header] { "title": "Connecting to Elasticsearch via Interactive Console" } [/block] The Bonsai dashboard offers an interactive console which allows users to engage with their cluster. This console simplifies the process of communicating with the cluster, and it obviates the need for dealing with credentials altogether. [block:image] { "images": [ { "image": [ "https://files.readme.io/c16b6f5-console.gif", "console.gif", 952, 586, "#06353c" ], "caption": "The interactive console in action." } ] } [/block]