Create your first instance of OpenSearch and connect to it

Prerequisites

• You have a STACKIT customer account: Create a customer Account
• You have a STACKIT user account: Create a user account
• You have a STACKIT project: Create a project

Prepare, order and create an instance

In this Getting started guide you will create an instance and configure it. This guide shows the most common settings for a small developer environment. When following this guide, you will work with the STACKIT Portal.

1. Visit the STACKIT Portal.
2. On the sidebar click on OpenSearch.
3. On the bar on the top click on Create OpenSearch.

After completing the steps, you see an overlay with three sections:

General information

• Either leave the name for the instance as it is or insert a custom one.
• Select Instance version.

Plans

• Leave the plan settings as they are stackit-opensearch-1.4.10-single (1 vCPU and 4GB RAM) unless you know in advance how much resources you’ll need. You can change the plan anytime by selecting Plans in the sidebar.

Custom parameters

• Add your clients IPv4 address to the list of ACLs.

  If you want to connect with the computer, with which you are browsing these docs, use Cloudflare’s IP trace tool to determine your IPv4 address. Open your browser of choice and visit the Cloudflare Trace Tool. Copy the value behind ip. It should look like xxx.xxx.xxx.xxx. Now append /32 to it and add it as ACL entry. To do so, add a comma behind the last IP and add yours. The field requires a comma separated list of IP networks in CIDR notation.

If you don’t add your clients IPv4 address to the list of ACLs, you won’t be able to connect to your instance!

After reviewing every setting, click on Order fee-based to create your new instance. Then you will see a confirmation that your instance is created. Your new instance will be added to the list of instances. After a few minutes it will switch from Creating to Active.

Performing the action described here may incur costs or change your ongoing costs. Please check carefully what one-time and/or ongoing costs will be charged, and only perform the actions if you agree and are authorized to do so.

Configure your instance

To make any changes to your instance, you need to select it. Please click on the sidebar on OpenSearch and then on your newly created instance. Then the overview page of you instance will be displayed.

Create credentials

1. Navigate to OpenSearch and select the instance.

2. Select Credentials in the menu.

3. Click on Create credentials.

   A service key will be created.

4. Store the Endpoint, Username and Password.

5. Click on Close.

Test the connection to your new instance

You can connect to OpenSearch instances using any REST API tool. Below are examples of connecting using the terminal and curl.

Terminal with curl

To connect to the OpenSearch instance, the following curl must be defined:

Parameter	Meaning	Example
Endpoint	The endpoint of your OpenSearch Instance.	https://sed24c2ed-0.data.eu01.onstackit.cloud:49339
Username	The username	a9s4051b692…
Password	The password	a9s4051b692…

curl -X GET [Endpoint] --user [Username]:[Password]

You get a response like this:

{
  "name" : "os/49f0d818-18ac-4301-91af-48b2ebe9a670",
  "cluster_name" : "sed24c2ed",
  "cluster_uuid" : "Y3xuV2lPTrK6snUyaNGnhw",
  "version" : {
    "distribution" : "opensearch",
    "number" : "2.19.1",
    "build_type" : "tar",
    "build_hash" : "2e4741fb45d1b150aaeeadf66d41445b23ff5982",
    "build_date" : "2025-02-27T01:16:47.726162386Z",
    "build_snapshot" : false,
    "lucene_version" : "9.12.1",
    "minimum_wire_compatibility_version" : "7.10.0",
    "minimum_index_compatibility_version" : "7.0.0"
  },
  "tagline" : "The OpenSearch Project: https://opensearch.org/"
}

You have now access to your OpenSearch service via its REST API. For more details on how to use the OpenSearch visit the How-Tos or the OpenSearch documentation.

Insert and query data

To get familiar with OpenSearch you can insert and query some sample data.

First add some sample data into OpenSearch.

Parameter	Meaning	Example
Endpoint	The endpoint of your OpenSearch Instance.	https://sed24c2ed-0.data.eu01.onstackit.cloud:49339
Username	The username	a9s4051b692…
Password	The password	a9s4051b692…
Data	A json you want to store in OpenSearch.	{ "Title": "The White Lioness", "Genre": "Thriller", "Year": 1993, "Author": "Henning Mankell", "Type": "novel" }

# Book 1
curl -X POST [Endpoint]/books/_doc/ \
  --user [Username]:[Password] \
  --header "Content-Type: application/json" \
  --data '{
           "Title": "The White Lioness",
           "Genre": "Thriller",
           "Year": 1993,
           "Author": "Henning Mankell",
           "Type": "novel"
         }'

# Book 2
curl -X POST [Endpoint]/books/_doc/ \
  --user [Username]:[Password] \
  --header "Content-Type: application/json" \
  --data '{
           "Title": "1984",
           "Genre": "Dystopian Fiction",
           "Year": 1949,
           "Author": "George Orwell",
           "Type": "novel"
         }'

# Book 3
curl -X POST [Endpoint]/books/_doc/ \
  --user [Username]:[Password] \
  --header "Content-Type: application/json" \
  --data '{
           "Title": "The Hobbit",
           "Genre": "Fantasy",
           "Year": 1937,
           "Author": "J.R.R. Tolkien",
           "Type": "novel"
         }'

OpenSearch should answer with a response which is similar to:

{"_index":"books","_id":"U9Fl6JkBSNAfLfHa8Pvs","_version":1,"result":"created","_shards":{"total":4,"successful":1,"failed":0},"_seq_no":0,"_primary_term":1}%

Now you can search for one entry in the dataset. This corresponds with a use case where a user searches in the frontend for a specific book:

Parameter	Meaning	Example
Endpoint	The endpoint of your OpenSearch Instance.	https://sed24c2ed-0.data.eu01.onstackit.cloud:49339
Username	The username	a9s4051b692…
Password	The password	a9s4051b692…
Data	The query by which you want to filter	{ "query": { "wildcard": { "Title.keyword": { "value": "*Hobbit*", "case_insensitive": true } } } }

curl -X POST [Endpoint]/books/_search?pretty \
  --user [Username]:[Password] \
  --header "Content-Type: application/json" \
  --data '{
           "query": {
             "wildcard": {
               "Title.keyword": {
                 "value": "*Hobbit*",
                 "case_insensitive": true
               }
             }
           }
         }'

You get an output similar to this:

{
  "took" : 662,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 1,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "books",
        "_id" : "V9Fv6JkBSNAfLfHa6vu7",
        "_score" : 1.0,
        "_source" : {
          "Title" : "The Hobbit",
          "Genre" : "Fantasy",
          "Year" : 1937,
          "Author" : "J.R.R. Tolkien",
          "Type" : "novel"
        }
      }
    ]
  }
}

Now you executed some basic commands with OpenSearch. From here on you can dig deeper with the How-tos.