{"_id":"5633fdb0fa71f30d00ba74e1","parentDoc":null,"__v":73,"user":"5633eb67737ea01700ea328b","project":"5633ebff7e9e880d00af1a53","version":{"_id":"5633ec007e9e880d00af1a56","project":"5633ebff7e9e880d00af1a53","__v":15,"createdAt":"2015-10-30T22:15:28.105Z","releaseDate":"2015-10-30T22:15:28.105Z","categories":["5633ec007e9e880d00af1a57","5633f072737ea01700ea329d","5637a37d0704070d00f06cf4","5637cf4e7ca5de0d00286aeb","564503082c74cf1900da48b4","564503cb7f1fff210078e70a","567af26cb56bac0d0019d87d","567afeb8802b2b17005ddea0","567aff47802b2b17005ddea1","567b0005802b2b17005ddea3","568adfffcbd4ca0d00aebf7e","56ba80078cf7c9210009673e","574d127f6f075519007da3d0","574fde60aef76a0e00840927","57a22ba6cd51b22d00f623a0"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"5633f072737ea01700ea329d","version":"5633ec007e9e880d00af1a56","__v":4,"pages":["5633fdb0fa71f30d00ba74e1","5637ce94aa96490d00a64f78","5637d7a34dbdd919001b27ab","56e8747747de1e170005945a"],"project":"5633ebff7e9e880d00af1a53","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-10-30T22:34:26.440Z","from_sync":false,"order":0,"slug":"early-project-setup","title":"Early Project Setup"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-10-30T23:30:56.237Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","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}","language":"json","status":200}]},"settings":"","auth":"required","params":[],"url":"/"},"isReference":false,"order":1,"body":"Elasticsearch provides developers with a well-designed RESTful JSON API that operates over HTTP. Each Bonsai cluster is created with a unique URL designed for secure, authenticated access to the Elasticsearch API.\n\nBecause Elasticsearch operates over HTTP, there are any number of platforms and application clients that can integrate with it. We will start by looking at the properties for an example cluster URL to provide general context of how to connect to your cluster. Following that, we'll include several code examples for common platforms, as well as some common tips and gotchas to keep in mind.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Cluster URL Properties\"\n}\n[/block]\n```\nhttps://wji4cg72wu:1lr4slrzuz:::at:::acme-development-8779249584.us-east-1.bonsai.io/\n```\n\n## Protocol\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. Deprecated.\",\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]\nAll Bonsai clusters default to secure HTTPS using recent versions of TLS for encryption. These connections communicate on the HTTPS default port of 443. We also support unencrypted HTTP access on the default HTTP port of 80.\n\nOur support for unencrypted HTTP on the Elasticsearch internal port 9200 is deprecated and will be removed from future versions of our platform. Unfortunately we do not support the native binary protocol on 9300 at this time.\n\nIf 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\n\n## Hostname\n\nEach cluster has a unique hostname, which is composed of three components. The first is the unique identifier, `acme-development-8779249584` in the example above, which is a blend of your cluster's name along with a unique identifier. The next component of the hostname, `region.bonsai.io`, is the regional endpoint based on the region in which your cluster is hosted.\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., `acme-development-8779249584`) to help us cross-reference with your account and your cluster's logs.\"\n}\n[/block]\n## API Credentials\n\nWhen it is created, your cluster is provided with a randomly generated set of credentials. In the example URL above, the API Key is `wji4cg72wu` and the API Secret is `1lr4slrzuz`. 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\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"It is your responsibility to maintain the security of your cluster's API credentials. It is important that you do not share or publish these credentials—not even with us via customer support. You may regenerate your credentials any time via your cluster's management console.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Configuration Examples\"\n}\n[/block]\nDon't see your language or platform of choice included here? No problem. Drop us a line and let us know what you use, we'll happily help get you set up.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"require 'elasticsearch'\\n\\n\",\n      \"language\": \"ruby\",\n      \"name\": \"Ruby\"\n    },\n    {\n      \"code\": \"# requirements.txt:\\n# elasticsearch>=1.0.0,<2.0.0\\n\\nimport os, base64, re, logging\\nfrom elasticsearch import Elasticsearch\\n\\n# Log transport details (optional):\\nlogging.basicConfig(level=logging.INFO)\\n\\n# Parse the auth and host from env:\\nbonsai = os.environ['BONSAI_URL']\\nauth = re.search('https\\\\:\\\\/\\\\/(.*)\\\\@', bonsai).group(1).split(':')\\nhost = bonsai.replace('https://%s:%s@' % (auth[0], auth[1]), '')\\n\\n# Connect to cluster over SSL using auth for best security:\\nes_header = [{\\n  'host': host,\\n  'port': 443,\\n  'use_ssl': True,\\n  'http_auth': (auth[0],auth[1])\\n}]\\n\\n# Instantiate the new Elasticsearch connection:\\nes = Elasticsearch(es_header)\\n\\n# Verify that Python can talk to Bonsai (optional):\\nes.ping()\\n\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"// Initialize the parameters for the cluster\\n$params = array();\\n$params['hosts'] = array (\\n    getenv(\\\"BONSAI_URL\\\"),\\n);\\n\\n$client = new Elasticsearch\\\\Client($params);\\n\\n// Indexing documents\\n\\n$indexParams = array();\\n$indexParams['index']  = 'my_index';    //index\\n\\n$client->indices()->create($indexParams);\\n\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"# This example walks through basic setup of search in a Ruby on Rails\\n# app, using the official Elasticsearch client gems.\\n\\n###\\n# 1. Gemfile\\n##\\n\\n# Elasticsearch::Model provides ORM integrations and includes low-level\\n# transport client via gem dependencies.\\ngem 'elasticsearch-model'\\n\\n# Elasticsearch::Rails includes Rake tasks and other Rails utilities.\\ngem 'elasticsearch-rails'\\n\\n\\n###\\n# 2. config/initializers/elasticsearch.rb\\n##\\n\\n# Require the Elasticsearch::Model gem.\\nrequire 'elasticsearch/model'\\n\\n# Load the Bonsai URL into your app. We recommend the \\\"12 Factor App\\\"\\n# convention of using an environment variable. You may also use the\\n# Rails 4.2+ config_for method to fetch the URL from an optional\\n# config/elasticsearch.yml file.\\n\\nBONSAI_URL = ENV['BONSAI_URL'] ||\\n  Rails.application.config_for(:elasticsearch)[\\\"url\\\"]\\n\\n# Set up an app-wide client object\\nElasticsearch::Model.client = Elasticsearch::Client.new(\\n  url: BONSAI_URL,\\n  log: true\\n)\\n\\n###\\n# 3. lib/tasks/elasticsearch.rake\\n##\\n\\n# Include various Elasticsearch rake tasks, i.e., for importing data\\nrequire 'elasticsearch/rails/tasks/import'\\n\\n###\\n# 4. config/application.rb\\n##\\n\\n# Optional: add extra instrumentation to your logs\\nrequire 'elasticsearch/rails/instrumentation'\\n\\n###\\n# 5. Very basic model integration, which indexes all fields. \\n# Refer to the client docs for more advanced usage.\\n##\\n\\nclass User < ActiveRecord::Base\\n  include Elasticsearch::Model\\n  include Elasticsearch::Model::Callbacks\\nend\\n\\n\",\n      \"language\": \"ruby\",\n      \"name\": \"Ruby on Rails\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"connecting-to-elasticsearch","type":"basic","title":"Connecting to Elasticsearch"}

Connecting to Elasticsearch


Elasticsearch provides developers with a well-designed RESTful JSON API that operates over HTTP. Each Bonsai cluster is created with a unique URL designed for secure, authenticated access to the Elasticsearch API. Because Elasticsearch operates over HTTP, there are any number of platforms and application clients that can integrate with it. We will start by looking at the properties for an example cluster URL to provide general context of how to connect to your cluster. Following that, we'll include several code examples for common platforms, as well as some common tips and gotchas to keep in mind. [block:api-header] { "type": "basic", "title": "Cluster URL Properties" } [/block] ``` https://wji4cg72wu:1lr4slrzuz@acme-development-8779249584.us-east-1.bonsai.io/ ``` ## Protocol [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. Deprecated.", "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] All Bonsai clusters default to secure HTTPS using recent versions of TLS for encryption. These connections communicate on the HTTPS default port of 443. We also support unencrypted HTTP access on the default HTTP port of 80. Our support for unencrypted HTTP on the Elasticsearch internal port 9200 is deprecated and will be removed from future versions of our platform. 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. ## Hostname Each cluster has a unique hostname, which is composed of three components. The first is the unique identifier, `acme-development-8779249584` in the example above, which is a blend of your cluster's name along with a unique identifier. The next component of the hostname, `region.bonsai.io`, is the regional endpoint based on the region in which your cluster is hosted. [block:callout] { "type": "info", "body": "When asking questions via our support channels, you may provide the unique identifier portion of your hostname (e.g., `acme-development-8779249584`) to help us cross-reference with your account and your cluster's logs." } [/block] ## API Credentials When it is created, your cluster is provided with a randomly generated set of credentials. In the example URL above, the API Key is `wji4cg72wu` and the API Secret is `1lr4slrzuz`. 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": "warning", "body": "It is your responsibility to maintain the security of your cluster's API credentials. It is important that you do not share or publish these credentials—not even with us via customer support. You may regenerate your credentials any time via your cluster's management console." } [/block] [block:api-header] { "type": "basic", "title": "Configuration Examples" } [/block] Don't see your language or platform of choice included here? No problem. Drop us a line and let us know what you use, we'll happily help get you set up. [block:code] { "codes": [ { "code": "require 'elasticsearch'\n\n", "language": "ruby", "name": "Ruby" }, { "code": "# requirements.txt:\n# elasticsearch>=1.0.0,<2.0.0\n\nimport os, base64, re, logging\nfrom elasticsearch import Elasticsearch\n\n# Log transport details (optional):\nlogging.basicConfig(level=logging.INFO)\n\n# Parse the auth and host from env:\nbonsai = os.environ['BONSAI_URL']\nauth = re.search('https\\:\\/\\/(.*)\\@', bonsai).group(1).split(':')\nhost = bonsai.replace('https://%s:%s@' % (auth[0], auth[1]), '')\n\n# Connect to cluster over SSL using auth for best security:\nes_header = [{\n 'host': host,\n 'port': 443,\n 'use_ssl': True,\n 'http_auth': (auth[0],auth[1])\n}]\n\n# Instantiate the new Elasticsearch connection:\nes = Elasticsearch(es_header)\n\n# Verify that Python can talk to Bonsai (optional):\nes.ping()\n", "language": "python" }, { "code": "// Initialize the parameters for the cluster\n$params = array();\n$params['hosts'] = array (\n getenv(\"BONSAI_URL\"),\n);\n\n$client = new Elasticsearch\\Client($params);\n\n// Indexing documents\n\n$indexParams = array();\n$indexParams['index'] = 'my_index'; //index\n\n$client->indices()->create($indexParams);\n", "language": "php" }, { "code": "# This example walks through basic setup of search in a Ruby on Rails\n# app, using the official Elasticsearch client gems.\n\n###\n# 1. Gemfile\n##\n\n# Elasticsearch::Model provides ORM integrations and includes low-level\n# transport client via gem dependencies.\ngem 'elasticsearch-model'\n\n# Elasticsearch::Rails includes Rake tasks and other Rails utilities.\ngem 'elasticsearch-rails'\n\n\n###\n# 2. config/initializers/elasticsearch.rb\n##\n\n# Require the Elasticsearch::Model gem.\nrequire 'elasticsearch/model'\n\n# Load the Bonsai URL into your app. We recommend the \"12 Factor App\"\n# convention of using an environment variable. You may also use the\n# Rails 4.2+ config_for method to fetch the URL from an optional\n# config/elasticsearch.yml file.\n\nBONSAI_URL = ENV['BONSAI_URL'] ||\n Rails.application.config_for(:elasticsearch)[\"url\"]\n\n# Set up an app-wide client object\nElasticsearch::Model.client = Elasticsearch::Client.new(\n url: BONSAI_URL,\n log: true\n)\n\n###\n# 3. lib/tasks/elasticsearch.rake\n##\n\n# Include various Elasticsearch rake tasks, i.e., for importing data\nrequire 'elasticsearch/rails/tasks/import'\n\n###\n# 4. config/application.rb\n##\n\n# Optional: add extra instrumentation to your logs\nrequire 'elasticsearch/rails/instrumentation'\n\n###\n# 5. Very basic model integration, which indexes all fields. \n# Refer to the client docs for more advanced usage.\n##\n\nclass User < ActiveRecord::Base\n include Elasticsearch::Model\n include Elasticsearch::Model::Callbacks\nend\n\n", "language": "ruby", "name": "Ruby on Rails" } ] } [/block]