Set advanced settings with the Amazon OpenSearch Service Dashboards API

Amazon OpenSearch Service (successor to Amazon Elasticsearch Service) is a fully managed service that you can use to deploy and operate OpenSearch clusters cost-effectively at scale in the AWS Cloud. The service makes it easy for you to perform interactive log analytics, real-time application monitoring, website search, and more by offering the latest versions of OpenSearch, support for 19 versions of Elasticsearch (1.5 to 7.10 versions), and visualization capabilities powered by OpenSearch Dashboards and Kibana (1.5 to 7.10 versions).

A common use case of OpenSearch in multi-tenant environments is to use tenants in OpenSearch Dashboards and provide segregated index patterns, dashboards, and visualizations to different teams in the organization. Tenants in OpenSearch Dashboards aren’t the same as indexes, where OpenSearch organizes all data. You may still have multiple indexes for multi-tenancy and tenants for controlling access to OpenSearch Dashboards’ saved objects.

In this post, we focus on operationalizing advanced settings for OpenSearch Dashboards tenants with programmatic ways, in particular with the Dashboards Advanced Settings API. For a deeper insight into multi-tenancy in OpenSearch, refer to OpenSearch Dashboards multi-tenancy.

One example of advanced settings configurations is deploying time zone settings in an environment where each tenant is aligned to a different geographic area with specific time zone. We explain the time zone configuration with the UI and demonstrate configuring it with the OpenSearch Dashboards Advanced Settings API using curl. This post also provides guidance for other advanced settings you may wish to include in your deployment.

To follow along in this post, make sure you have an Amazon OpenSearch Service domain with access to OpenSearch Dashboards through a role with administrator privileges for the domain. For more information about enabling access control mechanisms for your domains, see Fine-grained access control in Amazon OpenSearch Service.

The following examples use Amazon OpenSearch Service version 1.0, which was the latest release at the time of writing.

Configure advanced settings in the OpenSearch Dashboards UI

To configure advanced settings via the OpenSearch Dashboards UI, complete the following steps:

1. Log in to OpenSearch Dashboards.
2. Choose your user icon and choose Switch Tenants to choose the tenant you want to change configuration for.

By default, all OpenSearch Dashboards users have access to two tenants: private and global. The global tenant is shared between every OpenSearch Dashboards user. The private tenant is exclusive to each user and used mostly for experimenting before publishing configuration to other tenants. Make sure to check your configurations in the private tenant before replicating in other tenants, including global.

3. Choose Stack Management in the navigation pane, then choose Advanced Settings.
   
4. In your desired tenant context, choose a value for Timezone for date formatting.

In this example, we change the time zone from the default selection Browser to US/Eastern.

5. Choose Save changes.
   

Configure advanced settings with the OpenSearch Dashboards API

For environments where you prefer to perform operations programmatically, Amazon OpenSearch Service provides the ability to configure advanced settings with the OpenSearch Dashboards advanced settings API.

Let’s walk through configuring the time zone using curl.

1. First, you need to authenticate to the API endpoint with your user name and password, and retrieve the authorization cookies into the file auth.txt:

curl -X POST  https://<domain_endpoint>/_dashboards/auth/login 
-H "osd-xsrf: true" 
-H "content-type:application/json" 
-d '{"username":"<username>", "password":"<password>"}' 
-c auth.txt

In this example, we configure OpenSearch Dashboards to use the internal user database, and the user inherits administrative permissions under the global tenant. In multi-tenant environments, the user is required to have relevant tenant permissions. You can see an example of this in the next section, where we illustrate a multi-tenant environment. Access control in OpenSearch Dashboards is a broad and important topic, and it would be unfair to try to squeeze all of it in this post. Therefore, we don’t cover access control in depth here. For additional information on access control in multi-tenant OpenSearch Dashboards, refer to OpenSearch Dashboards multi-tenancy.

The auth.txt file holds authorization cookies that you use to pass configuration changes to the API endpoint. The auth.txt file should look similar to the following code:

# Netscape HTTP Cookie File
# https://curl.haxx.se/docs/http-cookies.html
# This file was generated by libcurl! Edit at your own risk.

#HttpOnly_<domain_endpoint> FALSE   /_dashboards    TRUE    0       security_authentication Fe26.2**80fca234dd0974fb6dfe9427e6b8362ba1dd78fc5a71
e7f9803694f40980012b*k9QboTT5A24hs71_wN32Cw*9-RvY2UhS-Cmat4RZPHohTbczyGRjmHezlIlhwePG1gv_P2bgSuZhx9XBV9I-zzdxrZIbJTTpymy4mv1rAB_GRuXjt-6ITUfsG58GrI7TI7D3pWKaw8n6lrhamccGYqL9K_dQrE4kr_godwEDLydR1d_
Oc11jEG98yi_O0qhBTu1kDNzNAEqgXEoaLS--afnbwPS0zvqUc4MUgrfGQOTt7mUoWMC778Tpii4V4gxhAcRqe_KoYQG1LhUq-j9XTHCouzB4qTJ8gR3tlbVYMFwhA**f278b1c9f2c9e4f50924c47bfd1a992234400c6f11ee6f005beecc4201760998*3Aj8gQAIKKPoUR0PX-5doFgZ9zqxlcB3YbfDgJIBNLU

2. Construct configuration changes within the curl body and submit them using an authorization cookie. In this example, we included a sample to modify the time zone to US/Eastern.

curl -X PUT https://<domain_endpoint>/_dashboards/api/saved_objects/config/1.0.0-SNAPSHOT 
-H "osd-xsrf:true" 
-H "content-type:application/json" 
-d '{"attributes":{"dateFormat:tz":"US/Eastern"}}' 
-b auth.txt

