Upgrading from Enterprise Search 7.x
editUpgrading from Enterprise Search 7.x
editThis document describes the breaking changes in Enterprise Search 8.0.0 and provides additional information to help operators upgrade from Enterprise Search 7.x to Enterprise Search 8.x.
Additional resources:
Upgrading to 7.17 is a prerequisite
editBefore upgrading to Enterprise Search 8.0.0 or greater, you must upgrade to Enterprise Search 7.17.x.
For example, if upgrading from Enterprise Search 7.14.1 to Enterprise Search 8.0.0, you must perform two upgrades:
7.14.1 → 7.17.0 → 8.0.0
When upgrading Enterprise Search, you must also upgrade Elasticsearch and Kibana. These services must use matching minor versions.
Security for the Elastic Stack is required
editBefore 8.0.0, it was possible to run Enterprise Search without first enabling security for the Elastic Stack. Since 8.0.0, Enterprise Search requires Elastic Stack security to be enabled.
Security for the Elastic Stack is always enabled on Elastic Cloud. This information applies to self-managed deployments only.
Since 8.0.0, Elastic security features are enabled by default. For details, see Start the Elastic Stack with security enabled.
Enterprise Search will not start if you disable security.
The standalone Enterprise Search management interface is removed
editEnterprise Search 8.0.0 removes the standalone management interface for Enterprise Search.
Manage Enterprise Search from Kibana, the standard management interface for Elastic. To set up Kibana, see Run using downloads (packages) or Run using Docker images.
This change also affects the following configuration settings:
-
The
ent_search.auth.*settings have been removed, since they are specific to the standalone management interface. -
The
kibana.hostsetting is now required.
Finally, if you have used the standalone management interface to connect Workplace Search content sources, you will need to update the client applications you have registered with 3rd party content services. See Update redirect URIs for Workplace Search content sources.
Update redirect URIs for Workplace Search content sources
editWorkplace Search connects your Elastic deployment to various content services, such as Dropbox, Google Drive, and OneDrive. Before you can initially connect to each service, you must register Workplace Search as a client of that service.
If you previously completed this process using the Workplace Search standalone management interface, you must update the OAuth applications you have registered with each 3rd party service. You must provide an updated redirect URI to ensure each service redirects to Kibana rather than to the standalone management interface (which was removed in 8.0).
If you don’t apply these changes, your existing connections will likely continue to sync. However, at some point a connector may fail to refresh its OAuth token and will need you to reauthorize the application. In this case, the "reauthorize" button in Kibana will not work, since you will not be redirected back to Kibana after authenticating to the 3rd party service.
Use the following sections to update or replace each OAuth app. For each app, try to update the existing app. If you cannot, replace the app.
Update an existing OAuth application:
- Locate the guide for connecting the service. See Configuring First-Party Content Sources for a list of these guides.
- Within the guide, locate the management UI for the OAuth app. This is usually a developer portal within the domain of the 3rd party service.
- Within the guide, locate the step to enter the redirect URI. Services may refer to this value as any of the following: redirect URI, redirect URL, callback URI, callback URL. The guide provides the correct redirect URI for Kibana.
- Log in to the management interface (from step 2), and edit the existing OAuth app you have registered. Change the redirect URI value to the value shown in the guide (from step 3). If the management UI will not let you edit the existing OAuth app or will not let you change the redirect URI, skip to Replace an OAuth app.
- Save your changes. If you were able to complete these steps, you have successfully updated the OAuth app for this service.
Replace an OAuth app:
- Locate the guide for connecting the service. See Configuring First-Party Content Sources for a list of these guides.
- Follow the steps in the guide to create a new OAuth application for this service. You will receive a new Client ID and Client secret for the app.
- Within Kibana, navigate to: Enterprise Search → Workplace Search → Sources.
- Locate the source you are updating, and choose Details.
- Choose Settings to edit the settings for that specific source.
- Choose Edit connector settings.
- Enter the updated Client ID and Client secret, and choose Save configuration. If you were able to complete these steps, you have successfully replaced the OAuth app for this service.
Workplace Search API keys replace admin access tokens
editEnterprise Search 8.0 removes Workplace Search admin access tokens and adds Workplace Search API keys.
When upgrading to Enterprise Search 8.0, existing admin access tokens are migrated to API keys. (Specifically, tokens with write access that are associated with an admin user are migrated.) Therefore, migrated admin access tokens will continue to work as API keys.
However, the behavior of API keys differs from admin access tokens. Each admin access token was associated with a specific user. When requesting documents using an admin access token, document-level permissions were applied, limiting the response to only the documents the user could access. When requesting documents using a Workplace Search API key, document-level permissions are not applied. Requests using a Workplace Search API key can access all documents for a content source.
Also, Workplace Search API keys can be used with organization content sources only. They cannot be used with private content sources.
Workplace Search API keys are useful for integrators who are building their own connectors using custom sources. For example, an integrator can use a Workplace Search API key to list all documents for a content source to determine which documents to delete.
Workplace Search admin users can list, create, and delete Workplace Search API keys within Kibana. See Workplace Search API keys.