diff --git a/deploy-manage/deploy/elastic-cloud/_snippets/find-endpoint-serverless-console.md b/deploy-manage/deploy/elastic-cloud/_snippets/find-endpoint-serverless-console.md index dca38f994d3..37d2400298e 100644 --- a/deploy-manage/deploy/elastic-cloud/_snippets/find-endpoint-serverless-console.md +++ b/deploy-manage/deploy/elastic-cloud/_snippets/find-endpoint-serverless-console.md @@ -1,12 +1,11 @@ -1. In the [{{ecloud}} Console](https://cloud.elastic.co?page=docs&placement=docs-body), select **Serverless**. -2. Find your project and select **Manage**. -3. Under **Application endpoints, cluster and component IDs**, select **{{es}}**. -4. Copy the **Endpoint** value. +1. In the [{{ecloud}} Console](https://cloud.elastic.co?page=docs&placement=docs-body), find your project and select **Manage**. +2. Under **Application endpoints**, select **{{es}}**. +3. Copy the **Direct endpoint** value. :::{image} /solutions/images/cloud-console-serverless-endpoint.png - :alt: The Elasticsearch panel on a Serverless project page in the Elastic Cloud Console, showing the Endpoint and AWS PrivateLink endpoint values with copy buttons + :alt: The Application endpoints panel in the {{ecloud}} Console, with {{es}} expanded to show the Direct endpoint and Direct Azure Private Link endpoint :screenshot: :width: 50% ::: -If your project runs on AWS, the panel also lists an **AWS PrivateLink endpoint**. Use it only when you connect through AWS PrivateLink. To learn more, refer to [](/deploy-manage/security/private-connectivity-aws.md). +Azure and {{aws}} also offer an endpoint you can use to connect to the deployment over a private connection. [Learn more about private connectivity](/deploy-manage/security/private-connectivity.md). diff --git a/solutions/elasticsearch-solution-project/_snippets/create-an-api-key.md b/solutions/elasticsearch-solution-project/_snippets/create-an-api-key.md new file mode 100644 index 00000000000..6d0791cc855 --- /dev/null +++ b/solutions/elasticsearch-solution-project/_snippets/create-an-api-key.md @@ -0,0 +1,83 @@ + + +A personal API key authenticates your client with your own privileges when it sends requests to {{es}}. The following steps show you where to create one for your deployment type. + +:::::{applies-switch} + +::::{applies-item} serverless: ga + +Follow these steps to create an API key for your project. + +1. In the [{{ecloud}} Console](https://cloud.elastic.co?page=docs&placement=docs-body), find your project and select **Open**. +2. From the **Help menu** {icon}`question`, select **Connection details**. +3. Select the **API key** tab. +4. In the **API key name** field, enter a name, then select **Create API key**. +5. Select an **API key format**: **Encoded** for {{es}} REST API requests, or **{{beats}}** or **{{ls}}** to configure those products. +6. Copy the key. It isn't available after you close the panel. + +Keys created here expire in 90 days and carry your own privileges. To set an expiration or restrict privileges, select **Manage API keys** and create the key there instead. + +:::{note} +You can also use an [{{ecloud}} API key](/deploy-manage/api-keys/elastic-cloud-api-keys.md) to access {{es}}. Use it when the same key needs to access more than one project, or when you use [{{cps}}](/deploy-manage/cross-project-search-config/cps-config-access-and-scope.md#manage-user-and-api-key-access). +::: +:::: + +::::{applies-item} ech: ga + +Follow these steps to create an API key for {{ech}}. + +1. In the [{{ecloud}} Console](https://cloud.elastic.co?page=docs&placement=docs-body), find your deployment and select **Open**. +2. From the **Help menu** {icon}`question`, select **Connection details**. +3. Select the **API key** tab. +4. In the **API key name** field, enter a name, then select **Create API key**. +5. Select an **API key format**: **Encoded** for {{es}} REST API requests, or **{{beats}}** or **{{ls}}** to configure those products. +6. Copy the key. It isn't available after you close the panel. + +Keys created here expire in 90 days and carry your own privileges. To set an expiration or restrict privileges, select **Manage API keys** and create the key there instead. +:::: + +::::{applies-item} ece: ga + +Follow these steps to create an API key for {{ece}}. + +1. Open {{kib}} for your deployment or project. +2. From the **Help menu** {icon}`question`, select **Connection details**. +3. Select the **API key** tab. +4. In the **API key name** field, enter a name, then select **Create API key**. +5. Select an **API key format**: **Encoded** for {{es}} REST API requests, or **{{beats}}** or **{{ls}}** to configure those products. +6. Copy the key. It isn't available after you close the panel. + +Keys created here expire in 90 days and carry your own privileges. To set an expiration or restrict privileges, select **Manage API keys** and create the key there instead. +:::: + +::::{applies-item} {"deployment": {"self": "ga"}} + +Follow these steps to create an API key for a self-managed cluster, one you install and manage. + +1. Go to the **API keys** management page, using the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md) to find it. +2. Select **Create API key**. +3. Enter a name, then select **Create API key**. +4. Copy the key. It isn't available after you leave the page. + +Keys created here don't expire unless you add an expiration date. +:::: + +::::{applies-item} {"deployment": {"eck": "ga"}} + +Follow these steps to create an API key for {{eck}}. + +1. Go to the **API keys** management page, using the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md) to find it. +2. Select **Create API key**. +3. Enter a name, then select **Create API key**. +4. Copy the key. It isn't available after you leave the page. + +Keys created here don't expire unless you add an expiration date. +:::: + +::::: + +For privileges and expiration options, refer to [](/deploy-manage/api-keys.md). diff --git a/solutions/elasticsearch-solution-project/_snippets/find-elasticsearch-endpoint.md b/solutions/elasticsearch-solution-project/_snippets/find-elasticsearch-endpoint.md new file mode 100644 index 00000000000..a1185d9c72a --- /dev/null +++ b/solutions/elasticsearch-solution-project/_snippets/find-elasticsearch-endpoint.md @@ -0,0 +1,145 @@ + + +:::::::{applies-switch} + +::::::{applies-item} serverless: ga +Copy the {{es}} endpoint for your project from the project UI or the {{ecloud}} Console. + +:::::{tab-set} + +::::{tab-item} Project UI + +1. In the [{{ecloud}} Console](https://cloud.elastic.co?page=docs&placement=docs-body), find your project and select **Open**. +2. From the **Help menu** {icon}`question` or the project selector in the header, select **Connection details**. +3. On the **Endpoints** tab, copy the **{{es}} endpoint**. + +:::{image} /solutions/images/kibana-connection-details-endpoints.png +:alt: The Connection details panel showing the {{es}} endpoint on the Endpoints tab, with the Show Cloud ID toggle and the API key tab +:screenshot: +:width: 50% +::: + +:::: + +::::{tab-item} {{ecloud}} Console + +1. In the [{{ecloud}} Console](https://cloud.elastic.co?page=docs&placement=docs-body), find your project and select **Manage**. +2. Under **Application endpoints**, select **{{es}}**. +3. Copy the **Direct endpoint** value. + +:::{image} /solutions/images/cloud-console-serverless-endpoint.png +:alt: The Application endpoints panel in the {{ecloud}} Console, with {{es}} expanded to show the Direct endpoint and Direct Azure Private Link endpoint +:screenshot: +:width: 50% +::: + +Azure and AWS also offer an endpoint you can use to connect to the deployment over a private connection. [Learn more about private connectivity](/deploy-manage/security/private-connectivity.md). + +:::: + +::::: + +:::::: + +::::::{applies-item} ech: ga +Copy the {{es}} endpoint for {{ech}} from the deployment UI or the {{ecloud}} Console. + +:::::{tab-set} + +::::{tab-item} {{kib}} UI + +1. In the [{{ecloud}} Console](https://cloud.elastic.co?page=docs&placement=docs-body), find your deployment and select **Open**. +2. From the **Help menu** {icon}`question`, select **Connection details**. +3. On the **Endpoints** tab, copy the **{{es}} endpoint** value. + +:::{image} /solutions/images/kibana-connection-details-endpoints.png +:alt: The Connection details panel showing the {{es}} endpoint on the Endpoints tab, with the Show Cloud ID toggle and the API key tab +:screenshot: +:width: 50% +::: + +:::{tip} +When the space uses the **{{es}}** solution view, the **Getting started** page shows the endpoint directly. +::: + +:::: + +::::{tab-item} {{ecloud}} Console + +1. In the [{{ecloud}} Console](https://cloud.elastic.co?page=docs&placement=docs-body), find your deployment and select **Manage**. +2. Under **Application endpoints, cluster and component IDs**, select **{{es}}**. +3. Copy the **Direct endpoint** value. + +:::{image} /solutions/images/cloud-console-hosted-endpoint.png +:alt: The Application endpoints, cluster and component IDs panel in the {{ecloud}} Console, with {{es}} expanded to show the Endpoint, Direct endpoint, and Cluster ID +:screenshot: +:width: 50% +::: + +:::: + +::::: + +:::::: + +::::::{applies-item} ece: ga + +:::::{tab-set} + +::::{tab-item} {{kib}} + +For {{ece}}, your endpoint details are in the **Connection details** panel in {{kib}}. + +1. Open {{kib}} for your deployment. +2. From the **Help menu** {icon}`question`, select **Connection details**. +3. Copy the **{{es}} endpoint** from the **Endpoints** tab. + +:::{image} /solutions/images/kibana-connection-details-endpoints.png +:alt: The Connection details panel showing the {{es}} endpoint on the Endpoints tab, with the Show Cloud ID toggle and the API key tab +:screenshot: +:width: 50% +::: + +:::{tip} +When the space uses the **{{es}}** solution view, the **Getting started** page shows the endpoint directly. +::: + +:::: + +::::{tab-item} Cloud UI + +To connect to your {{es}} cluster, copy the **{{es}} endpoint** from the deployment page in the [Cloud UI](/deploy-manage/deploy/cloud-enterprise/log-into-cloud-ui.md). + +:::: + +::::: + +:::::: + +::::{applies-item} {"deployment": {"self": "ga"}} +For a self-managed cluster, one you install and manage, your endpoint takes the form `://:`. Each part comes from your cluster's HTTP settings: + +* **Scheme**: `https` when TLS is enabled on the HTTP layer, and `http` when it isn't. TLS is enabled by default on first startup through [automatic security setup](/deploy-manage/security/self-auto-setup.md), unless the setup is [explicitly skipped](/deploy-manage/security/self-auto-setup.md#stack-skip-auto-configuration) or disabled, as in the local development quickstart. +* **Host**: The address clients use to reach the node, set by [`http.host` or `network.host`](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md). +* **Port**: The HTTP port, set by [`http.port`](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md). It defaults to the range `9200-9300`, and a node binds to the first free port in that range. + +For example, a single-node cluster from the [local development quickstart](/deploy-manage/deploy/self-managed/local-development-installation-quickstart.md) runs without TLS on the default port, so its endpoint is `http://localhost:9200`. + +If clients reach your cluster through a load balancer, reverse proxy, or ingress, use that address rather than the node address. +:::: + +::::{applies-item} {"deployment": {"eck": "ga"}} +The ECK operator automatically creates a service for your {{es}} cluster with TLS enabled. Your endpoint URL depends on where your application runs: + +- **Inside the same Kubernetes namespace**: `https://-es-http:9200` +- **In a different namespace**: `https://-es-http..svc:9200` +- **Outside the Kubernetes cluster**: You need to expose the service first. Refer to [Access the endpoint](/deploy-manage/deploy/cloud-on-k8s/accessing-services.md#k8s-request-elasticsearch-endpoint) for setup steps. + +To find your cluster name, run `kubectl get svc` and look for the service ending in `-es-http`. +:::: + +::::::: diff --git a/solutions/elasticsearch-solution-project/search-connection-details.md b/solutions/elasticsearch-solution-project/search-connection-details.md index 1068f2ff896..e5c13fc73c1 100644 --- a/solutions/elasticsearch-solution-project/search-connection-details.md +++ b/solutions/elasticsearch-solution-project/search-connection-details.md @@ -1,6 +1,6 @@ --- navigation_title: Find connection details -description: Find your Elasticsearch endpoint and create an API key so that client applications and tools can connect to your cluster or project. +description: Find your {{es}} endpoint and create an API key so that client applications and tools can connect to your cluster or project. mapped_pages: - https://www.elastic.co/guide/en/kibana/current/search-space-connection-details.html applies_to: @@ -18,88 +18,14 @@ To connect a client application or a third-party tool to {{es}}, you need two th ## Before you begin [before-you-begin] -To create an API key, you need the `manage_api_key` or the `manage_own_api_key` cluster privilege. +To create an API key, you need the `manage_api_key` or the `manage_own_api_key` cluster privilege. If you created the deployment or project, you already have this privilege. If you sign in as a different user, an administrator needs to grant it. In this case, refer to [](/deploy-manage/users-roles.md). ## Find your {{es}} endpoint [find-endpoint-cloud-self-managed] -:::::{applies-switch} - -::::{applies-item} serverless: ga -Your endpoint details are on your project's page in the {{ecloud}} Console. - -:::{include} /deploy-manage/deploy/elastic-cloud/_snippets/find-endpoint-serverless-console.md -::: - -:::{tip} -You can also find your endpoint details in {{kib}}. From the **Help menu** {icon}`question` or the project selector in the header, select **Connection details**, then copy the **{{es}} endpoint** from the **Endpoints** tab. -::: -:::: - -::::{applies-item} ech: ga -Your endpoint details are on your deployment's page in the [{{ecloud}} Console](https://cloud.elastic.co?page=docs&placement=docs-body). - -1. In the {{ecloud}} Console, select **Hosted**. -2. Select your deployment. -3. Under **Application endpoints, cluster and component IDs**, select **{{es}}**. -4. Copy the **Endpoint** value. - - :::{image} /solutions/images/cloud-console-hosted-endpoint.png - :alt: The Elasticsearch panel on a hosted deployment page in the Elastic Cloud Console, showing the Endpoint value with a copy button - :screenshot: - :width: 50% - ::: - -:::{tip} -You can also find your endpoint details in {{kib}}. From the **Help menu** {icon}`question`, select **Connection details**, then copy the **{{es}} endpoint** from the **Endpoints** tab. -::: -:::: - -::::{applies-item} ece: ga -Your endpoint details are in the **Connection details** panel in {{kib}}. - -1. Open {{kib}} for your deployment. -2. From the **Help menu** {icon}`question`, select **Connection details**. -3. Copy the **{{es}} endpoint** from the **Endpoints** tab. - -:::{image} /solutions/images/kibana-connection-details-endpoints.png -:alt: The Connection details panel showing the Elasticsearch endpoint on the Endpoints tab, with the Show Cloud ID toggle and the API key tab -:screenshot: -:width: 50% -::: - -:::{tip} -When the space uses the **{{es}}** solution view, the **Getting started** page shows the endpoint directly. +:::{include} /solutions/elasticsearch-solution-project/_snippets/find-elasticsearch-endpoint.md ::: -:::: - -::::{applies-item} {"deployment": {"self": "ga"}} -Your endpoint takes the form `://:`. Each part comes from your cluster's HTTP settings: - -* **Scheme**: `https` when TLS is enabled on the HTTP layer, and `http` when it isn't. [Automatic security setup](/deploy-manage/security/self-auto-setup.md) enables TLS on a new archive or package installation. -* **Host**: The address clients use to reach the node, set by [`http.host` or `network.host`](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md). -* **Port**: The HTTP port, set by [`http.port`](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md). It defaults to the range `9200-9300`, and a node binds to the first free port in that range. - -For example, a single-node cluster from the [local development quickstart](/deploy-manage/deploy/self-managed/local-development-installation-quickstart.md) runs without TLS on the default port, so its endpoint is `http://localhost:9200`. - -If clients reach your cluster through a load balancer, reverse proxy, or ingress, use that address rather than the node address. -:::: - -::::{applies-item} {"deployment": {"eck": "ga"}} -The {{eck}} operator creates a `ClusterIP` service named `-es-http` on port `9200`, with TLS enabled by default. - -From inside the Kubernetes cluster, your endpoint is `https://-es-http:9200` in the same namespace, or `https://-es-http..svc:9200` from another namespace. List your services to confirm the name: - -```sh -kubectl get svc -``` - -To reach the cluster from outside, expose the service and use its external address. Refer to [Access the endpoint](/deploy-manage/deploy/cloud-on-k8s/accessing-services.md#k8s-request-elasticsearch-endpoint) for both cases, including how to retrieve the certificate authority (CA) certificate. -:::: - -::::: - -### Find your Cloud ID [find-cloud-id-cloud-self-managed] +## Find your Cloud ID [find-cloud-id-cloud-self-managed] ```{applies_to} deployment: @@ -127,32 +53,8 @@ To skip {{kib}}, select **Hosted** in the {{ecloud}} Console, open your deployme ## Create an API key [create-an-api-key-cloud-self-managed] -:::::{applies-switch} - -::::{applies-item} { "deployment": { "ech": "ga", "ece": "ga" }, "serverless": "ga" } - -1. Open {{kib}} for your deployment or project. -2. From the **Help menu** {icon}`question`, select **Connection details**. -3. Select the **API key** tab. -4. In the **API key name** field, enter a name, then select **Create API key**. -5. Select an **API key format**: **Encoded** for {{es}} REST API requests, or **Beats** or **Logstash** to configure those products. -6. Copy the key. It isn't available after you close the panel. - -Keys created here expire in 90 days and carry your own privileges. To set an expiration or restrict privileges, select **Manage API keys** and create the key there instead. -:::: - -::::{applies-item} {"deployment": {"eck": "ga", "self": "ga"}} -1. Go to the **API keys** management page, using the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md) to find it. -2. Select **Create API key**. -3. Enter a name, then select **Create API key**. -4. Copy the key. It isn't available after you leave the page. - -Keys created here don't expire unless you add an expiration date. -:::: - -::::: - -For key types, privileges, and expiration options, refer to [](/deploy-manage/api-keys.md). +:::{include} /solutions/elasticsearch-solution-project/_snippets/create-an-api-key.md +::: ## Test your connection [elasticsearch-get-started-test-connection] @@ -196,6 +98,6 @@ If your cluster uses a self-signed certificate, pass your CA certificate with `c ## Related pages -* [Configure Beats and {{ls}} with a Cloud ID](/deploy-manage/deploy/elastic-cloud/find-cloud-id.md) +* [Configure {{beats}} and {{ls}} with a Cloud ID](/deploy-manage/deploy/elastic-cloud/find-cloud-id.md) * [Connect to {{es}} on {{ece}}](/deploy-manage/deploy/cloud-enterprise/connect-elasticsearch.md) * [Securing HTTP client applications](/deploy-manage/security/httprest-clients-security.md) diff --git a/solutions/images/cloud-console-hosted-endpoint.png b/solutions/images/cloud-console-hosted-endpoint.png index 980abed6af8..7bfd4da297e 100644 Binary files a/solutions/images/cloud-console-hosted-endpoint.png and b/solutions/images/cloud-console-hosted-endpoint.png differ diff --git a/solutions/images/cloud-console-serverless-endpoint.png b/solutions/images/cloud-console-serverless-endpoint.png index 21d0390b092..ec06bcf4dc4 100644 Binary files a/solutions/images/cloud-console-serverless-endpoint.png and b/solutions/images/cloud-console-serverless-endpoint.png differ diff --git a/solutions/search/set-up.md b/solutions/search/set-up.md new file mode 100644 index 00000000000..9926c38d9aa --- /dev/null +++ b/solutions/search/set-up.md @@ -0,0 +1,16 @@ +--- +applies_to: + stack: + serverless: +navigation_title: Set up +description: Prepare {{es}} for search by selecting a deployment type, then connecting with an endpoint, API key, and language client. +type: overview +--- + +# Set up {{es}} for search [set-up-elasticsearch-for-search] + +If you're building search on {{es}}, start here. These pages take you from selecting where to run {{es}} to sending your first request from code. + +1. [](/solutions/search/set-up/get-elasticsearch-running-for-search.md): Compare fully managed and self-managed options, and select the one that fits how much infrastructure you want to run. +2. [](/solutions/search/set-up/api-key-and-endpoints.md): Find your endpoint URL and create an API key. +3. [](/solutions/search/set-up/connect-with-an-sdk.md): Connect programmatically, install a language client, and send a request from code. If you don't want to connect programmatically, you can also get started with {{es}} in the {{kib}} [{{dev-tools-app}} Console](/explore-analyze/query-filter/tools/console.md). diff --git a/solutions/search/set-up/api-key-and-endpoints.md b/solutions/search/set-up/api-key-and-endpoints.md new file mode 100644 index 00000000000..e92f8a09441 --- /dev/null +++ b/solutions/search/set-up/api-key-and-endpoints.md @@ -0,0 +1,37 @@ +--- +applies_to: + stack: + serverless: +navigation_title: API key and endpoints +description: Find your {{es}} endpoint and create an API key so you can connect a search client. +type: how-to +--- + +# Get your {{es}} endpoint and API key [get-your-api-key-and-endpoints] + +If you want to work with {{es}} programmatically, you need an endpoint URL and an API key. This page shows how to find the endpoint and create an API key for each deployment type. + +## Before you begin + +* You need access to your deployment or project, such as an {{es}} {{vectordb}} project, an {{es}} project, or an {{ech}} deployment. If you don't have one yet, refer to [](/solutions/search/set-up/get-elasticsearch-running-for-search.md). +* To create an API key, you need the `manage_api_key` or the `manage_own_api_key` cluster privilege. If you created the deployment or project, you already have this privilege. If you sign in as a different user, an administrator needs to grant it. In this case, refer to [](/deploy-manage/users-roles.md). + +## Find your {{es}} endpoint [find-your-elasticsearch-endpoint] + +The {{es}} endpoint is the URL your client uses to send requests. Where you find it depends on your deployment type. The following steps show you where to copy it. + +:::{include} /solutions/elasticsearch-solution-project/_snippets/find-elasticsearch-endpoint.md +::: + +## Create an API key [get-your-api-key] + +:::{include} /solutions/elasticsearch-solution-project/_snippets/create-an-api-key.md +::: + +:::{tip} +If you just created a {{serverless-short}} project, the **Getting started** {icon}`rocket` page shows a generated API key that you can copy immediately. If you have navigated away from that page, create a new API key as described above. +::: + +## Next step [api-key-and-endpoints-next] + +After you have an endpoint and an API key, connect a language client in [](/solutions/search/set-up/connect-with-an-sdk.md). diff --git a/solutions/search/set-up/connect-with-an-sdk.md b/solutions/search/set-up/connect-with-an-sdk.md new file mode 100644 index 00000000000..7ab4d53ded2 --- /dev/null +++ b/solutions/search/set-up/connect-with-an-sdk.md @@ -0,0 +1,492 @@ +--- +applies_to: + stack: + serverless: +navigation_title: Connect with an SDK +description: Install an official {{es}} language client, connect it with your endpoint and API key, and verify the connection. +type: how-to +--- + +# Connect to {{es}} with an SDK [connect-with-an-sdk] + +You can use an official {{es}} client library to connect your application to {{es}} from code. This page shows how to install and initialize the client for each supported language. + +:::{note} +To get started without installing a client, work with {{es}} data in the {{kib}} [{{dev-tools-app}} Console](/explore-analyze/query-filter/tools/console.md), or send requests with `curl`. For `curl` examples, refer to the [{{es}} API documentation]({{es-apis}}). +::: + +## Before you begin + +You need the following: + +- A running {{es}} deployment or project. If you don't have one yet, refer to [](/solutions/search/set-up/get-elasticsearch-running-for-search.md). +- The {{es}} endpoint URL, which the client uses to reach {{es}}, and an API key, which the client uses to authenticate. If you don't have them yet, refer to [](/solutions/search/set-up/api-key-and-endpoints.md). + +## Connect a client + +The following steps show you how to set your endpoint and API key, install a client for your language, and verify the connection. + +:::::::{stepper} + +::::::{step} Set environment variables +:anchor: connect-with-an-sdk-connect + +Set your {{es}} endpoint and API key as environment variables: + +:::::{tab-set} +:group: operating-systems + +::::{tab-item} macOS and Linux +:sync: macos-linux + +```bash +export ES_URL="YOUR_PROJECT_URL" <1> +export ES_API_KEY="YOUR_API_KEY" +``` + +1. For example, `https://my-project.es.us-east-1.aws.elastic.cloud:443`. + +:::: + +::::{tab-item} Windows PowerShell +:sync: windows-powershell + +```powershell +$Env:ES_URL = "YOUR_PROJECT_URL" <1> +$Env:ES_API_KEY = "YOUR_API_KEY" +``` + +1. For example, `https://my-project.es.us-east-1.aws.elastic.cloud:443`. + +:::: + +::::: + +:::::: + +::::::{step} Install and initialize a client +:anchor: connect-with-an-sdk-install + +Install the client for your language. For a list of available clients, refer to [{{es}} clients](/reference/elasticsearch-clients/index.md). + +:::::{tab-set} +:group: languages + +::::{tab-item} Python +:sync: python + +```bash +pip install elasticsearch +``` + +For supported Python versions and other requirements, refer to the [Python client documentation](elasticsearch-py://reference/getting-started.md#_requirements). + +:::: + +::::{tab-item} TypeScript +:sync: typescript + +```bash +npm install @elastic/elasticsearch +npm install --save-dev typescript tsx +npm pkg set type=module +``` + +For supported Node.js versions and other requirements, refer to the [JavaScript client documentation](elasticsearch-js://reference/index.md). + +:::: + +::::{tab-item} PHP +:sync: php + +```bash +composer require elasticsearch/elasticsearch +``` + +For supported PHP versions and other requirements, refer to the [PHP client documentation](elasticsearch-php://reference/index.md). + +:::: + +::::{tab-item} Ruby +:sync: ruby + +```bash +bundle add elasticsearch +``` + +For supported Ruby versions and other requirements, refer to the [Ruby client installation documentation](elasticsearch-ruby://reference/installation.md). + +:::: + +::::{tab-item} C#/.NET +:sync: csharp + +```bash +dotnet add package Elastic.Clients.Elasticsearch +``` + +For supported .NET versions and other requirements, refer to the [.NET client documentation](elasticsearch-net://reference/index.md). + +:::: + +::::{tab-item} Java +:sync: java + +In the generated `build.gradle` file, add the client dependency to the `dependencies` block and set `mainClass` in the `application` block: + +```groovy +dependencies { + implementation "co.elastic.clients:elasticsearch-java:VERSION" +} + +application { + mainClass = "quickstart.App" +} +``` + +Replace `VERSION` with the version from the [latest Java client release](https://github.com/elastic/elasticsearch-java/releases). For supported Java versions and other requirements, refer to the [Java client documentation](elasticsearch-java://reference/index.md). + +:::: + +::::{tab-item} Go +:sync: go + +```bash +go get github.com/elastic/go-elasticsearch/v9 +``` + +For supported Go versions and other requirements, refer to the [Go client installation documentation](https://www.elastic.co/docs/reference/elasticsearch/clients/go/installation). + +:::: + +::::: + +After installation, initialize the client: + +:::::{tab-set} +:group: languages + +::::{tab-item} Python +:sync: python + +```python +import os +from elasticsearch import Elasticsearch + +es = Elasticsearch( + os.environ["ES_URL"], + api_key=os.environ["ES_API_KEY"], +) +``` + +:::: + +::::{tab-item} TypeScript +:sync: typescript + +```typescript +import { Client } from "@elastic/elasticsearch"; + +const es = new Client({ + node: process.env.ES_URL, + auth: { apiKey: process.env.ES_API_KEY! }, +}); +``` + +:::: + +::::{tab-item} PHP +:sync: php + +```php +setHosts([getenv("ES_URL")]) + ->setApiKey(getenv("ES_API_KEY")) + ->build(); +``` + +:::: + +::::{tab-item} Ruby +:sync: ruby + +```ruby +require "elasticsearch" + +es = Elasticsearch::Client.new( + url: ENV.fetch("ES_URL"), + api_key: ENV.fetch("ES_API_KEY") +) +``` + +:::: + +::::{tab-item} C#/.NET +:sync: csharp + +```csharp +using Elastic.Clients.Elasticsearch; +using Elastic.Transport; + +var url = Environment.GetEnvironmentVariable("ES_URL") + ?? throw new InvalidOperationException("ES_URL is not set."); +var apiKey = Environment.GetEnvironmentVariable("ES_API_KEY") + ?? throw new InvalidOperationException("ES_API_KEY is not set."); + +var settings = new ElasticsearchClientSettings(new Uri(url)) + .Authentication(new ApiKey(apiKey)); +var es = new ElasticsearchClient(settings); +``` + +:::: + +::::{tab-item} Java +:sync: java + +```java +package quickstart; + +import co.elastic.clients.elasticsearch.ElasticsearchClient; + +public class App { + public static void main(String[] args) throws Exception { + String serverUrl = System.getenv("ES_URL"); + String apiKey = System.getenv("ES_API_KEY"); + + ElasticsearchClient es = ElasticsearchClient.of(b -> b + .host(serverUrl) + .apiKey(apiKey) + ); + } +} +``` + +:::: + +::::{tab-item} Go +:sync: go + +```go +package main + +import ( + "log" + "os" + + "github.com/elastic/go-elasticsearch/v9" +) + +func main() { + es, err := elasticsearch.New( + elasticsearch.WithAddresses(os.Getenv("ES_URL")), + elasticsearch.WithAPIKey(os.Getenv("ES_API_KEY")), + ) + if err != nil { + log.Fatal(err) + } +} +``` + +:::: + +::::: + +:::::: + +::::::{step} Verify your connection +:anchor: connect-with-an-sdk-verify + +Call the info API to confirm that your endpoint URL and API key work. A successful response includes the cluster name and version. The exact output depends on your client and your deployment. + +:::::{tab-set} +:group: languages + +::::{tab-item} Python +:sync: python + +```python +print(es.info()) +``` + +:::{dropdown} Example response + +```python +{'name': 'instance-0000000000', 'cluster_name': 'my-deployment', 'cluster_uuid': 'QIpRB53HS1KSVYWtjP_rqg', 'version': {'number': '9.2.0', 'build_flavor': 'default', 'build_type': 'docker', 'build_hash': '25d88452371273dd27356c98598287b669a03eae', 'build_date': '2025-10-21T10:06:21.288851013Z', 'build_snapshot': False, 'lucene_version': '10.3.1', 'minimum_wire_compatibility_version': '8.19.0', 'minimum_index_compatibility_version': '8.0.0'}, 'tagline': 'You Know, for Search'} +``` + +::: + +:::: + +::::{tab-item} TypeScript +:sync: typescript + +```typescript +console.log(await es.info()); +``` + +:::{dropdown} Example response + +```typescript +{ + name: 'instance-0000000000', + cluster_name: 'my-deployment', + cluster_uuid: 'QIpRB53HS1KSVYWtjP_rqg', + version: { + number: '9.2.0', + build_flavor: 'default', + build_type: 'docker', + build_hash: '25d88452371273dd27356c98598287b669a03eae', + build_date: '2025-10-21T10:06:21.288851013Z', + build_snapshot: false, + lucene_version: '10.3.1', + minimum_wire_compatibility_version: '8.19.0', + minimum_index_compatibility_version: '8.0.0' + }, + tagline: 'You Know, for Search' +} +``` + +::: + +:::: + +::::{tab-item} PHP +:sync: php + +```php +echo $es->info()->asString(); +``` + +:::{dropdown} Example response + +```json +{ + "name" : "instance-0000000000", + "cluster_name" : "my-deployment", + "cluster_uuid" : "QIpRB53HS1KSVYWtjP_rqg", + "version" : { + "number" : "9.2.0", + "build_flavor" : "default", + "build_type" : "docker", + "build_hash" : "25d88452371273dd27356c98598287b669a03eae", + "build_date" : "2025-10-21T10:06:21.288851013Z", + "build_snapshot" : false, + "lucene_version" : "10.3.1", + "minimum_wire_compatibility_version" : "8.19.0", + "minimum_index_compatibility_version" : "8.0.0" + }, + "tagline" : "You Know, for Search" +} +``` + +::: + +:::: + +::::{tab-item} Ruby +:sync: ruby + +```ruby +puts es.info +``` + +:::{dropdown} Example response + +```ruby +{"name" => "instance-0000000000", "cluster_name" => "my-deployment", "cluster_uuid" => "QIpRB53HS1KSVYWtjP_rqg", "version" => {"number" => "9.2.0", "build_flavor" => "default", "build_type" => "docker", "build_hash" => "25d88452371273dd27356c98598287b669a03eae", "build_date" => "2025-10-21T10:06:21.288851013Z", "build_snapshot" => false, "lucene_version" => "10.3.1", "minimum_wire_compatibility_version" => "8.19.0", "minimum_index_compatibility_version" => "8.0.0"}, "tagline" => "You Know, for Search"} +``` + +::: + +:::: + +::::{tab-item} C#/.NET +:sync: csharp + +```csharp +var info = await es.InfoAsync(); +Console.WriteLine($"{info.ClusterName} {info.Version.Number}"); +``` + +:::{dropdown} Example response + +```text +my-deployment 9.2.0 +``` + +::: + +:::: + +::::{tab-item} Java +:sync: java + +```java +System.out.println(es.info()); +es._transport().close(); +``` + +:::{dropdown} Example response + +```text +InfoResponse: {"cluster_name":"my-deployment","cluster_uuid":"QIpRB53HS1KSVYWtjP_rqg","name":"instance-0000000000","tagline":"You Know, for Search","version":{"build_date":"2025-10-21T10:06:21.288851013Z","build_flavor":"default","build_hash":"25d88452371273dd27356c98598287b669a03eae","build_snapshot":false,"build_type":"docker","lucene_version":"10.3.1","minimum_index_compatibility_version":"8.0.0","minimum_wire_compatibility_version":"8.19.0","number":"9.2.0"}} +``` + +::: + +:::: + +::::{tab-item} Go +:sync: go + +```go +res, err := es.Info() +if err != nil { + log.Fatal(err) +} +defer res.Body.Close() +log.Println(res) +``` + +:::{dropdown} Example response + +```text +[200 OK] { + "name" : "instance-0000000000", + "cluster_name" : "my-deployment", + "cluster_uuid" : "QIpRB53HS1KSVYWtjP_rqg", + "version" : { + "number" : "9.2.0", + "build_flavor" : "default", + "build_type" : "docker", + "build_hash" : "25d88452371273dd27356c98598287b669a03eae", + "build_date" : "2025-10-21T10:06:21.288851013Z", + "build_snapshot" : false, + "lucene_version" : "10.3.1", + "minimum_wire_compatibility_version" : "8.19.0", + "minimum_index_compatibility_version" : "8.0.0" + }, + "tagline" : "You Know, for Search" +} +``` + +::: + +:::: + +::::: + +:::::: + +::::::: + +## Next steps [connect-with-an-sdk-next] + +{{es}} is up and running, and your application is connected. Next, learn how to ingest your own data in [](/solutions/search/ingest-for-search.md). diff --git a/solutions/search/set-up/get-elasticsearch-running-for-search.md b/solutions/search/set-up/get-elasticsearch-running-for-search.md new file mode 100644 index 00000000000..1050e9c4f11 --- /dev/null +++ b/solutions/search/set-up/get-elasticsearch-running-for-search.md @@ -0,0 +1,58 @@ +--- +applies_to: + stack: + serverless: +navigation_title: Get {{es}} running +description: Select an {{es}} deployment model for search, get it running, and try a search quickstart. +type: overview +--- + +# Get {{es}} running for search [get-elasticsearch-running-for-search] + +{{es}} is at the core of every Elastic deployment type. The deployment type you choose determines who manages the infrastructure, scaling, and upgrades, and how usage is billed. This page briefly introduces the deployment types you can use to get {{es}} running quickly, and points you to resources that compare them in detail. + +:::::{stepper} + +::::{step} Choose a deployment and get {{es}} running + +Get {{es}} running in a few minutes. + +### Try for free on {{ecloud}} + +* **{{serverless-full}}**: Elastic automatically scales and upgrades the project. Projects are versionless, so you always get the latest features. + + Serverless has two project types optimized for different search workloads. Choose the one that matches your data and use case: + + * **[{{es}} {{vectordb}} project](/solutions/vector-database/get-started.md)**: For most search workloads, this is the recommended option. It is optimized for vector workloads, such as [RAG](/solutions/search/rag.md), recommendations, and [multimodal search](/solutions/search/multimodal-search.md). Sign up for a [14-day free trial](https://cloud.elastic.co/registration?onboarding_token=vector). + * **[{{es}} project](/solutions/elasticsearch-solution-project/get-started.md)**: If you have logs, events, time series, or telemetry data, choose this project type. Sign up for a [14-day free trial](https://cloud.elastic.co/serverless-registration). +* **[{{ech}}](/deploy-manage/deploy/elastic-cloud/create-an-elastic-cloud-hosted-deployment.md)**: You size, scale, and upgrade the cluster yourself, and you select the hardware profile it runs on. The cluster runs a specific {{stack}} version. Sign up for a [14-day free trial](https://cloud.elastic.co/registration). + +### Run locally + +* **[Local development](/deploy-manage/deploy/self-managed/local-development-installation-quickstart.md)**: Get started quickly with {{es}} and {{kib}} in Docker for local development and testing. + +:::{tip} +These are the fastest ways to get {{es}} running for search. Elastic offers additional deployment types for production workloads on your own infrastructure. + +For more detail on the options listed here, and to compare all deployment types across factors like data residency, compliance, feature availability, and infrastructure control, refer to the [full list of deployment options](/deploy-manage/deploy.md) and the [detailed feature comparison](/deploy-manage/deploy/deployment-comparison.md). +::: + +:::: + +::::{step} Try a quickstart + +Once you have {{es}} running, try a quickstart tutorial: + +* [](/solutions/vector-database/vector-full-text-search.md): Connect a client and run full-text, semantic, and hybrid search. You can follow the examples in Python, TypeScript, PHP, Ruby, C#/.NET, Java, or Go. +* [](/solutions/search/get-started/index-basics.md): Create an index, add documents, and run a search. This tutorial goes further into indices, including dynamic and explicit mappings. +* [](/solutions/search/get-started/keyword-search-python.md): Build a keyword search query with Python. + +:::: + +::::{step} Next step + +After you have selected and started a deployment, get connected: find your endpoint and create an API key in [](/solutions/search/set-up/api-key-and-endpoints.md). + +:::: + +::::: diff --git a/solutions/toc.yml b/solutions/toc.yml index 433fb2e82b3..b24621cb5a4 100644 --- a/solutions/toc.yml +++ b/solutions/toc.yml @@ -11,6 +11,11 @@ toc: - file: search/get-started/index-basics.md - file: search/get-started/keyword-search-python.md - file: search/get-started/semantic-search.md + - file: search/set-up.md + children: + - file: search/set-up/get-elasticsearch-running-for-search.md + - file: search/set-up/api-key-and-endpoints.md + - file: search/set-up/connect-with-an-sdk.md - file: search/ingest-for-search.md children: - file: search/search-pipelines.md diff --git a/solutions/vector-database/vector-full-text-search.md b/solutions/vector-database/vector-full-text-search.md index 6182fe57e3a..e611c55f199 100644 --- a/solutions/vector-database/vector-full-text-search.md +++ b/solutions/vector-database/vector-full-text-search.md @@ -17,7 +17,7 @@ Are you an agent? Use the [elasticsearch-onboarding skill](https://github.com/el ## Create a Vector Database project [vector-full-text-search-create-project] -Create a free [{{es}} Vector Database project](https://cloud.elastic.co/serverless-registration?onboarding_token=vector). It's serverless and built for search and vector workloads, so you don't need to size or manage a cluster. +Create a free [{{es}} Vector Database project](https://cloud.elastic.co/serverless-registration?onboarding_token=vector). It's serverless and built for search and vector workloads, so you don't need to size or manage a cluster. For other quick start options that don't use a Vector Database project, refer to [Quick start options](/get-started/deployment-options.md#quick-start-options). The project takes about a minute to start. The **Getting started** page then displays the **Project endpoint** and a generated API key. Copy both values.