By default, the constructed API modifies the configuration in the private tenant, which is exclusive to each user, can’t be shared, and is ideal for testing. We provide instructions to modify configuration in multi-tenant environments later in the post.

Your API call should receive a response similar to the following code, indicating the changes you submitted:

{"id":"1.0.0-SNAPSHOT","type":"config","updated_at":"2021-09-06T19:59:42.425Z","version":"WzcsMV0=","namespaces":["default"],"attributes":{"dateFormat:tz":"US/Eastern"}}

If you prefer to make multiple changes, you can construct the API call as follows:

curl -X PUT https://<domain_endpoint>/_dashboards/api/saved_objects/config/1.0.0-SNAPSHOT 
-H "osd-xsrf:true" 
-H "content-type:application/json" 
-d 
'{
    "attributes":{
      "dateFormat:tz":"US/Eastern",
      "dateFormat:dow":"Monday"
    }
 }' 
-b auth.txt

To retrieve the latest configuration changes, construct a GET request as follows:

curl -X GET https://<domain_endpoint>/_dashboards/api/saved_objects/config/1.0.0-SNAPSHOT 
-H "osd-xsrf:true" 
-H "content-type:application/json" 
-b auth.txt

Configure advanced settings with the OpenSearch Dashboards API in multi-tenant environments

Tenants in OpenSearch Dashboards are commonly used to share custom index patterns, visualizations, dashboards, and other OpenSearch objects with different teams or organizations.

The OpenSearch Dashboards API provides the ability to modify advanced settings in different tenants. In the previous section, we covered making advanced configuration changes for a private tenant. We now walk through a similar scenario for multiple tenants.

1. First, you need to authenticate to the API endpoint and retrieve the authorization cookies into the file auth.txt. You can construct this request in the same way you would in a single-tenant environment as described in the previous section.

In multi-tenant environments, make sure you configure the user’s role with relevant tenant permissions. One pattern is to associate the user to the kibana_user and a custom group that has tenant permissions. In our example, we associated the tenant admin user tenant-a_admin_user to the two roles as shown in the following code: the kibana_user system role and a custom tenant-a_admin_role that includes tenant permissions.

GET _plugins/_security/api/account
{
  "user_name" : "tenant-a_admin_user",
  "is_reserved" : false,
  "is_hidden" : false,
  "is_internal_user" : true,
  "user_requested_tenant" : "tenant-a",
  "backend_roles" : [
    ""
  ],
  "custom_attribute_names" : [ ],
  "tenants" : {
    "global_tenant" : true,
    "tenant-a_admin_user" : true,
    "tenant-a" : true
  },
  "roles" : [
    "tenant-a_admin_role",
    "kibana_user"
  ]
}


GET _plugins/_security/api/roles/tenant-a_admin_role
{
  "tenant-a_admin_role" : {
    "reserved" : false,
    "hidden" : false,
    "cluster_permissions" : [ ],
    "index_permissions" : [ ],
    "tenant_permissions" : [
      {
        "tenant_patterns" : [
          "tenant-a"
        ],
        "allowed_actions" : [
          "kibana_all_write"
        ]
      }
    ],
    "static" : false
  }
}

After authenticating to the OpenSearch Dashboards API, the auth.txt file holds authorization cookies that you use to pass configuration changes to the API endpoint. The content of the auth.txt file should be similar to the one we illustrated in the previous section.

2. Construct the configuration changes by adding a securitytenant header. In this example, we modify the time zone and day of week in tenant-a:

curl -X PUT https://<domain_endpoint>/_dashboards/api/saved_objects/config/1.0.0-SNAPSHOT 
-H "osd-xsrf:true" 
-H "content-type:application/json" 
-H "securitytenant: tenant-a" 
-d 
'{
    "attributes":{
     "dateFormat:tz":"US/Eastern",
     "dateFormat:dow":"Monday"
    }
 }' 
-b auth.txt

The OpenSearch Dashboards API endpoint returns a response similar to the following:

{"id":"1.0.0-SNAPSHOT","type":"config","updated_at":"2021-10-10T17:41:47.249Z","version":"WzEsMV0=","namespaces":["default"],"attributes":{"dateFormat:tz":"US/Eastern","dateFormat:dow":"Monday"}}

You could also verify the configuration changes in the OpenSearch Dashboards UI, as shown in the following screenshot.

Conclusion

In this post, you used the Amazon OpenSearch Service Dashboards UI and API to configure advanced settings for a single-tenant and multi-tenant environment. Implementing OpenSearch Dashboards at scale in multi-tenant environments requires more efficient methods than simply using the UI. This is especially important in environments where you serve centralized logging and monitoring domains for different teams. You can use the OpenSearch Dashboards APIs we illustrated in this post and bake your advanced setting configurations into your infrastructure code to accelerate your deployments!

Let us know about your questions and other topics you’d like us to cover in the comment section.

About the Authors

Prashant Agrawal is a Specialist Solutions Architect at Amazon Web Services based in Seattle, WA.. Prashant works closely with Amazon OpenSearch team, helping customers migrate their workloads to the AWS Cloud. Before joining AWS, Prashant helped various customers use Elasticsearch for their search and analytics use cases.

Evren Sen is a Solutions Architect at AWS, focusing on strategic financial services customers. He helps his customers create Cloud Center of Excellence and design, and deploy solutions on the AWS Cloud. Outside of AWS, Evren enjoys spending time with family and friends, traveling, and cycling.